Repository navigation
docs(reference): document the readyz protocol fields and the remote-hub config keys - #3173
Conversation
…ub config keys /readyz gained protocol, minimumClientProtocol and managementUrl in the remote-hub work, but lifecycle.md still described the older six-field body, so a client author reading the reference had no way to know negotiation metadata was available. Three config keys shipped without reference coverage. Two were named only in passing inside a runtimeRole sentence; remoteGui.allowInsecureHttp appeared nowhere. Give each a row with its type, its default when absent, and what going wrong looks like. allowInsecureHttp is documented as retired rather than as a setting. It grants nothing - pairing crosses loopback or authenticated HTTPS only - and is still parsed purely so an older config keeps loading under a strict schema. Refs #3158 (T19, T21)
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
✅ Deterministic PR hygiene checks passed. |
github-actions
Bot
added
the
documentation
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Team Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThe documentation adds remote hub configuration details and updates ChangesRemote hub documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested reviewers: ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 12ee151578
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| A hub that is reachable from a browser needs `hub.managementPublicOrigin` and at least one entry | ||
| in `remoteGui.allowedTailscaleUsers`. Setting the origin without the user list produces a hub that | ||
| advertises itself correctly and then refuses every session; setting the user list without the |
There was a problem hiding this comment.
When a hub operator uses the supported single-use, origin-bound GUI pairing flow—for example behind a generic TLS frontend without trusted Tailscale identity headers—an empty allowedTailscaleUsers list does not cause the hub to refuse every session. createGuiPairingGrant and consumeGuiPairingGrant in src/server/gui-session.ts mint a pairing session without consulting this allowlist. State that an entry is required only for automatic Tailscale-identity issuance and retain the pairing flow as the alternative.
AGENTS.md reference: docs-site/AGENTS.md:L7-L10
Useful? React with 👍 / 👎.
| | `hub.managementPublicOrigin` | string | unset | The canonical browser-reachable management origin a hub advertises, for example the HTTPS origin Tailscale Serve prints. It is what `/readyz` reports as `managementUrl` while `runtimeRole` is `hub`; with it unset the hub falls back to whatever origin each request arrived on, so a client behind a different frontend can be handed an address it cannot reach. | | ||
| | `hub.managementIngress` | `{enabled:false}` or `{enabled:true, port}` | `{enabled:false}` | An extra management-only listener for a local HTTPS frontend. The hostname is not configurable: when enabled the socket always binds `127.0.0.1`, and only GUI, session-bootstrap, and management API routes are admitted. Data-plane routes are rejected before dispatch. | | ||
| | `remoteGui.allowedTailscaleUsers` | string[] | `[]` (empty — nobody) | Exact Tailscale login identities allowed to be issued an automatic remote GUI session. The `Tailscale-User-Login` header is trusted **only** on the separate management ingress; an empty list means no remote identity can mint a session, which is the safe default rather than an oversight. Identities are compared exactly, so a typo silently denies access. | | ||
| | `remoteGui.allowInsecureHttp` | boolean | unset | **Retired — has no effect.** It once permitted a one-time pairing exchange over non-loopback plaintext HTTP. A pairing grant now crosses loopback or authenticated HTTPS only. The key is still parsed so an existing `config.json` keeps loading (the schema is strict, and dropping the key outright would make an older config fail to load entirely); a persisted `true` is reported once and then ignored. Remove it from your config. | |
There was a problem hiding this comment.
When remoteGui.allowInsecureHttp is persisted as true, the schema in src/config.ts accepts it as a valid field, so the malformed-block warning path does not run, and there is no other runtime reporting path for this key. The claim that it is "reported once" therefore promises feedback users never receive; remove that claim or add the corresponding load-time diagnostic.
AGENTS.md reference: docs-site/AGENTS.md:L7-L10
Useful? React with 👍 / 👎.
| is `{service, version, uptime, pid, port, status}` plus the remote-hub protocol fields | ||
| `{protocol, minimumClientProtocol, managementUrl}`. `protocol` is the hub protocol this proxy |
There was a problem hiding this comment.
After declaring these three fields part of the HTTP readiness identity, the translated lifecycle pages still describe the identity as only {service, version, uptime, pid, port, status} (for example fr/reference/cli/lifecycle.md:125 and zh-tw/reference/cli/lifecycle.md:124). Because parseRemoteReadyMetadata treats the protocol fields as mandatory, those localized contracts now contradict the canonical page; update the directly affected translations to include the fields and their semantics.
AGENTS.md reference: docs-site/AGENTS.md:L9-L10
Useful? React with 👍 / 👎.
…ub config keys (lidge-jun#3173) /readyz gained protocol, minimumClientProtocol and managementUrl in the remote-hub work, but lifecycle.md still described the older six-field body, so a client author reading the reference had no way to know negotiation metadata was available. Three config keys shipped without reference coverage. Two were named only in passing inside a runtimeRole sentence; remoteGui.allowInsecureHttp appeared nowhere. Give each a row with its type, its default when absent, and what going wrong looks like. allowInsecureHttp is documented as retired rather than as a setting. It grants nothing - pairing crosses loopback or authenticated HTTPS only - and is still parsed purely so an older config keeps loading under a strict schema. Refs lidge-jun#3158 (T19, T21) Co-authored-by: jun <jun@lidge.dev>
…ub config keys (lidge-jun#3173) /readyz gained protocol, minimumClientProtocol and managementUrl in the remote-hub work, but lifecycle.md still described the older six-field body, so a client author reading the reference had no way to know negotiation metadata was available. Three config keys shipped without reference coverage. Two were named only in passing inside a runtimeRole sentence; remoteGui.allowInsecureHttp appeared nowhere. Give each a row with its type, its default when absent, and what going wrong looks like. allowInsecureHttp is documented as retired rather than as a setting. It grants nothing - pairing crosses loopback or authenticated HTTPS only - and is still parsed purely so an older config keeps loading under a strict schema. Refs lidge-jun#3158 (T19, T21) Co-authored-by: jun <jun@lidge.dev>
Summary
Two of the four follow-ups tracked by #3158 are documentation debt and close here. T2 and T3 are behaviour gaps and stay open.
T19 —
/readyzprotocol negotiation fields. The remote-hub work addedprotocol,minimumClientProtocol, andmanagementUrlto the readiness body (src/server/index.tsspreadsreadyProtocolMetadata), butreference/cli/lifecycle.mdstill described the older six-field shape. A client author reading the reference had no way to know negotiation metadata was there. The page now names the three fields, says what each is for, and explains thatmanagementUrlishub.managementPublicOriginwhenruntimeRoleishuband the observed request origin otherwise. It also states explicitly that the CLI's--jsonoutput is narrower than the HTTP body, which previously read as a contradiction between two adjacent sentences.T21 — three undocumented config keys.
hub.managementPublicOriginandremoteGui.allowedTailscaleUserswere named only in passing inside aruntimeRolesentence;remoteGui.allowInsecureHttpappeared nowhere. Each now has a table row with type, default when absent, and the failure mode of getting it wrong — including the pairing that setting the origin without the user list produces a hub that advertises itself correctly and then refuses every session.One correction worth flagging. The plan for this change assumed
allowInsecureHttpwas a live security-relevant opt-out and should be documented with a warning. Readingsrc/types/config.tsandsrc/server/gui-session.tsshows it is retired: it grants nothing, a pairing grant now crosses loopback or authenticated HTTPS only, and the key is still parsed solely so an olderconfig.jsonkeeps loading under a strict schema. It is documented as retired, with an instruction to remove it — documenting it as an active setting would have been actively misleading.Refs #3158 (T19, T21).
Verification
Exact head
12ee15157:git diff --statis two files, +22/-3.rgconfirms all four remote-hub keys and the three readiness fields now appear in their reference pages.bun test tests/docs-bun-source-requirement.test.ts— 1 pass, 0 fail.gatesjob.Locales are deliberately untouched. The tr/ja/fr/ru/zh-cn
server.mdpages already carry theruntimeRolesentence and do not contradict the English source; adding an English-only table to translated pages would be worse than the current gap. That translation work is not attempted here.Checklist
devsrc/server/index.ts,src/remote/protocol.ts,src/types/config.ts, andsrc/server/gui-session.tsrather than from the issue textSummary by CodeRabbit
/readyzendpoint.