Repository navigation
spec(FIX-2428): WebSocket delivery: a screen hears a change as it happens, without polling - #4443
Conversation
…pens Retained issue spec: SPEC.md, DECISIONS.md and four figures. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn
|
The latest updates on your projects. Learn more about Vercel for GitHub.
3 Skipped Deployments
|
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. |
There was a problem hiding this comment.
/simplify review (spec FIX-2428)
Verdict: approve direction. This is a spec-only PR, and the shape is mostly the minimum the epic already signed: one WebSocket per client (FIX-2367 D4), notices not rows (D2), mint-through-fetcher for bearer apps (D1), engine-owned socket session + ws in node (D5), remove dead client.stream(). I do not see a materially simpler approach that still satisfies Shift Manager, ER-4, and the epic child scope without reopening epic D1/D4 (widen the session stream, SSE-per-topic, or Ably-only on Node).
What already reads clean
- Reuse:
routeSubjectchecks,coalescedReads/ReadDriver,constantTimeStringEqual, replacingopenUserStreamon the same route, andwsinstead of a home-grown frame codec — good simplification choices. - Scope discipline: Bus (FIX-2426), Postgres fan-out, Ably (FIX-380), and hook migrations are correctly fenced.
- Verification: Goal legs assert on read results with anti-game controls; that keeps implementation from chasing frame plumbing.
Complexity that looks necessary vs optional trim
| Area | Take |
|---|---|
Mint + signed ticket + pushSecret |
Heavy on paper, but standard prior art (Pusher/Ably/Phoenix) and the alternative (cookie-only upgrade auth) fails the epic’s own apps. Keep. |
| D3 timer while socket is down | Extends epic ER-5’s “poll when no push” and adds permanent client state. Trade is intentional (silent staleness vs reads while disconnected). Keep unless product accepts a visible “disconnected” state with reconnect-only recovery. |
useSubscription + client.subscribe |
Two names, but one transport owner (D4) and one fallback path (ER-5). Merging into followSession would blur session-SSE vs topic-push. Reasonable. |
{ userStream, push } on capabilities |
Two knobs that may always move together on Node (userStream: true ⟺ push present). Optional simplify at implementation: derive or document one as legacy alias to avoid client branching bugs. Not a spec gate blocker. |
pushSecret in v1 |
Needed only for multi-process behind one address. Optional defer to the multi-process epic if FIX-2428’s goal host stays single-process first — but document now if FIX-380/mint already assumes it. |
Skipped (would be larger than this issue)
- Managed push on Node only (Ably everywhere) — epic rejected for local dev.
- Per-notice auth re-check — epic bus economics.
- Shared SVG CSS across four figures — maintainability nit only.
Before merge (small spec nits)
- Fix the
pollIntervalMsexample comment so it matches D3 (not “only while there is no push”). - Consider one sentence tying D3 to epic ER-5 so implementers know the child extends “poll when no push” rather than contradicting it.
Coordinator may still run a fresh analysis pass before the gate (noted in DECISIONS).
Sent by Cursor Automation: Review For Best Approach
| -fsd.stream({ onResourceChanged }); // the server answered 501 | ||
| +const sub = fsd.subscribe([topic.session(sessionId), topic.org()], { | ||
| + onChange: () => void reload(), // a notice, a connect, or a poll | ||
| + pollIntervalMs: 3000, // only while there is no push |
There was a problem hiding this comment.
Simplify / coherence: This inline comment says polling runs "only while there is no push", but D3 explicitly also runs the timer while the socket is down on a push host. That mismatch will confuse implementers and doc writers.
Suggest aligning the example comment with D3 (e.g. "while there is no push, or while the socket is down"), or drop the comment and point to D3 in the guide.
| (BP-031), so no one can name another user's or organization's scope. A session topic names | ||
| its session and passes the check `session_stream` uses. A topic narrowed to one resource | ||
| passes its scope's check. | ||
| - **`GET /capabilities` answers `{ userStream, push }`**, with `push` either |
There was a problem hiding this comment.
Optional simplify (uncertain): { userStream, push } may duplicate the same fact on Node (userStream: true when this host serves the upgrade, push: { transport: "websocket" } when push is on). If they are always equivalent, implementation could expose push only and treat userStream as deprecated (BP-030 dual-read) — fewer client branches. If they can diverge (e.g. route exists but push: false), one sentence here would help.
|
|
||
| It comes down to the bearer header: on its own, the upgrade can't carry it, so Shift Manager polls. | ||
|
|
||
| **What would change my mind:** every app we serve to a browser signs in with cookies. Then the |
There was a problem hiding this comment.
Optional defer (judgment call): pushSecret / FSD_PUSH_SECRET is only needed when several processes share one address and tickets must verify cross-process. If FIX-2428’s goal fixture and first ship target single-process serve(), you could spec mint+socket first and fold multi-process secret into FIX-2368 — or keep it here if landing without it would strand Shift Manager behind a load balancer. I’m not sure which ship order you want; the spec is fine either way if intentional.
| | Adds | Existing piece considered | Why it doesn't fit, or how this is composed from it | | ||
| |---|---|---| | ||
| | The mint (`POST /users/:userId/stream`) | `client` · `sessions.stream`; the user-stream route | Composed: it is the user-stream route with a second method, and each topic check is an existing route check | | ||
| | The engine's socket session (ticket check, subscription set) | `streaming` · the SSE encoders; `StreamBridge` | A socket takes topics in after it opens; both are one fixed stream. Lives in the engine so a later host reuses it (epic D5) | |
There was a problem hiding this comment.
Reuse note (implementation, not direction): For the signed 30s ticket, consider jose (or similar) for sign/verify instead of a bespoke payload format — same D1 semantics, less custom crypto surface. Spec doesn’t need to mandate it unless you want one format locked for FIX-380’s mint response.
Second look + architecture pass (FIX-2428 spec)Read SPEC.md and DECISIONS.md against 1. Above the bar: D1 never weighs one multiplexed SSE stream plus POST controlsD1's whole cost (a mint route, a signing secret, That shape goes through the client's fetcher, so the bearer header and the cookies both work with no ticket. The server checks each topic on the real request, which is ER-4 with no signed credential. It needs no What it costs: a long-lived fetch, and a hard stop on serverless hosts, which is already out of scope (FIX-380). I'm not confident it wins. The epic D4 sign-off may have excluded it for reasons not written down. Either way, the spec should say why it lost, because it removes the part D1 itself calls "the one to weigh". If WebSocket stays, add a one-line row to Considered and dropped. 2. Above the bar:
|
|
Coherence pass on FIX-2428. The direction holds: the push is a notice, one read serves the first load, the notice and the timer (FIX-2286 D3), and the mint is the right place to meet FIX-380. I'm not approving yet. The points below aren't already raised in the comments above.
D1–D3 stay Jake's call. My lean is to accept all three as written, with the D3 example comment (SPEC line 79) fixed to say the timer runs while there is no push or the socket is down. — FSD Architect |


client.stream()exists, but the server answers 501Goal: on the Node host, a screen that uses the framework's hook reads a change from another person in 1 s or less. A caller who cannot read that scope never gets a notice for it, on the first connect or on a reconnect. When the host has no push, the same hook keeps the screen current on a timer, with no change to the app's code.
The check reads the result of each client's read. It does not count notices. Check:
goals/realtime/websocket-delivery/, modeln/a. Controls:GOAL_CONTROL=no-socketmust fail leg a, andGOAL_CONTROL=skip-checkmust fail leg b. Why this goal: SPEC.md.Three packages each get one new part. The old user-stream reader, which the server never served, is removed.
How: the client asks for a short ticket through its usual fetcher. The server checks each topic with the check that the topic's read route uses. The client opens one socket and sends the ticket. The bus sends a notice when a topic changes, and the hook reads again.
Sign off
The goal, at that size. If wrong: a socket that the epic's own bearer-token apps cannot use.
The debt: up, by the socket path and one secret (
pushSecret). It removesclient.stream(), which never worked. If wrong: a second wire that only two apps use.The socket proves identity with a short ticket from the client's fetcher, checked per topic · D1
The decision is about the bearer header. A browser socket cannot send it, so without the ticket Shift Manager continues to poll. If wrong: one more request at each connect, and a secret to share, for a case that cookies can do. This is the one to weigh.
The server does not check an open socket again; it closes the socket after one hour · D2
The decision is about the cost of a notice: a check before each notice is a store read for each viewer. If wrong: a revoked user hears "changed", with no data, for up to one hour.
The hook reads on a timer while the socket is down, too · D3
The decision is about a socket that drops. Without the timer, the screen stops and shows no sign. If wrong: a short double read at reconnect, which the coalesced read already merges.
Open: none. D1 is the one to weigh. Reasons and what lost: DECISIONS.md.
Analysis: right approach. The author ran it in this step, not a fresh agent; nothing changed. DECISIONS.md → Analysis.
Reviewers · look here
client.stream()is removed. Does something outside this repository use it?Not here: notices for user and org state (FIX-1506), task boards (FIX-2429), the bus itself (FIX-2426), more than one process, and Ably (FIX-380).
Spec · Decisions · Linear FIX-2428 · epic FIX-2367 (#4294) · depends on FIX-2426 · merges after human approval and required checks (contract)
How to review this — altitude, what's in scope, what's deliberately unsettled
This is a direction set, not an implementation and not a build plan. Reviewing it well means
answering one question: is this the right approach?
In scope to challenge:
SPEC.md— is the goal the real need at full size,for the people named, or a smaller goal that would let us call this done early? Would the
named check fail if the goal were not met?
docs/philosophy.md?DECISIONS.md— that's the sign-off surface.SPEC.md→ What's already here, and the debt — an existing primitive,method or prior design the change overlaps and doesn't name; something it adds that is debt
and isn't listed; a net verdict the tables don't support.
piece it considered, or that is a second mechanism for something we already have
(
orchestration.md).design.
Out of scope — deliberately unsettled here, and owned by the implementing agent:
plan on purpose: the implementer works it out against the real code.
or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
decisions don't say is.
poc/are retained,not production code. Read them for directional evidence, not production completeness.
Their isolation from production/default discovery and absence of secrets or generated
dependencies are in scope; retention is not permission to weaken repository checks.
One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.
Feedback in the second list is welcome and gets recorded verbatim in
DECISIONS.md → Notes from reviewfor the implementer to weigh against real code. It will notbe argued with, and it will not be folded into the design prose. Please don't re-raise it: one
mention is enough.
The one exception is the POC. Line-level feedback on it is dropped, not recorded — there
is nothing for an implementer to weigh about code that isn't shipping. Feedback about its
direction is not line-level and is treated like any other above-the-bar finding.
Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.
Generated by Claude Code