Skip to content

spec(FIX-380): Ably adapter: bus and delivery through Ably, so serverless hosts get push - #4486

Open
jhoffner wants to merge 1 commit into
mainfrom
spec/FIX-380
Open

jhoffner wants to merge 1 commit into
mainfrom
spec/FIX-380

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 1, 2026

Copy link
Copy Markdown
Collaborator
Someone who… Today After
deploys a screen to Vercel or Next The hook reads on a timer. A function cannot keep a socket open The app adds an Ably key and two lines. The same hook gets a change in less than one second
runs many serverless instances Other viewers see a change only at their next poll Ably sends the change to them from each instance
asks for a topic that they cannot read The mint refuses it The mint refuses it, and Ably refuses each channel that is not in the token
loses access while the tab stays open The socket stops in one hour or less The Ably token stops in one hour or less. This is the same limit (D1)
makes an app without Ably n/a The app gets no Ably code (D2)

Goal: on a serverless host with Ably, a screen that uses the framework hook gets a change from a different instance in less than one second. A caller gets an Ably credential only for the topics that the mint granted. An app without Ably gets none of this code.

flowchart LR
  A["two separate server processes · Ably bus and delivery · fetch handler, no serve · polling off"] --> L1["leg a · tab 2 watches session S through process 2, process 1 writes a reply in S"]
  A --> L2["leg b · user C asks for S, then attaches S's channel by name with a token for S2"]
  A --> L3["leg c · tab 2 publishes on its own channel"]
  L1 --> T["what each client's read returns, and what Ably answers"]
  L2 --> T
  L3 --> T
  T -->|"a within 1 s · b and c refused by Ably"| P["PASS · goal met"]
  C1["control · memory-bus"] -.-> L1
  C2["control · wide-token"] -.-> L2
  L1 -.->|"under memory-bus"| F["must FAIL"]
  L2 -.->|"under wide-token"| F
Loading

The check reads the result of each client read and the answer from Ably. It does not read calls to publish. Check: goals/realtime/ably/, real Ably. The controls GOAL_CONTROL=memory-bus and GOAL_CONTROL=wide-token must fail.

A new package fills both seams: createAbly backs the bus slot and is the push delivery, so the mint signs an Ably token; in the browser, ablyPush is handed to createClient. The mint check, client.subscribe and useSubscription stay as FIX-2428 builds them

One package and two options. The hook that a screen uses does not change.

How: the Ably bus sends each notice to Ably over REST. The mint from FIX-2428 checks each topic as before. Then it signs an Ably token that can only subscribe, and only to the granted channels.

Sign off

The goal: push on serverless through Ably, a credential only for granted topics, and no code for apps without Ably. If wrong: Vercel apps poll and pay an Ably bill.

The debt: up, by one vendor package and two options (push on createFlowState and on createClient). It removes no code. If wrong: a package that nobody installs.

An Ably token lives one hour or less; a reconnect in that hour gets no new check · D1

D1: chosen, the token's hour is the bound, beside a fresh mint on every reconnect. Decides it: who sees the reconnect. Price: a revoked user hears that something changed, never what, for up to an hour

The deciding row is who sees the reconnect. Ably sees it, not our server, so a new mint in the browser does not make it safe. This is the one to weigh: it applies epic rule ER-4 to a service that our server cannot see. If wrong: a revoked user knows that something changed, but not what, for one hour or less.

The Ably package holds the browser half; the app gives it to its client · D2

D2: chosen, the app hands ablyPush() to its client, beside the client loading Ably when told to. Decides it: an app without Ably. Price: one more line in client setup

The deciding row is an app without Ably: each bundler must resolve an optional import. If wrong: one setup line that nobody needed.

A topic sends one Ably message at once, then one each 500 ms or less · D3

D3: chosen, one message at once then one per 500 ms, beside one message per notice. Decides it: the bill in a streaming reply. Price: a later change in a burst comes up to 500 ms later

The deciding row is the bill during a streaming reply: one message for each write, multiplied by each viewer. If wrong: a change comes half a second later, to save money that nobody was concerned about.

Open: none. D1 is the one to weigh. Reasons and alternatives: DECISIONS.md.

Analysis: right approach. The author did it in this dispatch, not a fresh agent. It changed nothing. DECISIONS.md → Analysis.

Reviewers · look here

  • Decisions → D1. Is one hour the correct limit, when Ably and not our server accepts a reconnect?
  • Decisions → Decided, not asked. push is on createFlowState, not on each host handler, and it replaces the WebSocket of serve(). Is this the correct place for the delivery seam?
  • Spec → the goal check. It uses real Ably (the sandbox or a key). Can our CI do this, or only the implementer at completion?

Not here: items, presence, barge-in or mobile push over Ably (the old spike). The epic removed them.

Spec · Decisions · Linear FIX-380 · epic FIX-2367 · builds on FIX-2426 (the bus) and FIX-2428 (the mint) · 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

Adapter of the epic's two seams: the Ably bus fills FIX-2426's bus slot
over REST, and the FIX-2428 mint signs a subscribe-only Ably token for
the granted topics. The browser half ships in @flow-state-dev/ably/client
behind a push slot on createClient.

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 9:24pm UTC
3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Nov 1, 2026 9:24pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Nov 1, 2026 9:24pm UTC
flow-state-dev-ui Ignored Ignored Preview Nov 1, 2026 9:24pm UTC

Request Review

@linear-code

linear-code Bot commented Nov 1, 2026

Copy link
Copy Markdown

FIX-380

@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-01T21:22:45.710176Z 7078971 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.

jhoffner commented Nov 1, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (direction-level only)

Read SPEC/DECISIONS against the FIX-2426 and FIX-2428 specs on main. The overall shape (Ably as one adapter of the bus slot plus one delivery behind the mint, browser half behind a client slot) is sound and I'd keep it. Four findings that change the approach or a contract; the rest I'd leave to the implementer.

1. D3's fold has no plumbing, and duplicates FIX-2426's (above the line)

  • D3 says the pending trailing message "is handed to onBackgroundWork". But createAbly() is built outside createFlowState, and FIX-2426's bus contract (publish, subscribe, crossesProcesses, onCrossingChange) gives the adapter no access to it. As written the serverless guarantee ("the last change of a burst is heard") has no path to the one hook that provides it.
  • FIX-2426 already folds on the read side (stream wakes at most once per intervalMs) and explicitly lets "a publisher fold one topic's notices". D3 adds a second, Ably-only publish-side window. Any cross-process bus (Postgres NOTIFY, Redis) has the same per-write cost shape.
  • Suggest: put the leading+trailing fold in the shared bus wrapper FIX-2426 already adds (one implementation, adapter-agnostic), and give the wrapper a flush/background-work hook that createFlowState wires to onBackgroundWork. Then D3 reduces to "the window is N ms for Ably" instead of a new mechanism in a vendor package. If that widens FIX-2426 too much, at least state in this spec how the adapter receives onBackgroundWork; it is a contract change either way.

2. Opaque channel hash key is unspecified (above the line)

"A keyed hash of the bus topic" must produce the same name on every process (publisher on process 1, mint on process 2). The spec doesn't say what the key is. FIX-2428 already hit this class of problem with pushSecret (a per-process default breaks multi-process). Suggest deriving it from the Ably API key (e.g. HKDF with a fixed label), so there is no new secret to configure and every process agrees by construction. Worth a line in "Decided, not asked".

3. Two options that must be set together (restraint / footgun)

stores.default.bus: ably and push: ably are separate, and each alone is a silent half-config: push without bus mints valid tokens but nothing is ever published; bus without push publishes into the void and the client sees push: null. Epic D5's "two places" is satisfied by one object passed twice, but nothing checks it. Suggest createFlowState fail loudly (or warn once) when push declares it needs a bus and the bus slot isn't the same adapter. Cheap, and it makes the goal check's "polling off" leg less likely to pass for the wrong reason.

4. Goal check vs CI (answers the reviewer question)

Real-Ably two-process runs are fine as an implementer-at-completion check, but most of leg b/c's assertion is checkable hermetically: the signed token request's capability JSON is a pure function of the granted topics (subscribe-only, exactly those channels, ttl ≤ 1h). Suggest a unit test that decodes it, so the security-relevant property (D1/ER-4) is guarded in CI and the live run only proves Ably honours it. Also keep the wide-token control wired to that same builder so the two can't drift.

Architecture notes (not asks)

  • Fits the packages: ably as its own vendor package (like bullmq/store-postgres), engine gains only the delivery seam, client gains only a slot. No engine → client dependency introduced. Good.
  • D2 (slot over optional import) is the right call; I'd keep it.
  • D1: agree this is the honest reading of ER-4 for a service the server can't see. One small addition worth stating: Ably's authorize() widening on added topics means the held token's channel set only ever grows within the hour; say so in the realtime guide so nobody expects narrowing on revoke.
  • Refactor opportunity tied to this PR: the delivery seam should be defined as a general "push delivery" interface in engine (mint → credential) with serve()'s WebSocket ticket signer as the first implementation, rather than Ably replacing it by an if (push) branch. That keeps FIX-2428's code path the default and Ably a peer, and is the natural moment to do it since both specs touch the same mint.

No concerns with the debt table or the "Not here" list.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7078971a52

ℹ️ 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".

Comment on lines +90 to +92
channel. The message carries `kind` and `origin` only, never the bus topic.
- **A narrowed notice publishes on its resource's channel and its scope's**, so both hear it, by
FIX-2426's hearing rule. Two messages, before D3's fold.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Preserve resource identity in scope-channel notices

When a resource-narrowed notice is also published to its scope's channel, a subscriber listening only to that scope receives neither the resource identifier nor any way to recover it: the channel identifies the broad scope, and the payload contains only kind and origin. This makes the adapter unable to satisfy specs/issues/FIX-2426/DECISIONS.md:52–54, which requires broad subscribers to receive the original narrowed topic on both the bus and the wire. Preserve a safe resource or wire-topic discriminator in the message without exposing tenant, user, or organization IDs.

Useful? React with 👍 / 👎.

@jhoffner

jhoffner commented Nov 1, 2026

Copy link
Copy Markdown
Collaborator Author

Architect read on #4486 (FIX-380, the Ably adapter), checked at 7078971 against main after #4477 (epic FIX-2367, FIX-2426, FIX-2428).

The direction is right. Ably fills both seams, the mint stays the one place access is decided, and the bus side mostly follows FIX-2426. Three places change merged contracts without editing them. This PR only touches specs/issues/FIX-380/, so those edits should go in here.

  1. The seam: two public ways to configure push (ER-5). FIX-2428 configures push on the host: serve() has push on by default, push: false turns it off, and pushSecret sets the secret (FIX-2428/DECISIONS.md:69-70,88, SPEC.md:85-88,129). This PR adds createFlowState({ push }), and "an explicit push replaces serve()'s WebSocket" (FIX-380/DECISIONS.md:77-80). That gives two options for one thing, plus a precedence rule between them. It also goes against epic D5, "delivery at the host… only the host knows it can hold a socket" (epics/FIX-2367/DECISIONS.md:100-106), and FIX-2428's "createServerApp alone reports push: null" (FIX-2428/DECISIONS.md:70, SPEC.md:118). Lean: make createFlowState({ push }) the only place to configure push. The WebSocket becomes its default delivery, with push: false and the secret on it, and serve() only takes the upgrade when that delivery is the WebSocket. Amend epic D5 and FIX-2428 to match in this PR. This moves a signed-off epic decision, so it's Jake's call, not decided-not-asked.

  2. The seam: the mint's answer shape. FIX-2428 D1 fixes "the public route POST /users/:userId/stream and its answer shape, which FIX-380 shares" (FIX-2428/DECISIONS.md:29). Here the mint returns an Ably token request plus a channel for each wire topic (FIX-380/DECISIONS.md:88-90, SPEC.md:123), which is a different shape. Write the shared answer once in FIX-2428 as a union keyed by transport, e.g. { transport: "websocket", ticket, path } | { transport: "ably", tokenRequest, channels }. Also say that a refused topic is simply missing from both, with the same answer a missing session gets (hiddenSessionResponse, FIX-2428/DECISIONS.md:79-81). The capabilities.push union also gains { transport: "ably" } (FIX-2428/DECISIONS.md:84-87).

  3. The seam: push: ably with a bus that isn't Ably. The same object goes in twice (SPEC.md:68-77). If bus is Postgres or memory and push is Ably, nothing ever publishes to the channels. Browsers would connect and never hear a change, and the timer would stay off because the socket counts as up (FIX-2428 D3). Fail at ready(), as FIX-2426 does for an undeclared bus slot (FIX-2426/DECISIONS.md:82). The "dropped" row at DECISIONS.md:115 needs to say what happens in that case, not only that it's out of scope.

  4. D1 (token hour, no recheck on reconnect): Jake's call. My lean is to accept it, with the epic amended. The bound matches FIX-2428 D2: at most one hour. The typical window is wider. On the WebSocket, every reconnect mints again (FIX-2428/DECISIONS.md:28), so a revoked user whose socket drops at minute 5 is refused at minute 5. On Ably, they keep hearing until the token expires. Either way they learn that something changed and never what, so it's a timing leak, not a data leak. But it doesn't meet ER-4 as written: "on every connect and reconnect, not only the first" (epics/FIX-2367/DECISIONS.md:144). It also fails the epic's "Not done if … a reconnect to a scope the caller can't read succeeds" (epics/FIX-2367/SPEC.md:33), and the closure's leg c would fail on an Ably host. This PR re-reads ER-4 as "at least once an hour" (FIX-380/DECISIONS.md:30, SPEC.md:126), but that wording only lands in the realtime guide. Amend ER-4 and the epic's Not-done line in this PR. Also consider a TTL shorter than an hour: renewal is just a mint through authCallback, so 15 minutes costs about four requests per client per hour and cuts the window by four. The goal check also has no revocation leg, unlike FIX-2428's leg b (FIX-2428/SPEC.md:56). Add one: revoke the user, wait for renewal, check that Ably refuses.

  5. The bus side, narrowed topics. This forks with FIX-1506 (spec(FIX-1506): resource and scope-state changes reach other sessions #4478). FIX-2426 says a subscriber to a scope's un-narrowed topic receives the narrowed topic, and that the same rule holds on the bus and the wire (FIX-2426/DECISIONS.md:52-54). spec(FIX-1506): resource and scope-state changes reach other sessions #4478's hooks filter on it. Here the message carries kind and origin only (FIX-380/DECISIONS.md:90-92), so a scope-channel listener can't tell which resource changed. That's true for browsers and for the process-side ChangeNotice.topic alike. Carry the wire topic's resource in the message. It's a name, not an id, so it fits the rule that channels name no ids.

  6. D3 (folding to one message per 500 ms): Jake's call. My lean is to accept it, with two edits. (a) FIX-2426 allows a publisher to fold "within a tick" (FIX-2426/DECISIONS.md:69-71). 500 ms is wider, so amend that line to let an adapter fold within a window it states. (b) When the folded notices have different origins, the folded message must carry no origin. Otherwise spec(FIX-1506): resource and scope-state changes reach other sessions #4478's writer skip (its D2) misses the second writer, which is the exact case that D2 guards against.

  7. Smaller points. (a) The keyed hash for channel names needs one key shared by every process (the same problem as pushSecret). Say it's derived from the Ably key's secret. (b) Say that an Ably reconnect makes subscribers read once (FIX-2426/DECISIONS.md:81). Right now the PR only routes it through onCrossingChange (FIX-380/DECISIONS.md:95-99). (c) SPEC.md:85 shows useSubscription([topic.session(sessionId)], refresh, …) without saying what refresh is. Keep FIX-2428's note that it's a flow read (FIX-2428/SPEC.md:68-69), so the line doesn't read as a second way to follow a session (FIX-2428/DECISIONS.md:82-83). For the record, main's FIX-2428/SPEC.md:74 already agrees with DECISIONS.md:83. The flagged leftover is closed.

Other forks: none with #4476 (FIX-2427). Both are adapters of the same slot that report crossesProcesses through onCrossingChange, and the Postgres default steps aside when bus: ably is named. The fork with #4478 is items 5 and 6b. D2 (ablyPush handed to createClient): Jake's call. I lean toward accepting it; it's a connector slot, not a second way to subscribe.

— FSD Architect

jhoffner pushed a commit that referenced this pull request Nov 2, 2026
- Epic FIX-2367: memory-bus control fails leg a's 1 s, not "B never
  updates" (FIX-2428 D3 keeps the poll); amendment logged.
- Closure grades memory-bus on the 1 s consistently; j4 waits on epic
  D5 and FIX-380's spec (#4486).
- a:same-source moved to anti-game; goals/lib reuse row widened; j3 on
  row 1's processes, j4 on FIX-380's wiring. Other Cursor notes recorded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn
jhoffner pushed a commit that referenced this pull request Nov 2, 2026
Owner decision on #4512: the closure proves the Postgres bus and the
polling fallback. j4 is the Next host's polling fallback only; D3 is
decided (no Ably), its figure dropped, and the wait on epic D5 and
#4486 removed.

Epic FIX-2367: FIX-380 (Ably) is a future transport behind the bus
seam and gates nothing; serverless polls today, in this epic, with a
native Vercel WebSocket transport named as a later adapter. Seams keep
their Ably fit. Amendment logged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn

This branch has not been deployed

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants