From 844a4f90636d667abe82606ff7cfc5b7212cfa8a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 02:30:41 +0000 Subject: [PATCH 1/8] feat(FIX-2428): WebSocket delivery: client.subscribe, useSubscription, the push mint A screen on the Node host hears a change within a second over one WebSocket per client, and reads on a timer wherever push can miss a change. - engine: POST /users/:userId/stream mints a 30 s ticket after running each topic through its scope's read check on the real request (BP-031); a refused topic is absent, as a missing session is. The socket session accepts topics only from tickets, sends crossing frames, closes after an hour. capabilities reports push; GET answers 426 instead of 501. - node: serve() takes the upgrade (ws), push and pushSecret options. - client: client.subscribe with one shared socket, onChange(notice | null), pollIntervalMs fallback; client.stream() and the user-stream types removed. - react: useSubscription over coalescedReads. - contracts/core: push wire types; user-stream event types removed. - goal: goals/realtime/websocket-delivery (PASS; three controls FAIL). - docs: realtime guide, client/react/server pages, READMEs, mechanisms row. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn --- .changeset/websocket-push.md | 16 + apps/docs/docs/api/client.md | 49 +- apps/docs/docs/api/react.md | 17 + apps/docs/docs/client/overview.md | 18 +- apps/docs/docs/client/react.md | 20 + apps/docs/docs/server/setup.md | 4 +- apps/docs/guides/realtime.md | 119 +++++ apps/docs/sidebarsGuides.ts | 1 + docs/architecture/authentication.md | 2 +- docs/architecture/server-and-client.md | 4 +- docs/mechanisms/mechanisms.yaml | 12 + goals/realtime/websocket-delivery/goal.md | 30 ++ goals/realtime/websocket-delivery/run.mts | 420 +++++++++++++++ packages/client/README.md | 31 +- packages/client/src/client.ts | 39 +- packages/client/src/index.ts | 10 +- packages/client/src/stream-client/streams.ts | 108 +--- packages/client/src/subscribe/push-hub.ts | 458 +++++++++++++++++ packages/client/src/types/index.ts | 38 +- packages/client/test/one-transport.test.ts | 11 +- packages/client/test/stream-client.test.ts | 79 +-- packages/client/test/subscribe.test.ts | 394 ++++++++++++++ packages/contracts/src/index.ts | 12 + packages/contracts/src/items/events.ts | 84 +-- packages/contracts/src/items/index.ts | 11 +- packages/contracts/src/types/push-delivery.ts | 93 ++++ packages/core/src/index.ts | 11 + packages/engine/README.md | 13 + packages/engine/src/index.ts | 5 + packages/engine/src/push/push-delivery.ts | 158 ++++++ packages/engine/src/push/socket-session.ts | 188 +++++++ packages/engine/src/push/ticket.ts | 85 +++ .../engine/src/routes/createFlowApiRouter.ts | 4 + packages/engine/src/routes/http-handlers.ts | 29 +- packages/engine/src/routes/parseFlowRoute.ts | 1 + packages/engine/src/routes/route-auth.ts | 3 + packages/engine/src/routes/router.ts | 6 + packages/engine/src/streaming/encode-event.ts | 6 +- packages/engine/test/push-delivery.test.ts | 483 ++++++++++++++++++ packages/engine/test/registry-routes.test.ts | 7 +- .../engine/test/user-route-scoping.test.ts | 91 +++- packages/node/README.md | 23 + packages/node/package.json | 4 +- packages/node/src/serve.ts | 136 ++++- packages/node/test/serve-push.test.ts | 211 ++++++++ packages/react/README.md | 18 + packages/react/src/hooks/useSubscription.ts | 83 +++ packages/react/src/index.ts | 2 + packages/react/test/support/fake-client.ts | 3 +- packages/react/test/useSubscription.test.ts | 176 +++++++ pnpm-lock.yaml | 22 +- 51 files changed, 3469 insertions(+), 379 deletions(-) create mode 100644 .changeset/websocket-push.md create mode 100644 apps/docs/guides/realtime.md create mode 100644 goals/realtime/websocket-delivery/goal.md create mode 100644 goals/realtime/websocket-delivery/run.mts create mode 100644 packages/client/src/subscribe/push-hub.ts create mode 100644 packages/client/test/subscribe.test.ts create mode 100644 packages/contracts/src/types/push-delivery.ts create mode 100644 packages/engine/src/push/push-delivery.ts create mode 100644 packages/engine/src/push/socket-session.ts create mode 100644 packages/engine/src/push/ticket.ts create mode 100644 packages/engine/test/push-delivery.test.ts create mode 100644 packages/node/test/serve-push.test.ts create mode 100644 packages/react/src/hooks/useSubscription.ts create mode 100644 packages/react/test/useSubscription.test.ts diff --git a/.changeset/websocket-push.md b/.changeset/websocket-push.md new file mode 100644 index 0000000000..ad27e456ac --- /dev/null +++ b/.changeset/websocket-push.md @@ -0,0 +1,16 @@ +--- +"@flow-state-dev/client": minor +"@flow-state-dev/react": minor +"@flow-state-dev/node": minor +"@flow-state-dev/engine": minor +"@flow-state-dev/contracts": minor +"@flow-state-dev/core": minor +--- + +Screens can read again when something they show changes, without polling on the Node host (FIX-2428). + +- **client:** `fsd.subscribe(topics, { onChange, pollIntervalMs? })` calls `onChange` with the notice that woke it (`{ topic, kind, origin? }`), or `null` for a connect, a reconnect or a timer tick. Build topics with `topic.session(id)`, `topic.user()` and `topic.org()`, now exported from the client too. On a host with push, one WebSocket per client carries the notices, signed in through the client's fetcher; elsewhere `onChange(null)` runs every `pollIntervalMs`. `FlowCapabilities` gains `push`. **Breaking:** `fsd.stream()` never worked (the server answered 501); use `fsd.subscribe()`. `UserStreamOptions`, `UserSSECallbacks` and `UserStreamHandle` are removed with it. +- **react:** `useSubscription(topics, read, { pollIntervalMs?, enabled? })` runs a screen's read again on a change, one read in flight and one waiting. +- **node:** `serve()` serves the change-notice WebSocket at `/users/:userId/stream`. New options: `push` (default `true`) and `pushSecret` (default `FSD_PUSH_SECRET`, then a random key), which every process behind one address must share. +- **engine:** `GET /capabilities` answers `{ userStream: false, push }`. `POST /users/:userId/stream` checks each topic with its scope's read check and answers a short ticket for the granted ones; a refused topic is left out, as a missing session is. `GET /users/:userId/stream` answers 426 instead of 501. `enablePushDelivery(router, { secret? })` turns push on for a host that serves the socket. +- **contracts / core:** the push wire types (`PushCapability`, `PushMintAnswer`, `PushServerFrame`, `PushClientFrame`, `WireNotice`). **Breaking:** the user-stream event types `UserStreamEvent`, `UserEventBase`, `UserResourceChangedEvent`, `ResourceContentUpdatedEvent`, `ResourceContentCreatedEvent`, `ResourceContentDeletedEvent`, `ScopeStateChangedEvent`, `UserDebugEvent` and `UserPingEvent` are removed; `StreamEvent` is `RequestStreamEvent`. diff --git a/apps/docs/docs/api/client.md b/apps/docs/docs/api/client.md index 067b47a885..ea837431f2 100644 --- a/apps/docs/docs/api/client.md +++ b/apps/docs/docs/api/client.md @@ -38,8 +38,8 @@ It returns a `Client`: | `resources` | Resource content and collections. See [`fsd.resources`](#fsdresources). | | `requests.interrupted(options?)` | The user's crash-interrupted requests. See [`fsd.requests.interrupted`](#fsdrequestsinterruptedoptions). | | `flows()` | The flows the server hosts, as `FlowListEntry[]`. | -| `capabilities()` | What the server supports, as `FlowCapabilities`. | -| `stream(options)` | Follow the user stream: resource and scope-state changes for this user. See [`fsd.stream`](#fsdstreamoptions). | +| `capabilities()` | What the server supports, as `FlowCapabilities`: `{ userStream, push }`, with `push` `{ transport: "websocket" }` on a host that serves push and `null` elsewhere. | +| `subscribe(topics, options)` | Run a read again when something under `topics` changes. See [`fsd.subscribe`](#fsdsubscribetopics-options). | | `transcribe({ audio, mediaType?, language? })` | Transcribe audio on the server. Resolves to `{ text, language? }`. `mediaType` defaults to `"audio/webm"`. | A different user or a different server is a different client. @@ -456,9 +456,50 @@ async function readHistory() { } ``` -### `fsd.stream(options)` +### `fsd.subscribe(topics, options)` -Follows the user stream: resource changes and scope-state changes for the client's user, across sessions. Callbacks are `onResourceChanged`, `onResourceContentUpdated`, `onResourceContentCreated`, `onResourceContentDeleted`, `onScopeStateChanged`, `onDebug`, `onEvent` and `onError`. It takes the same `startingAfter`, `lastEventId` and `dedupWindowSize` as a request stream. +Calls `onChange` when something under one of `topics` may have changed, so you can read it again. The call tells you when to read, never what changed: `onChange` makes the read your screen already makes, and that read is checked on the server as always. + +```ts +import { createClient, topic } from "@flow-state-dev/client"; + +const fsd = createClient({ userId, baseUrl: "" }); + +const sub = fsd.subscribe([topic.session(sessionId), topic.org()], { + onChange: (notice) => void reload(), + pollIntervalMs: 3000, +}); + +// later +sub.close(); +``` + +| Option | Type | Notes | +|--------|------|-------| +| `onChange` | `(notice: WireNotice \| null) => void` | Required. Gets the notice that woke it, `{ topic, kind, origin? }`, or `null` for a connect, a reconnect, a timer tick, or a change in whether push reaches every server process. | +| `pollIntervalMs` | `number` | Call `onChange(null)` at this pace wherever push can miss a change: the server has no push, the socket is down, or the server process the socket reached can't hear the others. Omitted, there is no timer. | + +It returns `{ close() }`. + +The topics come from `topic`, which `@flow-state-dev/client` and `@flow-state-dev/core` both export: + +| Topic | Covers | +|-------|--------| +| `topic.session(id)` | One session. | +| `topic.user()` | The caller's own user scope. | +| `topic.org()` | The caller's organization. | + +Each takes an optional `{ resource }` to watch one resource under the scope. A topic without one also hears changes narrowed to a resource under it. User and org topics name no id: the server fills them in from the signed-in caller, so a client can't ask for someone else's. + +A notice's `kind` is `"items"`, `"request"`, `"run"` or `"resync"`; `origin.requestId` names the request that made the change, when a request did. + +**On a host with push** (`serve()` from `@flow-state-dev/node`, `fsdev dev` and `fsdev serve`), the client opens one WebSocket, shared by every `subscribe` call on that client. It asks the server for each topic first, through the client's own `fetcher`, so a bearer token your fetcher adds is what proves who the socket is. A topic the caller may not read is left out, the same way a session that doesn't exist is: `onChange` never hears about it, and with `pollIntervalMs` the client asks for it again at each tick, so access given back recovers without a remount. Each connect and reconnect calls `onChange(null)` once. The server closes a socket after an hour and the client reconnects, which checks every topic again. + +**On a host with no push** (Vercel, Next.js, `createServerApp` alone), `onChange(null)` runs on the `pollIntervalMs` timer and nothing else. The same code works on both. + +**On several processes**, push reaches a socket only if the server's change bus carries changes between processes. The default in-memory bus doesn't, even with one process, so a subscription with `pollIntervalMs` keeps reading on its timer between notices there. Give every process behind one address the same `pushSecret` (see [server setup](/docs/server/setup)). + +See the [realtime guide](/guides/realtime) for the whole picture. ### `createSSEClientFromResponse(options)` diff --git a/apps/docs/docs/api/react.md b/apps/docs/docs/api/react.md index 01a60d8ac5..0c6defbd06 100644 --- a/apps/docs/docs/api/react.md +++ b/apps/docs/docs/api/react.md @@ -159,6 +159,23 @@ const { items, status, isStreaming } = useRequestStream({ Use `source: { response }` to consume a pre-fetched POST stream (inline streaming) instead of opening a separate GET-by-id connection. +### `useSubscription(topics, read, options?)` + +Runs `read` again when something under `topics` changes, through the provider's client and [`fsd.subscribe`](/docs/api/client#fsdsubscribetopics-options). + +```ts +useSubscription([topic.session(sessionId)], refresh, { pollIntervalMs: 3000 }); +``` + +| Argument | Type | Notes | +|----------|------|-------| +| `topics` | `WireTopic[]` | From `topic.session(id)`, `topic.user()`, `topic.org()`. A new array with the same topics keeps the subscription. | +| `read` | `(notice: WireNotice \| null) => unknown` | The screen's read. One runs at a time, and at most one more waits. Gets the notice that woke it, or `null` for a connect, a reconnect, a timer tick, or a wait that stands for several different notices. | +| `options.pollIntervalMs` | `number` | Read at this pace wherever push can miss a change. Omitted, no timer. | +| `options.enabled` | `boolean` | `false` subscribes nothing. Default `true`. | + +Returns nothing. It doesn't read on mount. + ### `useVoice(session, options)` Voice input/output composing with `useSession`. diff --git a/apps/docs/docs/client/overview.md b/apps/docs/docs/client/overview.md index c69f90b288..dca8e06639 100644 --- a/apps/docs/docs/client/overview.md +++ b/apps/docs/docs/client/overview.md @@ -303,6 +303,21 @@ const note = await fsd.resources.getCollectionItemState(sessionId, "notes", "lau See [Client access](/docs/resources/client-access) for what a flow lets a client see and write, [Resource Collections](/docs/resources/collections#lazy-state-by-default) and [Resource Manifest](/docs/resources/manifest) for the model, and [React](/docs/client/react#resource-collection-hooks) for the hooks. +## Hearing changes others make + +A screen that shows something other people or agents change, such as a flow read of a session or the user's own data, can ask to hear when it changes and read it again: + +```ts +import { topic } from "@flow-state-dev/client"; + +const sub = fsd.subscribe([topic.session(sessionId)], { + onChange: () => void refresh(), // the read the screen already makes + pollIntervalMs: 3000, +}); +``` + +`onChange` is told when to read, never what changed. On the Node host it runs within a second of a change, over a WebSocket. On a host with no push, such as Vercel, it runs every `pollIntervalMs`. The code is the same on both. To follow a session's own items, use `fsd.sessions.stream` (or `useSession({ live: true })`) instead. See [`fsd.subscribe`](/docs/api/client#fsdsubscribetopics-options) and the [realtime guide](/guides/realtime). + ## Transcription For voice flows, `fsd.transcribe` sends audio to the server and returns the text: @@ -317,7 +332,8 @@ await fsd.flow("voice-chat").send("reply", { text }, { sessionId }); - **Resume from a cursor.** Pass `startingAfter` (or `lastEventId`) to a request stream; the server replays what you missed and continues. - **Duplicate events.** A sliding window (`dedupWindowSize`, default 1000) drops events it has already delivered. - **Session streams reconnect.** `fsd.sessions.stream` retries with backoff on its own. A request stream doesn't; reopen it with `startingAfter`. -- **One transport.** Every call and stream goes through the client's `fetcher`, so credentials and in-process dispatch apply everywhere. +- **One transport.** Every call and stream goes through the client's `fetcher`, so credentials and in-process dispatch apply everywhere, including the request that opens `subscribe`'s socket. +- **One socket.** Every `subscribe` call on a client shares one WebSocket, which reconnects on its own and reads on its timer while it's down. ## Requirements diff --git a/apps/docs/docs/client/react.md b/apps/docs/docs/client/react.md index a834ba131d..25ff2eb7dd 100644 --- a/apps/docs/docs/client/react.md +++ b/apps/docs/docs/client/react.md @@ -147,6 +147,26 @@ A live view holds a connection open while it is mounted, and the server reads th Once the stream is open, a drop the first reconnect recovers from, such as the server's routine close, shows no change. If that reconnect fails, `session.childSessionsStale` turns `true`, and `session.items` stays as it is, with no error, missing what others write. A connection that gets through clears the flag and fills in what was missed. A reconnect is refused when the session is deleted while the view is open, when the reader's access is revoked, or when a new session takes its id. The flag then stays `true` and the view stops hearing other writers. If a new session has taken the id and the reader can open it, the next snapshot the view reads, from `refresh()` for example, moves the view onto that session and clears the flag. Otherwise `refresh()` sets `error` and the flag stays. +### Reading again when something changes: `useSubscription` + +For a screen that shows a read other writers change, and that isn't a session's own items, hand the hook the topics it shows and the read it already makes: + +```tsx +import { useSubscription } from "@flow-state-dev/react"; +import { topic } from "@flow-state-dev/client"; + +const refresh = useCallback( + () => fsd.flow(flow).read("listTasks_tasks", {}, { sessionId }).then(setTasks), + [sessionId], +); + +useSubscription([topic.session(sessionId)], refresh, { pollIntervalMs: 3000 }); +``` + +The read runs within a second of a change on the Node host, and every `pollIntervalMs` on a host with no push. A burst of changes runs it once more after the read in flight finishes, not once per change. The read gets the notice that woke it (`{ topic, kind, origin? }`), or `null` for a connect, a reconnect or a timer tick; act on `kind` when the screen only cares about some changes, and read everything on `null`. Leave `pollIntervalMs` out for no timer. `enabled: false` subscribes nothing. + +The hook doesn't read on mount; keep the first read where the screen already makes it. It uses the provider's client, so the provider's `fetcher` signs the socket in. See [`fsd.subscribe`](/docs/api/client#fsdsubscribetopics-options) for which topics a caller hears. + ### Background work Some flows dispatch a long job to run on its own. The conversation returns straight away and the job carries on in a session of its own, called a *dispatch run*. `session.childSessions` is how you show those runs, one `ChildSessionSummary` per run. diff --git a/apps/docs/docs/server/setup.md b/apps/docs/docs/server/setup.md index 3609d29542..29494f137a 100644 --- a/apps/docs/docs/server/setup.md +++ b/apps/docs/docs/server/setup.md @@ -224,7 +224,9 @@ The same holds after a restart, whichever instances are registered afterwards an | Method | Path | Purpose | |--------|------|---------| | GET | `/api/flows` | List registered flows | -| GET | `/api/flows/capabilities` | Feature flags | +| GET | `/api/flows/capabilities` | What the server supports: `{ userStream, push }`, `push` `{ transport: "websocket" }` under `serve()`, else `null` | +| POST | `/api/flows/users/:userId/stream` | Checks each topic the caller asks to hear and answers a short ticket for the ones it may (push hosts only) | +| GET | `/api/flows/users/:userId/stream` | The change-notice WebSocket, as an upgrade (`serve()` only); a plain GET answers 426 | | POST | `/api/flows/:flowId/actions/:action` | Execute action (new session) | | POST | `/api/flows/:flowId/:sessionId/actions/:action` | Execute action (existing session) | | GET | `/api/flows/:flowId/requests/:requestId/stream` | SSE request stream | diff --git a/apps/docs/guides/realtime.md b/apps/docs/guides/realtime.md new file mode 100644 index 0000000000..58ac434313 --- /dev/null +++ b/apps/docs/guides/realtime.md @@ -0,0 +1,119 @@ +--- +sidebar_label: Realtime screens +--- + +# Keeping a screen current + +Some screens show data other people or agents change: a task board a team works, a list of runs, a project's files. Without help, the screen goes stale until it reads again. This guide shows how to have the screen read again when the data changes, with code that works the same on every host. + +The idea is small. The server tells your screen *when* something under a topic changed. Your screen then makes the read it already makes, which says *what*. Nothing about the data travels with the notice, and every read is checked on the server as usual. + +## The hook + +Hand `useSubscription` the topics your screen shows and the read it makes: + +```tsx +import { useCallback, useEffect, useState } from "react"; +import { useSubscription } from "@flow-state-dev/react"; +import { createClient, topic } from "@flow-state-dev/client"; + +const fsd = createClient({ userId, baseUrl: "" }); + +type Task = { id: string; title: string }; + +function TaskList({ sessionId }: { sessionId: string }) { + const [tasks, setTasks] = useState([]); + const refresh = useCallback( + () => fsd.flow("support").read("listTasks", {}, { sessionId }).then(setTasks), + [sessionId], + ); + + useEffect(() => void refresh(), [refresh]); // the first read + useSubscription([topic.session(sessionId)], refresh, { pollIntervalMs: 3000 }); + + return
    {tasks.map((task) =>
  • {task.title}
  • )}
; +} +``` + +On the Node host, `refresh` runs within about a second of someone else's change. A burst of changes runs it once more after the read in flight finishes, not once per change. The hook doesn't read on mount, so keep the first read where your screen already makes it. + +There are three topics: + +| Topic | What changes it covers | +|-------|------------------------| +| `topic.session(id)` | One session: its requests, their items, and runs started under it. | +| `topic.user()` | The signed-in user's own scope. | +| `topic.org()` | The signed-in user's organization. | + +Each takes `{ resource }` to narrow it to one resource, such as `topic.session(id, { resource: "tasks" })`. User and org topics name no id. The server uses the caller it signed in, so a screen can only hear its own user and organization. + +## Acting on what changed + +`refresh` gets the notice that woke it, `{ topic, kind, origin? }`, or `null` for a connect, a reconnect or a timer tick. A screen that only cares about some changes can skip the others: + +```ts +useSubscription([topic.session(sessionId)], (notice) => { + if (notice !== null && notice.kind === "items") return; // a reply streaming in + return refresh(); +}); +``` + +`kind` is `"items"`, `"request"`, `"run"` or `"resync"`. Read everything on `null`: it means the screen may have missed something. + +## Outside React + +`useSubscription` wraps `fsd.subscribe`, which you can call directly: + +```ts +const sub = fsd.subscribe([topic.session(sessionId), topic.org()], { + onChange: () => void reload(), + pollIntervalMs: 3000, +}); + +// when the view goes away +sub.close(); +``` + +Every `subscribe` call on one client shares one connection. + +## Which hosts push + +| Host | What happens | +|------|--------------| +| `serve()` from `@flow-state-dev/node`, including `fsdev dev` and `fsdev serve` | One WebSocket per client carries the notices. | +| Vercel, Next.js, `createServerApp` alone (Lambda, Bun, Deno) | No push. The read runs every `pollIntervalMs`. | + +You don't write different code for either. The client asks the server what it supports and picks. + +`pollIntervalMs` is also the fallback on a push host. The read runs on that timer while the socket is down, and while the server process the socket reached can't hear changes made in other processes. Leave it out and there is no timer at all: the read runs on a notice, a connect and a reconnect only. + +## One process, several processes + +Whether a notice reaches every server process depends on the change bus in your stores profile. The default bus lives in memory and reaches only its own process. On it, a subscription with `pollIntervalMs` keeps reading on its timer between notices, even when you run a single process. A bus that carries changes between processes turns that timer off while the socket is up. + +When several processes serve one address, give them all the same signing key, so a connection that lands on any of them is accepted: + +```ts +await serve(flowstate, { + host, + pushSecret: process.env.FSD_PUSH_SECRET, +}); +``` + +`serve()` reads `FSD_PUSH_SECRET` itself when you don't pass `pushSecret`. Without a shared key, a connection that lands on another process is refused, and the screen reads on its timer until a retry lands. `push: false` turns push off for a `serve()` host. + +## Who hears what + +Each topic is checked on the server when the connection opens, with the same check the matching read uses. The client asks through its own `fetcher`, so a bearer token your fetcher adds signs the connection in, and so does a cookie. A topic the caller may not read is left out, exactly as a session that doesn't exist is, and the screen never hears of it. With `pollIntervalMs`, the client asks for it again at each tick, so access given back starts working without a reload. + +An open connection is not checked again. If someone loses access while their tab stays open, their reads are refused at once, and the connection can still say that something changed, never what, until it reconnects. The server closes every connection after an hour, and the reconnect checks again. + +## Following a session's own items + +To show the messages and items of a session as they land, use `useSession(sessionId, { live: true })` or `fsd.sessions.stream`, not a subscription. Those send the items themselves. A session topic on `useSubscription` is for other reads of the session, such as a flow read. + +## See also + +- [`fsd.subscribe`](/docs/api/client#fsdsubscribetopics-options) in the client API +- [`useSubscription`](/docs/api/react#usesubscriptiontopics-read-options) in the React API +- [Host adapters](/docs/server/host-adapters) diff --git a/apps/docs/sidebarsGuides.ts b/apps/docs/sidebarsGuides.ts index 7ff8efb8bd..60501240f1 100644 --- a/apps/docs/sidebarsGuides.ts +++ b/apps/docs/sidebarsGuides.ts @@ -27,6 +27,7 @@ const sidebars: SidebarsConfig = { "routing-with-evaluators", "adding-skills-to-your-app", "projects-on-org-scope", + "realtime", "writing-ui-stories", "choosing-patterns-with-benchmarks", "routing-errors-to-sentry", diff --git a/docs/architecture/authentication.md b/docs/architecture/authentication.md index fb4a8f0ae4..3b6984a251 100644 --- a/docs/architecture/authentication.md +++ b/docs/architecture/authentication.md @@ -130,7 +130,7 @@ The switch is exhaustive over `ParsedFlowRoute["kind"]`. | `session` | session CRUD, state, resources, debug-on-session | Owner is the stored session's `userId`. Flow comes from `session.flowKind`. A missing session is not an auth error — the handler 404s. Another user's session gets that same 404 from the guard (`sessionHidden`; a debug route applies its own gate first), so the answer never says the id is in use. An organization mismatch for the session's own user is 403. The guard returns the session record it checked (`session`, `null` when it found none). Every session-addressed route answers 404 when its own read of the session is not that record: deleted and created again since, or created after the guard found none (`loadCheckedSession`). `test/checked-session-routes.test.ts` derives the session-addressed set from this classification and fails until a new route has a row there, so a route cannot ship without the compare. A session's reads of its requests (the listing, the snapshot with items, the stream) keep to the session's own flow kind, and its owning instance when the session records one (`sessionRequestScope`), so the flow that admitted the caller never serves another flow's requests or items. The history a run in the session loads for its model (`createExecutionContext`) uses the same filter, so a legacy session holding another flow's, a peer instance's or another user's run never hands it to a model. The child runs the session stream lists are scoped by the parent's owner, organization and tenant, not its flow (`parentIdentity`), so work handed to another flow still shows. | | `request` | stream, abort, retry, continue, status, resume | Owner is the request record's `userId` (or the in-flight `activeRequests` entry when the record is not persisted yet). On every request route, another user's request, or a request another organization owns, gets the answer that route's handler gives an unused id: `unknownRequestResponse` for status, retry, continue, resume and abort; `unknownRequestStreamResponse` for the stream (an empty 200 when the caller sent a resume cursor). Each control handler also answers another tenant's request that way (`callerReachesRequest`). The guard hides another user's request before any held `migration-required` refusal, which stays its owner's to hear, and retry, continue and resume answer a request whose source is not open to public re-entry that way too (`public-reentry.ts`). With no record and no in-flight entry, nothing names an owner, so in an app that authenticates the stream answers every caller as an unused id rather than replaying an event log that outlived its record. | | `flow` | `create_session` | No record yet. The authenticated caller becomes the owner. Flow comes from the URL. An id already in use answers 409 whoever holds it, the one route where a session id shows it is taken. | -| `user` | `user_stream`, `check_interrupted_requests` | Owner is the `userId` in the path. There is no stored record to read an organization or tenant from, so the guard compares neither and each handler scopes its own rows: `check_interrupted_requests` sweeps only entries in the caller's tenant (`tenantMatches`) and, when a principal is resolved, the caller's organization (`user_stream` answers 501 and has no rows). A test enforces this in two stages (`packages/engine/test/user-route-scoping.test.ts`). First, every route the guard classifies as `user`, and every `/users/:userId/...` path, must have an entry in the engine's user-route scoping table; a route without one fails the suite. Second, each entry says how to seed, call and observe its route, and the test runs it through the router as the owner, then as a caller from another organization, another tenant and, in a mixed app, an anonymous caller. The owner's call must see its row; any other caller seeing or changing a row fails. A route that is not built yet must answer 501; building it means replacing that pin with a real entry. | +| `user` | `user_stream`, `user_stream_mint`, `check_interrupted_requests`, `list_interrupted_requests` | Owner is the `userId` in the path. There is no stored record to read an organization or tenant from, so the guard compares neither and each handler scopes its own rows: `check_interrupted_requests` sweeps only entries in the caller's tenant (`tenantMatches`) and, when a principal is resolved, the caller's organization. `user_stream_mint` (FIX-2428, `POST /users/:userId/stream`) runs each session topic through the `session_stream` check on its own request and drops a refused or missing one alike; it fills user and org topics from the principal, and gives an anonymous caller in an app where some flow authenticates neither. `user_stream` is the socket a host takes as an upgrade; through the router it answers 426 and has no rows, and its socket hears only topics a ticket from the mint names, for the path's user. A test enforces this in two stages (`packages/engine/test/user-route-scoping.test.ts`). First, every route the guard classifies as `user`, and every `/users/:userId/...` path, must have an entry in the engine's user-route scoping table; a route without one fails the suite. Second, each entry says how to seed, call and observe its route, and the test runs it through the router as the owner, then as a caller from another organization, another tenant and, in a mixed app, an anonymous caller. The owner's call must see its row; any other caller seeing or changing a row fails. A route that is not built yet must answer 501; building it means replacing that pin with a real entry. | | `host` | `list_sessions`, `active_requests`, `transcribe` | No single owner. The handler scopes rows to the caller. A listed row owned by an instance with its own `authentication.resolvePrincipal` is judged by that resolver, the one its doors use: shown only when it accepts the caller, the row's `userId` and `orgId` are the principal it returns, and a pinned instance's pin admits that principal. One instance's resolver accepting a credential says nothing about another instance's rows; each is judged by its own resolver. Instances that share a resolver and its `requireUser` / `defaultUserId` settings are resolved once per request, at the first such instance's address. | An owner-pinned instance is registered with `register(flow, { pin })`, where the pin is `{ orgId, userId? }`. The registering code supplies the pin; it never comes from the address. Workforce pins every instance it hires this way, and its `registerHiredWorker` refuses one that arrives with no pin. `create_session` and a session-less `execute_action` compare the caller to the pin before the acknowledgement and answer a mismatch with `404 Unknown flow`, the same sentence an address this process does not hold gets. An internal dispatch to a pinned instance is refused at the dispatch seam, before a child session is written: a sending principal outside the pin gets `flow-not-found`, the same refusal an unregistered address gets (see [Dispatched Work](./dispatched-work.md)). Execution admission is the backstop. Every run, including resume and retry, compares the bound session to the pin before any block and throws `InstancePinMismatchError` on a mismatch. Its `reason` is `"owning-org"` or `"owning-user"`, the half of the pin the caller missed; the organization is compared first. An instance registered without a pin stays shared. diff --git a/docs/architecture/server-and-client.md b/docs/architecture/server-and-client.md index 3e8d8d83ed..d880e587d2 100644 --- a/docs/architecture/server-and-client.md +++ b/docs/architecture/server-and-client.md @@ -76,7 +76,9 @@ custom) mount alongside it via the `adapters` option — see | Method | Path | Purpose | |--------|------|---------| | GET | `/api/flows` | List registered flows | -| GET | `/api/flows/capabilities` | Feature flags | +| GET | `/api/flows/capabilities` | `{ userStream: false, push }`: `push` is `{ transport: "websocket" }` once a host turns push delivery on (`serve()`), else `null` | +| POST | `/api/flows/users/:userId/stream` | Push mint (FIX-2428): checks each topic, answers a 30 s ticket for the granted ones | +| GET | `/api/flows/users/:userId/stream` | The push socket, taken as an upgrade by the host; a plain GET answers 426 | | POST | `/api/flows/:flowId/actions/:action` | Execute action (new session) | | POST | `/api/flows/:flowId/:sessionId/actions/:action` | Execute action (existing session) | | GET | `/api/flows/:flowId/requests/:requestId/stream` | SSE request stream | diff --git a/docs/mechanisms/mechanisms.yaml b/docs/mechanisms/mechanisms.yaml index 6f591db19c..5f58a7abde 100644 --- a/docs/mechanisms/mechanisms.yaml +++ b/docs/mechanisms/mechanisms.yaml @@ -306,6 +306,18 @@ mechanisms: status: canonical doc: packages/engine/README.md + - id: push-delivery + job: Carry change notices from the bus to a browser, so a screen reads again when something it shows changes. A mint checks each topic with its scope's read check and signs a short ticket; a socket hears only ticketed topics; `client.subscribe` keeps one socket per client and reads on a timer wherever push can miss a change. + package: "@flow-state-dev/engine" + anchor: enablePushDelivery + file: packages/engine/src/push/push-delivery.ts + adapters: ["@flow-state-dev/node"] + builtOn: [change-bus] + overlaps: + - { id: streaming, relation: distinct-jobs, note: "streaming sends a request's or a session's items themselves; push delivery sends only that a topic changed, and the client reads." } + status: canonical + doc: apps/docs/guides/realtime.md + # ── Transports and hosts ────────────────────────────────────────────────── - id: inbound-transport job: Turn an outside request into a run of an action. HTTP is the built-in adapter; the router mounts adapters. diff --git a/goals/realtime/websocket-delivery/goal.md b/goals/realtime/websocket-delivery/goal.md new file mode 100644 index 0000000000..8edcb3c2b9 --- /dev/null +++ b/goals/realtime/websocket-delivery/goal.md @@ -0,0 +1,30 @@ +# realtime › it delivers over a WebSocket + +**Issue:** FIX-2428 +**Outcome:** On the Node host, a screen reads a change someone else made within a second, with no read between changes; a caller who may not read a session never hears of it, on the first connect or any reconnect; and wherever push can miss a change (no push, or a socket whose bus doesn't cross processes), the same screen code stays current on its timer. +**Input:** Real `serve()` hosts on bound ports over a two-action handler flow (`say`, `note`) behind a bearer-token sign-in, and real WebSocket clients: `client.subscribe` with a fetcher that adds the token, reading the session's replies (`sessions.requests`) on each change, one read at a time. Legs a and b run on FIX-2426's crossing double (`goals/lib/crossing-bus.mts`). Leg c runs once with `push: false`, and once with two hosts over one Postgres (PGlite), each on its own in-memory bus, tab 2's socket on the second. Held-out: any reply text and any session id must pass; leg a also writes in a second session T that tab 2 doesn't watch, which must not run its read. +**Signal:** +- `a:within-1s` — three replies in S, each shown by tab 2's read less than 1000 ms after it was saved (read off the host's store every 5 ms). +- `a:no-read-between` — tab 2 makes 0 reads over a 10 s window that starts after its socket's first `crosses: true` frame, with a reply in T in the middle. +- `b:control` — B reads its own reply (written from B's other device) through push. +- `b:c-never-hears` — C, who subscribes to B's session, has its handler run 0 times. +- `b:revoked` — after B's token is revoked and B's socket is dropped (its TCP socket destroyed), B's handler runs 0 more times and its read never shows the next reply. +- `c:no-push` — on a host with `push: false`, tab 2's read shows the reply less than 3000 ms (one 2 s poll interval plus 1 s) after it was saved. +- `c:second-process` — with tab 2's socket on a second process on the in-memory bus, tab 2's read shows the first process's reply less than 3000 ms after it was saved. + +**Anti-game:** Not `publish` calls and not frames sent: every assertion reads what a client's own read returned (`sessions.requests`), or whether the client's handler ran at all. The socket taps (a `WebSocket` subclass that records frames) only time the start of leg a's window and floor leg c's crossing frames; they change nothing the client does. Real sockets against bound ports, not an in-process fetch. Each graded list is floored with `tell.over`; the two lists whose empty state is the claim say so. The check drives `client.subscribe`, which owns the socket and the timer; `useSubscription` is a coalesced read over it, proven by `packages/react/test/useSubscription.test.ts`. +**Model:** n/a +**Run:** `pnpm tsx goals/realtime/websocket-delivery/run.mts` +**Controls:** +- `GOAL_CONTROL=no-socket` — capabilities says push, the upgrade is never served (a scratch patch to `packages/node/src/serve.ts`). Must FAIL `a:within-1s` and `a:no-read-between`. +- `GOAL_CONTROL=skip-check` — the mint grants every session topic (a scratch patch to `packages/engine/src/push/push-delivery.ts`). Must FAIL `b:c-never-hears`. +- `GOAL_CONTROL=ignore-crossing` — the client treats every open socket as covering (a scratch patch to `packages/client/src/subscribe/push-hub.ts`). Must FAIL `c:second-process`. +- Today's `main` (the parent of this change) has no `client.subscribe` and answers the user-stream route 501, so no leg can run there; the three controls stand in for its red state. + +## Verdict log +| Date | Commit | Model | Verdict | Notes | +|------|--------|-------|---------|-------| +| 2026-11-03 | fix/FIX-2428-subscribe (pre-commit) | n/a | PASS | a: 0 reads in 10 s idle (a reply in T included); replies shown 14, 3, 6 ms after saved · b: C's handler never ran; B read its reply 1 ms after saved; B heard nothing after revocation · c: no push, shown 1496 ms; second process (crosses: false), shown 1391 ms | +| 2026-11-03 | fix/FIX-2428-subscribe (pre-commit) | n/a | FAIL (expected) | `no-socket`: `a:no-read-between` (5 reads in 10 s), `a:within-1s` (638, 1214, 1288 ms); also `a:crossing`, `b:control` and CAN'T TELL on c's crossing frames, since nothing pushes. The first run of this control found a client defect (Node's WebSocket reports a failed handshake as an error with no close), fixed before this row | +| 2026-11-03 | fix/FIX-2428-subscribe (pre-commit) | n/a | FAIL (expected) | `skip-check`: `b:c-never-hears` only (C's handler ran 7 times) | +| 2026-11-03 | fix/FIX-2428-subscribe (pre-commit) | n/a | FAIL (expected) | `ignore-crossing`: `c:second-process` only (tab 2 never showed the reply) | diff --git a/goals/realtime/websocket-delivery/run.mts b/goals/realtime/websocket-delivery/run.mts new file mode 100644 index 0000000000..f599fe2fa6 --- /dev/null +++ b/goals/realtime/websocket-delivery/run.mts @@ -0,0 +1,420 @@ +/** + * realtime › it delivers over a WebSocket (FIX-2428). + * + * Real `serve()` hosts on bound ports, real WebSocket clients (Node's own), + * and `client.subscribe` with a bearer token its fetcher adds. Every + * assertion reads what a client's own read returned after it heard a change. + * + * a — on a bus that crosses processes, tab 2 watches session S and tab 1 + * replies in S: tab 2's read shows each reply within 1 s, and tab 2 + * makes no read over a 10 s window from its first `crosses: true` + * frame, through a reply in another session T it doesn't watch. + * b — user C subscribes to B's session: refused, and C's handler never + * runs. Then B's token is revoked and B's socket drops: B's + * reconnect is refused, and B hears nothing more. + * c — the same tab 2 code with no push, and with tab 2's socket on a + * second process on the in-memory bus: tab 2's read shows the reply + * within one poll interval plus 1 s. + * + * Controls (each runs this file again with a patch applied as it loads): + * GOAL_CONTROL=no-socket the host never serves the upgrade: a must FAIL. + * GOAL_CONTROL=skip-check the mint grants every topic: b's "C never hears" must FAIL. + * GOAL_CONTROL=ignore-crossing the client treats every open socket as covering: c's second process must FAIL. + */ +import { spawnSync } from "node:child_process"; +import { rmSync } from "node:fs"; +import type { Duplex } from "node:stream"; +import { join } from "node:path"; +import { z } from "zod"; +import { PGlite } from "@electric-sql/pglite"; +import { defineFlow, handler } from "@flow-state-dev/core"; +import { createClient, topic, type WireNotice } from "@flow-state-dev/client"; +import { + createFlowApiRouter, + createFlowRegistry, + createInMemoryStores, + type ChangeBus, + type StoreRegistry +} from "@flow-state-dev/engine"; +import { serve, type ServeHandle } from "@flow-state-dev/node"; +import { createPostgresStores, type QueryExecutor } from "@flow-state-dev/store-postgres"; +import { crossingBus } from "../../lib/crossing-bus.mts"; +import { + REPO_ROOT, + RUN_STAMP, + assertPatched, + describePatches, + goalTmpDir, + modulePatchEnv, + runGoal, + type ModulePatch +} from "../../lib/index.mts"; + +const CONTROL = process.env.GOAL_CONTROL ?? ""; +const SCRATCH = process.env.GOAL_SCRATCH ?? goalTmpDir("realtime-websocket"); +const POLL_MS = 2_000; +const IDLE_WINDOW_MS = 10_000; + +const PATCHES: Record = { + // Capabilities still says push, but the upgrade is never served. + "no-socket": [ + { + module: "packages/node/src/serve.ts", + from: String.raw`push\.upgrade\(server, req, socket, head\)`, + to: "socket.destroy()" + } + ], + // The mint grants every session topic, checked or not. + "skip-check": [ + { + module: "packages/engine/src/push/push-delivery.ts", + from: String.raw`if \(checked\.denied !== undefined \|\| checked\.session === null\) continue;`, + to: "void checked;" + } + ], + // The client treats an open socket as covering, crossing or not. + "ignore-crossing": [ + { + module: "packages/client/src/subscribe/push-hub.ts", + from: String.raw`state === "open" && crosses && `, + to: 'state === "open" && ' + } + ] +}; + +if (CONTROL !== "" && PATCHES[CONTROL] === undefined) { + console.error(`unknown GOAL_CONTROL "${CONTROL}"; known: ${Object.keys(PATCHES).join(", ")}`); + process.exit(2); +} +if (PATCHES[CONTROL] !== undefined && process.env.GOAL_MODULE_PATCH === undefined) { + const mark = join(SCRATCH, `patch-mark-${RUN_STAMP}`); + rmSync(mark, { force: true }); + console.error(`control ${CONTROL}:\n${describePatches(PATCHES[CONTROL]!, REPO_ROOT)}`); + const child = spawnSync(process.execPath, [...process.execArgv, ...process.argv.slice(1)], { + stdio: "inherit", + env: { ...process.env, GOAL_SCRATCH: SCRATCH, ...modulePatchEnv(PATCHES[CONTROL]!, REPO_ROOT, mark) } + }); + assertPatched(PATCHES[CONTROL]!, REPO_ROOT, mark); + process.exit(child.status ?? 1); +} + +// --------------------------------------------------------------------------- +// Observing the sockets (taps only: nothing here changes what a client does) +// --------------------------------------------------------------------------- + +type Tap = { url: string; frames: Array<{ type: string; crosses?: boolean }> }; +const taps: Tap[] = []; +const NativeWebSocket = globalThis.WebSocket; +globalThis.WebSocket = class TappedWebSocket extends NativeWebSocket { + constructor(url: string | URL, protocols?: string | string[]) { + super(url, protocols); + const tap: Tap = { url: String(url), frames: [] }; + taps.push(tap); + this.addEventListener("message", (event) => tap.frames.push(JSON.parse(String(event.data)) as Tap["frames"][number])); + } +} as typeof WebSocket; + +// --------------------------------------------------------------------------- +// The app: a two-action handler flow, behind a bearer-token sign-in +// --------------------------------------------------------------------------- + +/** Bearer token → user. Revoking a token deletes it. */ +const tokens = new Map(); + +function chatFlow() { + const reply = (name: string) => + handler({ + name, + inputSchema: z.object({ text: z.string() }), + outputSchema: z.object({ text: z.string() }), + execute: (input) => ({ text: input.text }) + }); + return defineFlow({ + kind: "chat", + actions: { + say: { inputSchema: z.object({ text: z.string() }), block: reply("chat-say") }, + note: { inputSchema: z.object({ text: z.string() }), block: reply("chat-note") } + } + })(); +} + +type Host = { handle: ServeHandle; base: string; stores: StoreRegistry; raw: Array<{ url: string; socket: Duplex }> }; + +async function host(stores: StoreRegistry, options: { push?: boolean } = {}): Promise { + const registry = createFlowRegistry(); + registry.register(chatFlow()); + const router = createFlowApiRouter({ + registry, + stores, + staleSweepIntervalMs: 0, + resolvePrincipal: (context) => { + const header = context.request?.headers.get("authorization") ?? ""; + const user = tokens.get(header.replace(/^Bearer /, "")); + return user === undefined ? null : { userId: user, orgId: "acme" }; + } + }); + const handle = await serve(router, { + port: 0, + host: "127.0.0.1", + handleSignals: false, + shutdownGraceMs: 200, + ...(options.push !== undefined ? { push: options.push } : {}) + }); + const raw: Host["raw"] = []; + // A second listener, to drop a socket the way a network does. It records only. + handle.server.on("upgrade", (req, socket) => raw.push({ url: req.url ?? "", socket })); + return { handle, base: `http://127.0.0.1:${handle.port}`, stores, raw }; +} + +/** A tab: a client for `userId` whose fetcher adds the bearer token. */ +function tab(on: Host, userId: string, token: string) { + return createClient({ + userId, + baseUrl: on.base, + fetcher: (input, init) => + fetch(input, { ...init, headers: { ...(init?.headers as Record), authorization: `Bearer ${token}` } }) + }); +} + +type Tab = ReturnType; + +async function newSession(fsd: Tab): Promise { + return (await fsd.flow("chat").createSession()).id; +} + +/** Reply in `sessionId`, and return when the reply is saved, read off the host's store. */ +async function replyIn(fsd: Tab, on: Host, sessionId: string, text: string): Promise { + const sent = await fsd.flow("chat").send("say", { text }, { sessionId }); + const deadline = Date.now() + 5_000; + for (;;) { + const record = await on.stores.request.get(sent.id); + if (record !== undefined && record.status !== "in_progress") return Date.now(); + if (Date.now() > deadline) throw new Error(`setup: request ${sent.id} never finished`); + await delay(5); + } +} + +type Watch = { + reads: Array<{ at: number; texts: string[] }>; + notices: Array; + close(): void; +}; + +/** + * Tab 2's code: subscribe the session and, on each change, read the + * session's replies, one read at a time (as `useSubscription` does). + */ +function watch(fsd: Tab, sessionId: string, pollIntervalMs: number | undefined): Watch { + const reads: Watch["reads"] = []; + const notices: Watch["notices"] = []; + let running = false; + let queued = false; + const read = async (): Promise => { + if (running) { + queued = true; + return; + } + running = true; + try { + const requests = await fsd.sessions.requests(sessionId, { includeResultOutput: true }); + const texts = requests.map((r) => (r.result?.output as { text?: string } | undefined)?.text).filter((t): t is string => t !== undefined); + reads.push({ at: Date.now(), texts }); + } catch { + reads.push({ at: Date.now(), texts: [] }); + } finally { + running = false; + if (queued) { + queued = false; + void read(); + } + } + }; + const sub = fsd.subscribe([topic.session(sessionId)], { + onChange: (notice) => { + notices.push(notice); + void read(); + }, + ...(pollIntervalMs !== undefined ? { pollIntervalMs } : {}) + }); + return { reads, notices, close: () => sub.close() }; +} + +/** When `w`'s reads first showed `text`, waiting up to `withinMs`. */ +async function shownAt(w: Watch, text: string, withinMs: number): Promise { + const deadline = Date.now() + withinMs; + for (;;) { + const hit = w.reads.find((r) => r.texts.includes(text)); + if (hit !== undefined) return hit.at; + if (Date.now() > deadline) return undefined; + await delay(10); + } +} + +async function until(check: () => boolean, withinMs: number): Promise { + const deadline = Date.now() + withinMs; + while (!check()) { + if (Date.now() > deadline) return false; + await delay(10); + } + return true; +} + +function delay(ms: number): Promise { + return new Promise((resolve) => setTimeout(resolve, ms)); +} + +function executorOver(pglite: PGlite): QueryExecutor { + return { + async query(text: string, values?: unknown[]) { + const result = await pglite.query(text, values); + return { rows: result.rows as Record[], rowCount: result.affectedRows ?? 0 }; + } + }; +} + +function memory(bus?: ChangeBus): StoreRegistry { + return { ...createInMemoryStores(), ...(bus !== undefined ? { bus } : {}) }; +} + +// --------------------------------------------------------------------------- +// The legs +// --------------------------------------------------------------------------- + +await runGoal(async (failures, tell) => { + const evidence: string[] = []; + const hosts: Host[] = []; + const watches: Watch[] = []; + try { + // a · a bus that crosses: push covers tab 2, and only push. + { + tokens.set("tok-alice", "alice"); + const on = await host(memory(crossingBus())); + hosts.push(on); + const tab1 = tab(on, "alice", "tok-alice"); + const tab2 = tab(on, "alice", "tok-alice"); + const s = await newSession(tab1); + const t = await newSession(tab1); + const before = taps.length; + const view = watch(tab2, s, POLL_MS); + watches.push(view); + const crossed = await until(() => taps.slice(before).some((tp) => tp.frames.some((f) => f.type === "crossing" && f.crosses === true)), 3_000); + if (!crossed) failures.push("a:crossing: tab 2's socket never said crosses: true within 3 s"); + await delay(300); + + const readsBefore = view.reads.length; + await delay(IDLE_WINDOW_MS / 2); + await replyIn(tab1, on, t, "a reply in T, which tab 2 doesn't watch"); + await delay(IDLE_WINDOW_MS / 2); + const idleReads = view.reads.length - readsBefore; + tell.over("a:no-read-between · tab 2's reads before the window", view.reads.slice(0, readsBefore)); + if (idleReads !== 0) failures.push(`a:no-read-between: tab 2 made ${idleReads} reads in ${IDLE_WINDOW_MS / 1000} s with no change in S`); + else evidence.push(`a: 0 reads in ${IDLE_WINDOW_MS / 1000} s idle, a reply in T included`); + + const latencies: number[] = []; + for (const n of [1, 2, 3]) { + const text = `reply ${n} in S`; + const saved = await replyIn(tab1, on, s, text); + const shown = await shownAt(view, text, 3_000); + if (shown === undefined) failures.push(`a:within-1s: tab 2's read never showed "${text}" within 3 s`); + else latencies.push(shown - saved); + await delay(700); + } + const graded = tell.over("a:within-1s · tab 2's reads showing a reply", latencies); + const slow = graded.filter((ms) => ms >= 1_000); + if (slow.length > 0) failures.push(`a:within-1s: tab 2 showed replies ${graded.join(", ")} ms after saved (bound 1000)`); + else if (graded.length > 0) evidence.push(`a: replies shown ${graded.join(", ")} ms after saved`); + view.close(); + } + + // b · a refused topic is never heard, first connect or reconnect. + { + tokens.set("tok-b", "bob"); + tokens.set("tok-b-other-device", "bob"); + tokens.set("tok-c", "carol"); + const on = await host(memory(crossingBus())); + hosts.push(on); + const bob = tab(on, "bob", "tok-b"); + const bobElsewhere = tab(on, "bob", "tok-b-other-device"); + const carol = tab(on, "carol", "tok-c"); + const s = await newSession(bobElsewhere); + const bView = watch(bob, s, undefined); + const cView = watch(carol, s, undefined); + watches.push(bView, cView); + await until(() => bView.reads.length > 0, 3_000); + await until(() => taps.some((tp) => tp.url.includes("/users/carol/stream") && tp.frames.length > 0), 3_000); + + const saved = await replyIn(bobElsewhere, on, s, "B's first reply"); + const bShown = await shownAt(bView, "B's first reply", 3_000); + const bHeard = tell.over("b:control · B's reads showing its own reply", bShown === undefined ? [] : [bShown - saved]); + if (bHeard.length === 0) failures.push("b:control: B never read its own reply, so this leg can't tell C's silence from no delivery"); + await delay(500); + const cCalls = tell.over("b:c-never-hears · C's handler calls", cView.notices, { emptyIs: "the claim: C's handler never runs" }); + if (cCalls.length !== 0) failures.push(`b:c-never-hears: C's handler ran ${cCalls.length} times for B's session`); + else evidence.push(`b: C's handler never ran; B read its reply ${bHeard[0] ?? "?"} ms after saved`); + + // Revoke B's token, and drop B's socket the way a network does. + tokens.delete("tok-b"); + const bSockets = on.raw.filter((r) => r.url.includes("/users/bob/stream")); + tell.over("b:revoked · B's sockets dropped", bSockets); + for (const r of bSockets) r.socket.destroy(); + await delay(4_000); + const heardBefore = bView.notices.length; + const readsBefore = bView.reads.length; + await replyIn(bobElsewhere, on, s, "B's reply after revoking"); + await delay(3_000); + const after = bView.notices.slice(heardBefore); + tell.over("b:revoked · B's handler calls after the reconnect", after, { emptyIs: "the claim: B hears nothing more" }); + if (after.length !== 0 || bView.reads.slice(readsBefore).some((r) => r.texts.includes("B's reply after revoking"))) { + failures.push(`b:revoked: B heard ${after.length} more after its token was revoked`); + } else evidence.push("b: B heard nothing after revocation"); + bView.close(); + cView.close(); + } + + // c · where push can miss a change, the timer keeps tab 2 current. + { + tokens.set("tok-alice", "alice"); + // c1 · no push. + const noPush = await host(memory(), { push: false }); + hosts.push(noPush); + const writer = tab(noPush, "alice", "tok-alice"); + const s1 = await newSession(writer); + const view1 = watch(tab(noPush, "alice", "tok-alice"), s1, POLL_MS); + watches.push(view1); + await delay(500); + const saved1 = await replyIn(writer, noPush, s1, "a reply with no push"); + const shown1 = await shownAt(view1, "a reply with no push", POLL_MS + 3_000); + const c1 = tell.over("c:no-push · tab 2's reads showing the reply", shown1 === undefined ? [] : [shown1 - saved1]); + if (c1.length === 0) failures.push("c:no-push: tab 2 never showed the reply"); + else if (c1[0]! >= POLL_MS + 1_000) failures.push(`c:no-push: shown ${c1[0]} ms after saved (bound ${POLL_MS + 1_000})`); + else evidence.push(`c: no push, shown ${c1[0]} ms after saved`); + view1.close(); + + // c2 · tab 2's socket on a second process, each on its own in-memory bus. + const pglite = new PGlite(); + const first = await host(await createPostgresStores({ executor: executorOver(pglite) })); + const second = await host(await createPostgresStores({ executor: executorOver(pglite) })); + hosts.push(first, second); + const tab1 = tab(first, "alice", "tok-alice"); + const s2 = await newSession(tab1); + const before = taps.length; + const view2 = watch(tab(second, "alice", "tok-alice"), s2, POLL_MS); + watches.push(view2); + await until(() => taps.slice(before).some((tp) => tp.frames.some((f) => f.type === "crossing")), 3_000); + const crossing = taps.slice(before).flatMap((tp) => tp.frames.filter((f) => f.type === "crossing")); + tell.over("c:second-process · tab 2's crossing frames", crossing); + await delay(500); + const saved2 = await replyIn(tab1, first, s2, "a reply from the first process"); + const shown2 = await shownAt(view2, "a reply from the first process", POLL_MS + 3_000); + const c2 = tell.over("c:second-process · tab 2's reads showing the reply", shown2 === undefined ? [] : [shown2 - saved2]); + if (c2.length === 0) failures.push("c:second-process: tab 2 never showed the reply from the first process"); + else if (c2[0]! >= POLL_MS + 1_000) failures.push(`c:second-process: shown ${c2[0]} ms after saved (bound ${POLL_MS + 1_000})`); + else evidence.push(`c: second process (crosses: ${crossing[0]?.crosses}), shown ${c2[0]} ms after saved`); + view2.close(); + } + } finally { + for (const w of watches) w.close(); + await Promise.all(hosts.map((h) => h.handle.close())); + } + return { failures, evidence: evidence.join(" · ") }; +}); diff --git a/packages/client/README.md b/packages/client/README.md index 5665df9854..8724e730a6 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -206,12 +206,34 @@ stream.close(); `fsd.sessions.stream(sessionId, options)` follows a whole session: every finished item any request in it keeps, and a notice whenever its unfinished runs change. It reconnects with backoff; a 401, 403, 404, 409 or 501 stops it for -good (`onStop`). `fsd.stream(callbacks)` follows the user stream, the user's -resource and scope-state changes. +good (`onStop`). Every stream goes through the client's fetcher, so an in-process client streams with no web server, and a credentialed one streams with its credentials. +### Hearing changes others make + +`fsd.subscribe(topics, { onChange, pollIntervalMs? })` calls `onChange` when +something under a topic may have changed, so the screen reads again. It says +when, never what: `onChange` gets the notice (`{ topic, kind, origin? }`), or +`null` for a connect, a reconnect or a timer tick. + +```ts +import { topic } from "@flow-state-dev/client"; + +const sub = fsd.subscribe([topic.session(sessionId), topic.org()], { + onChange: () => void reload(), + pollIntervalMs: 3000, // while there is no push, the socket is down, or its bus can't cross processes +}); +sub.close(); +``` + +On a host with push (`serve()` from `@flow-state-dev/node`), one WebSocket per +client carries the notices, signed in through the client's fetcher; each topic +is checked on the server, and one the caller may not read is never heard. On a +host with no push, `onChange(null)` runs every `pollIntervalMs`. Omit +`pollIntervalMs` for no timer. + ### Following a session without React `sessionFeed(fsd, sessionId)` follows one session for a view that isn't a @@ -447,7 +469,7 @@ the flow is wired up. - `sessions` — `list`, `get`, `requests`, `children`, `state`, `updateMetadata`, `delete`, `stream`, and `debug` (DevTool reads; the server must opt in) - `resources` — content, collection items and the manifest (below) - `requests.interrupted({ staleThresholdMs? })` — The user's interrupted requests, as request handles - - `stream(callbacks)` — The user stream + - `subscribe(topics, { onChange, pollIntervalMs? })` — Hear that something under `topics` changed; `close()` stops - `transcribe({ audio, mediaType?, language? })` — Transcribe audio on the server - `createSSEClientFromResponse({ response, ...callbacks })` — Read an SSE `Response` a `{ stream: true }` call returned - `createRequestStreamStore({ keyOf? })` — Headless request-stream accumulator (sorted items, streaming text, status/sequence) @@ -459,6 +481,7 @@ the flow is wired up. - `sendHarnessLine(prompt, running, sender)` — Send a line typed into a harness session: into the running turn when its harness takes it (the flow's steer action, core's `harnessSteering`), else as the next turn. Answers `"taken"`, `"after-this-turn"` or `"turn"` - `harnessLines(sendOne?)` — Keep one page's lines in typed order: `send(prompt, running, sender)` waits for the line before, and once a line has gone to run after the running turn, later lines follow it until `turnChanged()` - `steerRunningTurn(client, { flowKind, sessionId, prompt, action? })` — Send the flow's steer action on its own, so a session hook's stream stays on the running turn, and read its `{ taken, live }` answer +- `topic.session(id)`, `topic.user()`, `topic.org()` — The topics `subscribe` takes, each with an optional `{ resource }` - `ClientHttpError` — Every failure. `status` is the server's answer, or `0` when the client refused before sending (a missing argument, a request with no session to continue) ### Resources @@ -477,7 +500,7 @@ The list/get-state methods require `client.state.read: true` on the collection. - `userId` is required: it is the user every call acts as - Stream resume supports both `Last-Event-ID` header and `starting_after` query param -- Request and user streams use a bounded sliding-window event dedup cache (`dedupWindowSize`, default `1000`) +- Request streams use a bounded sliding-window event dedup cache (`dedupWindowSize`, default `1000`) - When both are supplied, `starting_after` takes precedence ## Scripts diff --git a/packages/client/src/client.ts b/packages/client/src/client.ts index 18788d1ca4..22dcd181ac 100644 --- a/packages/client/src/client.ts +++ b/packages/client/src/client.ts @@ -4,20 +4,20 @@ * Built from a user and a transport (a `baseUrl` over HTTP, or a `fetcher` * such as the engine's `createInProcessFetch`). Its namespaces follow how the * server addresses its routes: the root is the user's (flows, sessions, - * resources, interrupted requests, the user stream); `flow(address)` holds a + * resources, interrupted requests, change subscriptions); `flow(address)` holds a * flow's actions; a request handle holds one request's lifecycle. Every call * and stream goes through the one transport built here. */ -import type { ResumeAction } from "@flow-state-dev/contracts"; +import type { ResumeAction, WireTopic } from "@flow-state-dev/contracts"; import type { ActionConfig, FlowActionInput, RequestStatusSnapshot } from "@flow-state-dev/core/types"; import { clientError, createTransport, requireValue, seg, topicPath, type Transport } from "./internal/http"; import { openRequestStream, openSessionStream, - openUserStream, type SessionStreamOptions, type StreamResumeOptions } from "./stream-client/streams"; +import { createPushHub, type SubscribeOptions, type Subscription } from "./subscribe/push-hub"; import type { ChildSessionSummary, ClientFetch, @@ -40,9 +40,7 @@ import type { SessionRequestSummary, SessionStateSnapshotResponse, SessionStreamHandle, - SessionSummary, - UserSSECallbacks, - UserStreamHandle + SessionSummary } from "./types"; // --------------------------------------------------------------------------- @@ -253,9 +251,6 @@ export type RequestStreamOptions = RequestSSECallbacks & includeTrace?: boolean; }; -/** Options for {@link Client.stream}, the user stream. */ -export type UserStreamOptions = UserSSECallbacks & StreamResumeOptions; - /** A flow whose actions type-check `send`, as `typeof myFlow` gives it. Types only. */ export type TypedFlow = { actions: Record }; @@ -463,8 +458,16 @@ export interface Client { */ interrupted(options?: { staleThresholdMs?: number }): Promise; }; - /** Follow the user stream: resource and scope-state changes for this user. */ - stream(options: UserStreamOptions): UserStreamHandle; + /** + * Hear that something under `topics` changed, and read again in + * `onChange`. A notice says when, never what: `onChange` gets the notice + * (or `null` for a connect, a reconnect or a timer tick) and makes the read + * the screen already makes. One socket per client, minted through this + * client's fetcher, on a host with push; `pollIntervalMs` reads on a timer + * wherever push can miss a change. Build topics with `topic.session(id)`, + * `topic.user()` and `topic.org()`. + */ + subscribe(topics: readonly WireTopic[], options: SubscribeOptions): Subscription; /** Transcribe audio on the server. */ transcribe(request: TranscribeRequest): Promise; } @@ -602,10 +605,13 @@ export function createClient(options: CreateClientOptions): Client { getResourceManifest: (sessionId) => t.json(`/api/flows/sessions/${sid(sessionId)}/manifest`) }; + const capabilities = (): Promise => t.json("/api/flows/capabilities"); + const push = createPushHub({ transport: t, userId, capabilities }); + const client: Client = { userId, flows: async () => (await t.json<{ flows: FlowListEntry[] }>("/api/flows")).flows, - capabilities: () => t.json("/api/flows/capabilities"), + capabilities, flow: (address: string) => flowHandle(t, userId, address), sessions, resources, @@ -640,14 +646,7 @@ export function createClient(options: CreateClientOptions): Client { ); } }, - stream: ({ startingAfter, lastEventId, dedupWindowSize, ...callbacks }) => - openUserStream( - { - fetcher: t.fetcher, - url: t.url(`/api/flows/users/${seg(userId)}/stream`, { starting_after: startingAfter }) - }, - { ...callbacks, startingAfter, lastEventId, dedupWindowSize } - ), + subscribe: (topics, subscribeOptions) => push.subscribe(topics, subscribeOptions), transcribe: (request) => { const mediaType = request.mediaType ?? "audio/webm"; const body = diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts index 115fceab29..427f8c143e 100644 --- a/packages/client/src/index.ts +++ b/packages/client/src/index.ts @@ -32,10 +32,14 @@ export { type TypedFlow, type UntypedFlow, type UpdateResourceContentOptions, - type UpdateSessionMetadataOptions, - type UserStreamOptions + type UpdateSessionMetadataOptions } from "./client"; +export type { SubscribeOptions, Subscription } from "./subscribe/push-hub"; +// The wire topics `subscribe` takes, and the notice `onChange` gets. +export { topic } from "@flow-state-dev/contracts"; +export type { ChangeKind, PushCapability, TopicOptions, WireNotice, WireTopic } from "@flow-state-dev/contracts"; + export { sessionQueryFor } from "./session-client/session-query"; export { interruptedBySession, type InterruptedBySessionOptions } from "./interrupted-by-session"; export type { SessionConnectionState } from "./session-client/follow-session"; @@ -131,8 +135,6 @@ export type { SessionStreamHandle, SessionStateSnapshotResponse, SessionSummary, - UserSSECallbacks, - UserStreamHandle, ChildSessionStatus, ChildSessionSummary } from "./types"; diff --git a/packages/client/src/stream-client/streams.ts b/packages/client/src/stream-client/streams.ts index cb92cbfb41..c89f71fec2 100644 --- a/packages/client/src/stream-client/streams.ts +++ b/packages/client/src/stream-client/streams.ts @@ -1,5 +1,5 @@ /** - * SSE stream readers for request, session and user streams. + * SSE stream readers for request and session streams. * * The openers here take a resolved URL and the fetcher of the client that * opens them: `createClient` is their only caller, so every stream goes @@ -7,19 +7,13 @@ * the pure reader for a stream a POST already returned (inline streaming). */ import { toError } from "@flow-state-dev/contracts/helpers"; -import type { - RequestStreamEvent, - SessionStreamEvent, - UserStreamEvent -} from "@flow-state-dev/core/items"; +import type { RequestStreamEvent, SessionStreamEvent } from "@flow-state-dev/core/items"; import type { ClientFetch, RequestSSECallbacks, RequestStreamHandle, SessionSSECallbacks, - SessionStreamHandle, - UserSSECallbacks, - UserStreamHandle + SessionStreamHandle } from "../types"; import { ClientHttpError } from "../types"; @@ -251,80 +245,6 @@ export function openRequestStream( }; } -/** - * Opens the user stream for optional capability-gated updates. - * Internal; `client.stream()` is the public way in. - */ -export function openUserStream( - target: StreamTarget, - options: UserSSECallbacks & StreamResumeOptions -): UserStreamHandle { - const { fetcher, url } = target; - const controller = new AbortController(); - const deduper = createSlidingEventDeduper( - options.dedupWindowSize ?? DEFAULT_DEDUP_WINDOW_SIZE - ); - let closed = false; - let lastEventId = options.lastEventId; - - void consumeSSE({ - fetcher, - url, - signal: controller.signal, - headers: - lastEventId === undefined || options.startingAfter !== undefined - ? undefined - : { - "last-event-id": lastEventId - }, - onFrame: (frame) => { - if (closed) { - return; - } - - if (frame.id !== undefined) { - lastEventId = frame.id; - } - - if (frame.data === undefined) { - return; - } - - try { - const parsed = JSON.parse(frame.data) as UserStreamEvent; - const key = userEventKey(parsed); - if (deduper.seen(key)) { - return; - } - - dispatchUserEvent(parsed, options); - } catch (error) { - options.onError?.(toError(error, "Unknown SSE client error")); - } - }, - onError: (error) => { - if (!closed) { - options.onError?.(error); - } - } - }); - - return { - close: () => { - if (closed) { - return; - } - - closed = true; - deduper.clear(); - controller.abort(); - }, - get lastEventId() { - return lastEventId; - } - }; -} - /** * Configuration for following a whole session over * `GET /api/flows/sessions/:sessionId/stream`. @@ -656,10 +576,6 @@ function requestEventKey(event: RequestStreamEvent): string { return `${event.stream}:${event.requestId}:${event.sequence_number}`; } -function userEventKey(event: UserStreamEvent): string { - return `${event.stream}:${event.userId}:${event.sequence_number}`; -} - function dispatchRequestEvent( event: RequestStreamEvent, callbacks: RequestSSECallbacks @@ -734,24 +650,6 @@ function dispatchRequestEvent( } } -function dispatchUserEvent(event: UserStreamEvent, callbacks: UserSSECallbacks): void { - callbacks.onEvent?.(event); - - if (event.type === "resource.changed") { - callbacks.onResourceChanged?.(event); - return; - } - - if (event.type === "scope.state.changed") { - callbacks.onScopeStateChanged?.(event); - return; - } - - if (event.type === "debug") { - callbacks.onDebug?.(event); - } -} - function dispatchSessionEvent( event: SessionStreamEvent, callbacks: SessionSSECallbacks diff --git a/packages/client/src/subscribe/push-hub.ts b/packages/client/src/subscribe/push-hub.ts new file mode 100644 index 0000000000..a80dd7b15a --- /dev/null +++ b/packages/client/src/subscribe/push-hub.ts @@ -0,0 +1,458 @@ +/** + * `client.subscribe` (FIX-2428): hear that something under a topic changed, + * and read again. + * + * One hub per client holds one socket (epic D4), shared by every + * subscription on the client, with each topic counted so the last `close()` + * on a topic unsubscribes it and the last handle closes the socket. + * + * - **Push.** If `GET /capabilities` reports a push, the hub mints through + * the client's own fetcher (`POST /users/:userId/stream`), so whatever + * credentials the fetcher adds prove who the socket is (D1). The answer's + * `transport` decides; only the `websocket` arm is built. The socket gets + * the ticket as its first message. + * - **The timer** (D3). A subscription with `pollIntervalMs` reads on it + * wherever push can miss a change: no push; the socket down, from the first + * failed reconnect; until the socket's first `crossing` frame says + * `crosses: true`, and while it says `false`; and while one of its topics + * was refused, which is asked for again at each tick. Without + * `pollIntervalMs` there is no timer, and a refused topic is asked for again + * on reconnect. + * - **`onChange`** gets the notice that woke it, or `null` for a connect, a + * reconnect, a change of the crossing answer, or a tick. A notice reaches + * every subscription with a topic that covers it: the same scope and + * session, and the same resource unless the subscription's topic names + * none. + */ +import { + PUSH_CLOSE_CODES, + wireTopicKey, + type PushMintAnswer, + type PushServerFrame, + type WireNotice, + type WireTopic +} from "@flow-state-dev/contracts"; +import type { Transport } from "../internal/http"; +import type { FlowCapabilities } from "../types"; + +/** Options for `client.subscribe`. */ +export type SubscribeOptions = { + /** + * Called when something under a subscribed topic may have changed: with + * the notice that woke it, or `null` for a connect, a reconnect, a change + * of whether push crosses processes, or a timer tick. Read again here. + */ + onChange: (notice: WireNotice | null) => void; + /** + * Read on a timer at this pace wherever push can miss a change: the host + * has no push, the socket is down, or its bus doesn't cross processes. + * Omitted: no timer; reads happen on a notice, a connect and a reconnect. + */ + pollIntervalMs?: number; +}; + +/** A live subscription. */ +export type Subscription = { + /** Stop hearing these topics. The last handle on a client closes its socket. */ + close(): void; +}; + +type Handle = { + readonly topics: readonly WireTopic[]; + readonly keys: readonly string[]; + readonly onChange: (notice: WireNotice | null) => void; + readonly pollIntervalMs?: number; + timer?: ReturnType; +}; + +/** How long a socket may take to open before the connect counts as failed. */ +const HANDSHAKE_TIMEOUT_MS = 10_000; + +/** Backoff between failed connects: 1 s, doubling, at most 30 s. */ +const RETRY_BASE_MS = 1_000; +const RETRY_MAX_MS = 30_000; + +/** Close codes that mean "this connect failed", not "the connection dropped". */ +const FAILED_CONNECT_CODES = new Set([ + PUSH_CLOSE_CODES.ticketRefused, + PUSH_CLOSE_CODES.ticketTimeout, + PUSH_CLOSE_CODES.badFrame +]); + +let warnedTransport = false; +let warnedHandler = false; + +/** Whether `subscribed` covers a notice under `heard`. */ +function covers(subscribed: WireTopic, heard: WireTopic): boolean { + if (subscribed.scope !== heard.scope) return false; + if (subscribed.scope === "session" && heard.scope === "session" && subscribed.id !== heard.id) return false; + return subscribed.resource === undefined || subscribed.resource === heard.resource; +} + +/** The hub one client holds. */ +export function createPushHub(deps: { + transport: Transport; + userId: string; + capabilities: () => Promise; +}): { subscribe(topics: readonly WireTopic[], options: SubscribeOptions): Subscription } { + const handles = new Set(); + /** Every subscribed topic, counted by handle. */ + const counts = new Map(); + /** Topics the current socket hears. */ + const granted = new Set(); + /** Topics the mint left out of its answer, until asked again. */ + const refused = new Set(); + /** Topics a mint is asking for now. */ + const minting = new Set(); + + let mode: "unknown" | "checking" | "none" | "push" = "unknown"; + let socket: WebSocket | undefined; + let state: "idle" | "connecting" | "open" = "idle"; + /** Whether the socket's process hears other processes. False until its first frame. */ + let crosses = false; + let firstCrossingFrame = true; + /** A connect has failed since the socket was last open: the timer runs meanwhile. */ + let lapsed = false; + let failures = 0; + let retryTimer: ReturnType | undefined; + /** Bumped on each connect and teardown, so a stale answer is ignored. */ + let generation = 0; + + const call = (handle: Handle, notice: WireNotice | null): void => { + if (!handles.has(handle)) return; + try { + handle.onChange(notice); + } catch (error) { + if (warnedHandler) return; + warnedHandler = true; + console.error("[flow-state] a client.subscribe onChange threw; later failures are not logged.", error); + } + }; + + const covered = (handle: Handle): boolean => + state === "open" && crosses && handle.keys.every((key) => granted.has(key)); + /** A first answer is on its way (capabilities, or a connect): no timer yet. */ + const waiting = (): boolean => (mode === "checking" || state === "connecting") && !lapsed; + + const tick = (handle: Handle): void => { + call(handle, null); + const asking = handle.keys.filter((key) => refused.has(key)); + if (asking.length > 0) void mintMore(asking); + }; + + /** Start or stop each handle's timer to match what push covers now. */ + const updateTimers = (): void => { + for (const handle of handles) { + const wanted = handle.pollIntervalMs !== undefined && !covered(handle) && !waiting(); + if (wanted && handle.timer === undefined) { + handle.timer = setInterval(() => tick(handle), handle.pollIntervalMs); + } else if (!wanted && handle.timer !== undefined) { + clearInterval(handle.timer); + handle.timer = undefined; + } + } + }; + + const allTopics = (): WireTopic[] => [...counts.values()].map((entry) => entry.topic); + + const mint = (topics: WireTopic[]): Promise => + deps.transport.json(`/api/flows/users/${encodeURIComponent(deps.userId)}/stream`, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ topics }) + }); + + /** Record which of `asked` the answer granted; returns the newly granted keys. */ + const record = (asked: readonly string[], answer: { topics: WireTopic[] }): Set => { + const answered = new Set(answer.topics.map(wireTopicKey)); + const added = new Set(); + for (const key of asked) { + if (!counts.has(key)) continue; + if (answered.has(key)) { + refused.delete(key); + if (!granted.has(key)) added.add(key); + granted.add(key); + } else { + refused.add(key); + } + } + return added; + }; + + const touched = (added: Set): void => { + for (const handle of [...handles]) if (handle.keys.some((key) => added.has(key))) call(handle, null); + }; + + /** Ask for topics the open socket doesn't hear yet. */ + const mintMore = async (keys: readonly string[]): Promise => { + if (state !== "open") return; + const asking = keys.filter((key) => counts.has(key) && !granted.has(key) && !minting.has(key)); + if (asking.length === 0) return; + for (const key of asking) minting.add(key); + const at = generation; + let answer: PushMintAnswer | undefined; + try { + answer = await mint(asking.map((key) => counts.get(key)!.topic)); + } catch { + answer = undefined; + } + for (const key of asking) minting.delete(key); + if (at !== generation || state !== "open" || socket === undefined) return; + if (answer === undefined || answer.transport !== "websocket") { + for (const key of asking) if (counts.has(key)) refused.add(key); + updateTimers(); + return; + } + if (answer.topics.length > 0) socket.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); + const added = record(asking, answer); + updateTimers(); + touched(added); + }; + + const scheduleRetry = (): void => { + failures += 1; + lapsed = true; + const delay = Math.min(RETRY_MAX_MS, RETRY_BASE_MS * 2 ** Math.max(0, failures - 1)); + clearTimeout(retryTimer); + retryTimer = setTimeout(() => void connect(), delay); + updateTimers(); + }; + + const socketUrl = (path: string): string | undefined => { + const url = deps.transport.url(`/api/flows${path}`); + let absolute: URL; + try { + const base = (globalThis as { location?: { href?: string } }).location?.href; + absolute = base !== undefined ? new URL(url, base) : new URL(url); + } catch { + return undefined; + } + if (absolute.protocol === "http:") absolute.protocol = "ws:"; + else if (absolute.protocol === "https:") absolute.protocol = "wss:"; + else return undefined; + return absolute.toString(); + }; + + /** No push for this client: every subscription reads on its timer. */ + const noPush = (): void => { + mode = "none"; + state = "idle"; + updateTimers(); + }; + + const connect = async (): Promise => { + if (handles.size === 0 || mode !== "push" || state !== "idle") return; + clearTimeout(retryTimer); + state = "connecting"; + const at = ++generation; + const asked = allTopics(); + updateTimers(); + let answer: PushMintAnswer; + try { + answer = await mint(asked); + } catch { + if (at !== generation) return; + state = "idle"; + scheduleRetry(); + return; + } + if (at !== generation) return; + if (answer.transport !== "websocket") { + if (!warnedTransport) { + warnedTransport = true; + console.warn(`[flow-state] client.subscribe: this client has no "${answer.transport}" push; reading on its timer.`); + } + noPush(); + return; + } + const WebSocketImpl = (globalThis as { WebSocket?: typeof WebSocket }).WebSocket; + const url = socketUrl(answer.path); + if (WebSocketImpl === undefined || url === undefined) { + noPush(); + return; + } + const ws = new WebSocketImpl(url); + socket = ws; + let opened = false; + /** + * The socket is gone. A browser reports a failed handshake as an error + * and a close; Node's WebSocket reports only the error. Either counts + * once, whichever comes first. + */ + const ended = (code: number | undefined): void => { + clearTimeout(handshakeTimer); + if (socket !== ws) return; + socket = undefined; + state = "idle"; + crosses = false; + granted.clear(); + generation += 1; + try { + ws.close(); + } catch { + // Already closing. + } + if (handles.size === 0) return; + if (!opened || (code !== undefined && FAILED_CONNECT_CODES.has(code))) { + scheduleRetry(); + return; + } + // A drop (or the server's hourly close): reconnect at once. If that + // fails, the timer runs from then. + void connect(); + }; + // A handshake that never answers is a failed connect too. + const handshakeTimer = setTimeout(() => ended(undefined), HANDSHAKE_TIMEOUT_MS); + ws.addEventListener("open", () => { + if (socket !== ws) return; + clearTimeout(handshakeTimer); + opened = true; + state = "open"; + lapsed = false; + failures = 0; + crosses = false; + firstCrossingFrame = true; + granted.clear(); + ws.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); + const added = record( + asked.map(wireTopicKey), + answer + ); + updateTimers(); + // Each connect reads once (ER-6): it may have missed changes. + touched(added); + // Topics subscribed while this connect was in flight. + void mintMore([...counts.keys()].filter((key) => !granted.has(key) && !refused.has(key))); + }); + ws.addEventListener("message", (event) => { + if (socket !== ws) return; + let frame: PushServerFrame; + try { + frame = JSON.parse(String((event as MessageEvent).data)) as PushServerFrame; + } catch { + return; + } + if (frame.type === "crossing") { + const first = firstCrossingFrame; + firstCrossingFrame = false; + const changed = frame.crosses !== crosses; + crosses = frame.crosses; + updateTimers(); + // A change of the answer reads once, as a connect does. The first + // frame follows the connect's own read, so it adds none. + if (changed && !first) touched(new Set(granted)); + return; + } + if (frame.type === "notice") { + const { type: _type, ...notice } = frame; + for (const handle of [...handles]) { + if (handle.topics.some((subscribed) => covers(subscribed, notice.topic))) call(handle, notice); + } + } + }); + ws.addEventListener("close", (event) => ended((event as CloseEvent).code)); + ws.addEventListener("error", () => ended(undefined)); + }; + + const start = async (): Promise => { + if (mode !== "unknown") { + if (mode === "push") void connect(); + updateTimers(); + return; + } + mode = "checking"; + let push: FlowCapabilities["push"]; + try { + push = (await deps.capabilities()).push; + } catch { + // Unknown: try again later, reading on the timer meanwhile. + mode = "unknown"; + lapsed = true; + clearTimeout(retryTimer); + retryTimer = setTimeout(() => void start(), RETRY_BASE_MS); + updateTimers(); + return; + } + // An older server sends no `push`: the same as none (BP-030). + if (push == null) { + noPush(); + return; + } + mode = "push"; + void connect(); + }; + + const stop = (): void => { + generation += 1; + clearTimeout(retryTimer); + const ws = socket; + socket = undefined; + state = "idle"; + // `ended` ignores a socket that is no longer the current one. + crosses = false; + lapsed = false; + failures = 0; + granted.clear(); + refused.clear(); + if (mode === "checking") mode = "unknown"; + ws?.close(1000); + }; + + return { + subscribe(topics, options) { + const handle: Handle = { + topics: [...topics], + keys: [...new Set(topics.map(wireTopicKey))], + onChange: options.onChange, + ...(options.pollIntervalMs !== undefined ? { pollIntervalMs: options.pollIntervalMs } : {}) + }; + const fresh: string[] = []; + handles.add(handle); + for (const [index, key] of handle.keys.entries()) { + const entry = counts.get(key); + if (entry !== undefined) entry.count += 1; + else { + counts.set(key, { topic: topics.find((t) => wireTopicKey(t) === key) ?? topics[index]!, count: 1 }); + fresh.push(key); + } + } + if (state === "open") { + if (fresh.length > 0) void mintMore(fresh); + // Every topic is already heard: this subscription's connect is now. + else if (handle.keys.every((key) => granted.has(key))) queueMicrotask(() => call(handle, null)); + updateTimers(); + } else if (mode === "unknown" || (mode === "push" && state === "idle" && !lapsed)) { + void start(); + } else { + updateTimers(); + } + + let closed = false; + return { + close() { + if (closed) return; + closed = true; + handles.delete(handle); + if (handle.timer !== undefined) clearInterval(handle.timer); + const gone: WireTopic[] = []; + for (const key of handle.keys) { + const entry = counts.get(key); + if (entry === undefined) continue; + entry.count -= 1; + if (entry.count > 0) continue; + counts.delete(key); + refused.delete(key); + if (granted.delete(key)) gone.push(entry.topic); + } + if (handles.size === 0) { + stop(); + return; + } + if (gone.length > 0 && state === "open" && socket !== undefined) { + socket.send(JSON.stringify({ type: "unsubscribe", topics: gone })); + } + } + }; + } + }; +} diff --git a/packages/client/src/types/index.ts b/packages/client/src/types/index.ts index cc756c0e5f..81059f4192 100644 --- a/packages/client/src/types/index.ts +++ b/packages/client/src/types/index.ts @@ -15,18 +15,12 @@ import type { RequestStatus, RequestStatusEvent, RequestStreamEvent, - ResourceContentCreatedEvent, - ResourceContentDeletedEvent, - ResourceContentUpdatedEvent, - ScopeStateChangedEvent, SessionItemEvent, SessionMetadataChangedEvent, SessionRunsChangedEvent, - SessionStreamEvent, - UserDebugEvent, - UserResourceChangedEvent, - UserStreamEvent + SessionStreamEvent } from "@flow-state-dev/core/items"; +import type { PushCapability } from "@flow-state-dev/contracts"; import type { OutputItem } from "@flow-state-dev/core/items"; import type { ActionInputSchema, @@ -114,10 +108,17 @@ export type FlowListEntry = { export type { ActionInputSchema, ActionFieldSchema, ActionFieldType } from "@flow-state-dev/core/types"; /** - * Capability flags advertised by the server. + * What the server supports, from `GET /capabilities`. */ export type FlowCapabilities = { + /** Always `false`: the server serves no user SSE stream. */ userStream: boolean; + /** + * The push `client.subscribe` hears change notices on, or `null` when the + * server has none (a serverless host). Missing from an older server's + * answer, which means none. It only advertises: the mint's answer decides. + */ + push?: PushCapability | null; }; /** @@ -497,11 +498,6 @@ export interface RequestStreamHandle { /** * Handle returned by optional user-stream SSE connections. */ -export interface UserStreamHandle { - close(): void; - readonly lastEventId?: string; -} - /** * Callback set for request-stream SSE events. */ @@ -707,17 +703,3 @@ export type SessionSSECallbacks = { /** An event the client could not parse. Connection drops are retried, not reported. */ onError?: (error: Error) => void; }; - -/** - * Callback set for optional user-stream SSE events. - */ -export type UserSSECallbacks = { - onResourceChanged?: (event: UserResourceChangedEvent) => void; - onResourceContentUpdated?: (event: ResourceContentUpdatedEvent) => void; - onResourceContentCreated?: (event: ResourceContentCreatedEvent) => void; - onResourceContentDeleted?: (event: ResourceContentDeletedEvent) => void; - onScopeStateChanged?: (event: ScopeStateChangedEvent) => void; - onDebug?: (event: UserDebugEvent) => void; - onEvent?: (event: UserStreamEvent) => void; - onError?: (error: Error) => void; -}; diff --git a/packages/client/test/one-transport.test.ts b/packages/client/test/one-transport.test.ts index 2c7da45f27..ab2f25df0e 100644 --- a/packages/client/test/one-transport.test.ts +++ b/packages/client/test/one-transport.test.ts @@ -32,6 +32,12 @@ afterEach(() => { }); function answer(url: string): Response { + if (url.endsWith("/capabilities")) { + return new Response(JSON.stringify({ userStream: false, push: { transport: "websocket" } }), { + status: 200, + headers: { "content-type": "application/json" } + }); + } if (url.includes("/stream")) { return new Response("", { status: 200, headers: { "content-type": "text/event-stream" } }); } @@ -75,11 +81,12 @@ describe("one client is one transport", () => { const requestStream = sent.stream({}); const sessionStream = fsd.sessions.stream("sess_1"); - const userStream = fsd.stream({}); + // The push mint goes through the same fetcher (FIX-2428). + const subscription = fsd.subscribe([{ scope: "user" }], { onChange: () => {} }); await vi.waitFor(() => expect(seen.filter((url) => url.includes("/stream"))).toHaveLength(3)); requestStream.close(); sessionStream.close(); - userStream.close(); + subscription.close(); expect(built.transports).toBe(1); expect(globalFetch).not.toHaveBeenCalled(); diff --git a/packages/client/test/stream-client.test.ts b/packages/client/test/stream-client.test.ts index 805a01ec5e..754820fe57 100644 --- a/packages/client/test/stream-client.test.ts +++ b/packages/client/test/stream-client.test.ts @@ -3,8 +3,7 @@ import { createClient, createSSEClientFromResponse, type ClientFetch, - type RequestStreamOptions, - type UserStreamOptions + type RequestStreamOptions } from "../src"; /** A request's stream, opened through one client's `request(id).stream()`. */ @@ -13,12 +12,6 @@ function requestStream({ url, fetcher, ...options }: RequestStreamOptions & { ur return createClient({ userId: "devuser", baseUrl: "", fetcher }).flow(flow!).request(id!).stream(options); } -/** The user stream, opened through one client's `stream()`. */ -function userStream({ url, fetcher, ...options }: UserStreamOptions & { url: string; fetcher: ClientFetch }) { - const [, userId] = /\/api\/flows\/users\/([^/]+)\/stream/.exec(url)!; - return createClient({ userId: userId!, baseUrl: "", fetcher }).stream(options); -} - function requestEventFrame(options: { id: string; event: string; @@ -27,14 +20,6 @@ function requestEventFrame(options: { return `id: ${options.id}\nevent: ${options.event}\ndata: ${JSON.stringify(options.data)}\n\n`; } -function userEventFrame(options: { - id: string; - event: string; - data: Record; -}): string { - return `id: ${options.id}\nevent: ${options.event}\ndata: ${JSON.stringify(options.data)}\n\n`; -} - async function flushSSE(): Promise { await new Promise((resolve) => setTimeout(resolve, 0)); await new Promise((resolve) => setTimeout(resolve, 0)); @@ -542,68 +527,6 @@ describe("request.streamFromResponse", () => { }); }); -describe("client.stream", () => { - it("parses optional user-stream events and dispatches callbacks", async () => { - const onResourceChanged = vi.fn(); - const onScopeStateChanged = vi.fn(); - - const streamBody = [ - userEventFrame({ - id: "devuser:1", - event: "resource.changed", - data: { - stream: "user", - type: "resource.changed", - userId: "devuser", - sequence_number: 1, - ts: 1, - scope: "session", - resourcePath: "docs/1", - changeType: "updated" - } - }), - userEventFrame({ - id: "devuser:2", - event: "scope.state.changed", - data: { - stream: "user", - type: "scope.state.changed", - userId: "devuser", - sequence_number: 2, - ts: 2, - scope: "session", - scopeId: "sess_1", - changeType: "updated" - } - }) - ].join(""); - - const fetcher = vi.fn(async () => - new Response(streamBody, { - status: 200, - headers: { - "content-type": "text/event-stream" - } - }) - ); - - const handle = userStream({ - url: "/api/flows/users/devuser/stream", - fetcher, - onResourceChanged, - onScopeStateChanged - }); - - await flushSSE(); - - expect(onResourceChanged).toHaveBeenCalledTimes(1); - expect(onScopeStateChanged).toHaveBeenCalledTimes(1); - expect(handle.lastEventId).toBe("devuser:2"); - - handle.close(); - }); -}); - describe("request.stream — heartbeat parsing", () => { it("invokes onHeartbeat for `: ping` comment frames and not for normal events", async () => { const onHeartbeat = vi.fn(); diff --git a/packages/client/test/subscribe.test.ts b/packages/client/test/subscribe.test.ts new file mode 100644 index 0000000000..424a7f811d --- /dev/null +++ b/packages/client/test/subscribe.test.ts @@ -0,0 +1,394 @@ +/** + * `client.subscribe` (FIX-2428): one socket per client, minted through the + * client's own fetcher, and a timer wherever push can miss a change: no + * push, the socket down, its bus not crossing processes, or a topic refused. + * + * `onChange` is passed the notice that woke it, and `null` for a connect, a + * reconnect, a change of the crossing answer, or a poll. + */ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { createClient, topic, type ClientFetch, type WireNotice, type WireTopic } from "../src"; + +/** A WebSocket double the test drives: open, deliver a frame, drop. */ +class FakeSocket { + static all: FakeSocket[] = []; + readonly sent: unknown[] = []; + readyState = 0; + closedWith: number | undefined; + private listeners: Record void>> = {}; + constructor(readonly url: string) { + FakeSocket.all.push(this); + } + addEventListener(type: string, listener: (event: unknown) => void): void { + (this.listeners[type] ??= []).push(listener); + } + send(data: string): void { + this.sent.push(JSON.parse(data)); + } + close(code = 1000): void { + if (this.readyState === 3) return; + this.closedWith = code; + this.readyState = 3; + this.emit("close", { code }); + } + // --- the test's side --- + open(): void { + if (this.readyState === 1) return; + this.readyState = 1; + this.emit("open", {}); + } + frame(frame: unknown): void { + this.emit("message", { data: JSON.stringify(frame) }); + } + drop(code = 1006): void { + this.readyState = 3; + this.emit("close", { code }); + } + /** A handshake that fails as Node's WebSocket reports it: an error, and no close. */ + fail(): void { + this.emit("error", {}); + } + private emit(type: string, event: unknown): void { + for (const listener of this.listeners[type] ?? []) listener(event); + } +} + +type MintCall = { topics: WireTopic[]; authorization: string | null }; + +/** A server double: capabilities, and a mint that grants what `grant` allows. */ +function server(options: { push?: unknown; grant?: (topic: WireTopic) => boolean; transport?: string; mintStatus?: () => number } = {}) { + const mints: MintCall[] = []; + let ticket = 0; + const fetcher: ClientFetch = async (input, init) => { + const url = String(input); + const headers = new Headers(init?.headers); + if (url.endsWith("/capabilities")) { + const body = options.push === undefined ? { userStream: false } : { userStream: false, push: options.push }; + return Response.json(body); + } + if (url.endsWith("/users/u1/stream") && init?.method === "POST") { + const { topics } = JSON.parse(String(init.body)) as { topics: WireTopic[] }; + mints.push({ topics, authorization: headers.get("authorization") }); + const status = options.mintStatus?.() ?? 200; + if (status !== 200) return Response.json({ error: "no" }, { status }); + const granted = topics.filter(options.grant ?? (() => true)); + if (options.transport === "ably") { + return Response.json({ transport: "ably", tokenRequest: {}, channels: [], topics: granted }); + } + ticket += 1; + return Response.json({ transport: "websocket", ticket: `t${ticket}`, path: "/users/u1/stream", topics: granted }); + } + return Response.json({ error: "unexpected" }, { status: 500 }); + }; + const wrapped: ClientFetch = (input, init) => + fetcher(input, { ...init, headers: { ...(init?.headers as Record), authorization: "Bearer secret" } }); + return { fetcher: wrapped, mints }; +} + +function client(fetcher: ClientFetch) { + return createClient({ userId: "u1", baseUrl: "http://host:3000", fetcher }); +} + +/** Let promise chains settle without moving the clock. */ +async function settle(): Promise { + for (let i = 0; i < 5; i += 1) await vi.advanceTimersByTimeAsync(0); +} + +const S1 = topic.session("s1"); +const notice = (topicValue: WireTopic, kind: WireNotice["kind"] = "items"): WireNotice => ({ topic: topicValue, kind }); + +beforeEach(() => { + FakeSocket.all = []; + vi.useFakeTimers(); + vi.stubGlobal("WebSocket", FakeSocket); +}); + +afterEach(() => { + vi.useRealTimers(); + vi.unstubAllGlobals(); +}); + +/** Subscribe, let the mint answer, open the socket, and send `crosses`. */ +async function connected(fsd: ReturnType, topics: WireTopic[], pollIntervalMs: number | undefined, crosses?: boolean) { + const onChange = vi.fn(); + const sub = fsd.subscribe(topics, { onChange, ...(pollIntervalMs !== undefined ? { pollIntervalMs } : {}) }); + await settle(); + const socket = FakeSocket.all.at(-1)!; + socket.open(); + if (crosses !== undefined) socket.frame({ type: "crossing", crosses }); + return { sub, onChange, socket }; +} + +describe("client.subscribe on a host with no push", () => { + it("reads on its timer, passing null, and never mints or opens a socket", async () => { + const { fetcher, mints } = server({ push: null }); + const onChange = vi.fn(); + client(fetcher).subscribe([S1], { onChange, pollIntervalMs: 1000 }); + await settle(); + expect(onChange).not.toHaveBeenCalled(); + await vi.advanceTimersByTimeAsync(3000); + expect(onChange.mock.calls).toEqual([[null], [null], [null]]); + expect(mints).toEqual([]); + expect(FakeSocket.all).toEqual([]); + }); + + it("treats an older server with no push field as no push", async () => { + const { fetcher, mints } = server(); + const onChange = vi.fn(); + client(fetcher).subscribe([S1], { onChange, pollIntervalMs: 1000 }); + await vi.advanceTimersByTimeAsync(1000); + expect(onChange).toHaveBeenCalledTimes(1); + expect(mints).toEqual([]); + }); + + it("with pollIntervalMs omitted, has no timer at all", async () => { + const { fetcher } = server({ push: null }); + const onChange = vi.fn(); + client(fetcher).subscribe([S1], { onChange }); + await vi.advanceTimersByTimeAsync(60_000); + expect(onChange).not.toHaveBeenCalled(); + }); + + it("stops reading once closed", async () => { + const { fetcher } = server({ push: null }); + const onChange = vi.fn(); + const sub = client(fetcher).subscribe([S1], { onChange, pollIntervalMs: 1000 }); + await vi.advanceTimersByTimeAsync(1000); + sub.close(); + await vi.advanceTimersByTimeAsync(5000); + expect(onChange).toHaveBeenCalledTimes(1); + }); +}); + +describe("client.subscribe on a host with push", () => { + it("mints through the client's own fetcher, then sends the ticket as the socket's first message", async () => { + const { fetcher, mints } = server({ push: { transport: "websocket" } }); + const { socket } = await connected(client(fetcher), [S1, topic.user()], 1000); + expect(mints).toEqual([{ topics: [S1, topic.user()], authorization: "Bearer secret" }]); + expect(socket.url).toBe("ws://host:3000/api/flows/users/u1/stream"); + expect(socket.sent[0]).toEqual({ type: "subscribe", ticket: "t1" }); + }); + + it("runs onChange once on connect, and passes each notice that wakes it", async () => { + const { fetcher } = server({ push: { transport: "websocket" } }); + const { onChange, socket } = await connected(client(fetcher), [S1], undefined, true); + expect(onChange.mock.calls).toEqual([[null]]); + socket.frame({ type: "notice", ...notice(S1, "request"), origin: { requestId: "r1" } }); + expect(onChange.mock.calls[1]).toEqual([{ topic: S1, kind: "request", origin: { requestId: "r1" } }]); + }); + + it("keeps reading on its timer until the first crossing frame says crosses: true, then stops", async () => { + const { fetcher } = server({ push: { transport: "websocket" } }); + const { onChange, socket } = await connected(client(fetcher), [S1], 1000); + onChange.mockClear(); + await vi.advanceTimersByTimeAsync(2000); + expect(onChange).toHaveBeenCalledTimes(2); + socket.frame({ type: "crossing", crosses: true }); + onChange.mockClear(); + await vi.advanceTimersByTimeAsync(10_000); + // The change of the answer runs it once, as a connect does; no polls. + expect(onChange.mock.calls).toEqual([]); + }); + + it("reads on its timer while the bus says it doesn't cross, and once on each change of the answer", async () => { + const { fetcher } = server({ push: { transport: "websocket" } }); + const { onChange, socket } = await connected(client(fetcher), [S1], 1000, false); + onChange.mockClear(); + await vi.advanceTimersByTimeAsync(3000); + expect(onChange).toHaveBeenCalledTimes(3); + onChange.mockClear(); + socket.frame({ type: "crossing", crosses: true }); + expect(onChange.mock.calls).toEqual([[null]]); + await vi.advanceTimersByTimeAsync(3000); + expect(onChange).toHaveBeenCalledTimes(1); + socket.frame({ type: "crossing", crosses: false }); + expect(onChange).toHaveBeenCalledTimes(2); + await vi.advanceTimersByTimeAsync(1000); + expect(onChange).toHaveBeenCalledTimes(3); + }); + + it("still runs onChange on a notice while it reads on its timer", async () => { + const { fetcher } = server({ push: { transport: "websocket" } }); + const { onChange, socket } = await connected(client(fetcher), [S1], 1000, false); + socket.frame({ type: "notice", ...notice(S1) }); + expect(onChange).toHaveBeenLastCalledWith(notice(S1)); + }); + + it("passes a notice only to the subscriptions whose topics cover it", async () => { + const { fetcher } = server({ push: { transport: "websocket" } }); + const fsd = client(fetcher); + const whole = await connected(fsd, [S1], undefined, true); + const tasks = vi.fn(); + fsd.subscribe([topic.session("s1", { resource: "tasks" })], { onChange: tasks }); + const other = vi.fn(); + fsd.subscribe([topic.session("s2")], { onChange: other }); + await settle(); + tasks.mockClear(); + other.mockClear(); + whole.onChange.mockClear(); + whole.socket.frame({ type: "notice", ...notice(topic.session("s1", { resource: "plan" })) }); + whole.socket.frame({ type: "notice", ...notice(topic.session("s1", { resource: "tasks" })) }); + expect(whole.onChange).toHaveBeenCalledTimes(2); + expect(tasks.mock.calls).toEqual([[notice(topic.session("s1", { resource: "tasks" }))]]); + expect(other).not.toHaveBeenCalled(); + }); + + it("shares one socket across subscriptions, mints only what is new, and closes it with the last handle", async () => { + const { fetcher, mints } = server({ push: { transport: "websocket" } }); + const fsd = client(fetcher); + const first = await connected(fsd, [S1], undefined, true); + const onChange = vi.fn(); + const second = fsd.subscribe([S1, topic.org()], { onChange }); + await settle(); + expect(FakeSocket.all).toHaveLength(1); + expect(mints.map((call) => call.topics)).toEqual([[S1], [topic.org()]]); + expect(first.socket.sent.at(-1)).toEqual({ type: "subscribe", ticket: "t2" }); + // Its connect: once, when the socket covers it. + expect(onChange.mock.calls).toEqual([[null]]); + + second.close(); + expect(first.socket.sent.at(-1)).toEqual({ type: "unsubscribe", topics: [topic.org()] }); + expect(first.socket.closedWith).toBeUndefined(); + first.sub.close(); + expect(first.socket.closedWith).toBe(1000); + }); + + it("mints again on a reconnect, reads once, and reads on its timer from the first failed reconnect", async () => { + let mintStatus = 200; + const { fetcher, mints } = server({ push: { transport: "websocket" }, mintStatus: () => mintStatus }); + const { onChange, socket } = await connected(client(fetcher), [S1], 1000, true); + onChange.mockClear(); + mintStatus = 503; + socket.drop(); + await settle(); + // The first reconnect is tried at once, and failed: the timer is on. + expect(mints).toHaveLength(2); + await vi.advanceTimersByTimeAsync(1000); + expect(onChange.mock.calls).toEqual([[null]]); + mintStatus = 200; + await vi.advanceTimersByTimeAsync(5000); + const again = FakeSocket.all.at(-1)!; + expect(again).not.toBe(socket); + onChange.mockClear(); + again.open(); + again.frame({ type: "crossing", crosses: true }); + // The reconnect reads once; then push covers it and the timer stops. + expect(onChange.mock.calls).toEqual([[null]]); + await vi.advanceTimersByTimeAsync(5000); + expect(onChange).toHaveBeenCalledTimes(1); + }); + + it("reads on its timer and retries when the handshake fails with an error and no close", async () => { + const { fetcher, mints } = server({ push: { transport: "websocket" } }); + const onChange = vi.fn(); + client(fetcher).subscribe([S1], { onChange, pollIntervalMs: 1000 }); + await settle(); + FakeSocket.all.at(-1)!.fail(); + await vi.advanceTimersByTimeAsync(1000); + expect(onChange.mock.calls).toEqual([[null]]); + expect(mints).toHaveLength(2); + expect(FakeSocket.all).toHaveLength(2); + }); + + it("gives up on a handshake that never answers, and reads on its timer meanwhile", async () => { + const { fetcher, mints } = server({ push: { transport: "websocket" } }); + const onChange = vi.fn(); + client(fetcher).subscribe([S1], { onChange, pollIntervalMs: 1000 }); + await settle(); + await vi.advanceTimersByTimeAsync(9_000); + expect(onChange).not.toHaveBeenCalled(); + await vi.advanceTimersByTimeAsync(2_000); + expect(FakeSocket.all[0]!.closedWith).toBeDefined(); + expect(onChange).toHaveBeenCalled(); + expect(mints.length).toBeGreaterThanOrEqual(2); + }); + + it("reconnects at once when the server ends the socket at its age limit", async () => { + const { fetcher, mints } = server({ push: { transport: "websocket" } }); + const { socket } = await connected(client(fetcher), [S1], 1000, true); + socket.drop(4000); + await settle(); + expect(mints).toHaveLength(2); + expect(FakeSocket.all).toHaveLength(2); + }); + + it("backs off, and reads on its timer, when the server refuses its ticket", async () => { + const { fetcher, mints } = server({ push: { transport: "websocket" } }); + const { onChange, socket } = await connected(client(fetcher), [S1], 1000, true); + onChange.mockClear(); + socket.drop(4401); + await settle(); + expect(mints).toHaveLength(1); + await vi.advanceTimersByTimeAsync(1000); + expect(onChange).toHaveBeenCalledTimes(1); + expect(mints).toHaveLength(2); + }); + + it("treats a refused topic as not covered: reads on its timer, and asks for it again at the poll pace", async () => { + let allow = false; + const { fetcher, mints } = server({ push: { transport: "websocket" }, grant: (t) => t.scope !== "session" || allow }); + const { onChange, socket } = await connected(client(fetcher), [S1], 1000, true); + // A refused topic gets no connect read and is not heard. + expect(onChange).not.toHaveBeenCalled(); + await vi.advanceTimersByTimeAsync(1000); + expect(onChange.mock.calls).toEqual([[null]]); + expect(mints.map((call) => call.topics)).toEqual([[S1], [S1]]); + allow = true; + onChange.mockClear(); + await vi.advanceTimersByTimeAsync(1000); + // Granted on this retry: it reads once, as a connect, and its timer stops. + expect(socket.sent.at(-1)).toEqual({ type: "subscribe", ticket: "t3" }); + expect(onChange.mock.calls).toEqual([[null], [null]]); + onChange.mockClear(); + await vi.advanceTimersByTimeAsync(5000); + expect(onChange).not.toHaveBeenCalled(); + }); + + it("with pollIntervalMs omitted, tries a refused topic again on reconnect only", async () => { + let allow = false; + const { fetcher, mints } = server({ push: { transport: "websocket" }, grant: () => allow }); + const { onChange, socket } = await connected(client(fetcher), [S1], undefined, true); + await vi.advanceTimersByTimeAsync(60_000); + expect(mints).toHaveLength(1); + expect(onChange).not.toHaveBeenCalled(); + allow = true; + socket.drop(); + await settle(); + FakeSocket.all.at(-1)!.open(); + expect(onChange.mock.calls).toEqual([[null]]); + }); + + it("decides by the mint answer's transport, not the capabilities it read", async () => { + const { fetcher } = server({ push: { transport: "ably" } }); + const { socket } = await connected(client(fetcher), [S1], 1000, true); + expect(socket.sent[0]).toEqual({ type: "subscribe", ticket: "t1" }); + }); + + it("reads on its timer when the mint answers a transport this client does not build (Ably)", async () => { + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); + const { fetcher } = server({ push: { transport: "ably" }, transport: "ably" }); + const onChange = vi.fn(); + client(fetcher).subscribe([S1], { onChange, pollIntervalMs: 1000 }); + await vi.advanceTimersByTimeAsync(2000); + expect(FakeSocket.all).toEqual([]); + expect(onChange).toHaveBeenCalledTimes(2); + expect(warn).toHaveBeenCalled(); + warn.mockRestore(); + }); + + it("keeps calling the other subscriptions when one onChange throws", async () => { + const error = vi.spyOn(console, "error").mockImplementation(() => {}); + const { fetcher } = server({ push: { transport: "websocket" } }); + const fsd = client(fetcher); + fsd.subscribe([S1], { + onChange: () => { + throw new Error("boom"); + } + }); + const { onChange, socket } = await connected(fsd, [S1], undefined, true); + onChange.mockClear(); + socket.frame({ type: "notice", ...notice(S1) }); + expect(onChange).toHaveBeenCalledTimes(1); + error.mockRestore(); + }); +}); diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts index 4b594df2a0..8cb9827a46 100644 --- a/packages/contracts/src/index.ts +++ b/packages/contracts/src/index.ts @@ -27,5 +27,17 @@ export type { ManifestDomain, ManifestEntry, ManifestSource } from "./types/mani export { topic } from "./types/change-notice"; export type { ChangeKind, TopicOptions, TopicScope, WireTopic } from "./types/change-notice"; +// Push delivery (FIX-2428): the mint's answer, the socket's frames and the +// push a server advertises. +export { PUSH_CLOSE_CODES, wireTopicKey } from "./types/push-delivery"; +export type { + PushCapability, + PushClientFrame, + PushMintAnswer, + PushMintRequest, + PushServerFrame, + WireNotice +} from "./types/push-delivery"; + // Deterministic blockInstanceId construction/parsing (pure string logic). export * from "./block-instance-id"; diff --git a/packages/contracts/src/items/events.ts b/packages/contracts/src/items/events.ts index e6c37cc6d4..509458722e 100644 --- a/packages/contracts/src/items/events.ts +++ b/packages/contracts/src/items/events.ts @@ -11,14 +11,7 @@ export type RequestEventBase = { ts: number; }; -export type UserEventBase = { - stream: "user"; - userId: string; - sequence_number: number; - ts: number; -}; - -export type EventBase = RequestEventBase | UserEventBase; +export type EventBase = RequestEventBase; export type RequestCreatedEvent = RequestEventBase & { type: "request.created"; @@ -115,54 +108,7 @@ export type RequestResourceChangedEvent = RequestEventBase & { changeType: "created" | "updated" | "deleted"; }; -export type UserResourceChangedEvent = UserEventBase & { - type: "resource.changed"; - scope: "session" | "user" | "org"; - resourcePath: string; - changeType: "created" | "updated" | "deleted"; -}; - -export type ResourceChangedEvent = RequestResourceChangedEvent | UserResourceChangedEvent; - -/** - * Pushed to clients that have fetched a resource's content when its content is updated. - * Only sent to clients with active content subscriptions (inferred from prior GET calls). - */ -export type ResourceContentUpdatedEvent = UserEventBase & { - type: "resource.content.updated"; - scope: "session" | "user" | "org"; - ref: string; - topic?: string; - content: string; -}; - -/** - * Pushed to subscribed clients when a new collection item is created. - * Does not include content — the client fetches if interested. - */ -export type ResourceContentCreatedEvent = UserEventBase & { - type: "resource.content.created"; - scope: "session" | "user" | "org"; - ref: string; - topic: string; -}; - -/** - * Pushed to subscribed clients when a collection item is deleted. - */ -export type ResourceContentDeletedEvent = UserEventBase & { - type: "resource.content.deleted"; - scope: "session" | "user" | "org"; - ref: string; - topic: string; -}; - -export type ScopeStateChangedEvent = UserEventBase & { - type: "scope.state.changed"; - scope: "session" | "user" | "org"; - scopeId: string; - changeType: "updated" | "deleted"; -}; +export type ResourceChangedEvent = RequestResourceChangedEvent; export type SessionMetadataChangedEvent = RequestEventBase & { type: "session.metadata.changed"; @@ -179,23 +125,13 @@ export type RequestDebugEvent = RequestEventBase & { data: unknown; }; -export type UserDebugEvent = UserEventBase & { - type: "debug"; - name: string; - data: unknown; -}; - -export type DebugEvent = RequestDebugEvent | UserDebugEvent; +export type DebugEvent = RequestDebugEvent; export type RequestPingEvent = RequestEventBase & { type: "ping"; }; -export type UserPingEvent = UserEventBase & { - type: "ping"; -}; - -export type PingEvent = RequestPingEvent | UserPingEvent; +export type PingEvent = RequestPingEvent; export type RequestStreamEvent = | RequestCreatedEvent @@ -212,16 +148,8 @@ export type RequestStreamEvent = | RequestDebugEvent | RequestPingEvent; -export type UserStreamEvent = - | UserResourceChangedEvent - | ResourceContentUpdatedEvent - | ResourceContentCreatedEvent - | ResourceContentDeletedEvent - | ScopeStateChangedEvent - | UserDebugEvent - | UserPingEvent; - -export type StreamEvent = RequestStreamEvent | UserStreamEvent; +/** Every event a request stream sends. */ +export type StreamEvent = RequestStreamEvent; /** * Fields every session-stream event carries. diff --git a/packages/contracts/src/items/index.ts b/packages/contracts/src/items/index.ts index 9aa8ca0803..9db324bcea 100644 --- a/packages/contracts/src/items/index.ts +++ b/packages/contracts/src/items/index.ts @@ -95,7 +95,6 @@ export type { RequestStreamEvent, RequestStatus, RequestStatusEvent, - ScopeStateChangedEvent, SessionEventBase, SessionItemEvent, SessionMetadataChangedEvent, @@ -104,13 +103,5 @@ export type { SessionRunsChangedEvent, SessionStreamEvent, ResourceChangedEvent, - ResourceContentCreatedEvent, - ResourceContentDeletedEvent, - ResourceContentUpdatedEvent, - StreamEvent, - UserDebugEvent, - UserEventBase, - UserPingEvent, - UserResourceChangedEvent, - UserStreamEvent + StreamEvent } from "./events"; diff --git a/packages/contracts/src/types/push-delivery.ts b/packages/contracts/src/types/push-delivery.ts new file mode 100644 index 0000000000..8550b624a0 --- /dev/null +++ b/packages/contracts/src/types/push-delivery.ts @@ -0,0 +1,93 @@ +/** + * The push-delivery wire (FIX-2428): what a client and a server say to each + * other to carry change notices to a browser. + * + * A client asks the server which push it has (`GET /capabilities` → + * {@link PushCapability}), then mints: it posts the topics it wants to + * `POST /users/:userId/stream`, and the server checks each one and answers a + * {@link PushMintAnswer} that carries only the topics it granted. On the + * WebSocket arm, the client opens the socket the answer names and sends the + * ticket as its first message ({@link PushClientFrame}); the server sends + * notices and control frames back ({@link PushServerFrame}). + * + * Notices carry no rows. A notice says *that* something under a topic + * changed; the client reads *what* through the route it already reads with. + */ +import type { ChangeKind, WireTopic } from "./change-notice"; + +/** + * The push a server has, as `GET /capabilities` reports it in `push`, or + * `null` when it has none (a serverless host, `createServerApp` alone). It + * only advertises: once a client mints, the answer's `transport` decides. + */ +export type PushCapability = { transport: "websocket" } | { transport: "ably" }; + +/** The body of `POST /users/:userId/stream`: the topics to hear. */ +export type PushMintRequest = { topics: WireTopic[] }; + +/** + * The answer to a mint, keyed by transport. Both arms carry only the granted + * topics: a topic the caller may not hear is absent, exactly as a topic for a + * session that doesn't exist is. + * + * - `websocket`: a short-lived signed `ticket` to send as the socket's first + * message, and the socket's `path`, relative to the flow API's mount. + * - `ably`: an Ably token request and the channels it covers. Defined here so + * an Ably transport shares this answer; no host serves it yet. An open + * Ably connection counts as crossing processes, so no `crossing` frame is + * sent or awaited on that arm. + */ +export type PushMintAnswer = + | { transport: "websocket"; ticket: string; path: string; topics: WireTopic[] } + | { transport: "ably"; tokenRequest: Record; channels: string[]; topics: WireTopic[] }; + +/** + * A change notice as the socket delivers it: the topic it happened under (the + * resource included when the change was narrowed to one), its kind, and the + * request that made it, when a request did. Never the rows that changed. + */ +export type WireNotice = { + topic: WireTopic; + kind: ChangeKind; + origin?: { requestId: string }; +}; + +/** + * What a server sends on the socket. + * + * - `notice`: a change under a topic the socket subscribed. + * - `crossing`: a delivery control frame saying whether this process's bus + * hears changes made in other processes. Sent after the first ticket and on + * each change of the answer. Never a notice kind, and never carries rows. + */ +export type PushServerFrame = ({ type: "notice" } & WireNotice) | { type: "crossing"; crosses: boolean }; + +/** + * What a client sends on the socket. + * + * - `subscribe`: a ticket from the mint. The first message must be one; later + * ones add the topics they grant. A topic is accepted only from a ticket. + * - `unsubscribe`: stop hearing topics. Needs no ticket. + */ +export type PushClientFrame = { type: "subscribe"; ticket: string } | { type: "unsubscribe"; topics: WireTopic[] }; + +/** + * The close codes a server ends a socket with. A client mints again and + * reconnects after any of them. + */ +export const PUSH_CLOSE_CODES = { + /** The socket reached its age limit (an hour). Reconnect at once. */ + maxAge: 4000, + /** A ticket failed its check: a bad signature, expired, or for another user. */ + ticketRefused: 4401, + /** No valid ticket arrived in time after the socket opened. */ + ticketTimeout: 4408, + /** A frame that isn't one of {@link PushClientFrame}. */ + badFrame: 4400 +} as const; + +/** The key two equal wire topics share: scope, session id and resource. */ +export function wireTopicKey(topic: WireTopic): string { + const id = topic.scope === "session" ? topic.id : ""; + return `${topic.scope}\u0000${id}\u0000${topic.resource ?? ""}`; +} diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 9aa0531973..288e3526a0 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -332,6 +332,17 @@ export { createManifestRegistry } from "./manifest/registry"; // client watches. export { topic } from "@flow-state-dev/contracts"; export type { ChangeKind, TopicOptions, TopicScope, WireTopic } from "@flow-state-dev/contracts"; +// Push delivery (FIX-2428): the mint's answer, the socket's frames and the +// push a server advertises. +export { PUSH_CLOSE_CODES, wireTopicKey } from "@flow-state-dev/contracts"; +export type { + PushCapability, + PushClientFrame, + PushMintAnswer, + PushMintRequest, + PushServerFrame, + WireNotice +} from "@flow-state-dev/contracts"; export type { BlockManifestSource, ManifestRegistry } from "./manifest/registry"; export { discoveryTools } from "./manifest/discovery-tools"; export { resourcesManifestSource } from "./manifest/resources-source"; diff --git a/packages/engine/README.md b/packages/engine/README.md index 48d8058199..31edea2067 100644 --- a/packages/engine/README.md +++ b/packages/engine/README.md @@ -676,6 +676,19 @@ publishes. A host that writes to the stores past those entries calls it too, and writes through the registry it returns. It is idempotent: every entry gets the same wrapped stores. +**Push delivery** carries these notices to a browser (FIX-2428). A host that +serves the socket calls `enablePushDelivery(router, { secret? })`: the router +then reports `push: { transport: "websocket" }` in `GET /capabilities` and +answers `POST /users/:userId/stream`, which runs each topic the caller asks for +through the read check its scope uses and signs a 30-second ticket for the ones +it grants. The host hands each socket that opens on `/users/:userId/stream` to +`delivery.openSocket(userId, { send, close })` and moves text frames to the +returned session's `receive`. The session accepts topics only from a ticket for +that user, sends `{ type: "crossing", crosses }` after the first ticket and on +each change of the bus's answer, and closes the socket after an hour. +`serve()` in `@flow-state-dev/node` does all of this; `secret` defaults to a +random key per router. + ## Store list options `SessionListOptions` and `RequestListOptions` are part of the store contract. diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts index 244dbf80d6..8b192233ab 100644 --- a/packages/engine/src/index.ts +++ b/packages/engine/src/index.ts @@ -60,6 +60,11 @@ export type { // default, and the wrap that makes a raw registry's writes publish. export { createInMemoryBus } from "./bus/in-memory-bus"; export { withChangeBus } from "./bus/publish-writes"; +// Push delivery (FIX-2428): a host that serves the socket turns it on, then +// hands each socket that opens on `/users/:userId/stream` to the delivery. +export { enablePushDelivery } from "./push/push-delivery"; +export type { EnablePushDeliveryOptions, PushDelivery } from "./push/push-delivery"; +export type { PushSocket, PushSocketIO } from "./push/socket-session"; export type { BusTopic, ChangeBus, ChangeListener, ChangeNotice } from "./bus/types"; export { createFlowState, isFlowState } from "./flowstate/createFlowState"; export type { diff --git a/packages/engine/src/push/push-delivery.ts b/packages/engine/src/push/push-delivery.ts new file mode 100644 index 0000000000..284ed87261 --- /dev/null +++ b/packages/engine/src/push/push-delivery.ts @@ -0,0 +1,158 @@ +/** + * Push delivery on a router (FIX-2428): a host that serves the socket turns + * it on, and from then the router reports `push` in `GET /capabilities` and + * answers the mint, `POST /users/:userId/stream`. + * + * The router owns both halves of the check. The mint runs each topic through + * the check its scope's read route uses, on the caller's real request, and + * signs a ticket naming only the topics it granted. The socket session + * ({@link openPushSocket}) accepts topics only from such a ticket. A host + * only takes the upgrade and moves frames (epic D5), so a later host reuses + * the check. + */ +import { randomBytes } from "node:crypto"; +import { DEFAULT_ORG_ID, type PushCapability, type PushMintAnswer } from "@flow-state-dev/core"; +import type { ResolvedPrincipal } from "../transports/types"; +import type { ChangeBus } from "../bus/types"; +import type { FlowApiRouter } from "../routes/createFlowApiRouter"; +import { authorizeManagementRoute, type RouteAuthContext } from "../routes/route-auth"; +import { jsonResponse, loadTenantSession } from "../routes/route-utils"; +import { isWireTopic, openPushSocket, type PushSocket, type PushSocketIO } from "./socket-session"; +import { PUSH_TICKET_TTL_MS, signPushTicket, type GrantedTopic } from "./ticket"; + +/** Options for {@link enablePushDelivery}. */ +export type EnablePushDeliveryOptions = { + /** + * The key tickets are signed with. Every process behind one address needs + * the same one, so a ticket minted on one is accepted by another. Read on + * each sign and check. Default: a random key for this router. + */ + secret?: string | (() => string); +}; + +/** A router's push delivery, as a host that serves the socket holds it. */ +export type PushDelivery = { + readonly transport: "websocket"; + /** + * Start the session for a socket that just opened on + * `/users/:userId/stream`, for the `userId` its path names. + */ + openSocket(userId: string, io: PushSocketIO): PushSocket; +}; + +/** The most topics one mint takes. */ +const MAX_MINT_TOPICS = 100; + +/** Where a router keeps its push state, read across engine copies. */ +const PUSH_STATE = Symbol.for("@flow-state-dev/engine/pushState"); + +/** + * A router's push state: built with its handlers, empty until a host turns + * push on. + */ +export type PushState = { + bus: ChangeBus; + secret?: () => string; +}; + +/** Create a router's push state over its bus. */ +export function createPushState(bus: ChangeBus): PushState { + return { bus }; +} + +/** Attach `state` to `router`, for {@link enablePushDelivery} to find. */ +export function attachPushState(router: FlowApiRouter, state: PushState): void { + Object.defineProperty(router, PUSH_STATE, { value: state, enumerable: false, configurable: true }); +} + +/** + * Turn push delivery on for `router`: it then reports + * `{ transport: "websocket" }` in `GET /capabilities` and answers the mint. + * Call it from a host that serves the socket on `/users/:userId/stream`, + * and hand each socket that opens there to the returned delivery. + * + * @throws When `router` was not built by `createFlowApiRouter`. + */ +export function enablePushDelivery(router: FlowApiRouter, options: EnablePushDeliveryOptions = {}): PushDelivery { + const state = (router as Record)[PUSH_STATE] as PushState | undefined; + if (state === undefined) { + throw new Error("enablePushDelivery takes a router built by createFlowApiRouter"); + } + const given = options.secret; + const generated = given === undefined ? randomBytes(32).toString("base64url") : undefined; + const secret = (): string => (typeof given === "function" ? given() : given ?? generated!); + state.secret = secret; + return { + transport: "websocket", + openSocket: (userId, io) => openPushSocket({ bus: state.bus, secret, userId, io }) + }; +} + +/** What `GET /capabilities` reports in `push`. */ +export function pushCapability(state: PushState): PushCapability | null { + return state.secret !== undefined ? { transport: "websocket" } : null; +} + +/** What the mint needs from the request's dispatch. */ +export type MintContext = RouteAuthContext & { + state: PushState; + /** The verified caller, when the app authenticates this route. */ + principal?: ResolvedPrincipal; + /** + * Set when the caller is anonymous in an app where some flow + * authenticates: no user or org scope is theirs to hear. + */ + anonymous: boolean; +}; + +/** + * `POST /users/:userId/stream`: check each topic and answer a ticket for the + * granted ones. The route guard has already checked that the path's user is + * the caller. + */ +export async function handleMintPush(request: Request, userId: string, ctx: MintContext): Promise { + const secret = ctx.state.secret; + if (secret === undefined) return jsonResponse(404, { error: "This host serves no push" }); + + let body: unknown; + try { + body = await request.json(); + } catch { + return jsonResponse(400, { error: "Expected a JSON body { topics }" }); + } + const topics = (body as { topics?: unknown } | null)?.topics; + if (!Array.isArray(topics) || topics.length > MAX_MINT_TOPICS || !topics.every(isWireTopic)) { + return jsonResponse(400, { error: `Expected { topics }: at most ${MAX_MINT_TOPICS} wire topics` }); + } + + const tenantId = ctx.tenantId ?? ""; + const granted: GrantedTopic[] = []; + for (const wire of topics) { + const resource = wire.resource !== undefined ? { resource: wire.resource } : {}; + if (wire.scope === "session") { + // The check the session stream answers to, on this request. A session + // the caller may not read is dropped exactly as one that doesn't exist. + const checked = await authorizeManagementRoute(request, { kind: "session_stream", sessionId: wire.id }, ctx); + if (checked.denied !== undefined || checked.session === null) continue; + if (checked.session === undefined && (await loadTenantSession(ctx.stores.session, wire.id, ctx.tenantId)) === undefined) { + continue; + } + granted.push({ wire, bus: { scope: "session", id: wire.id, tenantId, ...resource } }); + continue; + } + // A user or org topic names no id: the caller's own, from the verified + // principal (BP-031). An anonymous caller in an app that authenticates + // anything has none to claim. + if (ctx.anonymous) continue; + const id = wire.scope === "user" ? ctx.principal?.userId ?? userId : ctx.principal?.orgId ?? DEFAULT_ORG_ID; + granted.push({ wire, bus: { scope: wire.scope, id, tenantId, ...resource } }); + } + + const answer: PushMintAnswer = { + transport: "websocket", + ticket: signPushTicket({ sub: userId, exp: Date.now() + PUSH_TICKET_TTL_MS, topics: granted }, secret()), + path: `/users/${encodeURIComponent(userId)}/stream`, + topics: granted.map((topic) => topic.wire) + }; + return jsonResponse(200, answer); +} diff --git a/packages/engine/src/push/socket-session.ts b/packages/engine/src/push/socket-session.ts new file mode 100644 index 0000000000..9089ac525d --- /dev/null +++ b/packages/engine/src/push/socket-session.ts @@ -0,0 +1,188 @@ +/** + * One push socket's session (FIX-2428): which topics it hears, and the + * frames it sends. Transport-neutral: a host takes the upgrade and moves + * frames (`@flow-state-dev/node`'s `serve()`), and this decides everything + * else, so a later host reuses the check. + * + * - **Topics come only from tickets.** The first message must be a ticket + * (`{ type: "subscribe", ticket }`) the mint signed for the user the + * socket's path names; each later ticket adds its topics. A ticket that + * fails its check is logged and the socket closed (4401). No ticket within + * five seconds closes it too (4408). + * - **No check while open** (D2). An open socket hears its topics until it + * closes, at most an hour after it opened (4000); the client mints again to + * reconnect, and the mint checks again. + * - **`crossing` frames.** After the first ticket, and on each change, the + * socket says whether its process's bus hears other processes. A control + * frame about the socket, never a notice kind. + */ +import { PUSH_CLOSE_CODES, wireTopicKey, type PushServerFrame, type WireTopic } from "@flow-state-dev/core"; +import type { BusTopic, ChangeBus, ChangeNotice } from "../bus/types"; +import { verifyPushTicket } from "./ticket"; + +/** The socket session's clocks. */ +export const PUSH_SOCKET_TIMINGS = { + /** A socket with no valid ticket this long after it opened is closed. */ + ticketTimeoutMs: 5_000, + /** A socket is closed this long after it opened; the client reconnects. */ + maxAgeMs: 60 * 60_000 +} as const; + +/** How a session talks to its socket. The host moves frames; nothing else. */ +export type PushSocketIO = { + send(frame: PushServerFrame): void; + close(code: number, reason: string): void; +}; + +/** What a host tells the session about its socket. */ +export type PushSocket = { + /** A text message the client sent. */ + receive(data: string): void; + /** The socket closed, from either side. Idempotent. */ + closed(): void; +}; + +export type OpenPushSocketOptions = { + bus: ChangeBus; + /** The signing secret, read on each check. */ + secret: () => string; + /** The user the socket's path names. Every ticket must be minted for them. */ + userId: string; + io: PushSocketIO; + /** Where a refused ticket is reported. Default `console`. */ + logger?: { warn(message: string, meta?: Record): void }; +}; + +/** A bus topic as the wire names it: no tenant, and no user or org id. */ +function toWire(topic: BusTopic): WireTopic { + const resource = topic.resource !== undefined ? { resource: topic.resource } : {}; + return topic.scope === "session" ? { scope: "session", id: topic.id, ...resource } : { scope: topic.scope, ...resource }; +} + +/** The key two equal bus topics share. */ +function busKey(topic: BusTopic): string { + return `${topic.scope}\u0000${topic.tenantId}\u0000${topic.id}\u0000${topic.resource ?? ""}`; +} + +/** Start the session for a socket that just opened. */ +export function openPushSocket(options: OpenPushSocketOptions): PushSocket { + const { bus, io, userId } = options; + const logger = options.logger ?? console; + /** Bus key → the topic as the wire names it, and its unsubscribe. */ + const subscriptions = new Map void }>(); + let crossingOff: (() => void) | undefined; + let accepted = false; + let ended = false; + + const end = (): void => { + if (ended) return; + ended = true; + clearTimeout(ticketTimer); + clearTimeout(ageTimer); + crossingOff?.(); + for (const { off } of subscriptions.values()) off(); + subscriptions.clear(); + }; + const close = (code: number, reason: string): void => { + if (ended) return; + end(); + io.close(code, reason); + }; + + const ticketTimer = setTimeout( + () => close(PUSH_CLOSE_CODES.ticketTimeout, "no ticket"), + PUSH_SOCKET_TIMINGS.ticketTimeoutMs + ); + const ageTimer = setTimeout(() => close(PUSH_CLOSE_CODES.maxAge, "max age"), PUSH_SOCKET_TIMINGS.maxAgeMs); + // Neither clock keeps a process alive on its own. + (ticketTimer as { unref?: () => void }).unref?.(); + (ageTimer as { unref?: () => void }).unref?.(); + + const send = (frame: PushServerFrame): void => { + if (!ended) io.send(frame); + }; + const hear = (notice: ChangeNotice): void => { + send({ + type: "notice", + topic: toWire(notice.topic), + kind: notice.kind, + ...(notice.origin !== undefined ? { origin: notice.origin } : {}) + }); + }; + + const subscribe = (ticket: unknown): void => { + const checked = verifyPushTicket(ticket, options.secret(), userId); + if (!checked.ok) { + logger.warn(`[flow-state] push socket refused a ticket (${checked.reason}); closing it`, { + reason: checked.reason, + userId + }); + close(PUSH_CLOSE_CODES.ticketRefused, "ticket refused"); + return; + } + for (const granted of checked.claims.topics) { + const key = busKey(granted.bus); + if (subscriptions.has(key)) continue; + subscriptions.set(key, { wireKey: wireTopicKey(toWire(granted.bus)), off: bus.subscribe(granted.bus, hear) }); + } + if (accepted) return; + accepted = true; + clearTimeout(ticketTimer); + send({ type: "crossing", crosses: bus.crossesProcesses }); + crossingOff = bus.onCrossingChange((crosses) => send({ type: "crossing", crosses })); + }; + + const unsubscribe = (topics: unknown): void => { + if (!Array.isArray(topics) || !topics.every(isWireTopic)) { + close(PUSH_CLOSE_CODES.badFrame, "bad frame"); + return; + } + // A socket only holds topics a ticket granted, all for this socket's + // tenant and caller, so the wire form names exactly one of them. + const keys = new Set(topics.map(wireTopicKey)); + for (const [key, held] of [...subscriptions]) { + if (!keys.has(held.wireKey)) continue; + held.off(); + subscriptions.delete(key); + } + }; + + return { + receive(data) { + if (ended) return; + let frame: unknown; + try { + frame = JSON.parse(data); + } catch { + close(PUSH_CLOSE_CODES.badFrame, "bad frame"); + return; + } + const type = (frame as { type?: unknown } | null)?.type; + if (type === "subscribe") { + subscribe((frame as { ticket?: unknown }).ticket); + return; + } + if (type === "unsubscribe" && accepted) { + unsubscribe((frame as { topics?: unknown }).topics); + return; + } + close(PUSH_CLOSE_CODES.badFrame, "bad frame"); + }, + closed: end + }; +} + +/** Whether `value` is a wire topic: a scope, a session's id, an optional resource. */ +export function isWireTopic(value: unknown): value is WireTopic { + if (typeof value !== "object" || value === null) return false; + const topic = value as Record; + const keys = Object.keys(topic); + if (topic.resource !== undefined && typeof topic.resource !== "string") return false; + if (topic.scope === "session") { + return typeof topic.id === "string" && topic.id.length > 0 && keys.every((key) => ["scope", "id", "resource"].includes(key)); + } + if (topic.scope === "user" || topic.scope === "org") { + return keys.every((key) => ["scope", "resource"].includes(key)); + } + return false; +} diff --git a/packages/engine/src/push/ticket.ts b/packages/engine/src/push/ticket.ts new file mode 100644 index 0000000000..f8b3659439 --- /dev/null +++ b/packages/engine/src/push/ticket.ts @@ -0,0 +1,85 @@ +/** + * The push ticket (FIX-2428 D1): a short-lived, signed statement that the + * mint checked a caller and granted it some topics. + * + * The mint signs one after it has run each topic through its scope's route + * check on the caller's own request; the socket accepts topics only from a + * ticket whose signature, expiry and user all check out. It is stateless: a + * process that shares the secret can check a ticket another one signed. + * + * Format: `.`, both base64url. The payload is the JSON + * claims; the signature is HMAC-SHA256 over the encoded payload. + */ +import { createHmac } from "node:crypto"; +import type { WireTopic } from "@flow-state-dev/core"; +import type { BusTopic } from "../bus/types"; +import { constantTimeStringEqual } from "../transports/auth/constant-time"; + +/** How long a minted ticket is good for. */ +export const PUSH_TICKET_TTL_MS = 30_000; + +/** One granted topic: as the client named it, and as the bus names it. */ +export type GrantedTopic = { wire: WireTopic; bus: BusTopic }; + +/** What a ticket says. */ +export type PushTicketClaims = { + /** The user the mint checked; the socket's path must name the same one. */ + sub: string; + /** Expiry, epoch ms. */ + exp: number; + topics: GrantedTopic[]; +}; + +/** Why a ticket was refused, for the log line. */ +export type PushTicketRefusal = "malformed" | "signature" | "expired" | "user"; + +const VERSION = 1; + +function sign(payload: string, secret: string): string { + return createHmac("sha256", secret).update(payload).digest("base64url"); +} + +/** Sign `claims` with `secret`. */ +export function signPushTicket(claims: PushTicketClaims, secret: string): string { + const payload = Buffer.from(JSON.stringify({ v: VERSION, ...claims }), "utf8").toString("base64url"); + return `${payload}.${sign(payload, secret)}`; +} + +/** + * Check a ticket: its signature under `secret`, that it has not expired at + * `now`, and that it was minted for `userId`. Returns its claims, or why it + * was refused. + */ +export function verifyPushTicket( + ticket: unknown, + secret: string, + userId: string, + now: number = Date.now() +): { ok: true; claims: PushTicketClaims } | { ok: false; reason: PushTicketRefusal } { + if (typeof ticket !== "string") return { ok: false, reason: "malformed" }; + const dot = ticket.indexOf("."); + if (dot <= 0 || dot !== ticket.lastIndexOf(".")) return { ok: false, reason: "malformed" }; + const payload = ticket.slice(0, dot); + if (!constantTimeStringEqual(ticket.slice(dot + 1), sign(payload, secret))) return { ok: false, reason: "signature" }; + let claims: unknown; + try { + claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")); + } catch { + return { ok: false, reason: "malformed" }; + } + if (!isClaims(claims)) return { ok: false, reason: "malformed" }; + if (claims.exp <= now) return { ok: false, reason: "expired" }; + if (claims.sub !== userId) return { ok: false, reason: "user" }; + return { ok: true, claims: { sub: claims.sub, exp: claims.exp, topics: claims.topics } }; +} + +function isClaims(value: unknown): value is PushTicketClaims & { v: number } { + if (typeof value !== "object" || value === null) return false; + const claims = value as Record; + return ( + claims.v === VERSION && + typeof claims.sub === "string" && + typeof claims.exp === "number" && + Array.isArray(claims.topics) + ); +} diff --git a/packages/engine/src/routes/createFlowApiRouter.ts b/packages/engine/src/routes/createFlowApiRouter.ts index bd8d5da4d8..0e2bcaad54 100644 --- a/packages/engine/src/routes/createFlowApiRouter.ts +++ b/packages/engine/src/routes/createFlowApiRouter.ts @@ -7,6 +7,7 @@ * canonical `{ GET, POST, PATCH, DELETE }` dispatcher. The public API * shape and behavior is unchanged for callers that don't pass `adapters`. */ +import { attachPushState } from "../push/push-delivery"; import type { FlowStateSettings, ModelResolver, @@ -755,6 +756,9 @@ export function createFlowApiRouter(options: CreateFlowApiRouterOptions): FlowAp enumerable: false, configurable: true }); + // Push delivery's state (FIX-2428), for a host that serves the socket to + // turn on with `enablePushDelivery`. + attachPushState(router, handlers.push); return router; } diff --git a/packages/engine/src/routes/http-handlers.ts b/packages/engine/src/routes/http-handlers.ts index 61c5540ad7..4f30dafdad 100644 --- a/packages/engine/src/routes/http-handlers.ts +++ b/packages/engine/src/routes/http-handlers.ts @@ -13,6 +13,7 @@ import type { RuntimeConfig } from "../runtime-config"; import { createInMemoryStores } from "../stores"; import type { StoreRegistry } from "../stores/types"; import { withChangeBus } from "../bus/publish-writes"; +import type { ChangeBus } from "../bus/types"; import { detectInterruptedRequests, internalEntriesFrom } from "../execution/request-recovery"; import { parseFlowRoute, @@ -84,6 +85,7 @@ import { installWakes } from "../durability/request-wakes"; import { installWaits } from "../durability/wait-chain"; import { DEFAULT_RUNTIME_LOGGER } from "../execution/logging"; import { createParkedStopDeps } from "../durability/stop-suspended"; +import { createPushState, handleMintPush, pushCapability, type PushState } from "../push/push-delivery"; export type RequestContext = { method: string; @@ -204,7 +206,7 @@ export type FlowRouteContext = { path?: string[]; }; -export function resolveStores(partial: Partial | undefined): StoreRegistry { +export function resolveStores(partial: Partial | undefined): StoreRegistry & { bus: ChangeBus } { const fallback = createInMemoryStores(); // Every request and session write publishes on its session's topic // (FIX-2426), on the given bus or an in-memory one. @@ -239,6 +241,8 @@ export function resolveStores(partial: Partial | undefined): Stor export function createFlowRouteHandlers(options: CreateFlowRouteHandlersOptions): { handle: (request: Request, context: FlowRouteContext) => Promise; host: InboundTransportHost; + /** Push delivery's state (FIX-2428): empty until a host turns push on. */ + push: PushState; } { refuseRetiredDispatcherOption(options, "createFlowRouteHandlers"); const stores = resolveStores(options.stores); @@ -263,6 +267,7 @@ export function createFlowRouteHandlers(options: CreateFlowRouteHandlersOptions) }; const hostResolver = options.resolvePrincipal ?? defaultBodyUserIdPrincipalResolver; + const push = createPushState(stores.bus); const host: InboundTransportHost = createInboundTransportHost({ registry: options.registry, @@ -490,7 +495,7 @@ export function createFlowRouteHandlers(options: CreateFlowRouteHandlersOptions) } if (route.kind === "capabilities") { - return jsonResponse(200, { userStream: false }); + return jsonResponse(200, { userStream: false, push: pushCapability(push) }); } if (route.kind === "execute_action") { @@ -609,9 +614,22 @@ export function createFlowRouteHandlers(options: CreateFlowRouteHandlersOptions) }); } + // The socket (FIX-2428): the host takes the upgrade before a request + // reaches here, so what arrives is a plain GET. if (route.kind === "user_stream") { - return jsonResponse(501, { - error: "User stream is not enabled in Phase 1" + return jsonResponse(426, { error: "This route takes a WebSocket upgrade" }); + } + + if (route.kind === "user_stream_mint") { + return await handleMintPush(request, route.userId, { + registry: options.registry, + stores, + host, + hostResolver, + tenantId, + state: push, + ...(principal !== undefined ? { principal } : {}), + anonymous: anonymousFlowIds !== undefined }); } @@ -860,7 +878,8 @@ export function createFlowRouteHandlers(options: CreateFlowRouteHandlersOptions) return { handle, - host + host, + push }; } diff --git a/packages/engine/src/routes/parseFlowRoute.ts b/packages/engine/src/routes/parseFlowRoute.ts index a0047fc0c7..4d7de32624 100644 --- a/packages/engine/src/routes/parseFlowRoute.ts +++ b/packages/engine/src/routes/parseFlowRoute.ts @@ -21,6 +21,7 @@ export type ParsedFlowRoute = | { kind: "delete_session"; sessionId: string } | { kind: "patch_session_metadata"; sessionId: string } | { kind: "user_stream"; userId: string } + | { kind: "user_stream_mint"; userId: string } | { kind: "transcribe" } | { kind: "retry_request"; flowKind: string; sessionId: string; requestId: string } | { kind: "continue_request"; flowKind: string; sessionId: string; requestId: string } diff --git a/packages/engine/src/routes/route-auth.ts b/packages/engine/src/routes/route-auth.ts index f636677e8e..946a421f12 100644 --- a/packages/engine/src/routes/route-auth.ts +++ b/packages/engine/src/routes/route-auth.ts @@ -230,6 +230,9 @@ export function routeSubject(route: ParsedFlowRoute): RouteSubject { // (`test/user-route-scoping.test.ts`), which fails until it has one and // then probes it with cross-org, cross-tenant and anonymous callers. case "user_stream": + // The mint: the guard checks the path's user is the caller, and the + // handler checks each topic with its own scope's check (FIX-2428). + case "user_stream_mint": case "check_interrupted_requests": case "list_interrupted_requests": return { kind: "user", userId: route.userId }; diff --git a/packages/engine/src/routes/router.ts b/packages/engine/src/routes/router.ts index a87ac13c44..98016a377c 100644 --- a/packages/engine/src/routes/router.ts +++ b/packages/engine/src/routes/router.ts @@ -94,6 +94,12 @@ const ROUTES_BY_KIND: { [K in CoveredKind]: RouteEntry[] } = { userId: p.userId })) ], + user_stream_mint: [ + entry("POST", "/users/:userId/stream", (p) => ({ + kind: "user_stream_mint", + userId: p.userId + })) + ], check_interrupted_requests: [ entry("POST", "/users/:userId/check-interrupted", (p) => ({ kind: "check_interrupted_requests", diff --git a/packages/engine/src/streaming/encode-event.ts b/packages/engine/src/streaming/encode-event.ts index 0f547ae274..2659344a30 100644 --- a/packages/engine/src/streaming/encode-event.ts +++ b/packages/engine/src/streaming/encode-event.ts @@ -34,11 +34,7 @@ export function createUserEventId( * Resolves the canonical stream event id for any stream event. */ export function createStreamEventId(event: StreamEvent): string { - if (event.stream === "request") { - return createRequestEventId(event.requestId, event.sequence_number); - } - - return createUserEventId(event.userId, event.sequence_number); + return createRequestEventId(event.requestId, event.sequence_number); } export type EncodeStreamEventInternalOptions = { diff --git a/packages/engine/test/push-delivery.test.ts b/packages/engine/test/push-delivery.test.ts new file mode 100644 index 0000000000..0ad914adde --- /dev/null +++ b/packages/engine/test/push-delivery.test.ts @@ -0,0 +1,483 @@ +/** + * Push delivery (FIX-2428) in the engine: what `GET /capabilities` reports, + * what the mint grants, and what a socket session hears. + * + * The mint checks each topic with the check its scope's read route uses, on + * the mint's own request, and a refused topic is absent from the answer, as a + * topic for a missing session is. The socket accepts topics only from a + * ticket the mint signed, for the user the socket's path names. + */ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { z } from "zod"; +import { DEFAULT_ORG_ID, defineFlow, handler, topic, type PushMintAnswer, type PushServerFrame } from "@flow-state-dev/core"; +import { + createFlowApiRouter, + createFlowRegistry, + createInMemoryBus, + createInMemoryStores, + enablePushDelivery, + type ChangeBus, + type FlowApiRouter, + type PushDelivery, + type StoreRegistry +} from "../src"; +import { openPushSocket, PUSH_SOCKET_TIMINGS } from "../src/push/socket-session"; +import { signPushTicket } from "../src/push/ticket"; + +const SECRET = "test-secret"; + +function demoFlow(kind = "demo") { + return defineFlow({ + kind, + actions: { + run: { + inputSchema: z.object({}), + block: handler({ name: `${kind}-run`, inputSchema: z.object({}), outputSchema: z.object({}), execute: () => ({}) }) + } + } + })(); +} + +/** A host that verifies user and organization from two headers. */ +function app(options: { bus?: ChangeBus; push?: boolean } = {}) { + const registry = createFlowRegistry(); + registry.register(demoFlow()); + const stores: StoreRegistry = { ...createInMemoryStores(), ...(options.bus !== undefined ? { bus: options.bus } : {}) }; + const router = createFlowApiRouter({ + registry, + stores, + tenantIdHeader: "x-tenant-id", + resolvePrincipal: (context) => { + const user = context.request?.headers.get("x-user"); + const org = context.request?.headers.get("x-org") ?? "acme"; + return user == null ? null : { userId: user, orgId: org }; + } + }); + const delivery = options.push === false ? undefined : enablePushDelivery(router, { secret: SECRET }); + return { router, stores, delivery }; +} + +async function seedSession( + stores: StoreRegistry, + id: string, + owner: { userId: string; orgId?: string; tenantId?: string } +): Promise { + const now = Date.now(); + const key = owner.tenantId === undefined ? id : `${owner.tenantId}:${id}`; + await stores.session.set( + key, + { + id, + flowKind: "demo", + flowId: "demo", + userId: owner.userId, + orgId: owner.orgId ?? "acme", + ...(owner.tenantId !== undefined ? { tenantId: owner.tenantId } : {}), + state: {}, + version: 0, + createdAt: now, + updatedAt: now, + journal: [] + }, + "any" + ); +} + +async function call( + router: FlowApiRouter, + method: "GET" | "POST", + path: string, + headers: Record = {}, + body?: unknown +): Promise { + const segments = path.split("/").filter(Boolean); + return router[method]( + new Request(`http://localhost/api/flows/${segments.join("/")}`, { + method, + headers: { "content-type": "application/json", ...headers }, + ...(body !== undefined ? { body: JSON.stringify(body) } : {}) + }), + { params: { path: segments } } + ); +} + +const ALICE = { "x-user": "alice", "x-org": "acme" }; + +async function mint( + router: FlowApiRouter, + topics: unknown[], + headers: Record = ALICE, + userId = "alice" +): Promise<{ status: number; answer: PushMintAnswer }> { + const response = await call(router, "POST", `/users/${userId}/stream`, headers, { topics }); + return { status: response.status, answer: (await response.json()) as PushMintAnswer }; +} + +/** A socket session over a fake wire: what the server sent, and how it closed. */ +function socket(delivery: PushDelivery, userId = "alice") { + const frames: PushServerFrame[] = []; + let closed: { code: number; reason: string } | undefined; + const session = delivery.openSocket(userId, { + send: (frame) => frames.push(frame), + close: (code, reason) => { + closed ??= { code, reason }; + } + }); + return { + frames, + notices: () => frames.filter((frame) => frame.type === "notice"), + closed: () => closed, + send: (frame: unknown) => session.receive(JSON.stringify(frame)), + end: () => session.closed() + }; +} + +const flush = () => new Promise((resolve) => setTimeout(resolve, 0)); + +afterEach(() => { + vi.useRealTimers(); + vi.restoreAllMocks(); +}); + +describe("GET /capabilities", () => { + it("reports no push until a host serves the socket", async () => { + const { router } = app({ push: false }); + expect(await (await call(router, "GET", "/capabilities")).json()).toEqual({ userStream: false, push: null }); + }); + + it("reports the WebSocket push once the host serves it", async () => { + const { router } = app(); + expect(await (await call(router, "GET", "/capabilities")).json()).toEqual({ + userStream: false, + push: { transport: "websocket" } + }); + }); +}); + +describe("GET /users/:userId/stream without an upgrade", () => { + it("answers 426: the route only takes a WebSocket upgrade", async () => { + const { router } = app(); + const response = await call(router, "GET", "/users/alice/stream", ALICE); + expect(response.status).toBe(426); + }); +}); + +describe("POST /users/:userId/stream (the mint)", () => { + it("answers 404 on a host with no push", async () => { + const { router } = app({ push: false }); + expect((await mint(router, [topic.user()])).status).toBe(404); + }); + + it("refuses a caller who is not the path's user, before checking any topic", async () => { + const { router } = app(); + expect((await mint(router, [topic.user()], { "x-user": "bob" }, "alice")).status).toBe(403); + expect((await mint(router, [topic.user()], {}, "alice")).status).toBe(401); + }); + + it("answers a websocket ticket for the caller's own session, user and org topics", async () => { + const { router, stores } = app(); + await seedSession(stores, "s1", { userId: "alice" }); + const { status, answer } = await mint(router, [ + topic.session("s1"), + topic.session("s1", { resource: "tasks" }), + topic.user(), + topic.org() + ]); + expect(status).toBe(200); + expect(answer.transport).toBe("websocket"); + if (answer.transport !== "websocket") return; + expect(answer.path).toBe("/users/alice/stream"); + expect(typeof answer.ticket).toBe("string"); + expect(answer.topics).toEqual([ + topic.session("s1"), + topic.session("s1", { resource: "tasks" }), + topic.user(), + topic.org() + ]); + }); + + it("drops another user's session exactly as a session that doesn't exist", async () => { + const { router, stores } = app(); + await seedSession(stores, "bobs", { userId: "bob" }); + await seedSession(stores, "own", { userId: "alice" }); + const { status, answer } = await mint(router, [topic.session("bobs"), topic.session("missing"), topic.session("own")]); + expect(status).toBe(200); + expect(answer.topics).toEqual([topic.session("own")]); + }); + + it("drops a session of the caller's that another organization owns, and one on another tenant", async () => { + const { router, stores } = app(); + await seedSession(stores, "globex", { userId: "alice", orgId: "globex" }); + await seedSession(stores, "t2", { userId: "alice", tenantId: "t2" }); + await seedSession(stores, "t1", { userId: "alice", tenantId: "t1" }); + const { answer } = await mint(router, [topic.session("globex"), topic.session("t2"), topic.session("t1")], { + ...ALICE, + "x-tenant-id": "t1" + }); + expect(answer.topics).toEqual([topic.session("t1")]); + }); + + it("refuses a body whose topics aren't wire topics", async () => { + const { router } = app(); + expect((await mint(router, [{ scope: "user", id: "bob" }])).status).toBe(400); + expect((await mint(router, [{ scope: "session" }])).status).toBe(400); + expect((await mint(router, [{ scope: "team" }])).status).toBe(400); + const notArray = await call(router, "POST", "/users/alice/stream", ALICE, { topics: "user" }); + expect(notArray.status).toBe(400); + }); + + it("in a mixed app, gives an anonymous caller no user or org topic", async () => { + const registry = createFlowRegistry(); + registry.register(demoFlow("open")); + registry.register( + defineFlow({ + kind: "secure", + actions: demoFlow("secure").actions, + authentication: { resolvePrincipal: () => null } + })() + ); + const router = createFlowApiRouter({ registry, stores: createInMemoryStores() }); + enablePushDelivery(router, { secret: SECRET }); + const { status, answer } = await mint(router, [topic.user(), topic.org()], {}); + expect(status).toBe(200); + expect(answer.topics).toEqual([]); + }); +}); + +describe("the socket session", () => { + async function ticketFor(router: FlowApiRouter, topics: unknown[], headers = ALICE, userId = "alice") { + const { answer } = await mint(router, topics, headers, userId); + if (answer.transport !== "websocket") throw new Error("expected a websocket answer"); + return answer.ticket; + } + + it("hears a notice under a granted topic, as a wire topic with no tenant, user or org id", async () => { + const bus = createInMemoryBus(); + const { router, stores, delivery } = app({ bus }); + await seedSession(stores, "s1", { userId: "alice" }); + const ws = socket(delivery!); + ws.send({ type: "subscribe", ticket: await ticketFor(router, [topic.session("s1"), topic.user(), topic.org()]) }); + await bus.publish({ topic: { scope: "session", id: "s1", tenantId: "", resource: "tasks" }, kind: "items", origin: { requestId: "r1" } }); + await bus.publish({ topic: { scope: "user", id: "alice", tenantId: "" }, kind: "request" }); + await bus.publish({ topic: { scope: "org", id: "acme", tenantId: "" }, kind: "run" }); + await flush(); + expect(ws.notices()).toEqual([ + { type: "notice", topic: topic.session("s1", { resource: "tasks" }), kind: "items", origin: { requestId: "r1" } }, + { type: "notice", topic: topic.user(), kind: "request" }, + { type: "notice", topic: topic.org(), kind: "run" } + ]); + }); + + it("fills user and org topics from the verified caller: another user's or org's notices never arrive", async () => { + const bus = createInMemoryBus(); + const { router, delivery } = app({ bus }); + const ws = socket(delivery!); + ws.send({ type: "subscribe", ticket: await ticketFor(router, [topic.user(), topic.org()]) }); + await bus.publish({ topic: { scope: "user", id: "bob", tenantId: "" }, kind: "request" }); + await bus.publish({ topic: { scope: "org", id: "globex", tenantId: "" }, kind: "request" }); + await bus.publish({ topic: { scope: "user", id: "alice", tenantId: "t9" }, kind: "request" }); + await flush(); + expect(ws.notices()).toEqual([]); + }); + + it("hears nothing of a topic the mint dropped", async () => { + const bus = createInMemoryBus(); + const { router, stores, delivery } = app({ bus }); + await seedSession(stores, "bobs", { userId: "bob" }); + const ws = socket(delivery!); + ws.send({ type: "subscribe", ticket: await ticketFor(router, [topic.session("bobs")]) }); + await bus.publish({ topic: { scope: "session", id: "bobs", tenantId: "" }, kind: "items" }); + await flush(); + expect(ws.notices()).toEqual([]); + expect(ws.closed()).toBeUndefined(); + }); + + it("says whether its bus crosses processes after the first ticket, and on every change", async () => { + const inner = createInMemoryBus(); + const crossingListeners = new Set<(crosses: boolean) => void>(); + let crosses = false; + const bus: ChangeBus = { + publish: inner.publish, + subscribe: inner.subscribe, + get crossesProcesses() { + return crosses; + }, + onCrossingChange(listener) { + crossingListeners.add(listener); + return () => crossingListeners.delete(listener); + } + }; + const { router, delivery } = app({ bus }); + const ws = socket(delivery!); + expect(ws.frames).toEqual([]); + ws.send({ type: "subscribe", ticket: await ticketFor(router, [topic.user()]) }); + expect(ws.frames).toEqual([{ type: "crossing", crosses: false }]); + crosses = true; + for (const listener of crossingListeners) listener(true); + expect(ws.frames).toEqual([ + { type: "crossing", crosses: false }, + { type: "crossing", crosses: true } + ]); + // A second ticket adds topics; it sends no second first frame. + ws.send({ type: "subscribe", ticket: await ticketFor(router, [topic.org()]) }); + expect(ws.frames).toHaveLength(2); + ws.end(); + expect(crossingListeners.size).toBe(0); + }); + + it("stops hearing a topic it unsubscribes, and everything once it closes", async () => { + const bus = createInMemoryBus(); + const { router, delivery } = app({ bus }); + const ws = socket(delivery!); + ws.send({ type: "subscribe", ticket: await ticketFor(router, [topic.user(), topic.org()]) }); + ws.send({ type: "unsubscribe", topics: [topic.user()] }); + await bus.publish({ topic: { scope: "user", id: "alice", tenantId: "" }, kind: "request" }); + await bus.publish({ topic: { scope: "org", id: "acme", tenantId: "" }, kind: "request" }); + await flush(); + expect(ws.notices().map((frame) => frame.type === "notice" && frame.topic.scope)).toEqual(["org"]); + ws.end(); + await bus.publish({ topic: { scope: "org", id: "acme", tenantId: "" }, kind: "request" }); + await flush(); + expect(ws.notices()).toHaveLength(1); + }); + + it("closes a socket whose ticket names another user, and logs it", async () => { + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); + const { router, delivery } = app(); + const ws = socket(delivery!, "bob"); + ws.send({ type: "subscribe", ticket: await ticketFor(router, [topic.user()]) }); + expect(ws.closed()).toEqual({ code: 4401, reason: expect.any(String) }); + expect(ws.frames).toEqual([]); + expect(warn).toHaveBeenCalled(); + }); + + it("closes a socket whose ticket was signed with another secret, or has expired", async () => { + vi.spyOn(console, "warn").mockImplementation(() => {}); + const { delivery } = app(); + const forged = signPushTicket( + { sub: "alice", exp: Date.now() + 30_000, topics: [{ wire: topic.user(), bus: { scope: "user", id: "alice", tenantId: "" } }] }, + "another-secret" + ); + const a = socket(delivery!); + a.send({ type: "subscribe", ticket: forged }); + expect(a.closed()?.code).toBe(4401); + const expired = signPushTicket( + { sub: "alice", exp: Date.now() - 1, topics: [{ wire: topic.user(), bus: { scope: "user", id: "alice", tenantId: "" } }] }, + SECRET + ); + const b = socket(delivery!); + b.send({ type: "subscribe", ticket: expired }); + expect(b.closed()?.code).toBe(4401); + }); + + it("accepts no topic named outside a ticket", () => { + const { delivery } = app(); + const ws = socket(delivery!); + ws.send({ type: "subscribe", topics: [topic.user()] }); + expect(ws.closed()?.code).toBe(4401); + const other = socket(delivery!); + other.send({ type: "unsubscribe", topics: [topic.user()] }); + expect(other.closed()?.code).toBe(4400); + }); + + it("closes a socket with no ticket within five seconds, and any socket after an hour", async () => { + const { router, delivery } = app(); + const ticket = await ticketFor(router, [topic.user()]); + vi.useFakeTimers(); + const silent = socket(delivery!); + vi.advanceTimersByTime(PUSH_SOCKET_TIMINGS.ticketTimeoutMs); + expect(silent.closed()?.code).toBe(4408); + expect(PUSH_SOCKET_TIMINGS.ticketTimeoutMs).toBe(5_000); + + const ws = socket(delivery!); + ws.send({ type: "subscribe", ticket }); + vi.advanceTimersByTime(PUSH_SOCKET_TIMINGS.maxAgeMs - 1); + expect(ws.closed()).toBeUndefined(); + vi.advanceTimersByTime(1); + expect(ws.closed()?.code).toBe(4000); + expect(PUSH_SOCKET_TIMINGS.maxAgeMs).toBe(60 * 60_000); + }); + + it("refuses a ticket thirty seconds after it was minted", async () => { + vi.spyOn(console, "warn").mockImplementation(() => {}); + const { router, delivery } = app(); + vi.useFakeTimers({ toFake: ["Date"] }); + const ticket = await ticketFor(router, [topic.user()]); + vi.setSystemTime(Date.now() + 30_001); + const ws = socket(delivery!); + ws.send({ type: "subscribe", ticket }); + expect(ws.closed()?.code).toBe(4401); + }); + + it("is reachable without a router, for a host that runs the session itself", () => { + const frames: PushServerFrame[] = []; + const session = openPushSocket({ + bus: createInMemoryBus(), + secret: () => SECRET, + userId: "alice", + io: { send: (frame) => frames.push(frame), close: () => {} } + }); + session.receive( + JSON.stringify({ + type: "subscribe", + ticket: signPushTicket( + { sub: "alice", exp: Date.now() + 1000, topics: [{ wire: topic.user(), bus: { scope: "user", id: "alice", tenantId: "" } }] }, + SECRET + ) + }) + ); + expect(frames).toEqual([{ type: "crossing", crosses: false }]); + session.closed(); + }); +}); + +describe("enablePushDelivery", () => { + it("takes the secret from a function, read when a ticket is signed and checked", async () => { + let secret = "one"; + const registry = createFlowRegistry(); + registry.register(demoFlow()); + const router = createFlowApiRouter({ registry, stores: createInMemoryStores() }); + const delivery = enablePushDelivery(router, { secret: () => secret }); + const { answer } = await mint(router, [topic.user()], {}, "alice"); + if (answer.transport !== "websocket") throw new Error("expected websocket"); + secret = "two"; + vi.spyOn(console, "warn").mockImplementation(() => {}); + const ws = socket(delivery); + ws.send({ type: "subscribe", ticket: answer.ticket }); + expect(ws.closed()?.code).toBe(4401); + }); + + it("uses one random secret per router when none is given", async () => { + const registry = createFlowRegistry(); + registry.register(demoFlow()); + const a = createFlowApiRouter({ registry, stores: createInMemoryStores() }); + const b = createFlowApiRouter({ registry, stores: createInMemoryStores() }); + enablePushDelivery(a); + const deliveryB = enablePushDelivery(b); + const { answer } = await mint(a, [topic.user()], {}, "alice"); + if (answer.transport !== "websocket") throw new Error("expected websocket"); + vi.spyOn(console, "warn").mockImplementation(() => {}); + const ws = socket(deliveryB); + ws.send({ type: "subscribe", ticket: answer.ticket }); + expect(ws.closed()?.code).toBe(4401); + }); + + it("refuses a value that is not a router from createFlowApiRouter", () => { + expect(() => enablePushDelivery({} as FlowApiRouter)).toThrow(/createFlowApiRouter/); + }); + + it("keeps the default organization for a caller of an app that authenticates nothing", async () => { + const bus = createInMemoryBus(); + const registry = createFlowRegistry(); + registry.register(demoFlow()); + const router = createFlowApiRouter({ registry, stores: { ...createInMemoryStores(), bus } }); + const delivery = enablePushDelivery(router, { secret: SECRET }); + const { answer } = await mint(router, [topic.org()], {}, "alice"); + if (answer.transport !== "websocket") throw new Error("expected websocket"); + const ws = socket(delivery); + ws.send({ type: "subscribe", ticket: answer.ticket }); + await bus.publish({ topic: { scope: "org", id: DEFAULT_ORG_ID, tenantId: "" }, kind: "request" }); + await flush(); + expect(ws.notices()).toHaveLength(1); + }); +}); diff --git a/packages/engine/test/registry-routes.test.ts b/packages/engine/test/registry-routes.test.ts index db9b75b8fd..3dbf7d73ff 100644 --- a/packages/engine/test/registry-routes.test.ts +++ b/packages/engine/test/registry-routes.test.ts @@ -239,7 +239,8 @@ describe("createFlowApiRouter", () => { ); expect(capabilitiesResponse.status).toBe(200); expect((await capabilitiesResponse.json()) as { userStream: boolean }).toEqual({ - userStream: false + userStream: false, + push: null }); const missingUserResponse = await router.POST( @@ -346,7 +347,9 @@ describe("createFlowApiRouter", () => { } } ); - expect(userStreamResponse.status).toBe(501); + // The push socket is a host's upgrade; a plain GET reaching the router + // is told so (FIX-2428). + expect(userStreamResponse.status).toBe(426); const deleteSessionResponse = await router.DELETE( new Request("http://localhost/api/flows/sessions/sess_1", { diff --git a/packages/engine/test/user-route-scoping.test.ts b/packages/engine/test/user-route-scoping.test.ts index d6bce44415..79d0d8a779 100644 --- a/packages/engine/test/user-route-scoping.test.ts +++ b/packages/engine/test/user-route-scoping.test.ts @@ -35,13 +35,15 @@ * * A route that is not built yet is pinned: its owner's call must answer 501 and * name no row. Building it breaks the pin, and the pin must then be replaced by - * a real entry. + * a real entry. A route a host serves as a WebSocket upgrade is pinned the same + * way to 426: the router itself serves it no rows, and the topics its socket + * hears come only from the mint, which has an entry of its own. */ import { defineFlow, handler, DEFAULT_ORG_ID } from "@flow-state-dev/core"; import { z } from "zod"; import { describe, expect, it } from "vitest"; -import { createFlowApiRouter, createFlowRegistry, createInMemoryStores } from "../src"; -import type { StoreRegistry } from "../src"; +import { createFlowApiRouter, createFlowRegistry, createInMemoryStores, enablePushDelivery } from "../src"; +import type { FlowApiRouter, StoreRegistry } from "../src"; import { listFlowRoutes, matchFlowRoute } from "../src/routes/router"; import { routeSubject } from "../src/routes/route-auth"; @@ -68,12 +70,44 @@ type ProbeEntry = { /** Values for path params other than `:userId`, if the pattern has any. */ params?: Record; query?: string; + /** A JSON body to send, given the row's id. */ + body?: (rowId: string) => unknown; + /** Set the app's router up before the call (turn a host feature on). */ + prepare?: (router: FlowApiRouter) => void; }; /** A route that is not built yet: it must answer 501 and serve nothing. */ type NotBuiltYet = { notBuiltYet: 501 }; -type TableEntry = ProbeEntry | NotBuiltYet; +/** + * A route a host serves as a WebSocket upgrade: through the router it must + * answer 426 and serve nothing. + */ +type UpgradeOnly = { upgradeOnly: 426 }; + +type TableEntry = ProbeEntry | NotBuiltYet | UpgradeOnly; + +/** A session owned by exactly `owner`, as the push mint checks one. */ +async function seedSession(stores: StoreRegistry, rowId: string, owner: Identity): Promise { + const at = Date.now() - 60_000; + await stores.session.set( + `${owner.tenantId}:${rowId}`, + { + id: rowId, + flowKind: owner.flowId, + flowId: owner.flowId, + userId: owner.userId, + orgId: owner.orgId, + tenantId: owner.tenantId, + state: {}, + version: 0, + createdAt: at, + updatedAt: at, + journal: [] + }, + "any" + ); +} /** * An in-flight request whose heartbeat stopped long ago: a request record in @@ -185,7 +219,20 @@ const USER_ROUTE_SCOPING: Record = { (entry) => entry.requestId === rowId ) ?? false }, - user_stream: { notBuiltYet: 501 } + user_stream: { upgradeOnly: 426 }, + user_stream_mint: { + // The push mint (FIX-2428): a row is reached when the answer grants its + // session's topic, which the socket would then hear. + seed: seedSession, + body: (rowId) => ({ topics: [{ scope: "session", id: rowId }] }), + prepare: (router) => { + enablePushDelivery(router, { secret: "scoping-test" }); + }, + saw: async ({ body }, rowId) => + (parseJson(body) as { topics?: Array<{ scope: string; id?: string }> } | undefined)?.topics?.some( + (topic) => topic.scope === "session" && topic.id === rowId + ) ?? false + } }; // ─── The apps and callers the harness probes with ─────────────────────────── @@ -332,15 +379,22 @@ const userRoutes = classifiedRoutes().filter((route) => route.subject === "user" async function callRoute( app: App, route: { method: string; pattern: string }, - entry: { params?: Record; query?: string }, + entry: Pick, userId: string, - headers: Record + headers: Record, + rowId = "" ): Promise { const path = samplePath(route.pattern, { ...entry.params, userId }).split("/").filter(Boolean); const method = route.method as "GET" | "POST" | "PATCH" | "DELETE"; const query = entry.query === undefined ? "" : `?${entry.query}`; + entry.prepare?.(app.router); + const body = entry.body?.(rowId); const response = await app.router[method]( - new Request(`http://localhost/api/flows/${path.join("/")}${query}`, { method, headers }), + new Request(`http://localhost/api/flows/${path.join("/")}${query}`, { + method, + headers: body === undefined ? headers : { ...headers, "content-type": "application/json" }, + ...(body === undefined ? {} : { body: JSON.stringify(body) }) + }), { params: { path } } ); return { status: response.status, body: await response.text(), stores: app.stores }; @@ -399,6 +453,19 @@ describe("user-route scoping · stage 2: no caller reaches a row outside their s continue; } + if ("upgradeOnly" in entry) { + describe(label, () => { + it("is a WebSocket upgrade: through the router the owner's call answers 426 and names no row", async () => { + const app = hostResolverApp(); + await seedStaleInFlight(app.stores, "owners-row", OWNER); + const observed = await callRoute(app, route, {}, OWNER.userId, OWNER_HEADERS); + expect(observed.status).toBe(426); + expect(observed.body).not.toContain("owners-row"); + }); + }); + continue; + } + describe(label, () => { // Runs first, and alone: an entry whose seed writes nothing, or whose // observer never reports a row, fails here instead of passing every axis @@ -412,7 +479,7 @@ describe("user-route scoping · stage 2: no caller reaches a row outside their s await entry.saw({ status: 0, body: "", stores: app.stores }, "owners-row"), "the entry's observer reports the row as reached before the route was called" ).toBe(false); - const observed = await callRoute(app, route, entry, OWNER.userId, OWNER_HEADERS); + const observed = await callRoute(app, route, entry, OWNER.userId, OWNER_HEADERS, "owners-row"); expect(observed.status).toBeLessThan(400); expect( await entry.saw(observed, "owners-row"), @@ -428,7 +495,7 @@ describe("user-route scoping · stage 2: no caller reaches a row outside their s it(`reaches the caller's own row (positive control for: ${axis.name})`, async () => { const app = axis.app(); await entry.seed(app.stores, "own-row", axis.own); - const observed = await callRoute(app, route, entry, axis.own.userId, axis.headers); + const observed = await callRoute(app, route, entry, axis.own.userId, axis.headers, "own-row"); expect( await entry.saw(observed, "own-row"), "the caller's own row was not reached, so the probe beside this proves nothing" @@ -442,7 +509,7 @@ describe("user-route scoping · stage 2: no caller reaches a row outside their s it(`serves nothing to ${axis.name}`, async () => { const app = axis.app(); await entry.seed(app.stores, "foreign-row", axis.foreign); - const observed = await callRoute(app, route, entry, axis.own.userId, axis.headers); + const observed = await callRoute(app, route, entry, axis.own.userId, axis.headers, "foreign-row"); expect(await entry.saw(observed, "foreign-row"), "a row outside the caller's scope was reached").toBe( false ); @@ -452,7 +519,7 @@ describe("user-route scoping · stage 2: no caller reaches a row outside their s it("refuses an anonymous caller when a host resolver is configured, before reading a row", async () => { const app = hostResolverApp(); await entry.seed(app.stores, "owners-row", OWNER); - const observed = await callRoute(app, route, entry, OWNER.userId, { [TENANT_HEADER]: "t1" }); + const observed = await callRoute(app, route, entry, OWNER.userId, { [TENANT_HEADER]: "t1" }, "owners-row"); expect(observed.status).toBe(401); expect(await entry.saw(observed, "owners-row")).toBe(false); }); diff --git a/packages/node/README.md b/packages/node/README.md index dc67011dda..82e31aaddf 100644 --- a/packages/node/README.md +++ b/packages/node/README.md @@ -49,6 +49,27 @@ until the router's stores are ready, then `200`. connections, drains in-flight requests (force-closing after the grace window), then disposes the router and the `FlowState`. +## Push + +`serve()` serves push: the WebSocket a client's `fsd.subscribe` (and React's +`useSubscription`) hears change notices on, at `/users/:userId/stream`. +`GET /capabilities` reports `push: { transport: "websocket" }`, so a client on +this host hears a change within about a second instead of reading on its timer. +`push: false` turns it off. `createServerApp` alone serves no socket and reports +`push: null`. + +Several processes behind one address need one signing key, so a connection +that lands on any of them is accepted: + +```ts +await serve(flowState, { pushSecret: process.env.FSD_PUSH_SECRET }); +``` + +`serve()` reads `FSD_PUSH_SECRET` itself when `pushSecret` is not given, and +otherwise uses a random key for the process. A notice reaches every process only +when the stores profile's change bus carries changes between processes; on the +default in-memory bus, clients keep reading on their timer between notices. + ## Serving a built `FlowApiRouter` directly If you already hold a router (for example from `createFlowApiRouter`, or to manage @@ -150,6 +171,8 @@ durable background work). See the deployment guides for the full topology: | `pageHandler` | — | A Connect-style `(req, res, next)` handler tried before `staticDir`'s SPA fallback for non-API GET requests, for a dev server's middleware. A real file in `staticDir` and a dedicated adapter route are served ahead of it. Calling `next()` passes the request on; `next(err)` returns a 500. | | `shutdownGraceMs` | `10000` | Grace window before lingering connections are force-closed. | | `disposeOnClose` | `true` | Whether `close()` disposes the `FlowState` after draining. Set `false` when several servers share one runtime, and dispose it yourself once they have all closed. | +| `push` | `true` | Serve the change-notice WebSocket at `/users/:userId/stream` (see [Push](#push)). `false` reports `push: null`. | +| `pushSecret` | `process.env.FSD_PUSH_SECRET`, then a random key | `string \| (() => string)`. The key push tickets are signed with. Give every process behind one address the same one. | ### `createPageHtmlTransform(options)` diff --git a/packages/node/package.json b/packages/node/package.json index 291d37a4ab..55a372f587 100644 --- a/packages/node/package.json +++ b/packages/node/package.json @@ -73,13 +73,15 @@ "dependencies": { "@flow-state-dev/engine": "workspace:*", "@hono/node-server": "^1.13.7", - "hono": "^4.6.14" + "hono": "^4.6.14", + "ws": "^8.21.3" }, "devDependencies": { "@flow-state-dev/client": "workspace:*", "@flow-state-dev/core": "workspace:*", "@flow-state-dev/testing": "workspace:*", "@types/node": "^22.0.0", + "@types/ws": "^8.18.1", "zod": "^3.24.1" }, "scripts": { diff --git a/packages/node/src/serve.ts b/packages/node/src/serve.ts index 176859507f..cab5a01fab 100644 --- a/packages/node/src/serve.ts +++ b/packages/node/src/serve.ts @@ -16,13 +16,30 @@ * on a non-API path to the SPA fallback; and a mid-stream SSE failure is handled * inside `@hono/node-server` rather than logged to stderr, so there is no longer a * server-side signal when a live stream dies mid-flight. + * + * Push delivery (FIX-2428): `serve()` is the host that serves the change + * notice socket. It turns push on for the router it fronts, so + * `GET /capabilities` reports `{ transport: "websocket" }` and the router + * answers the mint, then takes the WebSocket upgrade on + * `/users/:userId/stream` and moves frames between the socket and + * the engine's socket session. The engine decides what a socket hears; this + * file only carries frames. */ import type { IncomingMessage, Server, ServerResponse } from "node:http"; +import type { Duplex } from "node:stream"; +import { WebSocketServer, type WebSocket } from "ws"; import { serve as honoServe, type HttpBindings } from "@hono/node-server"; import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response"; import { readFile, stat } from "node:fs/promises"; import { extname, join, resolve, sep } from "node:path"; -import type { FlowApiRouter, FlowState, DevToolConnectionConfig } from "@flow-state-dev/engine"; +import { + enablePushDelivery, + isFlowState, + type DevToolConnectionConfig, + type FlowApiRouter, + type FlowState, + type PushDelivery, +} from "@flow-state-dev/engine"; import { createServerApp } from "./app"; import { createPageHtmlTransform } from "./page-html"; import { isLoopbackHost } from "./bind-guard"; @@ -83,6 +100,20 @@ export interface ServeOptions { * caller disposes it once, after every server has drained. */ disposeOnClose?: boolean; + /** + * Whether to serve push delivery: the WebSocket a client's + * `client.subscribe` hears change notices on, at + * `/users/:userId/stream`. Default `true`. With `false`, + * `GET /capabilities` reports `push: null` and clients read on their timer. + */ + push?: boolean; + /** + * The key push tickets are signed with. Needed only when several processes + * serve one address: give every one the same key, so a ticket minted on one + * is accepted by another. Default: `process.env.FSD_PUSH_SECRET`, else a + * random key for this process. + */ + pushSecret?: string | (() => string); } /** A Connect-style request handler: answer by writing `res`, or call `next()` to pass. */ @@ -163,6 +194,7 @@ export function serve( basePath: options.basePath, healthPath: options.healthPath, }); + const push = servePush(app, options); // Static assets + SPA fallback for the DevTool UI, GET-only (Hono also answers // HEAD). Registered after the portable app's health/API routes, so it only @@ -238,6 +270,7 @@ export function serve( clearTimeout(timer); resolveClose(); }; + push.close(); server.close(() => done()); // Force-close lingering connections (e.g. open SSE streams) once the // grace window elapses so shutdown can't hang. @@ -282,9 +315,110 @@ export function serve( }, ) as Server; server.once("error", onError); + server.on("upgrade", (req, socket, head) => push.upgrade(server, req, socket, head)); }); } +const DEFAULT_BASE_PATH = "/api/flows"; +/** The largest frame a client may send: a ticket, or a list of topics. */ +const MAX_PUSH_FRAME_BYTES = 64 * 1024; + +/** The push half of a served app: the upgrade it takes, and its teardown. */ +type ServedPush = { + upgrade(server: Server, req: IncomingMessage, socket: Duplex, head: Buffer): void; + close(): void; +}; + +/** + * Turn push on for the router `app` resolves to, and take upgrades on its + * socket path. A router not built by `createFlowApiRouter` has no push, and + * reports none. + */ +function servePush(app: FlowState | FlowApiRouter, options: ServeOptions): ServedPush { + const basePath = (options.basePath ?? DEFAULT_BASE_PATH).replace(/\/+$/, ""); + const envSecret = process.env.FSD_PUSH_SECRET; + const secret = options.pushSecret ?? (envSecret !== undefined && envSecret.length > 0 ? envSecret : undefined); + const enable = (router: FlowApiRouter): PushDelivery | undefined => { + try { + return enablePushDelivery(router, secret !== undefined ? { secret } : {}); + } catch { + return undefined; + } + }; + // A raw router is enabled at once; a FlowState once its router resolves, + // which is before any request it serves can reach the router. + const delivery: Promise = + options.push === false + ? Promise.resolve(undefined) + : isFlowState(app) + ? app.getRouter().then(enable, () => undefined) + : Promise.resolve(enable(app)); + const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_PUSH_FRAME_BYTES }); + + return { + upgrade(server, req, socket, head) { + const userId = socketUserId(req.url, basePath); + if (userId === undefined) { + // Another listener (a dev server's hot reload) may own this path. + if (server.listenerCount("upgrade") <= 1) refuseUpgrade(socket, 404); + return; + } + void delivery.then((served) => { + if (served === undefined) { + refuseUpgrade(socket, 404); + return; + } + wss.handleUpgrade(req, socket, head, (ws) => carry(ws, served.openSocket(userId, ioFor(ws)))); + }); + }, + close() { + for (const client of wss.clients) client.terminate(); + wss.close(); + }, + }; +} + +/** The engine's view of a socket: send a frame, or close with a code. */ +function ioFor(ws: WebSocket) { + return { + send: (frame: unknown) => { + if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(frame)); + }, + close: (code: number, reason: string) => ws.close(code, reason), + }; +} + +/** Move the client's text frames to the session, and tell it when the socket goes. */ +function carry(ws: WebSocket, session: ReturnType): void { + ws.on("message", (data, isBinary) => { + if (isBinary) { + ws.close(4400, "bad frame"); + return; + } + session.receive(Array.isArray(data) ? Buffer.concat(data).toString("utf8") : Buffer.from(data as ArrayBuffer).toString("utf8")); + }); + ws.on("close", () => session.closed()); + ws.on("error", () => session.closed()); +} + +/** The user a socket path names: `/users/:userId/stream`, or undefined. */ +function socketUserId(url: string | undefined, basePath: string): string | undefined { + if (url === undefined) return undefined; + const pathname = url.split("?")[0] ?? ""; + if (!pathname.startsWith(`${basePath}/users/`)) return undefined; + const rest = pathname.slice(`${basePath}/users/`.length).split("/"); + if (rest.length !== 2 || rest[1] !== "stream" || rest[0] === "") return undefined; + try { + return decodeURIComponent(rest[0]!); + } catch { + return undefined; + } +} + +function refuseUpgrade(socket: Duplex, status: 404): void { + socket.end(`HTTP/1.1 ${status} Not Found\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`); +} + /** * Run a Connect-style handler on the raw Node request. Resolves `true` once the * handler has finished the response, `false` when it calls `next()`; rejects on diff --git a/packages/node/test/serve-push.test.ts b/packages/node/test/serve-push.test.ts new file mode 100644 index 0000000000..a3917e67af --- /dev/null +++ b/packages/node/test/serve-push.test.ts @@ -0,0 +1,211 @@ +/** + * Push delivery on `serve()` (FIX-2428): the Node host serves the socket on + * `GET /users/:userId/stream` with an upgrade, and the router it + * fronts reports `push` and answers the mint. Real WebSocket clients against + * a bound port. + */ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { z } from "zod"; +import { defineFlow, handler, topic, type PushMintAnswer, type PushServerFrame } from "@flow-state-dev/core"; +import { createFlowState, inMemoryStores, type FlowState } from "@flow-state-dev/engine"; +import { createServerApp } from "../src/app"; +import { serve, type ServeHandle, type ServeOptions } from "../src/serve"; + +const chat = defineFlow({ + kind: "chat", + actions: { + say: { + inputSchema: z.object({ text: z.string() }), + block: handler({ + name: "chat-say", + inputSchema: z.object({ text: z.string() }), + execute: () => ({}) + }) + } + } +})(); + +const handles: ServeHandle[] = []; +const sockets: WebSocket[] = []; + +afterEach(async () => { + for (const socket of sockets.splice(0)) socket.close(); + await Promise.all(handles.splice(0).map((handle) => handle.close())); + vi.unstubAllEnvs(); + vi.restoreAllMocks(); +}); + +async function start(options: ServeOptions = {}): Promise<{ handle: ServeHandle; base: string; flowState: FlowState }> { + const flowState = createFlowState({ flows: { chat }, stores: { default: { primary: inMemoryStores() } } }); + const handle = await serve(flowState, { port: 0, host: "127.0.0.1", handleSignals: false, shutdownGraceMs: 200, ...options }); + handles.push(handle); + return { handle, base: `http://127.0.0.1:${handle.port}`, flowState }; +} + +async function mint(base: string, topics: unknown[], apiPath = "/api/flows"): Promise { + const response = await fetch(`${base}${apiPath}/users/alice/stream`, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ topics }) + }); + expect(response.status).toBe(200); + return (await response.json()) as PushMintAnswer; +} + +/** Open a socket at `path` and collect what it hears. */ +function open(base: string, path: string) { + const socket = new WebSocket(`${base.replace(/^http/, "ws")}${path}`); + sockets.push(socket); + const frames: PushServerFrame[] = []; + let closeCode: number | undefined; + const opened = new Promise((resolve, reject) => { + socket.addEventListener("open", () => resolve(), { once: true }); + socket.addEventListener("error", () => reject(new Error("socket failed")), { once: true }); + }); + const closed = new Promise((resolve) => { + socket.addEventListener("close", (event) => { + closeCode = event.code; + resolve(event.code); + }); + }); + socket.addEventListener("message", (event) => frames.push(JSON.parse(String(event.data)) as PushServerFrame)); + return { socket, frames, opened, closed, closeCode: () => closeCode }; +} + +async function until(check: () => boolean, ms = 2000): Promise { + const end = Date.now() + ms; + while (!check()) { + if (Date.now() > end) throw new Error("timed out"); + await new Promise((resolve) => setTimeout(resolve, 10)); + } +} + +describe("serve() push delivery", () => { + it("reports the WebSocket push in capabilities, and none with push: false", async () => { + const on = await start(); + expect(await (await fetch(`${on.base}/api/flows/capabilities`)).json()).toEqual({ + userStream: false, + push: { transport: "websocket" } + }); + const off = await start({ push: false }); + expect(await (await fetch(`${off.base}/api/flows/capabilities`)).json()).toEqual({ userStream: false, push: null }); + expect((await fetch(`${off.base}/api/flows/users/alice/stream`, { method: "POST", body: "{}" })).status).toBe(404); + }); + + it("delivers a change in a session to a socket subscribed through the mint", async () => { + const { base } = await start(); + const created = await fetch(`${base}/api/flows/chat/sessions`, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ userId: "alice" }) + }); + const sessionId = ((await created.json()) as { session: { id: string } }).session.id; + const answer = await mint(base, [topic.session(sessionId)]); + expect(answer.transport).toBe("websocket"); + if (answer.transport !== "websocket") return; + expect(answer.topics).toEqual([topic.session(sessionId)]); + + const ws = open(base, `/api/flows${answer.path}`); + await ws.opened; + ws.socket.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); + await until(() => ws.frames.length > 0); + expect(ws.frames[0]).toEqual({ type: "crossing", crosses: false }); + + await fetch(`${base}/api/flows/chat/${sessionId}/actions/say`, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ userId: "alice", input: { text: "hi" } }) + }); + await until(() => ws.frames.some((frame) => frame.type === "notice")); + const notice = ws.frames.find((frame) => frame.type === "notice"); + expect(notice).toMatchObject({ type: "notice", topic: { scope: "session", id: sessionId } }); + }); + + it("serves the socket under a custom basePath, and nowhere else", async () => { + const { base } = await start({ basePath: "/v1" }); + const answer = await mint(base, [topic.user()], "/v1"); + if (answer.transport !== "websocket") throw new Error("expected websocket"); + const ws = open(base, `/v1${answer.path}`); + await ws.opened; + const stray = open(base, `/api/flows${answer.path}`); + await expect(stray.opened).rejects.toThrow(); + }); + + it("closes a socket whose ticket names another user than its path", async () => { + vi.spyOn(console, "warn").mockImplementation(() => {}); + const { base } = await start(); + const answer = await mint(base, [topic.user()]); + if (answer.transport !== "websocket") throw new Error("expected websocket"); + const ws = open(base, "/api/flows/users/bob/stream"); + await ws.opened; + ws.socket.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); + expect(await ws.closed).toBe(4401); + }); + + it("accepts a ticket another process minted when both share pushSecret, and refuses it otherwise", async () => { + vi.spyOn(console, "warn").mockImplementation(() => {}); + const a = await start({ pushSecret: "shared" }); + const b = await start({ pushSecret: () => "shared" }); + const c = await start(); + const answer = await mint(a.base, [topic.user()]); + if (answer.transport !== "websocket") throw new Error("expected websocket"); + + const onB = open(b.base, `/api/flows${answer.path}`); + await onB.opened; + onB.socket.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); + await until(() => onB.frames.length > 0); + expect(onB.frames[0]).toEqual({ type: "crossing", crosses: false }); + + const onC = open(c.base, `/api/flows${answer.path}`); + await onC.opened; + onC.socket.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); + expect(await onC.closed).toBe(4401); + }); + + it("takes the shared secret from FSD_PUSH_SECRET when pushSecret is not given", async () => { + vi.stubEnv("FSD_PUSH_SECRET", "from-env"); + const a = await start(); + const b = await start({ pushSecret: "from-env" }); + const answer = await mint(a.base, [topic.user()]); + if (answer.transport !== "websocket") throw new Error("expected websocket"); + const ws = open(b.base, `/api/flows${answer.path}`); + await ws.opened; + ws.socket.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); + await until(() => ws.frames.length > 0); + expect(ws.frames[0]?.type).toBe("crossing"); + }); + + it("closes open sockets when the server closes", async () => { + const { base, handle } = await start(); + const answer = await mint(base, [topic.user()]); + if (answer.transport !== "websocket") throw new Error("expected websocket"); + const ws = open(base, `/api/flows${answer.path}`); + await ws.opened; + handles.splice(handles.indexOf(handle), 1); + await handle.close(); + await ws.closed; + expect(ws.closeCode()).toBeDefined(); + }); + + it("leaves an upgrade on another path to another listener", async () => { + const { base, handle } = await start(); + let heard = ""; + handle.server.on("upgrade", (req, socket) => { + heard = req.url ?? ""; + socket.destroy(); + }); + const other = open(base, "/hmr"); + await expect(other.opened).rejects.toThrow(); + expect(heard).toBe("/hmr"); + }); +}); + +describe("createServerApp", () => { + it("serves no push: capabilities says so, with no socket to open", async () => { + const flowState = createFlowState({ flows: { chat }, stores: { default: { primary: inMemoryStores() } } }); + const { app, dispose } = createServerApp(flowState); + const response = await app.fetch(new Request("http://localhost/api/flows/capabilities")); + expect(await response.json()).toEqual({ userStream: false, push: null }); + await dispose(); + }); +}); diff --git a/packages/react/README.md b/packages/react/README.md index 71479dc195..a0c97d7702 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -249,6 +249,24 @@ Fetches the static manifest of public resources for the session's flow. Cached m Low-level hook for direct action execution without session management. +### `useSubscription(topics, read, options?)` + +Runs `read` again when something under `topics` changes, through the provider's +client and `fsd.subscribe`. One read runs at a time and at most one more waits, +so a burst of changes is one more read. `read` gets the notice that woke it, or +`null` for a connect, a reconnect, a timer tick, or a wait that stands for +several different notices. It doesn't read on mount. + +```tsx +import { topic } from "@flow-state-dev/client"; + +useSubscription([topic.session(sessionId)], refresh, { pollIntervalMs: 3000 }); +``` + +`pollIntervalMs` reads on a timer wherever push can miss a change (a host with +no push, a socket that is down); omit it for no timer. `enabled: false` +subscribes nothing. For a session's own items, use `useSession({ live: true })`. + ### `useRequestStream(options)` Low-level hook for subscribing to a request's SSE stream with reactive item/status views. Message and reasoning text streams in token-by-token. diff --git a/packages/react/src/hooks/useSubscription.ts b/packages/react/src/hooks/useSubscription.ts new file mode 100644 index 0000000000..3a1c4fc92b --- /dev/null +++ b/packages/react/src/hooks/useSubscription.ts @@ -0,0 +1,83 @@ +/** + * `useSubscription(topics, read, options)` (FIX-2428): run a screen's read + * again when something under `topics` changes. + * + * It subscribes through the provider's client (`client.subscribe`), which + * owns the one socket and the timer: push on a host that has it, and a read + * every `pollIntervalMs` wherever push can miss a change. The read goes + * through the coalesced read, so a burst of notices is one read in flight + * and at most one waiting. + * + * `read` gets the notice that woke it, or `null` for a connect, a reconnect + * or a timer tick. A waiting read that stands for several different notices + * gets `null` too, so a read that acts on a notice's kind reads everything + * then. + */ +import { useEffect, useMemo, useRef } from "react"; +import type { WireNotice, WireTopic } from "@flow-state-dev/client"; +import { coalescedReads } from "../internal/coalescedReads"; +import { useClient } from "../internal/useClient"; + +/** Options for {@link useSubscription}. */ +export type UseSubscriptionOptions = { + /** + * Read at this pace wherever push can miss a change: the host has no push, + * the socket is down, or its bus doesn't cross processes. Omit for no + * timer: the read then runs on a notice, a connect and a reconnect. + */ + pollIntervalMs?: number; + /** `false` subscribes nothing. Default `true`. */ + enabled?: boolean; +}; + +/** One key per distinct topic list, so an equal list keeps the subscription. */ +function topicsKey(topics: readonly WireTopic[]): string { + return JSON.stringify( + topics.map((t) => [t.scope, t.scope === "session" ? t.id : "", t.resource ?? ""]) + ); +} + +function sameNotice(a: WireNotice | null, b: WireNotice | null): boolean { + if (a === null || b === null) return a === b; + return a.kind === b.kind && topicsKey([a.topic]) === topicsKey([b.topic]); +} + +/** + * Run `read` when something under `topics` changes. `read` may return a + * promise; the next read waits for it. + */ +export function useSubscription( + topics: readonly WireTopic[], + read: (notice: WireNotice | null) => unknown, + options: UseSubscriptionOptions = {} +): void { + const client = useClient(); + const readRef = useRef(read); + readRef.current = read; + const key = topicsKey(topics); + // The latest list for this key: a new array of the same topics keeps it. + // eslint-disable-next-line react-hooks/exhaustive-deps + const stable = useMemo(() => topics, [key]); + const { pollIntervalMs, enabled = true } = options; + + useEffect(() => { + if (!enabled || stable.length === 0) return; + let next: { notice: WireNotice | null } | undefined; + const reads = coalescedReads(async () => { + const notice = next?.notice ?? null; + next = undefined; + await readRef.current(notice); + }); + const subscription = client.subscribe(stable, { + onChange: (notice) => { + next = next === undefined || sameNotice(next.notice, notice) ? { notice } : { notice: null }; + reads.request(); + }, + ...(pollIntervalMs !== undefined ? { pollIntervalMs } : {}) + }); + return () => { + subscription.close(); + reads.close(); + }; + }, [client, stable, pollIntervalMs, enabled]); +} diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts index 2488744c43..54c06bc099 100644 --- a/packages/react/src/index.ts +++ b/packages/react/src/index.ts @@ -192,6 +192,8 @@ export { export { useDraft, clearDraft, readDraft, saveDraft } from "./hooks/useDraft"; +export { useSubscription, type UseSubscriptionOptions } from "./hooks/useSubscription"; + export { isSendKey, isTypingTarget, diff --git a/packages/react/test/support/fake-client.ts b/packages/react/test/support/fake-client.ts index 9a3d1a65e0..212566843c 100644 --- a/packages/react/test/support/fake-client.ts +++ b/packages/react/test/support/fake-client.ts @@ -35,6 +35,7 @@ export type FakeClientParts = { // eslint-disable-next-line @typescript-eslint/no-explicit-any -- each test types its own capture requestStream?: (options: RequestStreamOptions & { url: string } & Record) => RequestStreamHandle; sessionStream?: (options: SessionStreamOptions & { sessionId: string }) => SessionStreamHandle; + subscribe?: Client["subscribe"]; }; const closed = { close() {}, lastEventId: undefined } as RequestStreamHandle; @@ -113,7 +114,7 @@ export function fakeClient(parts: FakeClientParts): Client { (parts.resources as Record | undefined)?.[name] ?? (() => missing(`resources.${name}`)) }), requests: { interrupted: async () => missing("requests.interrupted") }, - stream: () => ({ close() {}, lastEventId: undefined }), + subscribe: (topics, options) => parts.subscribe?.(topics, options) ?? { close() {} }, transcribe: async () => missing("transcribe") }; } diff --git a/packages/react/test/useSubscription.test.ts b/packages/react/test/useSubscription.test.ts new file mode 100644 index 0000000000..e9720fa99c --- /dev/null +++ b/packages/react/test/useSubscription.test.ts @@ -0,0 +1,176 @@ +// @vitest-environment happy-dom +/** + * `useSubscription` (FIX-2428): the hook a screen calls with the topics it + * shows and the read it already makes. It subscribes through the client's + * `subscribe`, which owns the socket and the timer, and runs the read through + * the coalesced read, so a burst of notices is one read in flight and one + * waiting. + * + * The read gets the notice that woke it, or `null` for a connect, a + * reconnect or a timer tick. A waiting read that stands for several + * different notices gets `null`: read everything, since no one notice + * describes it. + */ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { act, renderHook } from "@testing-library/react"; +import type { SubscribeOptions, WireNotice, WireTopic } from "@flow-state-dev/client"; + +const { subscriptions } = vi.hoisted(() => ({ + subscriptions: [] as Array<{ topics: readonly WireTopic[]; options: SubscribeOptions; closed: boolean }> +})); + +vi.mock("@flow-state-dev/client", async (importOriginal) => { + const actual = await importOriginal(); + const { fakeClient } = await import("./support/fake-client"); + return { + ...actual, + createClient: () => + fakeClient({ + subscribe: (topics, options) => { + const entry = { topics, options, closed: false }; + subscriptions.push(entry); + return { + close() { + entry.closed = true; + } + }; + } + }) + }; +}); + +const { useSubscription } = await import("../src"); +const { topic } = await import("@flow-state-dev/client"); + +afterEach(() => { + subscriptions.length = 0; +}); + +const S1 = topic.session("s1"); +const notice = (kind: WireNotice["kind"], at: WireTopic = S1): WireNotice => ({ topic: at, kind }); + +/** A read the test settles by hand. */ +function gatedRead() { + const calls: Array = []; + let release: (() => void) | undefined; + const read = vi.fn((n: WireNotice | null) => { + calls.push(n); + return new Promise((resolve) => { + release = resolve; + }); + }); + return { + read, + calls, + settle: async () => { + await act(async () => { + release?.(); + await Promise.resolve(); + await Promise.resolve(); + }); + } + }; +} + +describe("useSubscription", () => { + it("subscribes its topics through the client, with its poll interval, and closes on unmount", () => { + const { unmount } = renderHook(() => useSubscription([S1, topic.org()], () => {}, { pollIntervalMs: 3000 })); + expect(subscriptions).toHaveLength(1); + expect(subscriptions[0]!.topics).toEqual([S1, topic.org()]); + expect(subscriptions[0]!.options.pollIntervalMs).toBe(3000); + unmount(); + expect(subscriptions[0]!.closed).toBe(true); + }); + + it("omits the poll interval when the screen does: no timer", () => { + renderHook(() => useSubscription([S1], () => {})); + expect(subscriptions[0]!.options.pollIntervalMs).toBeUndefined(); + }); + + it("passes the read the notice that woke it, and null for a connect or a tick", async () => { + const gate = gatedRead(); + renderHook(() => useSubscription([S1], gate.read)); + act(() => subscriptions[0]!.options.onChange(notice("request"))); + await gate.settle(); + act(() => subscriptions[0]!.options.onChange(null)); + await gate.settle(); + expect(gate.calls).toEqual([notice("request"), null]); + }); + + it("folds a burst of notices into one read in flight and one waiting", async () => { + const gate = gatedRead(); + renderHook(() => useSubscription([S1], gate.read)); + const { onChange } = subscriptions[0]!.options; + act(() => { + onChange(notice("items")); + onChange(notice("items")); + onChange(notice("items")); + onChange(notice("items")); + }); + expect(gate.read).toHaveBeenCalledTimes(1); + await gate.settle(); + expect(gate.read).toHaveBeenCalledTimes(2); + await gate.settle(); + expect(gate.read).toHaveBeenCalledTimes(2); + expect(gate.calls).toEqual([notice("items"), notice("items")]); + }); + + it("gives a waiting read that stands for different notices null, so it reads everything", async () => { + const gate = gatedRead(); + renderHook(() => useSubscription([S1], gate.read)); + const { onChange } = subscriptions[0]!.options; + act(() => { + onChange(notice("items")); + onChange(notice("request")); + onChange(notice("items")); + }); + await gate.settle(); + expect(gate.calls).toEqual([notice("items"), null]); + }); + + it("keeps one subscription across renders with an equal topic list, and calls the latest read", async () => { + const first = vi.fn(); + const second = vi.fn(); + const { rerender } = renderHook(({ read }) => useSubscription([topic.session("s1")], read), { + initialProps: { read: first } + }); + rerender({ read: second }); + expect(subscriptions).toHaveLength(1); + await act(async () => { + subscriptions[0]!.options.onChange(null); + await Promise.resolve(); + }); + expect(first).not.toHaveBeenCalled(); + expect(second).toHaveBeenCalledWith(null); + }); + + it("subscribes again when the topics change, and closes the old one", () => { + const { rerender } = renderHook(({ id }) => useSubscription([topic.session(id)], () => {}), { + initialProps: { id: "s1" } + }); + rerender({ id: "s2" }); + expect(subscriptions.map((entry) => [entry.topics, entry.closed])).toEqual([ + [[topic.session("s1")], true], + [[topic.session("s2")], false] + ]); + }); + + it("subscribes nothing while disabled or with no topics", () => { + renderHook(() => useSubscription([S1], () => {}, { enabled: false })); + renderHook(() => useSubscription([], () => {})); + expect(subscriptions).toEqual([]); + }); + + it("drops a waiting read on unmount", async () => { + const gate = gatedRead(); + const { unmount } = renderHook(() => useSubscription([S1], gate.read)); + const { onChange } = subscriptions[0]!.options; + act(() => { + onChange(notice("items")); + onChange(notice("items")); + }); + unmount(); + await gate.settle(); + expect(gate.read).toHaveBeenCalledTimes(1); + }); +}); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 3eb804e000..40ee647ad6 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1555,6 +1555,9 @@ importers: hono: specifier: ^4.6.14 version: 4.12.27 + ws: + specifier: ^8.21.3 + version: 8.21.3 devDependencies: '@flow-state-dev/client': specifier: workspace:* @@ -1568,6 +1571,9 @@ importers: '@types/node': specifier: ^22.0.0 version: 22.19.13 + '@types/ws': + specifier: ^8.18.1 + version: 8.18.1 zod: specifier: ^3.24.1 version: 3.25.76 @@ -12401,18 +12407,6 @@ packages: utf-8-validate: optional: true - ws@8.19.0: - resolution: {integrity: sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==} - engines: {node: '>=10.0.0'} - peerDependencies: - bufferutil: ^4.0.1 - utf-8-validate: '>=5.0.2' - peerDependenciesMeta: - bufferutil: - optional: true - utf-8-validate: - optional: true - ws@8.21.3: resolution: {integrity: sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==} engines: {node: '>=10.0.0'} @@ -23677,7 +23671,7 @@ snapshots: recast: 0.23.11 semver: 7.7.4 use-sync-external-store: 1.6.0(react@19.2.4) - ws: 8.19.0 + ws: 8.21.3 optionalDependencies: prettier: 2.8.8 transitivePeerDependencies: @@ -24772,8 +24766,6 @@ snapshots: ws@7.5.10: {} - ws@8.19.0: {} - ws@8.21.3: {} wsl-utils@0.1.0: From 7d98fce7b4a4e5e1dede0f14f7351c504070eaa0 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 02:44:06 +0000 Subject: [PATCH 2/8] fix(FIX-2428): mint answer, session recheck, shared key, backoff; docs pass - client: a mint answer the client can't use (no body, a proxy page, no ticket, another transport) means no push: read on the timer, never reject. Fixes the unhandled rejection in CI (Test 3/3). - engine: the mint rechecks the session with loadCheckedSession after the guard, so a session recreated for another user mid-sign-in is dropped (Codex r4450345464). - engine: one default key per router; sockets read the router's current key, so two hosts on one router accept each other's tickets (Codex r4450345470). - client: the backoff resets on the first crossing frame, not on open, so refused tickets back off 1, 2, 4, 8, 16 s (Codex r4450345475). - docs: docs-editor round (one null list, change bus introduced, no "within a second" claim, listTasks_tasks), changeset migration note. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn --- .changeset/websocket-push.md | 2 +- apps/docs/docs/api/client.md | 6 +-- apps/docs/docs/api/react.md | 2 +- apps/docs/docs/client/overview.md | 2 +- apps/docs/docs/client/react.md | 2 +- apps/docs/docs/server/setup.md | 2 +- apps/docs/guides/realtime.md | 16 ++++--- goals/realtime/websocket-delivery/goal.md | 1 + packages/client/README.md | 6 ++- packages/client/src/subscribe/push-hub.ts | 49 +++++++++++++++++----- packages/client/test/subscribe.test.ts | 49 +++++++++++++++++++++- packages/engine/README.md | 8 ++-- packages/engine/src/push/push-delivery.ts | 23 ++++++---- packages/engine/test/push-delivery.test.ts | 48 +++++++++++++++++++++ packages/node/README.md | 8 ++-- packages/node/test/serve-push.test.ts | 22 ++++++++++ packages/react/README.md | 6 ++- 17 files changed, 205 insertions(+), 47 deletions(-) diff --git a/.changeset/websocket-push.md b/.changeset/websocket-push.md index ad27e456ac..eefd80f240 100644 --- a/.changeset/websocket-push.md +++ b/.changeset/websocket-push.md @@ -9,7 +9,7 @@ Screens can read again when something they show changes, without polling on the Node host (FIX-2428). -- **client:** `fsd.subscribe(topics, { onChange, pollIntervalMs? })` calls `onChange` with the notice that woke it (`{ topic, kind, origin? }`), or `null` for a connect, a reconnect or a timer tick. Build topics with `topic.session(id)`, `topic.user()` and `topic.org()`, now exported from the client too. On a host with push, one WebSocket per client carries the notices, signed in through the client's fetcher; elsewhere `onChange(null)` runs every `pollIntervalMs`. `FlowCapabilities` gains `push`. **Breaking:** `fsd.stream()` never worked (the server answered 501); use `fsd.subscribe()`. `UserStreamOptions`, `UserSSECallbacks` and `UserStreamHandle` are removed with it. +- **client:** `fsd.subscribe(topics, { onChange, pollIntervalMs? })` calls `onChange` with the notice that woke it (`{ topic, kind, origin? }`), or `null` for a connect, a reconnect or a timer tick. Build topics with `topic.session(id)`, `topic.user()` and `topic.org()`, now exported from the client too. On a host with push, one WebSocket per client carries the notices, signed in through the client's fetcher; elsewhere `onChange(null)` runs every `pollIntervalMs`. `FlowCapabilities` gains `push`. **Breaking:** `fsd.stream()` is removed. It never worked (the server answered 501); use `fsd.subscribe()`. `UserStreamOptions`, `UserSSECallbacks` and `UserStreamHandle` are removed with it. Migration: replace `fsd.stream({ onResourceChanged, onScopeStateChanged, ... })` with `fsd.subscribe([topic.user(), topic.org()], { onChange: () => reread() })`, and read what you show in `onChange`. A notice carries no rows, so the read is what tells you what changed. - **react:** `useSubscription(topics, read, { pollIntervalMs?, enabled? })` runs a screen's read again on a change, one read in flight and one waiting. - **node:** `serve()` serves the change-notice WebSocket at `/users/:userId/stream`. New options: `push` (default `true`) and `pushSecret` (default `FSD_PUSH_SECRET`, then a random key), which every process behind one address must share. - **engine:** `GET /capabilities` answers `{ userStream: false, push }`. `POST /users/:userId/stream` checks each topic with its scope's read check and answers a short ticket for the granted ones; a refused topic is left out, as a missing session is. `GET /users/:userId/stream` answers 426 instead of 501. `enablePushDelivery(router, { secret? })` turns push on for a host that serves the socket. diff --git a/apps/docs/docs/api/client.md b/apps/docs/docs/api/client.md index ea837431f2..ec3dbaec98 100644 --- a/apps/docs/docs/api/client.md +++ b/apps/docs/docs/api/client.md @@ -458,7 +458,7 @@ async function readHistory() { ### `fsd.subscribe(topics, options)` -Calls `onChange` when something under one of `topics` may have changed, so you can read it again. The call tells you when to read, never what changed: `onChange` makes the read your screen already makes, and that read is checked on the server as always. +Calls `onChange` when something under one of `topics` may have changed, so you can read it again. The call tells you when to read, never what changed: `onChange` makes the read your screen already makes, and that read is checked on the server like any other. ```ts import { createClient, topic } from "@flow-state-dev/client"; @@ -476,7 +476,7 @@ sub.close(); | Option | Type | Notes | |--------|------|-------| -| `onChange` | `(notice: WireNotice \| null) => void` | Required. Gets the notice that woke it, `{ topic, kind, origin? }`, or `null` for a connect, a reconnect, a timer tick, or a change in whether push reaches every server process. | +| `onChange` | `(notice: WireNotice \| null) => void` | Required. Gets the notice that woke it, `{ topic, kind, origin? }`, or `null` when the screen should read everything again: after a connect or a reconnect, on a timer tick, and when push starts or stops reaching every server process. | | `pollIntervalMs` | `number` | Call `onChange(null)` at this pace wherever push can miss a change: the server has no push, the socket is down, or the server process the socket reached can't hear the others. Omitted, there is no timer. | It returns `{ close() }`. @@ -497,7 +497,7 @@ A notice's `kind` is `"items"`, `"request"`, `"run"` or `"resync"`; `origin.requ **On a host with no push** (Vercel, Next.js, `createServerApp` alone), `onChange(null)` runs on the `pollIntervalMs` timer and nothing else. The same code works on both. -**On several processes**, push reaches a socket only if the server's change bus carries changes between processes. The default in-memory bus doesn't, even with one process, so a subscription with `pollIntervalMs` keeps reading on its timer between notices there. Give every process behind one address the same `pushSecret` (see [server setup](/docs/server/setup)). +**On several processes**: Each server keeps a *change bus*, the `bus` slot of its stores profile (the stores you hand `createFlowState`; see [Store adapters](/docs/persistence/overview#store-adapters)). A bus that *crosses processes* hands a change made in one server process to every other one. Push reaches every socket only on such a bus. The default in-memory bus doesn't cross processes, even when you run one, so a subscription with `pollIntervalMs` keeps reading on its timer between notices there. Give every process behind one address the same `pushSecret` (see [server setup](/docs/server/setup)). See the [realtime guide](/guides/realtime) for the whole picture. diff --git a/apps/docs/docs/api/react.md b/apps/docs/docs/api/react.md index 0c6defbd06..1f5d047677 100644 --- a/apps/docs/docs/api/react.md +++ b/apps/docs/docs/api/react.md @@ -170,7 +170,7 @@ useSubscription([topic.session(sessionId)], refresh, { pollIntervalMs: 3000 }); | Argument | Type | Notes | |----------|------|-------| | `topics` | `WireTopic[]` | From `topic.session(id)`, `topic.user()`, `topic.org()`. A new array with the same topics keeps the subscription. | -| `read` | `(notice: WireNotice \| null) => unknown` | The screen's read. One runs at a time, and at most one more waits. Gets the notice that woke it, or `null` for a connect, a reconnect, a timer tick, or a wait that stands for several different notices. | +| `read` | `(notice: WireNotice \| null) => unknown` | The screen's read. One runs at a time, and at most one more waits. Gets the notice that woke it, or `null` when the screen should read everything again: after a connect or a reconnect, on a timer tick, and when push starts or stops reaching every server process. It also gets `null` when several changes arrived during one read (one follow-up read covers them all). | | `options.pollIntervalMs` | `number` | Read at this pace wherever push can miss a change. Omitted, no timer. | | `options.enabled` | `boolean` | `false` subscribes nothing. Default `true`. | diff --git a/apps/docs/docs/client/overview.md b/apps/docs/docs/client/overview.md index dca8e06639..31f29c5e37 100644 --- a/apps/docs/docs/client/overview.md +++ b/apps/docs/docs/client/overview.md @@ -316,7 +316,7 @@ const sub = fsd.subscribe([topic.session(sessionId)], { }); ``` -`onChange` is told when to read, never what changed. On the Node host it runs within a second of a change, over a WebSocket. On a host with no push, such as Vercel, it runs every `pollIntervalMs`. The code is the same on both. To follow a session's own items, use `fsd.sessions.stream` (or `useSession({ live: true })`) instead. See [`fsd.subscribe`](/docs/api/client#fsdsubscribetopics-options) and the [realtime guide](/guides/realtime). +`onChange` is told when to read, never what changed. On the Node host it runs as soon as the change is saved: the server sends the notice once the change can be read, and no timer is involved, so the delay is the network and your read, over a WebSocket. On a host with no push, such as Vercel, it runs every `pollIntervalMs`. The code is the same on both. To follow a session's own items, use `fsd.sessions.stream` (or `useSession({ live: true })`) instead. See [`fsd.subscribe`](/docs/api/client#fsdsubscribetopics-options) and the [realtime guide](/guides/realtime). ## Transcription diff --git a/apps/docs/docs/client/react.md b/apps/docs/docs/client/react.md index 25ff2eb7dd..c23238a2ba 100644 --- a/apps/docs/docs/client/react.md +++ b/apps/docs/docs/client/react.md @@ -163,7 +163,7 @@ const refresh = useCallback( useSubscription([topic.session(sessionId)], refresh, { pollIntervalMs: 3000 }); ``` -The read runs within a second of a change on the Node host, and every `pollIntervalMs` on a host with no push. A burst of changes runs it once more after the read in flight finishes, not once per change. The read gets the notice that woke it (`{ topic, kind, origin? }`), or `null` for a connect, a reconnect or a timer tick; act on `kind` when the screen only cares about some changes, and read everything on `null`. Leave `pollIntervalMs` out for no timer. `enabled: false` subscribes nothing. +On the Node host the read runs as soon as the change is saved, over a WebSocket; on a host with no push it runs every `pollIntervalMs`. A burst of changes runs it once more after the read in flight finishes, not once per change. The read gets the notice that woke it (`{ topic, kind, origin? }`), or `null` when the screen should read everything again: after a connect or a reconnect, on a timer tick, and when push starts or stops reaching every server process. Act on `kind` when the screen only cares about some changes, and read everything on `null`. Leave `pollIntervalMs` out for no timer. `enabled: false` subscribes nothing. The hook doesn't read on mount; keep the first read where the screen already makes it. It uses the provider's client, so the provider's `fetcher` signs the socket in. See [`fsd.subscribe`](/docs/api/client#fsdsubscribetopics-options) for which topics a caller hears. diff --git a/apps/docs/docs/server/setup.md b/apps/docs/docs/server/setup.md index 29494f137a..d4b519ce99 100644 --- a/apps/docs/docs/server/setup.md +++ b/apps/docs/docs/server/setup.md @@ -225,7 +225,7 @@ The same holds after a restart, whichever instances are registered afterwards an |--------|------|---------| | GET | `/api/flows` | List registered flows | | GET | `/api/flows/capabilities` | What the server supports: `{ userStream, push }`, `push` `{ transport: "websocket" }` under `serve()`, else `null` | -| POST | `/api/flows/users/:userId/stream` | Checks each topic the caller asks to hear and answers a short ticket for the ones it may (push hosts only) | +| POST | `/api/flows/users/:userId/stream` | Checks which requested topics the caller may hear and returns a short-lived token for opening the WebSocket (push hosts only) | | GET | `/api/flows/users/:userId/stream` | The change-notice WebSocket, as an upgrade (`serve()` only); a plain GET answers 426 | | POST | `/api/flows/:flowId/actions/:action` | Execute action (new session) | | POST | `/api/flows/:flowId/:sessionId/actions/:action` | Execute action (existing session) | diff --git a/apps/docs/guides/realtime.md b/apps/docs/guides/realtime.md index 58ac434313..10972839f4 100644 --- a/apps/docs/guides/realtime.md +++ b/apps/docs/guides/realtime.md @@ -6,7 +6,7 @@ sidebar_label: Realtime screens Some screens show data other people or agents change: a task board a team works, a list of runs, a project's files. Without help, the screen goes stale until it reads again. This guide shows how to have the screen read again when the data changes, with code that works the same on every host. -The idea is small. The server tells your screen *when* something under a topic changed. Your screen then makes the read it already makes, which says *what*. Nothing about the data travels with the notice, and every read is checked on the server as usual. +The idea is small. The server tells your screen *when* something under a topic changed. Your screen then makes the read it already makes, which says *what*. Nothing about the data travels with the notice, and every read is checked on the server like any other. ## The hook @@ -24,7 +24,7 @@ type Task = { id: string; title: string }; function TaskList({ sessionId }: { sessionId: string }) { const [tasks, setTasks] = useState([]); const refresh = useCallback( - () => fsd.flow("support").read("listTasks", {}, { sessionId }).then(setTasks), + () => fsd.flow("support").read("listTasks_tasks", {}, { sessionId }).then(setTasks), [sessionId], ); @@ -35,9 +35,7 @@ function TaskList({ sessionId }: { sessionId: string }) { } ``` -On the Node host, `refresh` runs within about a second of someone else's change. A burst of changes runs it once more after the read in flight finishes, not once per change. The hook doesn't read on mount, so keep the first read where your screen already makes it. - -There are three topics: +On the Node host, `refresh` runs as soon as the change is saved: the server sends the notice once the change can be read, and no timer is involved, so the delay is the network and your read. A burst of changes runs it once more after the read in flight finishes, not once per change. The hook doesn't read on mount, so keep the first read where your screen already makes it. | Topic | What changes it covers | |-------|------------------------| @@ -49,7 +47,7 @@ Each takes `{ resource }` to narrow it to one resource, such as `topic.session(i ## Acting on what changed -`refresh` gets the notice that woke it, `{ topic, kind, origin? }`, or `null` for a connect, a reconnect or a timer tick. A screen that only cares about some changes can skip the others: +`refresh` gets the notice that woke it, `{ topic, kind, origin? }`, or `null` when the screen should read everything again: after a connect or a reconnect, on a timer tick, and when push starts or stops reaching every server process. A screen that only cares about some changes can skip the others: ```ts useSubscription([topic.session(sessionId)], (notice) => { @@ -58,7 +56,7 @@ useSubscription([topic.session(sessionId)], (notice) => { }); ``` -`kind` is `"items"`, `"request"`, `"run"` or `"resync"`. Read everything on `null`: it means the screen may have missed something. +`kind` is `"items"`, `"request"`, `"run"` or `"resync"`. Read everything on `null` and on `"resync"`: the screen may have missed something. ## Outside React @@ -85,11 +83,11 @@ Every `subscribe` call on one client shares one connection. You don't write different code for either. The client asks the server what it supports and picks. -`pollIntervalMs` is also the fallback on a push host. The read runs on that timer while the socket is down, and while the server process the socket reached can't hear changes made in other processes. Leave it out and there is no timer at all: the read runs on a notice, a connect and a reconnect only. +`pollIntervalMs` is also the fallback on a push host. The read runs on that timer while the socket is down, and while the server process the socket reached can't hear changes made in other processes (see below). Leave it out and there is no timer at all: the read runs on a notice, a connect and a reconnect only. ## One process, several processes -Whether a notice reaches every server process depends on the change bus in your stores profile. The default bus lives in memory and reaches only its own process. On it, a subscription with `pollIntervalMs` keeps reading on its timer between notices, even when you run a single process. A bus that carries changes between processes turns that timer off while the socket is up. +Each server keeps a *change bus*, the `bus` slot of its stores profile (the stores you hand `createFlowState`; see [Store adapters](/docs/persistence/overview#store-adapters)). A bus that *crosses processes* hands a change made in one server process to every other one. The default bus lives in memory and reaches only its own process, so it doesn't cross processes. On it, a subscription with `pollIntervalMs` keeps reading on its timer between notices, even when you run a single process. On a bus that crosses processes, the timer stays off while the socket is up. When several processes serve one address, give them all the same signing key, so a connection that lands on any of them is accepted: diff --git a/goals/realtime/websocket-delivery/goal.md b/goals/realtime/websocket-delivery/goal.md index 8edcb3c2b9..78188c334f 100644 --- a/goals/realtime/websocket-delivery/goal.md +++ b/goals/realtime/websocket-delivery/goal.md @@ -28,3 +28,4 @@ | 2026-11-03 | fix/FIX-2428-subscribe (pre-commit) | n/a | FAIL (expected) | `no-socket`: `a:no-read-between` (5 reads in 10 s), `a:within-1s` (638, 1214, 1288 ms); also `a:crossing`, `b:control` and CAN'T TELL on c's crossing frames, since nothing pushes. The first run of this control found a client defect (Node's WebSocket reports a failed handshake as an error with no close), fixed before this row | | 2026-11-03 | fix/FIX-2428-subscribe (pre-commit) | n/a | FAIL (expected) | `skip-check`: `b:c-never-hears` only (C's handler ran 7 times) | | 2026-11-03 | fix/FIX-2428-subscribe (pre-commit) | n/a | FAIL (expected) | `ignore-crossing`: `c:second-process` only (tab 2 never showed the reply) | +| 2026-11-03 | fix/FIX-2428-subscribe (fix-up after 844a4f9) | n/a | PASS | After the mint answer, session recheck, shared key and backoff fixes. a: 0 reads in 10 s idle; replies shown 4, 3, 2 ms after saved · b: C never heard; B nothing after revocation · c: no push 1497 ms; second process 1431 ms | diff --git a/packages/client/README.md b/packages/client/README.md index 8724e730a6..7af7489a20 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -216,14 +216,16 @@ with no web server, and a credentialed one streams with its credentials. `fsd.subscribe(topics, { onChange, pollIntervalMs? })` calls `onChange` when something under a topic may have changed, so the screen reads again. It says when, never what: `onChange` gets the notice (`{ topic, kind, origin? }`), or -`null` for a connect, a reconnect or a timer tick. +`null` when the screen should read everything again: after a connect or a +reconnect, on a timer tick, and when push starts or stops reaching every server +process. ```ts import { topic } from "@flow-state-dev/client"; const sub = fsd.subscribe([topic.session(sessionId), topic.org()], { onChange: () => void reload(), - pollIntervalMs: 3000, // while there is no push, the socket is down, or its bus can't cross processes + pollIntervalMs: 3000, // read on this timer wherever push can miss a change }); sub.close(); ``` diff --git a/packages/client/src/subscribe/push-hub.ts b/packages/client/src/subscribe/push-hub.ts index a80dd7b15a..f754283e63 100644 --- a/packages/client/src/subscribe/push-hub.ts +++ b/packages/client/src/subscribe/push-hub.ts @@ -82,6 +82,21 @@ const FAILED_CONNECT_CODES = new Set([ let warnedTransport = false; let warnedHandler = false; +/** The websocket arm of a mint answer. */ +type WebSocketAnswer = Extract; + +/** A mint answer this client can use, a transport it doesn't build, or nothing usable. */ +function readMintAnswer(value: unknown): WebSocketAnswer | { transport: "other"; name: string } | undefined { + if (typeof value !== "object" || value === null) return undefined; + const answer = value as Record; + if (answer.transport === "websocket") { + const usable = + typeof answer.ticket === "string" && typeof answer.path === "string" && Array.isArray(answer.topics); + return usable ? (answer as WebSocketAnswer) : undefined; + } + return typeof answer.transport === "string" ? { transport: "other", name: answer.transport } : undefined; +} + /** Whether `subscribed` covers a notice under `heard`. */ function covers(subscribed: WireTopic, heard: WireTopic): boolean { if (subscribed.scope !== heard.scope) return false; @@ -155,12 +170,18 @@ export function createPushHub(deps: { const allTopics = (): WireTopic[] => [...counts.values()].map((entry) => entry.topic); - const mint = (topics: WireTopic[]): Promise => - deps.transport.json(`/api/flows/users/${encodeURIComponent(deps.userId)}/stream`, { + /** + * Ask the server for `topics`. Resolves to the answer, or `undefined` when + * what came back is not a mint answer this client can use (no body, a page + * from a proxy, an answer missing its ticket). Rejects only when the call + * itself failed (a network error, a non-2xx status), which is retried. + */ + const mint = async (topics: WireTopic[]): Promise => + readMintAnswer(await deps.transport.json(`/api/flows/users/${encodeURIComponent(deps.userId)}/stream`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ topics }) - }); + })); /** Record which of `asked` the answer granted; returns the newly granted keys. */ const record = (asked: readonly string[], answer: { topics: WireTopic[] }): Set => { @@ -190,7 +211,7 @@ export function createPushHub(deps: { if (asking.length === 0) return; for (const key of asking) minting.add(key); const at = generation; - let answer: PushMintAnswer | undefined; + let answer: Awaited>; try { answer = await mint(asking.map((key) => counts.get(key)!.topic)); } catch { @@ -247,7 +268,7 @@ export function createPushHub(deps: { const at = ++generation; const asked = allTopics(); updateTimers(); - let answer: PushMintAnswer; + let answer: Awaited>; try { answer = await mint(asked); } catch { @@ -257,16 +278,20 @@ export function createPushHub(deps: { return; } if (at !== generation) return; - if (answer.transport !== "websocket") { + // An answer this client can't use (another transport, or not a mint + // answer at all) means no push here: read on the timer, never reject. + if (answer === undefined || answer.transport !== "websocket") { if (!warnedTransport) { warnedTransport = true; - console.warn(`[flow-state] client.subscribe: this client has no "${answer.transport}" push; reading on its timer.`); + const what = answer === undefined ? "an answer it can't read" : `"${answer.name}" push`; + console.warn(`[flow-state] client.subscribe: the server sent ${what}; reading on the timer.`); } noPush(); return; } + const ready = answer; const WebSocketImpl = (globalThis as { WebSocket?: typeof WebSocket }).WebSocket; - const url = socketUrl(answer.path); + const url = socketUrl(ready.path); if (WebSocketImpl === undefined || url === undefined) { noPush(); return; @@ -309,14 +334,13 @@ export function createPushHub(deps: { opened = true; state = "open"; lapsed = false; - failures = 0; crosses = false; firstCrossingFrame = true; granted.clear(); - ws.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); + ws.send(JSON.stringify({ type: "subscribe", ticket: ready.ticket })); const added = record( asked.map(wireTopicKey), - answer + ready ); updateTimers(); // Each connect reads once (ER-6): it may have missed changes. @@ -333,6 +357,9 @@ export function createPushHub(deps: { return; } if (frame.type === "crossing") { + // The server sends this only once it accepted the ticket: the connect + // has succeeded, so the backoff starts over. + failures = 0; const first = firstCrossingFrame; firstCrossingFrame = false; const changed = frame.crosses !== crosses; diff --git a/packages/client/test/subscribe.test.ts b/packages/client/test/subscribe.test.ts index 424a7f811d..43cfed7b19 100644 --- a/packages/client/test/subscribe.test.ts +++ b/packages/client/test/subscribe.test.ts @@ -56,7 +56,16 @@ class FakeSocket { type MintCall = { topics: WireTopic[]; authorization: string | null }; /** A server double: capabilities, and a mint that grants what `grant` allows. */ -function server(options: { push?: unknown; grant?: (topic: WireTopic) => boolean; transport?: string; mintStatus?: () => number } = {}) { +function server( + options: { + push?: unknown; + grant?: (topic: WireTopic) => boolean; + transport?: string; + mintStatus?: () => number; + /** A raw 200 body for the mint, in place of a real answer. */ + mintBody?: string; + } = {} +) { const mints: MintCall[] = []; let ticket = 0; const fetcher: ClientFetch = async (input, init) => { @@ -71,6 +80,7 @@ function server(options: { push?: unknown; grant?: (topic: WireTopic) => boolean mints.push({ topics, authorization: headers.get("authorization") }); const status = options.mintStatus?.() ?? 200; if (status !== 200) return Response.json({ error: "no" }, { status }); + if (options.mintBody !== undefined) return new Response(options.mintBody, { status: 200 }); const granted = topics.filter(options.grant ?? (() => true)); if (options.transport === "ably") { return Response.json({ transport: "ably", tokenRequest: {}, channels: [], topics: granted }); @@ -303,6 +313,27 @@ describe("client.subscribe on a host with push", () => { expect(mints.length).toBeGreaterThanOrEqual(2); }); + it("backs off 1, 2, 4, 8, 16 s across sockets that open and then have their ticket refused", async () => { + vi.spyOn(console, "warn").mockImplementation(() => {}); + const { fetcher } = server({ push: { transport: "websocket" } }); + client(fetcher).subscribe([S1], { onChange: () => {}, pollIntervalMs: 60_000 }); + await settle(); + const gaps: number[] = []; + for (let i = 0; i < 6; i += 1) { + const socket = FakeSocket.all.at(-1)!; + socket.open(); + socket.drop(4401); + const count = FakeSocket.all.length; + let waited = 0; + while (FakeSocket.all.length === count && waited < 60_000) { + await vi.advanceTimersByTimeAsync(500); + waited += 500; + } + gaps.push(waited); + } + expect(gaps.slice(0, 5)).toEqual([1000, 2000, 4000, 8000, 16000]); + }); + it("reconnects at once when the server ends the socket at its age limit", async () => { const { fetcher, mints } = server({ push: { transport: "websocket" } }); const { socket } = await connected(client(fetcher), [S1], 1000, true); @@ -376,6 +407,22 @@ describe("client.subscribe on a host with push", () => { warn.mockRestore(); }); + for (const [name, body] of [ + ["no body", ""], + ["a page that isn't JSON", "bad gateway"], + ["JSON that isn't a mint answer", JSON.stringify({ transport: "websocket" })], + ["JSON null", "null"] + ] as const) { + it(`reads on its timer, and never rejects, when the mint answers ${name}`, async () => { + const { fetcher } = server({ push: { transport: "websocket" }, mintBody: body }); + const onChange = vi.fn(); + client(fetcher).subscribe([S1], { onChange, pollIntervalMs: 1000 }); + await vi.advanceTimersByTimeAsync(2000); + expect(FakeSocket.all).toEqual([]); + expect(onChange.mock.calls).toEqual([[null], [null]]); + }); + } + it("keeps calling the other subscriptions when one onChange throws", async () => { const error = vi.spyOn(console, "error").mockImplementation(() => {}); const { fetcher } = server({ push: { transport: "websocket" } }); diff --git a/packages/engine/README.md b/packages/engine/README.md index 31edea2067..40165efb1a 100644 --- a/packages/engine/README.md +++ b/packages/engine/README.md @@ -676,7 +676,7 @@ publishes. A host that writes to the stores past those entries calls it too, and writes through the registry it returns. It is idempotent: every entry gets the same wrapped stores. -**Push delivery** carries these notices to a browser (FIX-2428). A host that +**Push delivery** carries these notices to a browser. A host that serves the socket calls `enablePushDelivery(router, { secret? })`: the router then reports `push: { transport: "websocket" }` in `GET /capabilities` and answers `POST /users/:userId/stream`, which runs each topic the caller asks for @@ -684,8 +684,10 @@ through the read check its scope uses and signs a 30-second ticket for the ones it grants. The host hands each socket that opens on `/users/:userId/stream` to `delivery.openSocket(userId, { send, close })` and moves text frames to the returned session's `receive`. The session accepts topics only from a ticket for -that user, sends `{ type: "crossing", crosses }` after the first ticket and on -each change of the bus's answer, and closes the socket after an hour. +that user, and closes the socket after an hour. After the first ticket, and each +time the bus's `crossesProcesses` changes, it sends `{ type: "crossing", crosses }`: +whether notices from other processes reach this socket. A client keeps reading on +its timer until it hears `crosses: true`. `serve()` in `@flow-state-dev/node` does all of this; `secret` defaults to a random key per router. diff --git a/packages/engine/src/push/push-delivery.ts b/packages/engine/src/push/push-delivery.ts index 284ed87261..17de25bdc2 100644 --- a/packages/engine/src/push/push-delivery.ts +++ b/packages/engine/src/push/push-delivery.ts @@ -16,7 +16,7 @@ import type { ResolvedPrincipal } from "../transports/types"; import type { ChangeBus } from "../bus/types"; import type { FlowApiRouter } from "../routes/createFlowApiRouter"; import { authorizeManagementRoute, type RouteAuthContext } from "../routes/route-auth"; -import { jsonResponse, loadTenantSession } from "../routes/route-utils"; +import { jsonResponse, loadCheckedSession } from "../routes/route-utils"; import { isWireTopic, openPushSocket, type PushSocket, type PushSocketIO } from "./socket-session"; import { PUSH_TICKET_TTL_MS, signPushTicket, type GrantedTopic } from "./ticket"; @@ -52,7 +52,10 @@ const PUSH_STATE = Symbol.for("@flow-state-dev/engine/pushState"); */ export type PushState = { bus: ChangeBus; + /** The key tickets are signed and checked with, read on each use. Unset until push is on. */ secret?: () => string; + /** This router's random key, made once, so every host that turns push on shares it. */ + generated?: string; }; /** Create a router's push state over its bus. */ @@ -79,12 +82,15 @@ export function enablePushDelivery(router: FlowApiRouter, options: EnablePushDel throw new Error("enablePushDelivery takes a router built by createFlowApiRouter"); } const given = options.secret; - const generated = given === undefined ? randomBytes(32).toString("base64url") : undefined; - const secret = (): string => (typeof given === "function" ? given() : given ?? generated!); - state.secret = secret; + if (given === undefined) state.generated ??= randomBytes(32).toString("base64url"); + const generated = state.generated; + state.secret = (): string => (typeof given === "function" ? given() : given ?? generated!); + // Every socket checks with the router's current key, the one the mint signs + // with, so two hosts in front of one router accept each other's tickets. + const current = (): string => state.secret!(); return { transport: "websocket", - openSocket: (userId, io) => openPushSocket({ bus: state.bus, secret, userId, io }) + openSocket: (userId, io) => openPushSocket({ bus: state.bus, secret: current, userId, io }) }; } @@ -134,9 +140,10 @@ export async function handleMintPush(request: Request, userId: string, ctx: Mint // the caller may not read is dropped exactly as one that doesn't exist. const checked = await authorizeManagementRoute(request, { kind: "session_stream", sessionId: wire.id }, ctx); if (checked.denied !== undefined || checked.session === null) continue; - if (checked.session === undefined && (await loadTenantSession(ctx.stores.session, wire.id, ctx.tenantId)) === undefined) { - continue; - } + // The session as it is now must be the one the check read, as on every + // session route: one deleted and created again for someone else while + // the caller was being signed in is dropped like a missing one. + if ((await loadCheckedSession(ctx.stores.session, wire.id, ctx.tenantId, checked.session)) === undefined) continue; granted.push({ wire, bus: { scope: "session", id: wire.id, tenantId, ...resource } }); continue; } diff --git a/packages/engine/test/push-delivery.test.ts b/packages/engine/test/push-delivery.test.ts index 0ad914adde..b31ff4dde0 100644 --- a/packages/engine/test/push-delivery.test.ts +++ b/packages/engine/test/push-delivery.test.ts @@ -226,6 +226,38 @@ describe("POST /users/:userId/stream (the mint)", () => { expect(notArray.status).toBe(400); }); + it("drops a session deleted and created again for another user while the caller is being signed in", async () => { + const registry = createFlowRegistry(); + registry.register(demoFlow()); + const stores = createInMemoryStores(); + let swap: (() => Promise) | undefined; + const router = createFlowApiRouter({ + registry, + stores, + resolvePrincipal: async (context) => { + const user = context.request?.headers.get("x-user"); + // The session check signs the caller in after reading the session: + // that is the window in which the id changes hands. + if (swap !== undefined && context.envelope.sessionId === "s1") { + const run = swap; + swap = undefined; + await run(); + } + return user == null ? null : { userId: user, orgId: "acme" }; + } + }); + enablePushDelivery(router, { secret: SECRET }); + await seedSession(stores, "s1", { userId: "alice" }); + swap = async () => { + await stores.session.delete("s1"); + await seedSession(stores, "s1", { userId: "bob" }); + }; + const { status, answer } = await mint(router, [topic.session("s1")]); + expect(swap).toBeUndefined(); + expect(status).toBe(200); + expect(answer.topics).toEqual([]); + }); + it("in a mixed app, gives an anonymous caller no user or org topic", async () => { const registry = createFlowRegistry(); registry.register(demoFlow("open")); @@ -447,6 +479,22 @@ describe("enablePushDelivery", () => { expect(ws.closed()?.code).toBe(4401); }); + it("keeps one key when two hosts turn push on for the same router", async () => { + const registry = createFlowRegistry(); + registry.register(demoFlow()); + const router = createFlowApiRouter({ registry, stores: createInMemoryStores() }); + const first = enablePushDelivery(router); + const second = enablePushDelivery(router); + const { answer } = await mint(router, [topic.user()], {}, "alice"); + if (answer.transport !== "websocket") throw new Error("expected websocket"); + for (const delivery of [first, second]) { + const ws = socket(delivery); + ws.send({ type: "subscribe", ticket: answer.ticket }); + expect(ws.closed()).toBeUndefined(); + expect(ws.frames).toEqual([{ type: "crossing", crosses: false }]); + } + }); + it("uses one random secret per router when none is given", async () => { const registry = createFlowRegistry(); registry.register(demoFlow()); diff --git a/packages/node/README.md b/packages/node/README.md index 82e31aaddf..7c43bbb517 100644 --- a/packages/node/README.md +++ b/packages/node/README.md @@ -54,7 +54,7 @@ then disposes the router and the `FlowState`. `serve()` serves push: the WebSocket a client's `fsd.subscribe` (and React's `useSubscription`) hears change notices on, at `/users/:userId/stream`. `GET /capabilities` reports `push: { transport: "websocket" }`, so a client on -this host hears a change within about a second instead of reading on its timer. +this host hears a change as soon as it is saved instead of on its timer. `push: false` turns it off. `createServerApp` alone serves no socket and reports `push: null`. @@ -67,8 +67,10 @@ await serve(flowState, { pushSecret: process.env.FSD_PUSH_SECRET }); `serve()` reads `FSD_PUSH_SECRET` itself when `pushSecret` is not given, and otherwise uses a random key for the process. A notice reaches every process only -when the stores profile's change bus carries changes between processes; on the -default in-memory bus, clients keep reading on their timer between notices. +when the change bus crosses processes: the `bus` slot of the stores profile you +hand `createFlowState` must hold a bus that hands a change made in one process to +the others (see the engine README's *Change bus* section). On the default +in-memory bus, clients keep reading on their timer between notices. ## Serving a built `FlowApiRouter` directly diff --git a/packages/node/test/serve-push.test.ts b/packages/node/test/serve-push.test.ts index a3917e67af..bfe7aeb920 100644 --- a/packages/node/test/serve-push.test.ts +++ b/packages/node/test/serve-push.test.ts @@ -162,6 +162,28 @@ describe("serve() push delivery", () => { expect(await onC.closed).toBe(4401); }); + it("accepts tickets on either of two hosts that serve one router, with no pushSecret", async () => { + const flowState = createFlowState({ flows: { chat }, stores: { default: { primary: inMemoryStores() } } }); + const router = await flowState.getRouter(); + const options = { port: 0, host: "127.0.0.1", handleSignals: false, shutdownGraceMs: 200, disposeOnClose: false }; + const first = await serve(router, options); + const second = await serve(router, options); + handles.push(first, second); + const bases = [first, second].map((handle) => `http://127.0.0.1:${handle.port}`); + for (const mintOn of bases) { + const answer = await mint(mintOn, [topic.user()]); + if (answer.transport !== "websocket") throw new Error("expected websocket"); + for (const openOn of bases) { + const ws = open(openOn, `/api/flows${answer.path}`); + await ws.opened; + ws.socket.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); + await until(() => ws.frames.length > 0 || ws.closeCode() !== undefined); + expect(ws.closeCode()).toBeUndefined(); + expect(ws.frames[0]).toEqual({ type: "crossing", crosses: false }); + } + } + }); + it("takes the shared secret from FSD_PUSH_SECRET when pushSecret is not given", async () => { vi.stubEnv("FSD_PUSH_SECRET", "from-env"); const a = await start(); diff --git a/packages/react/README.md b/packages/react/README.md index a0c97d7702..e47bed74af 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -254,8 +254,10 @@ Low-level hook for direct action execution without session management. Runs `read` again when something under `topics` changes, through the provider's client and `fsd.subscribe`. One read runs at a time and at most one more waits, so a burst of changes is one more read. `read` gets the notice that woke it, or -`null` for a connect, a reconnect, a timer tick, or a wait that stands for -several different notices. It doesn't read on mount. +`null` when the screen should read everything again: after a connect or a +reconnect, on a timer tick, and when push starts or stops reaching every server +process. It also gets `null` when several changes arrived during one read (one +follow-up read covers them all). It doesn't read on mount. ```tsx import { topic } from "@flow-state-dev/client"; From 7ac2f3f33a5246780260461447709c5d351d0db7 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 02:47:34 +0000 Subject: [PATCH 3/8] goal(FIX-2428): record the three controls on 7d98fce Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn --- goals/realtime/websocket-delivery/goal.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/goals/realtime/websocket-delivery/goal.md b/goals/realtime/websocket-delivery/goal.md index 78188c334f..ab6bfb00da 100644 --- a/goals/realtime/websocket-delivery/goal.md +++ b/goals/realtime/websocket-delivery/goal.md @@ -29,3 +29,6 @@ | 2026-11-03 | fix/FIX-2428-subscribe (pre-commit) | n/a | FAIL (expected) | `skip-check`: `b:c-never-hears` only (C's handler ran 7 times) | | 2026-11-03 | fix/FIX-2428-subscribe (pre-commit) | n/a | FAIL (expected) | `ignore-crossing`: `c:second-process` only (tab 2 never showed the reply) | | 2026-11-03 | fix/FIX-2428-subscribe (fix-up after 844a4f9) | n/a | PASS | After the mint answer, session recheck, shared key and backoff fixes. a: 0 reads in 10 s idle; replies shown 4, 3, 2 ms after saved · b: C never heard; B nothing after revocation · c: no push 1497 ms; second process 1431 ms | +| 2026-11-03 | 7d98fce | n/a | FAIL (expected) | `no-socket`: `a:no-read-between` (5 reads in 10 s), `a:within-1s` (673, 1284, 1283 ms); also `a:crossing`, `b:control` and CAN'T TELL on c's crossing frames, as before: nothing pushes | +| 2026-11-03 | 7d98fce | n/a | FAIL (expected) | `skip-check`: `b:c-never-hears` only (C's handler ran 7 times) | +| 2026-11-03 | 7d98fce | n/a | FAIL (expected) | `ignore-crossing`: `c:second-process` only (tab 2 never showed the reply) | From 14122c50d7d34b4b79e164614413d14211978fbe Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 11:19:10 +0000 Subject: [PATCH 4/8] fix(FIX-2428): read after the ticket is heard; scope mints; push per host - engine/contracts: the socket acknowledges each accepted ticket with a `subscribed` control frame once its topics are on the bus. The client reads on connect, and covers a topic, only on that acknowledgement, so a change in the gap is never missed (Codex r4453840539). - client: in-flight mint markers are scoped to the connection and cleared on stop and drop, so a stale mint can't skip a re-subscribed topic (Codex r4453840560). - node: createServerApp reports push and answers the mint only for the host that serves the socket (`servesPush`, set by serve()), so a push:false host over a shared router reports push: null (Codex r4453840568). - client: inbound frames are checked before fan-out; the session stream and subscribe share the 1 s to 30 s delay math. react: useSubscription keys topics with wireTopicKey. A stale user-stream comment is removed (Cursor). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn --- goals/realtime/websocket-delivery/goal.md | 2 + packages/client/src/internal/backoff.ts | 15 +++ packages/client/src/stream-client/streams.ts | 7 +- packages/client/src/subscribe/push-hub.ts | 121 +++++++++++++----- packages/client/src/types/index.ts | 3 - packages/client/test/subscribe.test.ts | 95 +++++++++++++- packages/contracts/src/types/push-delivery.ts | 14 +- packages/engine/README.md | 6 +- packages/engine/src/push/socket-session.ts | 5 + packages/engine/test/push-delivery.test.ts | 40 +++++- packages/node/README.md | 2 +- packages/node/src/app.ts | 20 +++ packages/node/src/serve.ts | 1 + packages/node/test/serve-push.test.ts | 42 +++++- packages/react/src/hooks/useSubscription.ts | 7 +- 15 files changed, 321 insertions(+), 59 deletions(-) create mode 100644 packages/client/src/internal/backoff.ts diff --git a/goals/realtime/websocket-delivery/goal.md b/goals/realtime/websocket-delivery/goal.md index ab6bfb00da..2c075ce68c 100644 --- a/goals/realtime/websocket-delivery/goal.md +++ b/goals/realtime/websocket-delivery/goal.md @@ -32,3 +32,5 @@ | 2026-11-03 | 7d98fce | n/a | FAIL (expected) | `no-socket`: `a:no-read-between` (5 reads in 10 s), `a:within-1s` (673, 1284, 1283 ms); also `a:crossing`, `b:control` and CAN'T TELL on c's crossing frames, as before: nothing pushes | | 2026-11-03 | 7d98fce | n/a | FAIL (expected) | `skip-check`: `b:c-never-hears` only (C's handler ran 7 times) | | 2026-11-03 | 7d98fce | n/a | FAIL (expected) | `ignore-crossing`: `c:second-process` only (tab 2 never showed the reply) | +| 2026-11-03 | fix/FIX-2428-subscribe (after 7ac2f3f, pre-commit) | n/a | PASS | After the ticket acknowledgement, stale-mint and per-host push fixes. a: 0 reads in 10 s idle; replies shown 4, 2, 4 ms · b: C never heard; B nothing after revocation · c: no push 1496 ms; second process 1446 ms | +| 2026-11-03 | fix/FIX-2428-subscribe (after 7ac2f3f, pre-commit) | n/a | FAIL (expected) | `no-socket`: `a:no-read-between` (5 reads), `a:within-1s` (674, 1283, 1287 ms); plus `a:crossing`, `b:control` and c's frames CAN'T TELL, as before · `skip-check`: `b:c-never-hears` only (7 calls) · `ignore-crossing`: `c:second-process` only | diff --git a/packages/client/src/internal/backoff.ts b/packages/client/src/internal/backoff.ts new file mode 100644 index 0000000000..7dba64ed7d --- /dev/null +++ b/packages/client/src/internal/backoff.ts @@ -0,0 +1,15 @@ +/** + * The client's reconnect delay: 1 s, doubling, at most 30 s. Shared by the + * session stream and `subscribe`'s socket, which each decide for themselves + * when a try counts as failed and when to start over. + */ + +/** The first delay. */ +export const BACKOFF_INITIAL_MS = 1_000; +/** The longest delay. */ +export const BACKOFF_MAX_MS = 30_000; + +/** The delay before try `attempt` (0 for the first retry). */ +export function backoffDelay(attempt: number, initialMs = BACKOFF_INITIAL_MS, maxMs = BACKOFF_MAX_MS): number { + return Math.min(maxMs, initialMs * 2 ** Math.max(0, attempt)); +} diff --git a/packages/client/src/stream-client/streams.ts b/packages/client/src/stream-client/streams.ts index c89f71fec2..5a0c1dce50 100644 --- a/packages/client/src/stream-client/streams.ts +++ b/packages/client/src/stream-client/streams.ts @@ -16,6 +16,7 @@ import type { SessionStreamHandle } from "../types"; import { ClientHttpError } from "../types"; +import { BACKOFF_INITIAL_MS, BACKOFF_MAX_MS, backoffDelay } from "../internal/backoff"; /** Where an opener connects, and through what: the opening client's transport. */ type StreamTarget = { @@ -304,8 +305,8 @@ export function openSessionStream( options: SessionStreamOptions ): SessionStreamHandle { const { fetcher } = target; - const initialDelayMs = options.retry?.initialDelayMs ?? 1_000; - const maxDelayMs = options.retry?.maxDelayMs ?? 30_000; + const initialDelayMs = options.retry?.initialDelayMs ?? BACKOFF_INITIAL_MS; + const maxDelayMs = options.retry?.maxDelayMs ?? BACKOFF_MAX_MS; const itemTypes = options.itemTypes === undefined || options.itemTypes.length === 0 ? undefined @@ -318,7 +319,7 @@ export function openSessionStream( const reconnectLater = (): void => { if (stopped) return; - const delay = Math.min(maxDelayMs, initialDelayMs * 2 ** attempt); + const delay = backoffDelay(attempt, initialDelayMs, maxDelayMs); attempt += 1; timer = setTimeout(() => { timer = undefined; diff --git a/packages/client/src/subscribe/push-hub.ts b/packages/client/src/subscribe/push-hub.ts index f754283e63..e4fca9d9ac 100644 --- a/packages/client/src/subscribe/push-hub.ts +++ b/packages/client/src/subscribe/push-hub.ts @@ -32,6 +32,7 @@ import { type WireNotice, type WireTopic } from "@flow-state-dev/contracts"; +import { BACKOFF_INITIAL_MS, backoffDelay } from "../internal/backoff"; import type { Transport } from "../internal/http"; import type { FlowCapabilities } from "../types"; @@ -68,9 +69,6 @@ type Handle = { /** How long a socket may take to open before the connect counts as failed. */ const HANDSHAKE_TIMEOUT_MS = 10_000; -/** Backoff between failed connects: 1 s, doubling, at most 30 s. */ -const RETRY_BASE_MS = 1_000; -const RETRY_MAX_MS = 30_000; /** Close codes that mean "this connect failed", not "the connection dropped". */ const FAILED_CONNECT_CODES = new Set([ @@ -97,6 +95,21 @@ function readMintAnswer(value: unknown): WebSocketAnswer | { transport: "other"; return typeof answer.transport === "string" ? { transport: "other", name: answer.transport } : undefined; } +/** A frame the server sends, checked before anything reads it; anything else is dropped. */ +function readServerFrame(value: unknown): PushServerFrame | undefined { + if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined; + const frame = value as Record; + if (frame.type === "subscribed") return { type: "subscribed" }; + if (frame.type === "crossing") return typeof frame.crosses === "boolean" ? { type: "crossing", crosses: frame.crosses } : undefined; + if (frame.type !== "notice" || typeof frame.kind !== "string") return undefined; + const topic = frame.topic as Record | null | undefined; + if (typeof topic !== "object" || topic === null) return undefined; + if (topic.resource !== undefined && typeof topic.resource !== "string") return undefined; + const scoped = + topic.scope === "session" ? typeof topic.id === "string" : topic.scope === "user" || topic.scope === "org"; + return scoped ? (frame as PushServerFrame) : undefined; +} + /** Whether `subscribed` covers a notice under `heard`. */ function covers(subscribed: WireTopic, heard: WireTopic): boolean { if (subscribed.scope !== heard.scope) return false; @@ -113,12 +126,18 @@ export function createPushHub(deps: { const handles = new Set(); /** Every subscribed topic, counted by handle. */ const counts = new Map(); - /** Topics the current socket hears. */ + /** Topics the current socket hears: the server acknowledged their ticket. */ const granted = new Set(); /** Topics the mint left out of its answer, until asked again. */ const refused = new Set(); - /** Topics a mint is asking for now. */ - const minting = new Set(); + /** Topics a mint is asking for now, each with the connection it asks for. */ + const minting = new Map(); + /** + * The topics of each ticket sent and not yet acknowledged, in the order + * sent. The server acknowledges tickets in that order, once it hears their + * topics; until then a read could miss a change under them. + */ + let unacknowledged: Array> = []; let mode: "unknown" | "checking" | "none" | "push" = "unknown"; let socket: WebSocket | undefined; @@ -183,21 +202,48 @@ export function createPushHub(deps: { body: JSON.stringify({ topics }) })); - /** Record which of `asked` the answer granted; returns the newly granted keys. */ + /** + * Record which of `asked` the answer left out, and return the ones it + * granted. Those are heard only once the server acknowledges the ticket. + */ const record = (asked: readonly string[], answer: { topics: WireTopic[] }): Set => { const answered = new Set(answer.topics.map(wireTopicKey)); - const added = new Set(); + const grantedNow = new Set(); for (const key of asked) { if (!counts.has(key)) continue; if (answered.has(key)) { refused.delete(key); - if (!granted.has(key)) added.add(key); - granted.add(key); + grantedNow.add(key); } else { refused.add(key); } } - return added; + return grantedNow; + }; + + /** Send a ticket for `keys`, to be heard once the server acknowledges it. */ + const sendTicket = (ws: WebSocket, ticket: string, keys: Set): void => { + // Queued before sending: a server may acknowledge before `send` returns. + unacknowledged.push(keys); + ws.send(JSON.stringify({ type: "subscribe", ticket })); + }; + + /** The server heard the oldest ticket's topics: they are covered, and read once. */ + const acknowledged = (): void => { + const keys = unacknowledged.shift(); + if (keys === undefined) return; + // A ticket accepted: the connect worked, so the backoff starts over. + failures = 0; + const added = new Set(); + for (const key of keys) { + if (!counts.has(key) || granted.has(key)) continue; + granted.add(key); + added.add(key); + } + updateTimers(); + // Each connect, and each topic added, reads once (ER-6): it may have + // missed changes made before the server heard it. + touched(added); }; const touched = (added: Set): void => { @@ -207,33 +253,36 @@ export function createPushHub(deps: { /** Ask for topics the open socket doesn't hear yet. */ const mintMore = async (keys: readonly string[]): Promise => { if (state !== "open") return; - const asking = keys.filter((key) => counts.has(key) && !granted.has(key) && !minting.has(key)); + const asking = keys.filter( + (key) => counts.has(key) && !granted.has(key) && !minting.has(key) && !unacknowledged.some((set) => set.has(key)) + ); if (asking.length === 0) return; - for (const key of asking) minting.add(key); const at = generation; + for (const key of asking) minting.set(key, at); let answer: Awaited>; try { answer = await mint(asking.map((key) => counts.get(key)!.topic)); } catch { answer = undefined; } - for (const key of asking) minting.delete(key); + // Only this mint's own markers: a newer connection's mint of the same + // topic stays in flight. + for (const key of asking) if (minting.get(key) === at) minting.delete(key); if (at !== generation || state !== "open" || socket === undefined) return; if (answer === undefined || answer.transport !== "websocket") { for (const key of asking) if (counts.has(key)) refused.add(key); updateTimers(); return; } - if (answer.topics.length > 0) socket.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); - const added = record(asking, answer); + const grantedNow = record(asking, answer); + if (answer.topics.length > 0) sendTicket(socket, answer.ticket, grantedNow); updateTimers(); - touched(added); }; const scheduleRetry = (): void => { failures += 1; lapsed = true; - const delay = Math.min(RETRY_MAX_MS, RETRY_BASE_MS * 2 ** Math.max(0, failures - 1)); + const delay = backoffDelay(failures - 1); clearTimeout(retryTimer); retryTimer = setTimeout(() => void connect(), delay); updateTimers(); @@ -311,6 +360,8 @@ export function createPushHub(deps: { state = "idle"; crosses = false; granted.clear(); + minting.clear(); + unacknowledged = []; generation += 1; try { ws.close(); @@ -337,36 +388,38 @@ export function createPushHub(deps: { crosses = false; firstCrossingFrame = true; granted.clear(); - ws.send(JSON.stringify({ type: "subscribe", ticket: ready.ticket })); - const added = record( - asked.map(wireTopicKey), - ready - ); + unacknowledged = []; + // The connect reads once the server acknowledges this ticket, not now: + // a read now could finish before the server hears the topics. + sendTicket(ws, ready.ticket, record(asked.map(wireTopicKey), ready)); updateTimers(); - // Each connect reads once (ER-6): it may have missed changes. - touched(added); // Topics subscribed while this connect was in flight. - void mintMore([...counts.keys()].filter((key) => !granted.has(key) && !refused.has(key))); + const asked2 = new Set(asked.map(wireTopicKey)); + void mintMore([...counts.keys()].filter((key) => !asked2.has(key) && !refused.has(key))); }); ws.addEventListener("message", (event) => { if (socket !== ws) return; - let frame: PushServerFrame; + let parsed: unknown; try { - frame = JSON.parse(String((event as MessageEvent).data)) as PushServerFrame; + parsed = JSON.parse(String((event as MessageEvent).data)); } catch { return; } + const frame = readServerFrame(parsed); + if (frame === undefined) return; + if (frame.type === "subscribed") { + acknowledged(); + return; + } if (frame.type === "crossing") { - // The server sends this only once it accepted the ticket: the connect - // has succeeded, so the backoff starts over. - failures = 0; const first = firstCrossingFrame; firstCrossingFrame = false; const changed = frame.crosses !== crosses; crosses = frame.crosses; updateTimers(); // A change of the answer reads once, as a connect does. The first - // frame follows the connect's own read, so it adds none. + // frame follows the connect's own read (on its acknowledgement), so + // it adds none. if (changed && !first) touched(new Set(granted)); return; } @@ -396,7 +449,7 @@ export function createPushHub(deps: { mode = "unknown"; lapsed = true; clearTimeout(retryTimer); - retryTimer = setTimeout(() => void start(), RETRY_BASE_MS); + retryTimer = setTimeout(() => void start(), BACKOFF_INITIAL_MS); updateTimers(); return; } @@ -421,6 +474,8 @@ export function createPushHub(deps: { failures = 0; granted.clear(); refused.clear(); + minting.clear(); + unacknowledged = []; if (mode === "checking") mode = "unknown"; ws?.close(1000); }; diff --git a/packages/client/src/types/index.ts b/packages/client/src/types/index.ts index 81059f4192..0cce3b2c69 100644 --- a/packages/client/src/types/index.ts +++ b/packages/client/src/types/index.ts @@ -495,9 +495,6 @@ export interface RequestStreamHandle { readonly lastEventId?: string; } -/** - * Handle returned by optional user-stream SSE connections. - */ /** * Callback set for request-stream SSE events. */ diff --git a/packages/client/test/subscribe.test.ts b/packages/client/test/subscribe.test.ts index 43cfed7b19..9ed240234f 100644 --- a/packages/client/test/subscribe.test.ts +++ b/packages/client/test/subscribe.test.ts @@ -12,6 +12,12 @@ import { createClient, topic, type ClientFetch, type WireNotice, type WireTopic /** A WebSocket double the test drives: open, deliver a frame, drop. */ class FakeSocket { static all: FakeSocket[] = []; + /** + * Acknowledge each ticket at once, as a server that subscribes it before + * the next frame does. A test of the gap before the acknowledgement turns + * it off and sends `subscribed` itself. + */ + static autoAck = true; readonly sent: unknown[] = []; readyState = 0; closedWith: number | undefined; @@ -23,7 +29,9 @@ class FakeSocket { (this.listeners[type] ??= []).push(listener); } send(data: string): void { - this.sent.push(JSON.parse(data)); + const frame = JSON.parse(data) as { type: string }; + this.sent.push(frame); + if (frame.type === "subscribe" && FakeSocket.autoAck) this.frame({ type: "subscribed" }); } close(code = 1000): void { if (this.readyState === 3) return; @@ -64,6 +72,8 @@ function server( mintStatus?: () => number; /** A raw 200 body for the mint, in place of a real answer. */ mintBody?: string; + /** Hold a mint's answer until the promise this returns settles. */ + holdMint?: (topics: WireTopic[]) => Promise | undefined; } = {} ) { const mints: MintCall[] = []; @@ -78,6 +88,7 @@ function server( if (url.endsWith("/users/u1/stream") && init?.method === "POST") { const { topics } = JSON.parse(String(init.body)) as { topics: WireTopic[] }; mints.push({ topics, authorization: headers.get("authorization") }); + await options.holdMint?.(topics); const status = options.mintStatus?.() ?? 200; if (status !== 200) return Response.json({ error: "no" }, { status }); if (options.mintBody !== undefined) return new Response(options.mintBody, { status: 200 }); @@ -109,6 +120,7 @@ const notice = (topicValue: WireTopic, kind: WireNotice["kind"] = "items"): Wire beforeEach(() => { FakeSocket.all = []; + FakeSocket.autoAck = true; vi.useFakeTimers(); vi.stubGlobal("WebSocket", FakeSocket); }); @@ -314,6 +326,7 @@ describe("client.subscribe on a host with push", () => { }); it("backs off 1, 2, 4, 8, 16 s across sockets that open and then have their ticket refused", async () => { + FakeSocket.autoAck = false; // a refused ticket is never acknowledged vi.spyOn(console, "warn").mockImplementation(() => {}); const { fetcher } = server({ push: { transport: "websocket" } }); client(fetcher).subscribe([S1], { onChange: () => {}, pollIntervalMs: 60_000 }); @@ -334,6 +347,86 @@ describe("client.subscribe on a host with push", () => { expect(gaps.slice(0, 5)).toEqual([1000, 2000, 4000, 8000, 16000]); }); + it("reads on connect only once the server acknowledges the ticket, and keeps its timer until then", async () => { + FakeSocket.autoAck = false; + const { fetcher } = server({ push: { transport: "websocket" } }); + const onChange = vi.fn(); + client(fetcher).subscribe([S1], { onChange, pollIntervalMs: 1000 }); + await settle(); + const socket = FakeSocket.all.at(-1)!; + socket.open(); + // A read now could finish before the server hears S1: a write in that + // gap would be missed. So no connect read yet, and the timer runs. + expect(onChange).not.toHaveBeenCalled(); + await vi.advanceTimersByTimeAsync(1000); + expect(onChange.mock.calls).toEqual([[null]]); + onChange.mockClear(); + socket.frame({ type: "subscribed" }); + socket.frame({ type: "crossing", crosses: true }); + // The connect read, after acceptance; the first crossing frame adds none. + expect(onChange.mock.calls).toEqual([[null]]); + onChange.mockClear(); + await vi.advanceTimersByTimeAsync(5000); + expect(onChange).not.toHaveBeenCalled(); + }); + + it("covers a topic added to a live socket only once the server acknowledges its ticket", async () => { + const { fetcher } = server({ push: { transport: "websocket" } }); + const fsd = client(fetcher); + const first = await connected(fsd, [S1], undefined, true); + FakeSocket.autoAck = false; + const onChange = vi.fn(); + fsd.subscribe([topic.org()], { onChange, pollIntervalMs: 1000 }); + await settle(); + expect(first.socket.sent.at(-1)).toEqual({ type: "subscribe", ticket: "t2" }); + expect(onChange).not.toHaveBeenCalled(); + await vi.advanceTimersByTimeAsync(1000); + expect(onChange.mock.calls).toEqual([[null]]); + onChange.mockClear(); + first.socket.frame({ type: "subscribed" }); + expect(onChange.mock.calls).toEqual([[null]]); + onChange.mockClear(); + await vi.advanceTimersByTimeAsync(5000); + expect(onChange).not.toHaveBeenCalled(); + }); + + it("mints a topic again after a stop and reopen, though an older mint for it was still in flight", async () => { + let release: (() => void) | undefined; + const { fetcher, mints } = server({ + push: { transport: "websocket" }, + holdMint: (topics) => + topics.some((t) => t.scope === "org") && release === undefined + ? new Promise((resolve) => (release = resolve)) + : undefined + }); + const fsd = client(fetcher); + const first = await connected(fsd, [S1], undefined, true); + const pending = fsd.subscribe([topic.org()], { onChange: () => {} }); + await settle(); + first.sub.close(); + pending.close(); + const second = await connected(fsd, [topic.user()], undefined, true); + const onChange = vi.fn(); + fsd.subscribe([topic.org()], { onChange }); + await settle(); + release!(); + await settle(); + expect(mints.filter((call) => call.topics.some((t) => t.scope === "org"))).toHaveLength(2); + expect(second.socket.sent.filter((frame) => (frame as { type: string }).type === "subscribe")).toHaveLength(2); + expect(onChange.mock.calls).toEqual([[null]]); + }); + + it("drops a frame that isn't one the server sends", async () => { + const { fetcher } = server({ push: { transport: "websocket" } }); + const { onChange, socket } = await connected(client(fetcher), [S1], undefined, true); + onChange.mockClear(); + socket.frame({ type: "notice", topic: { scope: "session" }, kind: "items" }); + socket.frame({ type: "notice", kind: "items" }); + socket.frame({ type: "crossing", crosses: "yes" }); + socket.frame(["notice"]); + expect(onChange).not.toHaveBeenCalled(); + }); + it("reconnects at once when the server ends the socket at its age limit", async () => { const { fetcher, mints } = server({ push: { transport: "websocket" } }); const { socket } = await connected(client(fetcher), [S1], 1000, true); diff --git a/packages/contracts/src/types/push-delivery.ts b/packages/contracts/src/types/push-delivery.ts index 8550b624a0..97f78d84b4 100644 --- a/packages/contracts/src/types/push-delivery.ts +++ b/packages/contracts/src/types/push-delivery.ts @@ -56,11 +56,19 @@ export type WireNotice = { * What a server sends on the socket. * * - `notice`: a change under a topic the socket subscribed. + * - `subscribed`: a delivery control frame acknowledging one accepted ticket, + * in the order the tickets arrived. Sent once the ticket's topics are heard, + * so a read the client makes after it misses no change under them. * - `crossing`: a delivery control frame saying whether this process's bus - * hears changes made in other processes. Sent after the first ticket and on - * each change of the answer. Never a notice kind, and never carries rows. + * hears changes made in other processes. Sent after the first ticket's + * `subscribed`, and on each change of the answer. + * + * Control frames are never a notice kind, and never carry rows. */ -export type PushServerFrame = ({ type: "notice" } & WireNotice) | { type: "crossing"; crosses: boolean }; +export type PushServerFrame = + | ({ type: "notice" } & WireNotice) + | { type: "subscribed" } + | { type: "crossing"; crosses: boolean }; /** * What a client sends on the socket. diff --git a/packages/engine/README.md b/packages/engine/README.md index 40165efb1a..f5997de2be 100644 --- a/packages/engine/README.md +++ b/packages/engine/README.md @@ -684,8 +684,10 @@ through the read check its scope uses and signs a 30-second ticket for the ones it grants. The host hands each socket that opens on `/users/:userId/stream` to `delivery.openSocket(userId, { send, close })` and moves text frames to the returned session's `receive`. The session accepts topics only from a ticket for -that user, and closes the socket after an hour. After the first ticket, and each -time the bus's `crossesProcesses` changes, it sends `{ type: "crossing", crosses }`: +that user, and closes the socket after an hour. It answers each accepted ticket +with `{ type: "subscribed" }` once the ticket's topics are heard, so a client reads +after that point and misses nothing. After the first ticket, and each time the +bus's `crossesProcesses` changes, it sends `{ type: "crossing", crosses }`: whether notices from other processes reach this socket. A client keeps reading on its timer until it hears `crosses: true`. `serve()` in `@flow-state-dev/node` does all of this; `secret` defaults to a diff --git a/packages/engine/src/push/socket-session.ts b/packages/engine/src/push/socket-session.ts index 9089ac525d..6acf15a1e8 100644 --- a/packages/engine/src/push/socket-session.ts +++ b/packages/engine/src/push/socket-session.ts @@ -12,6 +12,8 @@ * - **No check while open** (D2). An open socket hears its topics until it * closes, at most an hour after it opened (4000); the client mints again to * reconnect, and the mint checks again. + * - **`subscribed` frames.** Each accepted ticket is acknowledged once its + * topics are subscribed on the bus, so the client reads after that point. * - **`crossing` frames.** After the first ticket, and on each change, the * socket says whether its process's bus hears other processes. A control * frame about the socket, never a notice kind. @@ -125,6 +127,9 @@ export function openPushSocket(options: OpenPushSocketOptions): PushSocket { if (subscriptions.has(key)) continue; subscriptions.set(key, { wireKey: wireTopicKey(toWire(granted.bus)), off: bus.subscribe(granted.bus, hear) }); } + // Its topics are heard from here on: a read the client makes once it + // hears this misses nothing under them. + send({ type: "subscribed" }); if (accepted) return; accepted = true; clearTimeout(ticketTimer); diff --git a/packages/engine/test/push-delivery.test.ts b/packages/engine/test/push-delivery.test.ts index b31ff4dde0..ab83cedbb5 100644 --- a/packages/engine/test/push-delivery.test.ts +++ b/packages/engine/test/push-delivery.test.ts @@ -343,20 +343,50 @@ describe("the socket session", () => { const ws = socket(delivery!); expect(ws.frames).toEqual([]); ws.send({ type: "subscribe", ticket: await ticketFor(router, [topic.user()]) }); - expect(ws.frames).toEqual([{ type: "crossing", crosses: false }]); + expect(ws.frames).toEqual([{ type: "subscribed" }, { type: "crossing", crosses: false }]); crosses = true; for (const listener of crossingListeners) listener(true); expect(ws.frames).toEqual([ + { type: "subscribed" }, { type: "crossing", crosses: false }, { type: "crossing", crosses: true } ]); - // A second ticket adds topics; it sends no second first frame. + // A second ticket adds topics: it is acknowledged once its topics are + // heard, and sends no second crossing frame. ws.send({ type: "subscribe", ticket: await ticketFor(router, [topic.org()]) }); - expect(ws.frames).toHaveLength(2); + expect(ws.frames.slice(3)).toEqual([{ type: "subscribed" }]); ws.end(); expect(crossingListeners.size).toBe(0); }); + it("acknowledges a ticket only after its topics are subscribed on the bus", async () => { + const inner = createInMemoryBus(); + const order: string[] = []; + const bus: ChangeBus = { + ...inner, + publish: inner.publish, + subscribe: (busTopic, listener) => { + order.push(`bus:${busTopic.scope}`); + return inner.subscribe(busTopic, listener); + }, + crossesProcesses: true, + onCrossingChange: () => () => {} + }; + const { router, delivery } = app({ bus }); + const frames: string[] = []; + const session = delivery!.openSocket("alice", { + send: (frame) => { + order.push(`frame:${frame.type}`); + frames.push(frame.type); + }, + close: () => {} + }); + session.receive(JSON.stringify({ type: "subscribe", ticket: await ticketFor(router, [topic.user()]) })); + session.receive(JSON.stringify({ type: "subscribe", ticket: await ticketFor(router, [topic.org()]) })); + expect(order).toEqual(["bus:user", "frame:subscribed", "frame:crossing", "bus:org", "frame:subscribed"]); + session.closed(); + }); + it("stops hearing a topic it unsubscribes, and everything once it closes", async () => { const bus = createInMemoryBus(); const { router, delivery } = app({ bus }); @@ -458,7 +488,7 @@ describe("the socket session", () => { ) }) ); - expect(frames).toEqual([{ type: "crossing", crosses: false }]); + expect(frames).toEqual([{ type: "subscribed" }, { type: "crossing", crosses: false }]); session.closed(); }); }); @@ -491,7 +521,7 @@ describe("enablePushDelivery", () => { const ws = socket(delivery); ws.send({ type: "subscribe", ticket: answer.ticket }); expect(ws.closed()).toBeUndefined(); - expect(ws.frames).toEqual([{ type: "crossing", crosses: false }]); + expect(ws.frames).toEqual([{ type: "subscribed" }, { type: "crossing", crosses: false }]); } }); diff --git a/packages/node/README.md b/packages/node/README.md index 7c43bbb517..d7079ab465 100644 --- a/packages/node/README.md +++ b/packages/node/README.md @@ -173,7 +173,7 @@ durable background work). See the deployment guides for the full topology: | `pageHandler` | — | A Connect-style `(req, res, next)` handler tried before `staticDir`'s SPA fallback for non-API GET requests, for a dev server's middleware. A real file in `staticDir` and a dedicated adapter route are served ahead of it. Calling `next()` passes the request on; `next(err)` returns a 500. | | `shutdownGraceMs` | `10000` | Grace window before lingering connections are force-closed. | | `disposeOnClose` | `true` | Whether `close()` disposes the `FlowState` after draining. Set `false` when several servers share one runtime, and dispose it yourself once they have all closed. | -| `push` | `true` | Serve the change-notice WebSocket at `/users/:userId/stream` (see [Push](#push)). `false` reports `push: null`. | +| `push` | `true` | Serve the change-notice WebSocket at `/users/:userId/stream` (see [Push](#push)). `false` reports `push: null` and answers the mint 404, also over a router another host serves push for. | | `pushSecret` | `process.env.FSD_PUSH_SECRET`, then a random key | `string \| (() => string)`. The key push tickets are signed with. Give every process behind one address the same one. | ### `createPageHtmlTransform(options)` diff --git a/packages/node/src/app.ts b/packages/node/src/app.ts index bd58f3a376..f2a7c8e6cb 100644 --- a/packages/node/src/app.ts +++ b/packages/node/src/app.ts @@ -31,6 +31,14 @@ export interface ServerAppOptions { basePath?: string; /** Health endpoint path. Default `"/healthz"`. 200 once ready, 503 before. */ healthPath?: string; + /** + * Whether the host running this app serves the push socket. Default + * `false`: the app reports `push: null` in `GET /capabilities` and answers + * the push mint 404, even over a router another host serves push for, so a + * client reads on its timer instead of minting for a socket this host + * doesn't open. `serve()` sets it when it serves push. + */ + servesPush?: boolean; } /** The portable host app plus its lifecycle handles. */ @@ -137,6 +145,18 @@ export function createServerApp( // resolves the same memoized router this app holds. const inProcessFetch = createInProcessFetch(app, { basePath }); + // Push belongs to the host that serves its socket. A router shared with a + // host that does may have push on; this app says what it serves itself. + if (options.servesPush !== true) { + hono.get(`${basePath}/capabilities`, async (c) => { + const response = await inProcessFetch(c.req.raw); + if (!response.ok) return response; + const body = (await response.json()) as Record; + return c.json({ ...body, push: null }, 200); + }); + hono.post(`${basePath}/users/:userId/stream`, (c) => c.json({ error: "This host serves no push" }, 404)); + } + // The bare mount and everything under it both reach the engine router. hono.all(basePath, (c) => inProcessFetch(c.req.raw)); hono.all(`${basePath}/*`, (c) => inProcessFetch(c.req.raw)); diff --git a/packages/node/src/serve.ts b/packages/node/src/serve.ts index cab5a01fab..430adf6f16 100644 --- a/packages/node/src/serve.ts +++ b/packages/node/src/serve.ts @@ -193,6 +193,7 @@ export function serve( const { app: honoApp, tryDedicatedRoute, dispose } = createServerApp(app, { basePath: options.basePath, healthPath: options.healthPath, + servesPush: options.push !== false, }); const push = servePush(app, options); diff --git a/packages/node/test/serve-push.test.ts b/packages/node/test/serve-push.test.ts index bfe7aeb920..ff465ff97f 100644 --- a/packages/node/test/serve-push.test.ts +++ b/packages/node/test/serve-push.test.ts @@ -109,7 +109,7 @@ describe("serve() push delivery", () => { await ws.opened; ws.socket.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); await until(() => ws.frames.length > 0); - expect(ws.frames[0]).toEqual({ type: "crossing", crosses: false }); + expect(ws.frames[0]).toEqual({ type: "subscribed" }); await fetch(`${base}/api/flows/chat/${sessionId}/actions/say`, { method: "POST", @@ -154,7 +154,7 @@ describe("serve() push delivery", () => { await onB.opened; onB.socket.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); await until(() => onB.frames.length > 0); - expect(onB.frames[0]).toEqual({ type: "crossing", crosses: false }); + expect(onB.frames[0]).toEqual({ type: "subscribed" }); const onC = open(c.base, `/api/flows${answer.path}`); await onC.opened; @@ -179,11 +179,31 @@ describe("serve() push delivery", () => { ws.socket.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); await until(() => ws.frames.length > 0 || ws.closeCode() !== undefined); expect(ws.closeCode()).toBeUndefined(); - expect(ws.frames[0]).toEqual({ type: "crossing", crosses: false }); + expect(ws.frames[0]).toEqual({ type: "subscribed" }); } } }); + it("reports and mints push only on the host that serves the socket, when two hosts share a router", async () => { + const flowState = createFlowState({ flows: { chat }, stores: { default: { primary: inMemoryStores() } } }); + const router = await flowState.getRouter(); + const options = { port: 0, host: "127.0.0.1", handleSignals: false, shutdownGraceMs: 200, disposeOnClose: false }; + const withPush = await serve(router, options); + const withoutPush = await serve(router, { ...options, push: false }); + handles.push(withPush, withoutPush); + const on = `http://127.0.0.1:${withPush.port}`; + const off = `http://127.0.0.1:${withoutPush.port}`; + expect(await (await fetch(`${on}/api/flows/capabilities`)).json()).toEqual({ userStream: false, push: { transport: "websocket" } }); + expect(await (await fetch(`${off}/api/flows/capabilities`)).json()).toEqual({ userStream: false, push: null }); + const offMint = await fetch(`${off}/api/flows/users/alice/stream`, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ topics: [topic.user()] }) + }); + expect(offMint.status).toBe(404); + expect((await mint(on, [topic.user()])).transport).toBe("websocket"); + }); + it("takes the shared secret from FSD_PUSH_SECRET when pushSecret is not given", async () => { vi.stubEnv("FSD_PUSH_SECRET", "from-env"); const a = await start(); @@ -194,7 +214,7 @@ describe("serve() push delivery", () => { await ws.opened; ws.socket.send(JSON.stringify({ type: "subscribe", ticket: answer.ticket })); await until(() => ws.frames.length > 0); - expect(ws.frames[0]?.type).toBe("crossing"); + expect(ws.frames[0]?.type).toBe("subscribed"); }); it("closes open sockets when the server closes", async () => { @@ -223,6 +243,20 @@ describe("serve() push delivery", () => { }); describe("createServerApp", () => { + it("reports no push over a router another host serves push for", async () => { + const flowState = createFlowState({ flows: { chat }, stores: { default: { primary: inMemoryStores() } } }); + const router = await flowState.getRouter(); + const handle = await serve(router, { port: 0, host: "127.0.0.1", handleSignals: false, disposeOnClose: false }); + handles.push(handle); + const { app } = createServerApp(router); + const response = await app.fetch(new Request("http://localhost/api/flows/capabilities")); + expect(await response.json()).toEqual({ userStream: false, push: null }); + const minted = await app.fetch( + new Request("http://localhost/api/flows/users/alice/stream", { method: "POST", body: JSON.stringify({ topics: [] }) }) + ); + expect(minted.status).toBe(404); + }); + it("serves no push: capabilities says so, with no socket to open", async () => { const flowState = createFlowState({ flows: { chat }, stores: { default: { primary: inMemoryStores() } } }); const { app, dispose } = createServerApp(flowState); diff --git a/packages/react/src/hooks/useSubscription.ts b/packages/react/src/hooks/useSubscription.ts index 3a1c4fc92b..e1694e6dde 100644 --- a/packages/react/src/hooks/useSubscription.ts +++ b/packages/react/src/hooks/useSubscription.ts @@ -15,6 +15,7 @@ */ import { useEffect, useMemo, useRef } from "react"; import type { WireNotice, WireTopic } from "@flow-state-dev/client"; +import { wireTopicKey } from "@flow-state-dev/contracts"; import { coalescedReads } from "../internal/coalescedReads"; import { useClient } from "../internal/useClient"; @@ -32,14 +33,12 @@ export type UseSubscriptionOptions = { /** One key per distinct topic list, so an equal list keeps the subscription. */ function topicsKey(topics: readonly WireTopic[]): string { - return JSON.stringify( - topics.map((t) => [t.scope, t.scope === "session" ? t.id : "", t.resource ?? ""]) - ); + return topics.map(wireTopicKey).join("\u0001"); } function sameNotice(a: WireNotice | null, b: WireNotice | null): boolean { if (a === null || b === null) return a === b; - return a.kind === b.kind && topicsKey([a.topic]) === topicsKey([b.topic]); + return a.kind === b.kind && wireTopicKey(a.topic) === wireTopicKey(b.topic); } /** From 94d37c121fd8a5e7976934d7d405b375738cee1c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 11:29:54 +0000 Subject: [PATCH 5/8] fix(FIX-2428): origin in coalescing, chunked mints, one client per provider - react: useSubscription's waiting read gets null when its notices came from different requests: sameNotice compares origin.requestId (Codex 4454007227). - client/engine/contracts: PUSH_MINT_MAX_TOPICS (100) lives in contracts; the engine refuses longer lists with it and the client mints in chunks of it over the one socket (Codex 4454007211). - react: FlowProvider owns a client cache, so hooks with the same user and transport under one provider share one client and one push socket. Each provider has its own; no module-level cache (Codex 4454007237). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn --- packages/client/src/subscribe/push-hub.ts | 13 ++++- packages/client/test/subscribe.test.ts | 20 ++++++- packages/contracts/src/index.ts | 2 +- packages/contracts/src/types/push-delivery.ts | 8 ++- packages/core/src/index.ts | 2 +- packages/engine/src/push/push-delivery.ts | 8 ++- packages/react/src/context/FlowContext.ts | 20 ++++++- packages/react/src/hooks/useSubscription.ts | 6 ++- packages/react/src/internal/useClient.ts | 22 +++++--- packages/react/test/useSubscription.test.ts | 53 ++++++++++++++++--- 10 files changed, 128 insertions(+), 26 deletions(-) diff --git a/packages/client/src/subscribe/push-hub.ts b/packages/client/src/subscribe/push-hub.ts index e4fca9d9ac..103abf69a3 100644 --- a/packages/client/src/subscribe/push-hub.ts +++ b/packages/client/src/subscribe/push-hub.ts @@ -26,6 +26,7 @@ */ import { PUSH_CLOSE_CODES, + PUSH_MINT_MAX_TOPICS, wireTopicKey, type PushMintAnswer, type PushServerFrame, @@ -257,6 +258,14 @@ export function createPushHub(deps: { (key) => counts.has(key) && !granted.has(key) && !minting.has(key) && !unacknowledged.some((set) => set.has(key)) ); if (asking.length === 0) return; + // One mint takes at most PUSH_MINT_MAX_TOPICS; more go as several tickets + // over the same socket. + if (asking.length > PUSH_MINT_MAX_TOPICS) { + for (let i = 0; i < asking.length; i += PUSH_MINT_MAX_TOPICS) { + void mintMore(asking.slice(i, i + PUSH_MINT_MAX_TOPICS)); + } + return; + } const at = generation; for (const key of asking) minting.set(key, at); let answer: Awaited>; @@ -315,7 +324,9 @@ export function createPushHub(deps: { clearTimeout(retryTimer); state = "connecting"; const at = ++generation; - const asked = allTopics(); + // The connect's own ticket carries the first chunk; the rest are minted + // once the socket is open. + const asked = allTopics().slice(0, PUSH_MINT_MAX_TOPICS); updateTimers(); let answer: Awaited>; try { diff --git a/packages/client/test/subscribe.test.ts b/packages/client/test/subscribe.test.ts index 9ed240234f..719218d124 100644 --- a/packages/client/test/subscribe.test.ts +++ b/packages/client/test/subscribe.test.ts @@ -7,6 +7,7 @@ * reconnect, a change of the crossing answer, or a poll. */ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { PUSH_MINT_MAX_TOPICS } from "@flow-state-dev/contracts"; import { createClient, topic, type ClientFetch, type WireNotice, type WireTopic } from "../src"; /** A WebSocket double the test drives: open, deliver a frame, drop. */ @@ -89,7 +90,8 @@ function server( const { topics } = JSON.parse(String(init.body)) as { topics: WireTopic[] }; mints.push({ topics, authorization: headers.get("authorization") }); await options.holdMint?.(topics); - const status = options.mintStatus?.() ?? 200; + // The server's own limit: a longer list is refused whole. + const status = topics.length > PUSH_MINT_MAX_TOPICS ? 400 : (options.mintStatus?.() ?? 200); if (status !== 200) return Response.json({ error: "no" }, { status }); if (options.mintBody !== undefined) return new Response(options.mintBody, { status: 200 }); const granted = topics.filter(options.grant ?? (() => true)); @@ -416,6 +418,22 @@ describe("client.subscribe on a host with push", () => { expect(onChange.mock.calls).toEqual([[null]]); }); + it("mints more topics than one mint takes in chunks, over the one socket", async () => { + const { fetcher, mints } = server({ push: { transport: "websocket" } }); + const fsd = client(fetcher); + const many = Array.from({ length: 2 * PUSH_MINT_MAX_TOPICS + 5 }, (_, i) => topic.session(`s${i}`)); + const { socket, onChange } = await connected(fsd, many, 1000, true); + await settle(); + expect(FakeSocket.all).toHaveLength(1); + expect(mints.every((call) => call.topics.length <= PUSH_MINT_MAX_TOPICS)).toBe(true); + expect(new Set(mints.flatMap((call) => call.topics.map((t) => (t as { id: string }).id))).size).toBe(many.length); + expect(socket.sent.filter((frame) => (frame as { type: string }).type === "subscribe")).toHaveLength(3); + // Every topic is heard: push covers the subscription and its timer stops. + onChange.mockClear(); + await vi.advanceTimersByTimeAsync(5000); + expect(onChange).not.toHaveBeenCalled(); + }); + it("drops a frame that isn't one the server sends", async () => { const { fetcher } = server({ push: { transport: "websocket" } }); const { onChange, socket } = await connected(client(fetcher), [S1], undefined, true); diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts index 8cb9827a46..80a39817b6 100644 --- a/packages/contracts/src/index.ts +++ b/packages/contracts/src/index.ts @@ -29,7 +29,7 @@ export type { ChangeKind, TopicOptions, TopicScope, WireTopic } from "./types/ch // Push delivery (FIX-2428): the mint's answer, the socket's frames and the // push a server advertises. -export { PUSH_CLOSE_CODES, wireTopicKey } from "./types/push-delivery"; +export { PUSH_CLOSE_CODES, PUSH_MINT_MAX_TOPICS, wireTopicKey } from "./types/push-delivery"; export type { PushCapability, PushClientFrame, diff --git a/packages/contracts/src/types/push-delivery.ts b/packages/contracts/src/types/push-delivery.ts index 97f78d84b4..6e8d8a7ae1 100644 --- a/packages/contracts/src/types/push-delivery.ts +++ b/packages/contracts/src/types/push-delivery.ts @@ -22,7 +22,13 @@ import type { ChangeKind, WireTopic } from "./change-notice"; */ export type PushCapability = { transport: "websocket" } | { transport: "ably" }; -/** The body of `POST /users/:userId/stream`: the topics to hear. */ +/** + * The most topics one mint takes. A longer list is refused whole, so a client + * with more topics mints them in chunks of this size. + */ +export const PUSH_MINT_MAX_TOPICS = 100; + +/** The body of `POST /users/:userId/stream`: the topics to hear, at most {@link PUSH_MINT_MAX_TOPICS}. */ export type PushMintRequest = { topics: WireTopic[] }; /** diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 288e3526a0..0d5034c267 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -334,7 +334,7 @@ export { topic } from "@flow-state-dev/contracts"; export type { ChangeKind, TopicOptions, TopicScope, WireTopic } from "@flow-state-dev/contracts"; // Push delivery (FIX-2428): the mint's answer, the socket's frames and the // push a server advertises. -export { PUSH_CLOSE_CODES, wireTopicKey } from "@flow-state-dev/contracts"; +export { PUSH_CLOSE_CODES, PUSH_MINT_MAX_TOPICS, wireTopicKey } from "@flow-state-dev/contracts"; export type { PushCapability, PushClientFrame, diff --git a/packages/engine/src/push/push-delivery.ts b/packages/engine/src/push/push-delivery.ts index 17de25bdc2..1cd7b44f89 100644 --- a/packages/engine/src/push/push-delivery.ts +++ b/packages/engine/src/push/push-delivery.ts @@ -11,7 +11,7 @@ * the check. */ import { randomBytes } from "node:crypto"; -import { DEFAULT_ORG_ID, type PushCapability, type PushMintAnswer } from "@flow-state-dev/core"; +import { DEFAULT_ORG_ID, PUSH_MINT_MAX_TOPICS, type PushCapability, type PushMintAnswer } from "@flow-state-dev/core"; import type { ResolvedPrincipal } from "../transports/types"; import type { ChangeBus } from "../bus/types"; import type { FlowApiRouter } from "../routes/createFlowApiRouter"; @@ -40,8 +40,6 @@ export type PushDelivery = { openSocket(userId: string, io: PushSocketIO): PushSocket; }; -/** The most topics one mint takes. */ -const MAX_MINT_TOPICS = 100; /** Where a router keeps its push state, read across engine copies. */ const PUSH_STATE = Symbol.for("@flow-state-dev/engine/pushState"); @@ -127,8 +125,8 @@ export async function handleMintPush(request: Request, userId: string, ctx: Mint return jsonResponse(400, { error: "Expected a JSON body { topics }" }); } const topics = (body as { topics?: unknown } | null)?.topics; - if (!Array.isArray(topics) || topics.length > MAX_MINT_TOPICS || !topics.every(isWireTopic)) { - return jsonResponse(400, { error: `Expected { topics }: at most ${MAX_MINT_TOPICS} wire topics` }); + if (!Array.isArray(topics) || topics.length > PUSH_MINT_MAX_TOPICS || !topics.every(isWireTopic)) { + return jsonResponse(400, { error: `Expected { topics }: at most ${PUSH_MINT_MAX_TOPICS} wire topics` }); } const tenantId = ctx.tenantId ?? ""; diff --git a/packages/react/src/context/FlowContext.ts b/packages/react/src/context/FlowContext.ts index d1679a5674..2e3ddd1f78 100644 --- a/packages/react/src/context/FlowContext.ts +++ b/packages/react/src/context/FlowContext.ts @@ -8,9 +8,10 @@ import { createElement, useContext, useMemo, + useRef, type ReactNode } from "react"; -import type { ClientFetch } from "@flow-state-dev/client"; +import type { Client, ClientFetch } from "@flow-state-dev/client"; import type { RendererRegistry } from "../registry/block-renderers"; /** @@ -24,8 +25,17 @@ export type FlowContextValue = { apiPath?: string; fetcher?: ClientFetch; renderers?: RendererRegistry; + /** + * The clients this provider's hooks share, by transport, so hooks with the + * same user and transport hold one client (and so one push socket). Owned + * by the provider; absent outside one. + */ + clients?: ClientCache; }; +/** A provider's clients: by fetcher, then by user, base URL and API path. */ +export type ClientCache = Map>; + /** * Props for the canonical FlowProvider component. */ @@ -92,6 +102,10 @@ function mergeRenderers( */ export function FlowProvider(props: FlowProviderProps): ReactNode { const parent = useContext(FlowCtx); + // This provider's own client cache: never shared with another provider. + const clients = useRef(undefined); + clients.current ??= new Map(); + const cache = clients.current; const contextValue = useMemo(() => { return { @@ -101,9 +115,11 @@ export function FlowProvider(props: FlowProviderProps): ReactNode { baseUrl: props.baseUrl ?? parent.baseUrl, apiPath: props.apiPath ?? parent.apiPath, fetcher: props.fetcher ?? parent.fetcher, - renderers: mergeRenderers(parent.renderers, props.renderers) + renderers: mergeRenderers(parent.renderers, props.renderers), + clients: cache }; }, [ + cache, parent.baseUrl, parent.apiPath, parent.fetcher, diff --git a/packages/react/src/hooks/useSubscription.ts b/packages/react/src/hooks/useSubscription.ts index e1694e6dde..882206443d 100644 --- a/packages/react/src/hooks/useSubscription.ts +++ b/packages/react/src/hooks/useSubscription.ts @@ -38,7 +38,11 @@ function topicsKey(topics: readonly WireTopic[]): string { function sameNotice(a: WireNotice | null, b: WireNotice | null): boolean { if (a === null || b === null) return a === b; - return a.kind === b.kind && wireTopicKey(a.topic) === wireTopicKey(b.topic); + return ( + a.kind === b.kind && + wireTopicKey(a.topic) === wireTopicKey(b.topic) && + a.origin?.requestId === b.origin?.requestId + ); } /** diff --git a/packages/react/src/internal/useClient.ts b/packages/react/src/internal/useClient.ts index 7653161717..52774b2ac9 100644 --- a/packages/react/src/internal/useClient.ts +++ b/packages/react/src/internal/useClient.ts @@ -3,7 +3,9 @@ * `baseUrl` (or the provider's) and the provider's `apiPath` and `fetcher`. * * Memoized on those inputs, so a re-render keeps the same client and the - * streams opened through it stay open. + * streams opened through it stay open. Under a provider, hooks with the same + * user and transport share one client from the provider's cache, so they + * share one push socket too. */ import { useMemo } from "react"; import { createClient, type Client } from "@flow-state-dev/client"; @@ -18,16 +20,22 @@ export function useClient(overrides: { userId?: string; baseUrl?: string; apiPat const userId = overrides.userId ?? context.userId ?? DEFAULT_HOOK_USER_ID; const baseUrl = overrides.baseUrl ?? context.baseUrl; const apiPath = overrides.apiPath ?? context.apiPath; - const { fetcher } = context; - return useMemo( - () => + const { fetcher, clients } = context; + return useMemo(() => { + const build = (): Client => createClient({ userId, // No base URL means the page's own origin, with or without a fetcher. baseUrl: baseUrl ?? "", apiPath, fetcher - }), - [userId, baseUrl, apiPath, fetcher] - ); + }); + if (clients === undefined) return build(); + let byTransport = clients.get(fetcher); + if (byTransport === undefined) clients.set(fetcher, (byTransport = new Map())); + const key = `${userId}\u0000${baseUrl ?? ""}\u0000${apiPath ?? ""}`; + let client = byTransport.get(key); + if (client === undefined) byTransport.set(key, (client = build())); + return client; + }, [userId, baseUrl, apiPath, fetcher, clients]); } diff --git a/packages/react/test/useSubscription.test.ts b/packages/react/test/useSubscription.test.ts index e9720fa99c..89ccc5192d 100644 --- a/packages/react/test/useSubscription.test.ts +++ b/packages/react/test/useSubscription.test.ts @@ -15,8 +15,9 @@ import { afterEach, describe, expect, it, vi } from "vitest"; import { act, renderHook } from "@testing-library/react"; import type { SubscribeOptions, WireNotice, WireTopic } from "@flow-state-dev/client"; -const { subscriptions } = vi.hoisted(() => ({ - subscriptions: [] as Array<{ topics: readonly WireTopic[]; options: SubscribeOptions; closed: boolean }> +const { subscriptions, built } = vi.hoisted(() => ({ + subscriptions: [] as Array<{ topics: readonly WireTopic[]; options: SubscribeOptions; closed: boolean }>, + built: { clients: 0 } })); vi.mock("@flow-state-dev/client", async (importOriginal) => { @@ -24,8 +25,9 @@ vi.mock("@flow-state-dev/client", async (importOriginal) => { const { fakeClient } = await import("./support/fake-client"); return { ...actual, - createClient: () => - fakeClient({ + createClient: () => { + built.clients += 1; + return fakeClient({ subscribe: (topics, options) => { const entry = { topics, options, closed: false }; subscriptions.push(entry); @@ -35,15 +37,18 @@ vi.mock("@flow-state-dev/client", async (importOriginal) => { } }; } - }) + }); + } }; }); -const { useSubscription } = await import("../src"); +const { FlowProvider, useSubscription } = await import("../src"); +const { createElement } = await import("react"); const { topic } = await import("@flow-state-dev/client"); afterEach(() => { subscriptions.length = 0; + built.clients = 0; }); const S1 = topic.session("s1"); @@ -128,6 +133,42 @@ describe("useSubscription", () => { expect(gate.calls).toEqual([notice("items"), null]); }); + it("gives a waiting read null when its notices came from different requests", async () => { + const gate = gatedRead(); + renderHook(() => useSubscription([S1], gate.read)); + const { onChange } = subscriptions[0]!.options; + const from = (requestId: string): WireNotice => ({ topic: S1, kind: "request", origin: { requestId } }); + act(() => { + onChange(from("r1")); + onChange(from("r2")); + onChange(from("r3")); + }); + await gate.settle(); + expect(gate.calls).toEqual([from("r1"), null]); + }); + + it("shares one client, and so one socket, across hooks under one provider", () => { + const wrapper = ({ children }: { children: React.ReactNode }) => + createElement(FlowProvider, { userId: "u1", baseUrl: "http://host", children }); + renderHook( + () => { + useSubscription([S1], () => {}); + useSubscription([topic.org()], () => {}); + }, + { wrapper } + ); + expect(subscriptions).toHaveLength(2); + expect(built.clients).toBe(1); + }); + + it("gives each provider its own clients", () => { + const wrapper = ({ children }: { children: React.ReactNode }) => + createElement(FlowProvider, { userId: "u1", baseUrl: "http://host", children }); + renderHook(() => useSubscription([S1], () => {}), { wrapper }); + renderHook(() => useSubscription([S1], () => {}), { wrapper }); + expect(built.clients).toBe(2); + }); + it("keeps one subscription across renders with an equal topic list, and calls the latest read", async () => { const first = vi.fn(); const second = vi.fn(); From c1bdd49076dec90af703f7aa3ec59cd50ce16930 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 11:40:00 +0000 Subject: [PATCH 6/8] fix(FIX-2428): push hub teardown: no retry after the last close, refusals per connection - A capabilities read that fails or answers after the last subscription closed arms no retry and connects nothing (Codex 4454101939). - `refused` is cleared with the connection, so a reconnect asks for every topic again, refused ones past the first chunk included, as the first chunk already does (Codex 4454101930). - Each socket holds its own handshake deadline, and stop() clears the current one. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn --- packages/client/src/subscribe/push-hub.ts | 25 +++++++-- packages/client/test/subscribe.test.ts | 65 ++++++++++++++++++++++- 2 files changed, 84 insertions(+), 6 deletions(-) diff --git a/packages/client/src/subscribe/push-hub.ts b/packages/client/src/subscribe/push-hub.ts index 103abf69a3..bfe6dc50f3 100644 --- a/packages/client/src/subscribe/push-hub.ts +++ b/packages/client/src/subscribe/push-hub.ts @@ -150,6 +150,8 @@ export function createPushHub(deps: { let lapsed = false; let failures = 0; let retryTimer: ReturnType | undefined; + /** The current socket's handshake deadline, cleared on open, end and stop. */ + let handshakeTimer: ReturnType | undefined; /** Bumped on each connect and teardown, so a stale answer is ignored. */ let generation = 0; @@ -365,12 +367,15 @@ export function createPushHub(deps: { * once, whichever comes first. */ const ended = (code: number | undefined): void => { - clearTimeout(handshakeTimer); + clearTimeout(deadline); if (socket !== ws) return; socket = undefined; state = "idle"; crosses = false; + // Everything this connection learnt goes with it: the next connect asks + // for every topic again, refused ones included, as its first chunk does. granted.clear(); + refused.clear(); minting.clear(); unacknowledged = []; generation += 1; @@ -388,11 +393,14 @@ export function createPushHub(deps: { // fails, the timer runs from then. void connect(); }; - // A handshake that never answers is a failed connect too. - const handshakeTimer = setTimeout(() => ended(undefined), HANDSHAKE_TIMEOUT_MS); + // A handshake that never answers is a failed connect too. Each socket + // holds its own deadline, so an older socket ending late never clears a + // newer one's; `stop()` clears the current one. + const deadline = setTimeout(() => ended(undefined), HANDSHAKE_TIMEOUT_MS); + handshakeTimer = deadline; ws.addEventListener("open", () => { if (socket !== ws) return; - clearTimeout(handshakeTimer); + clearTimeout(deadline); opened = true; state = "open"; lapsed = false; @@ -452,10 +460,13 @@ export function createPushHub(deps: { return; } mode = "checking"; + const at = generation; let push: FlowCapabilities["push"]; try { push = (await deps.capabilities()).push; } catch { + // Torn down meanwhile (the last subscription closed): nothing to retry for. + if (at !== generation || handles.size === 0) return; // Unknown: try again later, reading on the timer meanwhile. mode = "unknown"; lapsed = true; @@ -464,6 +475,11 @@ export function createPushHub(deps: { updateTimers(); return; } + if (at !== generation || handles.size === 0) { + // Torn down meanwhile; keep what was learnt, start nothing. + mode = push == null ? "none" : "push"; + return; + } // An older server sends no `push`: the same as none (BP-030). if (push == null) { noPush(); @@ -476,6 +492,7 @@ export function createPushHub(deps: { const stop = (): void => { generation += 1; clearTimeout(retryTimer); + clearTimeout(handshakeTimer); const ws = socket; socket = undefined; state = "idle"; diff --git a/packages/client/test/subscribe.test.ts b/packages/client/test/subscribe.test.ts index 719218d124..1eb516f293 100644 --- a/packages/client/test/subscribe.test.ts +++ b/packages/client/test/subscribe.test.ts @@ -7,7 +7,7 @@ * reconnect, a change of the crossing answer, or a poll. */ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; -import { PUSH_MINT_MAX_TOPICS } from "@flow-state-dev/contracts"; +import { PUSH_MINT_MAX_TOPICS, wireTopicKey as wireKey } from "@flow-state-dev/contracts"; import { createClient, topic, type ClientFetch, type WireNotice, type WireTopic } from "../src"; /** A WebSocket double the test drives: open, deliver a frame, drop. */ @@ -75,14 +75,19 @@ function server( mintBody?: string; /** Hold a mint's answer until the promise this returns settles. */ holdMint?: (topics: WireTopic[]) => Promise | undefined; + /** Fail `GET /capabilities` while this returns true. */ + capabilitiesFail?: () => boolean; } = {} ) { const mints: MintCall[] = []; + const capabilityCalls = { count: 0 }; let ticket = 0; const fetcher: ClientFetch = async (input, init) => { const url = String(input); const headers = new Headers(init?.headers); if (url.endsWith("/capabilities")) { + capabilityCalls.count += 1; + if (options.capabilitiesFail?.() === true) return Response.json({ error: "down" }, { status: 503 }); const body = options.push === undefined ? { userStream: false } : { userStream: false, push: options.push }; return Response.json(body); } @@ -105,7 +110,7 @@ function server( }; const wrapped: ClientFetch = (input, init) => fetcher(input, { ...init, headers: { ...(init?.headers as Record), authorization: "Bearer secret" } }); - return { fetcher: wrapped, mints }; + return { fetcher: wrapped, mints, capabilityCalls }; } function client(fetcher: ClientFetch) { @@ -434,6 +439,62 @@ describe("client.subscribe on a host with push", () => { expect(onChange).not.toHaveBeenCalled(); }); + it("asks again on a reconnect for a topic past the first chunk that the last connection refused", async () => { + let allow = false; + const late = topic.session(`s${PUSH_MINT_MAX_TOPICS + 1}`); + const { fetcher, mints } = server({ + push: { transport: "websocket" }, + grant: (t) => allow || wireKey(t) !== wireKey(late) + }); + const many = Array.from({ length: PUSH_MINT_MAX_TOPICS + 2 }, (_, i) => topic.session(`s${i}`)); + const { socket } = await connected(client(fetcher), many, undefined, true); + await settle(); + const before = mints.length; + allow = true; + socket.drop(); + await settle(); + FakeSocket.all.at(-1)!.open(); + await settle(); + const asked = mints.slice(before).flatMap((call) => call.topics.map(wireKey)); + expect(asked).toContain(wireKey(late)); + }); + + for (const [name, setup] of [ + ["the capabilities read keeps failing", { capabilitiesFail: () => true }], + ["each connect fails", { mintStatus: () => 503 }] + ] as const) { + it(`arms no timer once the last subscription closes, when ${name}`, async () => { + const { fetcher, capabilityCalls, mints } = server({ push: { transport: "websocket" }, ...setup }); + const sub = client(fetcher).subscribe([S1], { onChange: () => {}, pollIntervalMs: 1000 }); + await vi.advanceTimersByTimeAsync(3500); + sub.close(); + await settle(); + const probes = capabilityCalls.count + mints.length; + await vi.advanceTimersByTimeAsync(60_000); + expect(capabilityCalls.count + mints.length).toBe(probes); + expect(vi.getTimerCount()).toBe(0); + }); + } + + it("arms no retry when a capabilities read in flight fails after the last close", async () => { + let fail = false; + let release: (() => void) | undefined; + const held: ClientFetch = async (input, init) => { + if (String(input).endsWith("/capabilities")) { + await new Promise((resolve) => (release = resolve)); + if (fail) return Response.json({ error: "down" }, { status: 503 }); + } + return server({ push: { transport: "websocket" } }).fetcher(input, init); + }; + const sub = client(held).subscribe([S1], { onChange: () => {}, pollIntervalMs: 1000 }); + await settle(); + sub.close(); + fail = true; + release!(); + await settle(); + expect(vi.getTimerCount()).toBe(0); + }); + it("drops a frame that isn't one the server sends", async () => { const { fetcher } = server({ push: { transport: "websocket" } }); const { onChange, socket } = await connected(client(fetcher), [S1], undefined, true); From c1acd914e14c1130066b788230bec26637bff4d0 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 11:51:04 +0000 Subject: [PATCH 7/8] fix(shift-manager): pass readiness, not the removed ACCOUNT, in the coder-label test (FIX-2510) FIX-2391 changed start() to take a readiness array and removed ACCOUNT; FIX-2487 then added a test still using the old shape. Both merged, so typecheck was red on main. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn (cherry picked from commit 27c8abdd1227be2725cf53c75a33324f0cebc96b) --- packages/shift-manager/test/harness-start.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/shift-manager/test/harness-start.test.ts b/packages/shift-manager/test/harness-start.test.ts index 78a5f89ee8..d595226709 100644 --- a/packages/shift-manager/test/harness-start.test.ts +++ b/packages/shift-manager/test/harness-start.test.ts @@ -173,7 +173,7 @@ describe("each coder's label", () => { ["codex", "Codex"], ["cursor", "Cursor"], ] as const)("%s is called %s", async (value, label) => { - const started = await start("stub", value, ACCOUNT); + const started = await start("stub", value, [READY]); expect(started.harness?.label).toBe(label); }); }); From f3f48ed881b571e884b51e02466c548a0a31842a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 12:00:37 +0000 Subject: [PATCH 8/8] fix(FIX-2428): unsubscribe topics whose last handle closed while their ticket was in flight - The acknowledgement now accounts for every topic its ticket granted: one no subscription wants any more is unsubscribed, beside topics on the same ticket that are still wanted (Codex 4454225694). - A mint whose topics all lost their subscriptions while it was in flight sends no ticket. - A notice reaches a subscription only through a topic this socket was granted, so a refused subscription never hears another's. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn --- packages/client/src/subscribe/push-hub.ts | 50 ++++++++++++++++------- packages/client/test/subscribe.test.ts | 49 ++++++++++++++++++++++ 2 files changed, 84 insertions(+), 15 deletions(-) diff --git a/packages/client/src/subscribe/push-hub.ts b/packages/client/src/subscribe/push-hub.ts index bfe6dc50f3..fd088ae10d 100644 --- a/packages/client/src/subscribe/push-hub.ts +++ b/packages/client/src/subscribe/push-hub.ts @@ -138,7 +138,7 @@ export function createPushHub(deps: { * sent. The server acknowledges tickets in that order, once it hears their * topics; until then a read could miss a change under them. */ - let unacknowledged: Array> = []; + let unacknowledged: Array> = []; let mode: "unknown" | "checking" | "none" | "push" = "unknown"; let socket: WebSocket | undefined; @@ -206,8 +206,8 @@ export function createPushHub(deps: { })); /** - * Record which of `asked` the answer left out, and return the ones it - * granted. Those are heard only once the server acknowledges the ticket. + * Record which of `asked` the answer left out. The ones it granted are + * heard only once the server acknowledges the ticket. */ const record = (asked: readonly string[], answer: { topics: WireTopic[] }): Set => { const answered = new Set(answer.topics.map(wireTopicKey)); @@ -224,25 +224,37 @@ export function createPushHub(deps: { return grantedNow; }; - /** Send a ticket for `keys`, to be heard once the server acknowledges it. */ - const sendTicket = (ws: WebSocket, ticket: string, keys: Set): void => { + /** + * Send a ticket, to be heard once the server acknowledges it. `topics` is + * every topic the ticket grants, wanted or not: the server subscribes them + * all, so the acknowledgement must account for each. + */ + const sendTicket = (ws: WebSocket, ticket: string, topics: readonly WireTopic[]): void => { // Queued before sending: a server may acknowledge before `send` returns. - unacknowledged.push(keys); + unacknowledged.push(new Map(topics.map((t) => [wireTopicKey(t), t]))); ws.send(JSON.stringify({ type: "subscribe", ticket })); }; /** The server heard the oldest ticket's topics: they are covered, and read once. */ const acknowledged = (): void => { - const keys = unacknowledged.shift(); - if (keys === undefined) return; + const ticketTopics = unacknowledged.shift(); + if (ticketTopics === undefined) return; // A ticket accepted: the connect worked, so the backoff starts over. failures = 0; const added = new Set(); - for (const key of keys) { - if (!counts.has(key) || granted.has(key)) continue; + const unwanted: WireTopic[] = []; + for (const [key, ticketTopic] of ticketTopics) { + // Its last subscription closed while the ticket was in flight: the + // server now hears it for nobody, so stop it hearing it. + if (!counts.has(key)) { + if (!granted.has(key)) unwanted.push(ticketTopic); + continue; + } + if (granted.has(key)) continue; granted.add(key); added.add(key); } + if (unwanted.length > 0 && socket !== undefined) socket.send(JSON.stringify({ type: "unsubscribe", topics: unwanted })); updateTimers(); // Each connect, and each topic added, reads once (ER-6): it may have // missed changes made before the server heard it. @@ -257,7 +269,7 @@ export function createPushHub(deps: { const mintMore = async (keys: readonly string[]): Promise => { if (state !== "open") return; const asking = keys.filter( - (key) => counts.has(key) && !granted.has(key) && !minting.has(key) && !unacknowledged.some((set) => set.has(key)) + (key) => counts.has(key) && !granted.has(key) && !minting.has(key) && !unacknowledged.some((pending) => pending.has(key)) ); if (asking.length === 0) return; // One mint takes at most PUSH_MINT_MAX_TOPICS; more go as several tickets @@ -285,8 +297,10 @@ export function createPushHub(deps: { updateTimers(); return; } - const grantedNow = record(asking, answer); - if (answer.topics.length > 0) sendTicket(socket, answer.ticket, grantedNow); + record(asking, answer); + // A ticket none of whose topics is still wanted would only subscribe the + // server for nobody. + if (answer.topics.some((t) => counts.has(wireTopicKey(t)))) sendTicket(socket, answer.ticket, answer.topics); updateTimers(); }; @@ -410,7 +424,8 @@ export function createPushHub(deps: { unacknowledged = []; // The connect reads once the server acknowledges this ticket, not now: // a read now could finish before the server hears the topics. - sendTicket(ws, ready.ticket, record(asked.map(wireTopicKey), ready)); + record(asked.map(wireTopicKey), ready); + sendTicket(ws, ready.ticket, ready.topics); updateTimers(); // Topics subscribed while this connect was in flight. const asked2 = new Set(asked.map(wireTopicKey)); @@ -445,7 +460,12 @@ export function createPushHub(deps: { if (frame.type === "notice") { const { type: _type, ...notice } = frame; for (const handle of [...handles]) { - if (handle.topics.some((subscribed) => covers(subscribed, notice.topic))) call(handle, notice); + // Only through a topic this socket was granted: a notice for any + // other never reaches a subscription, whatever the server sent. + const heard = handle.topics.some( + (subscribed) => granted.has(wireTopicKey(subscribed)) && covers(subscribed, notice.topic) + ); + if (heard) call(handle, notice); } } }); diff --git a/packages/client/test/subscribe.test.ts b/packages/client/test/subscribe.test.ts index 1eb516f293..5ebb700b43 100644 --- a/packages/client/test/subscribe.test.ts +++ b/packages/client/test/subscribe.test.ts @@ -495,6 +495,55 @@ describe("client.subscribe on a host with push", () => { expect(vi.getTimerCount()).toBe(0); }); + it("unsubscribes a topic whose last subscription closed before its ticket was acknowledged", async () => { + const { fetcher } = server({ push: { transport: "websocket" } }); + const fsd = client(fetcher); + const keep = await connected(fsd, [S1], undefined, true); + FakeSocket.autoAck = false; + const both = fsd.subscribe([topic.org(), topic.user()], { onChange: () => {} }); + await settle(); + expect(keep.socket.sent.at(-1)).toEqual({ type: "subscribe", ticket: "t2" }); + // Another subscription wants `user` too, while the ticket is in flight. + const userOnly = vi.fn(); + fsd.subscribe([topic.user()], { onChange: userOnly }); + both.close(); + keep.socket.frame({ type: "subscribed" }); + // The server subscribed `org` for that ticket; nothing wants it now. + expect(keep.socket.sent.at(-1)).toEqual({ type: "unsubscribe", topics: [topic.org()] }); + // `user` is still wanted: it is heard, and read once. + expect(userOnly.mock.calls).toEqual([[null]]); + }); + + it("sends no ticket for a mint whose topics all lost their subscriptions while it was in flight", async () => { + let release: (() => void) | undefined; + const { fetcher } = server({ + push: { transport: "websocket" }, + holdMint: (topics) => (topics.some((t) => t.scope === "org") ? new Promise((resolve) => (release = resolve)) : undefined) + }); + const fsd = client(fetcher); + const keep = await connected(fsd, [S1], undefined, true); + const sent = keep.socket.sent.length; + const org = fsd.subscribe([topic.org()], { onChange: () => {} }); + await settle(); + org.close(); + release!(); + await settle(); + expect(keep.socket.sent.slice(sent)).toEqual([]); + }); + + it("passes a notice only to a subscription whose topic this socket was granted", async () => { + const { fetcher } = server({ push: { transport: "websocket" }, grant: (t) => t.scope !== "org" }); + const fsd = client(fetcher); + const keep = await connected(fsd, [S1], undefined, true); + const refusedOrg = vi.fn(); + fsd.subscribe([topic.org()], { onChange: refusedOrg }); + await settle(); + refusedOrg.mockClear(); + // A notice for a topic the mint refused this socket never reaches it. + keep.socket.frame({ type: "notice", ...notice(topic.org(), "request") }); + expect(refusedOrg).not.toHaveBeenCalled(); + }); + it("drops a frame that isn't one the server sends", async () => { const { fetcher } = server({ push: { transport: "websocket" } }); const { onChange, socket } = await connected(client(fetcher), [S1], undefined, true);