Skip to content

spec(FIX-2428): WebSocket delivery: a screen hears a change as it happens, without polling - #4443

Merged
jhoffner merged 1 commit into
mainfrom
spec/FIX-2428
Nov 1, 2026
Merged

jhoffner merged 1 commit into
mainfrom
spec/FIX-2428

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 1, 2026

Copy link
Copy Markdown
Collaborator
Someone who… Today After
builds a screen on the Node host that other people change Writes a timer that reads every few seconds. client.stream() exists, but the server answers 501 Uses one hook with the topics and the read. The read runs in 1 s or less after a change, and not between changes
deploys the same screen to Vercel or Next The same timer The same hook. No code change. It reads on a timer, because the server says that it has no push
subscribes to a session that they cannot read n/a The server refuses the topic before the socket sends a notice. It refuses again at each reconnect
runs Shift Manager with a bearer token Polls each 3 s The hook works with no more setup. The socket gets its proof of identity through the client's fetcher
has a tab with a socket that drops n/a The hook reads on a timer while the socket is down. It reads one time when the socket is back

Goal: 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.

flowchart LR
  A["one Node serve process · in-memory bus · real WebSocket clients · polling off"] --> L1["leg a · tab 2 watches session S, tab 1 sends a reply in S"]
  A --> L2["leg b · user C subscribes to S, then B is revoked and reconnects"]
  A --> L3["leg c · the same tab 2 code on a host with no push"]
  L1 --> T["what each client's read returns"]
  L2 --> T
  L3 --> T
  T -->|"a within 1 s · b never hears · c within one poll"| P["PASS · goal met"]
  C1["control · no-socket"] -.-> L1
  C2["control · skip-check"] -.-> L2
  L1 -.->|"under no-socket"| F["must FAIL"]
  L2 -.->|"under skip-check"| F
Loading

The check reads the result of each client's read. It does not count notices. Check: goals/realtime/websocket-delivery/, model n/a. Controls: GOAL_CONTROL=no-socket must fail leg a, and GOAL_CONTROL=skip-check must fail leg b. Why this goal: SPEC.md.

What changes. Client: client.subscribe and useSubscription are new; client.stream is removed. Engine: a POST on the user-stream route checks each topic and mints a ticket; a socket session verifies the ticket; capabilities gets a push field; the 501 answer is removed. Node host: serve takes the upgrade. The bus comes from FIX-2426

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 removes client.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

D1: a ticket from the client's fetcher, chosen, beside the upgrade signing in on its own. Decides it: an app that signs in with a bearer header. Price: one more request per connect, and a shared secret for several processes

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

D2: check at connect, with a one-hour limit, chosen, beside a check before each notice. Decides it: the cost of a notice. Price: a revoked user hears that something changed, never what, for up to one hour

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

D3: read on a timer when there is no push or the socket is down, chosen, beside no push only. Decides it: a socket that drops on a host with push. Price: one read per interval while it is down

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

  • Decisions → D1. Is a minted ticket the right way to identify a browser socket, when the client's fetcher is the only part that knows the credential?
  • Decisions → Decided, not asked → the convergence point. A topic gets into a socket only from a ticket that the mint signed. Is there a different path that adds a topic?
  • Spec → what's already 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:

  • The goal and the problem framing in 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?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • The debt in 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.
  • Builds on / Adds in that same section — an Adds item that does not name the existing
    piece it considered, or that is a second mechanism for something we already have
    (orchestration.md).
  • A case a person would hit that the people table misses, when it would invalidate the
    design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • The build plan. Order, file-level changes, the test list, the PR split. The set has no
    plan on purpose: the implementer works it out against the real code.
  • Names, signatures, file paths, and module layout, beyond the few a decision locks.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Edge cases that don't change the approach. The implementer's tests own them.
  • Documentation wording. It is written at implementation, against what shipped.
  • Micro-optimizations and style preferences.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    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 implementation polish. Experiments under the owning spec's 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 review
for the implementer to weigh against real code. It will not
be 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

…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
@jhoffner jhoffner added the spec label Nov 1, 2026 — with Claude
@vercel

vercel Bot commented Nov 1, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-build-site Ready Ready Preview Nov 1, 2026 6:05pm UTC
3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Nov 1, 2026 6:05pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Nov 1, 2026 6:05pm UTC
flow-state-dev-ui Ignored Ignored Nov 1, 2026 6:05pm UTC

Request Review

@linear-code

linear-code Bot commented Nov 1, 2026

Copy link
Copy Markdown

FIX-2428

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-01T18:07:37.249486Z 4701a87 PR opened
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/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: routeSubject checks, coalescedReads / ReadDriver, constantTimeStringEqual, replacing openUserStream on the same route, and ws instead 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)

  1. Fix the pollIntervalMs example comment so it matches D3 (not “only while there is no push”).
  2. 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).

Open in Web View Automation 

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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) |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

jhoffner commented Nov 1, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (FIX-2428 spec)

Read SPEC.md and DECISIONS.md against main and epic FIX-2367. Verdict: direction is sound. The mint, the per-topic route check and the "push says when, a read says what" split all hold up. The findings below are ordered by weight, and only the first two are above the direction-review bar.

1. Above the bar: D1 never weighs one multiplexed SSE stream plus POST controls

D1's whole cost (a mint route, a signing secret, pushSecret, an extra request per connect, and a ticket lifecycle) exists because a browser WebSocket can't carry the bearer header. "Considered and dropped" and epic D4 reject only an SSE stream per topic. They don't consider one SSE stream per client, with add/drop topic as POST /users/:userId/stream calls.

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 ws dependency and no upgrade handler on serve(). It reuses the existing SSE encoders and the vercel heartbeat shaping. The 6-connection limit that sank "per topic" doesn't apply to one stream.

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: pushSecret ships with no way to exercise it

The in-memory bus is single-process and the Postgres bus is unfiled (epic table: "Not filed"). Multi-process delivery is explicitly Not here. Yet this issue adds a public option (pushSecret / FSD_PUSH_SECRET), an env var and a documented failure mode ("a connect that lands on another process is refused"). The goal check is one process, so nothing in it can fail if the option is wrong. By the same restraint test the spec applies to everything else, it is speculative surface. Suggest dropping it here (a random per-process key is enough) and having the Postgres-bus issue add it when a second process can exist. That also shrinks the debt line, which is currently "up".

3. Note for the implementer (not above the bar)

  • Ticket identity across messages. Topics can be added to an open socket via further tickets. The socket should bind to the first ticket's user and reject any later ticket for a different user. The spec says each ticket "names the caller" but not that the socket enforces one caller.
  • Three pollers. followSession's lapsed-pace poll, the timer inside client.subscribe, and coalescedReads all schedule reads. The spec says useSubscription reads through coalescedReads. Make sure the timer lives in exactly one place and followSession doesn't gain a second path (ER-5's "one obvious way").
  • Replay window. The 30 s ticket is not single-use. Because it travels in the first frame and not the URL, the risk is low. Still, the ticket should carry an expiry the socket checks at the time the frame arrives, not at mint.

Refactor opportunities (only where this PR makes them natural)

  • Removing client.stream() / openUserStream / UserSSECallbacks while client.subscribe takes over the same route is the right time to drop the 501 branch (http-handlers.ts user_stream) and { userStream: false } in the same change, not later. The spec already says so. I confirmed the only callers are the client's own tests and docs (client.ts, stream-client/streams.ts, types/index.ts, index.ts).
  • Placing the socket session in the engine, with serve() only moving frames, is the right seam. Keep it transport-neutral so FIX-380's Ably token can share the mint without importing anything WebSocket-specific.
  • No wider refactor is warranted. improve-codebase-architecture finds nothing else this PR should absorb.

Generated by Claude Code

@jhoffner

jhoffner commented Nov 1, 2026

Copy link
Copy Markdown
Collaborator Author

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.

  1. Two hooks for one scope (epic ER-5, "not done if"). The headline example puts useSubscription([topic.session(id)]) on a session that useSession({ live }) already follows, and BoardList's liveBoardDriver (panels/reads.ts) already re-reads boards from the session stream. Please say that useSession({ live }) stays the one way to follow a session's own items, that a session topic on useSubscription is for reads beyond them (flow reads), and that FIX-2429 moves liveBoardDriver onto client.subscribe so only one board trigger is left. Switch the example to a flow read.
  2. A refused topic should look like an unknown one. A session topic the caller can't read should get the same answer as a session that doesn't exist (hiddenSessionResponse, the same rule as fix(core): resourceTools reads only llmReadable collections, without secret fields (FIX-2436) #4426), so the mint doesn't tell anyone which ids exist. Add the new POST to the user-route scoping table.
  3. Changesets. The engine changes too (new route, capabilities shape, the 501 goes), and @flow-state-dev/contracts still exports UserStreamEvent / StreamEvent. Either name those as removed with a contracts changeset, or say they stay. Put a migration line in the client changeset: "fsd.stream() never worked (501); use fsd.subscribe()".
  4. If pushSecret stays, take the same string | (() => string) shape the webhook verifiers use, and log when a ticket fails its signature check instead of quietly falling back to the timer.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants