Repository navigation
feat(link): Child link WebSocket counters and a Child-local opt-out - #8620
Conversation
…s Home leg (not wired yet) A Child relays Codex's model requests to its Home over HTTP only, so every request re-sends the whole conversation through the link. This is the first Child-side piece of carrying the Responses WebSocket instead. - Every relay-auth preflight takes a number when it starts; a verified answer's x-opencodex-link-ws-state applies only when its number is higher than the last applied one for the link, so a late answer never overwrites a newer one. No pair, or a pair whose proof fails, is off. - openLinkWebsocket runs the preflight and the upgrade on one authenticated connection, proceeds only on that answer's own verified on, and accepts only a complete 101 on that socket. - A client RFC 6455 framer for the Home leg: Bun resolves ws to its built-in shim, whose framer is not implemented. Nothing calls the transport yet and a Child-side release gate stays closed, so Codex's upgrade still gets today's 426.
… order and text exact Review round 1 of the Child's link WebSocket pieces: - the relay-transport hook (preflight numbers, the state pair checked on every verified answer, the exports the Home leg needs) was missing from the previous commit, so link-ws-transport.ts could not load; - evicting a link from the 256-entry book no longer drops its ordering: an answer for a link without an entry applies only when its preflight started after every evicted entry's last applied one; - a leading U+FEFF in a text message or close reason is kept; - fragments are written into one reassembly buffer of the maximum message size, so a fragmented message holds at most that much.
…nk when the Home advertises it A Child answered Codex's upgrade with 426, so every model request went over HTTP and re-sent the whole conversation. With the Child's release gate open (it stays closed) and the Home advertising the feature on its last applied relay answer, the Child now accepts the upgrade and relays whole text messages over the link's authenticated socket. - Fallbacks: a local Origin, no link key, the caps (8 open, 4 setting up), the 256 MiB memory budget, a failed tunnel, a preflight that is refused or not on, a Home refusal, a broken 101 and the 8 s setup budget all answer today's 426. A Child-initiated tunnel that is still reconnecting after a 3 s hold answers 503 link_websocket_unavailable. - Relay: binary from Codex closes both legs (1003); a Home message over 4 MiB + 64 KiB closes Codex with 1011; close codes are relayed with 1005/1006/1015 as 1011; a second unflushed message from Codex closes both legs (1013/1001); the Home leg pauses above 1 MiB buffered toward Codex. The local 101 advertises the 8 MiB message limit. - Any listener stop closes link sockets with 1001 on both legs. - A socket counts as one request in the Child's traffic book (payload bytes); fixed-word diagnostics link_ws_open/close/fallback. - The release gate's 503 sequence now runs the real Child listener.
…er links from voiding an answer Review round 2: - the reassembly buffer of a fragmented message is dropped once that message is complete, so it never coexists with the next message's own buffer; heldBytes() lets a test check the bound; - an evicted link keeps its own watermark (at most 1,024), so answers for links that were never evicted are not compared against other links' numbers; only a dropped watermark raises a shared floor.
…lay registered close codes Review round 1 of the Child relay: - a listener stop aborts every upgrade still in its tunnel hold or at the Home, and keeps nothing set up after the stop began; - a close decided before Bun opened Codex's socket is applied when it opens, so a Home that is gone by then never leaves Codex waiting; - a socket keeps its slot and memory reservation until its Home connection has actually closed, and a Home-started close is bounded by the same 5 s as a Child-started one; - every tunnel ownership check is raced against the 8 s setup budget; - close codes 1012-1014 are valid on the wire and relayed both ways.
… the same chunk Review round 2: the framer now appends events to the caller's array as they complete, so when a later frame in the same TCP chunk is refused, the relay still delivers the messages before it (a response.completed included) in wire order, and only then closes both legs.
…ade, and never leaves an early error unhandled
Final-review notes on the previous slice and review round 3:
- openLinkWebsocket refuses with 'disabled' before any I/O while the
Child's release gate is closed, whatever the caller does;
- the upgrade after a verified preflight has its own 8 s bound
('timeout'), so a Home that never answers it cannot hold the
connection;
- the socket handed off after a 101 gets an error listener until its
owner adds one;
- tests: a 64-bit length with a non-zero high word is 1009, and the
delivered-before-refused case is also fed to the relay in one piece
through the bytes coalesced with the 101.
…call Review round 4: the socket test can split the frames across reads, so a unit test now builds a HomeLeg whose head holds both frames and checks that attach() delivers the completed message before closing with 1011.
- GET /api/link/status?transport=1 on a Child adds its own link WebSocket counters: open and setting-up sockets, upgrades, fallbacks and closes by reason, and message bytes from and to Codex (design 9.3). In memory, display only; without the query the document is unchanged. - linkResponsesWebsocketOptOut: true in a Child's config keeps that Child on HTTP whatever its Home advertises (owner decision D4), counted as local_optout. Anything else follows the Home. Both gates stay closed, so neither changes what a Child does today.
Review round 1 of the Child counters: the tunnel_connecting_timeout path answers 503 without going through the 426 fallback, so it now counts itself in fallbacks.
…ild-t6-1b # Conflicts: # scripts/test-layout/layout-clients.json
|
Caution Review failedThe pull request is closed.
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. |
|
✅ Deterministic PR hygiene checks passed. |
…k-websocket-child-t6-2 # Conflicts: # scripts/test-layout/layout-clients.json # structure/remote-link.md
# Conflicts: # scripts/test-layout/layout-clients.json
…d-t6-2 Brings in dev 20fb0d3 and the squash of the lower slice; no file of this slice is edited (git merge-tree, no conflicts).
…d-t6-3 Brings in dev 6ee1b91 and the squash of the lower slice; no file of this slice is edited (git merge-tree, no conflicts).
Codex Review Summary: ✅ CompletedThis 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. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2bbfe37c4f
ℹ️ 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".
| const transport = url.searchParams.get("transport") === "1" && linkWebsocket ? { websocket: linkWebsocket.counters() } : {}; | ||
| return Response.json({ ...status, joinAvailable: false, ...transport }, { headers: { "Cache-Control": "no-store" } }); |
There was a problem hiding this comment.
Document the Child transport status API in docs-site
For a connected Child, GET /api/link/status?transport=1 now exposes a new response shape even while the WebSocket release gate is closed: this branch checks only the query and the existence of the relay, not its readiness. Deferring all public documentation until the gates open therefore leaves an already-accessible API undocumented. A repository-wide search of docs-site/ found no transport=1 documentation. Add public documentation for the query, counter meanings, and restart/reset semantics in this change; structure/ documentation alone does not satisfy src/AGENTS.md's requirement to document user-visible behavior in docs-site/.
AGENTS.md reference: src/AGENTS.md:L29-L29
Useful? React with 👍 / 👎.
Builds on #8619 (T6-2, merged as 09f9d43: the Child carries Codex's Responses WebSocket over its link). This PR was stacked on that branch and reviewed as the commits after its head e0a6924; it was tied to the squash and retargeted to dev before merging.
Summary
Two small pieces the link WebSocket design asks of the Child, both inert while the release gates stay closed.
Counters (design 9.3).
GET /api/link/status?transport=1on a Child's machine listener addswebsocket: { open, settingUp, upgrades, fallbacks{reason}, closes{reason}, fromCodexBytes, toCodexBytes }fromcreateLinkWebsocketRelay().counters()(src/client/link-websocket.ts).fallbacksuses the relay's closed set of reasons, includingtunnel_connecting_timeoutfor each 503 sent while the tunnel reconnects.closesuses the closed set of close reasons.fromCodexBytesis the message payload Codex sent on link sockets, counted on arrival whether forwarded or not (design L2).toCodexBytesis what the Child sent to Codex.local_optout,not_advertised) without writing a diagnostic.Child-local opt-out (owner decision D4, recommended default "follow the Home").
linkResponsesWebsocketOptOut: truein a Child'sconfig.jsonkeeps that Child on HTTP whatever its Home advertises: Codex's upgrade gets today's 426 with no network I/O. The Child reads the key once when its listener starts, and onlytrueopts out; anything else follows the Home. The new fallback wordlocal_optoutjoins the diagnostics allowlist.What keeps this inert. The Child's release gate is closed and Homes advertise nothing, so every upgrade still gets today's 426 and nothing is counted. The status document changes only with the new opt-in query. The new config key is read only by a Child's listener and changes nothing while the gate is closed.
docs-site/will document the key with the change that opens the gates;structure/config.mdandstructure/remote-link.mddescribe it now.Verification
Tests that failed first (
tests/clients/link-ws-child-status.test.ts, against a raw-TCP stand-in Home and the real machine listener):?transport=1adds the counters after one socket session and one refused upgrade, with the exact values; the document without the query is unchanged, before and after;linkResponsesWebsocketOptOut: trueanswers 426 with no connection to the Home and countslocal_optout;tunnel_connecting_timeout(added in review)."An opt-out set to anything but true follows the Home" passes before and after.
Commands (Bun 1.4.4,
TMPDIR=/tmp):bun run typecheck: exit 0.bun run privacy:scan: exit 0.bun run structure:check: exit 0.bun scripts/test.ts --parallel=2 tests/clients/ tests/config/ tests/e2e-style/link-ws-child-home.test.ts tests/e2e-style/link-websocket-release-gate.test.ts tests/test-layout.test.ts tests/test-layout-tooling.test.ts tests/ci-workflows/structure-ssot.test.ts tests/ci-workflows/file-size-ratchet.test.ts tests/lab/core-lab-boundary.test.ts: 4455 pass, 84 skip, 16 fail, exit 1. All 16 failures are environment-only and fail the same way on origin/dev: 13 intests/config/serving-runtimes.test.ts(23 pass / 13 fail on both origin/dev and this head, run alone), and the threeocx-childRust tests that needcargo build, with no Rust toolchain on the build machine.NOT RUN: the full suite (resource limits on the build machine; CI covers it). The environment-only failures above were run, and they fail identically without this change.
Checklist
structure/now;docs-site/with the gate-opening change, since nothing user-visible changes before it.)Implemented by Claude Opus 5.5 (anthropic/claude-opus-5-5) in GOAT through the Codex harness; in-lane review by GPT-6.1 Terra (xhigh). Received as a git bundle from the VM that built it and pushed by the coordinator.