@preventive/triage 1.0.0-alpha.0 → 1.0.0-alpha.2

package/server/sse-server.ts

@@ -0,0 +1,352 @@
+// SSE+POST fallback for clients that can't establish a WebSocket
+// upgrade — corporate proxies that strip `Upgrade: websocket`, legacy
+// HTTP/1.0 intermediaries, or environments where `new WebSocket(…)`
+// errors before `open`. Wire protocol on the SSE downstream is
+// identical to the WS plane (same JSON message taxonomy, same Ed25519-
+// signed canonicals, same `challenge` / `pong` / `authenticate` flow);
+// the upstream direction batches frames into HTTP POSTs.
+//
+// One route, POSTs only:
+//
+//   POST /api/sync/sse[?id=<sid>]
+//       Request body:
+//         { password?: string,                   — cached client password
+//           frames?:   Array<protocol-frame>     — WS-style JSON frames
+//         }
+//       Response:
+//         200 OK, content-type: text/event-stream
+//         First frame on a *fresh* session is an SSE event named
+//         `session` whose data is the raw continuation-token string
+//         (22-char base64url, from `randomId()`). The per-session
+//         challenge nonce is delivered separately on the next default-
+//         named `data:` event as the standard protocol `challenge`
+//         frame, so the SSE plane uses the SAME nonce-handshake the WS
+//         plane does. Subsequent frames are default-named SSE messages
+//         carrying the WS protocol's JSON envelopes.
+//
+// Continuation: each POST replaces the previous POST's response as the
+// session's downstream channel. If the `?id=<sid>` in the URL matches
+// a session this replica knows, the session continues (new outbound
+// stream attached, old one end()ed). If the id is unknown (different
+// replica picked up the POST, or session expired), a fresh session
+// with a new id is created and announced via the first `session`
+// event; the client uses the new id on all subsequent POSTs and re-
+// sends its subscribe frames on the next POST (its `frames` carry the
+// signed subscribes — they always do, see client/sync/sse-transport.ts).
+//
+// Why POSTs only: a long-lived GET pins the client to one replica via
+// TCP affinity, which would mean POSTs from the same client must be
+// sticky-routed to the same replica. POSTs-only makes the protocol
+// stateless across replicas — any replica can pick up the next POST
+// from any client.
+
+import type { IncomingMessage as HttpRequest, ServerResponse } from 'node:http'
+import { Buffer } from 'node:buffer'
+import type { WebSocket } from 'ws'
+import { type PeerConnectionDeps, setupPeerConnection } from './ws-server.ts'
+import { SseSession } from './sse-session.ts'
+import { errMsg, randomId } from './util.ts'
+
+// Same prefix the WS upgrade lives under (server/http.ts WS_UPGRADE_PATH
+// = '/api/sync'); subroute keeps the SSE plane sibling to the upgrade
+// path so the same `location` block routes both.
+export const SSE_OPEN_PATH = '/api/sync/sse'
+
+export type SseServerDeps = {
+  // The WS dispatch is the cohesive unit; SSE just provides another
+  // transport into it. Closure over the same handler / hub / objstore
+  // / track / debug surface the WS path uses.
+  peerDeps: PeerConnectionDeps
+  // Shutdown gate. Mirror of the REST + WS branches in server/http.ts:
+  // an SSE POST arriving on an existing keep-alive socket after
+  // SIGTERM should be rejected, not dispatched against a draining DB.
+  isShuttingDown: () => boolean
+  // Max number of concurrent SSE sessions per process. Above this we
+  // 503 the open request. Caps the SSE-side equivalent of `wss.clients`.
+  maxSessions: number
+  // Max body size for one POST. Matches the WS `maxPayload` in
+  // server/index.ts so the SSE plane can't accept frames the WS plane
+  // would reject. The POST body envelope can hold multiple frames so
+  // the per-frame budget is the same as the WS plane after the
+  // dispatcher splits them.
+  maxBodyBytes: number
+  // Idle timeout for a session with no inbound POSTs. Detects the
+  // wandered-off browser tab the WS heartbeat sweep handles via
+  // ping/pong on real sockets. The client's JSON ping/pong heartbeat
+  // (every 15s) is the steady-state liveness signal; this is the
+  // hard ceiling.
+  sessionIdleMs: number
+  debug: boolean
+}
+
+export type SseServer = {
+  // Returns true if the request matched an SSE route (caller should
+  // not fall through to other handlers). false otherwise.
+  handle: (req: HttpRequest, res: ServerResponse) => boolean
+  // Iterates active sessions. Lifecycle's graceful-shutdown loop
+  // reads this to close SSE sessions alongside WS clients.
+  sessions: () => Iterable<SseSession>
+}
+
+// Inbound POST body. Every field optional — an empty-body POST is a
+// valid "wake the session" probe (the response stream rides on every
+// POST), and a body that carries only `password` or only `frames` is
+// a normal partial update.
+type SseBody = {
+  password?: unknown
+  frames?: unknown
+}
+
+export function installSseServer(deps: SseServerDeps): SseServer {
+  const { peerDeps, isShuttingDown, maxSessions, maxBodyBytes, sessionIdleMs, debug } = deps
+
+  // Active SSE sessions, keyed by the random session id `createSession`
+  // mints on the first POST that lacks a `?id=` (or whose id this
+  // replica doesn't recognise) and that subsequent POSTs echo back to
+  // continue the session. Bounded by `maxSessions` — over the cap, new
+  // POSTs get a 503. POSTs against an unknown id are NOT 404'd — they
+  // mint a fresh session instead, so a multi-replica deployment doesn't
+  // require sticky LB routing to recover.
+  const sessions = new Map<string, SseSession>()
+  // Per-session idle timer handle. Reset on every inbound POST; fires
+  // after `sessionIdleMs` of silence to close a stranded session.
+  const idleTimers = new Map<string, ReturnType<typeof setTimeout>>()
+
+  function armIdleTimer(sid: string, session: SseSession): void {
+    clearTimeout(idleTimers.get(sid))
+    if (sessionIdleMs <= 0) return
+    const t = setTimeout(() => {
+      if (debug) console.warn(`sse: session ${sid.slice(0, 8)}… idle ${sessionIdleMs}ms → close`)
+      try { session.terminate() } catch {}
+    }, sessionIdleMs)
+    t.unref?.()
+    idleTimers.set(sid, t)
+  }
+
+  function dropSession(sid: string): void {
+    sessions.delete(sid)
+    const t = idleTimers.get(sid)
+    if (t) clearTimeout(t)
+    idleTimers.delete(sid)
+  }
+
+  function writeSseHeaders(res: ServerResponse): void {
+    // `no-store` keeps stale event copies out of intermediate caches;
+    // `x-accel-buffering: no` is the nginx-specific opt-out from
+    // response buffering (without it nginx queues up to its
+    // `proxy_buffer_size` of events before flushing, breaking the
+    // realtime contract).
+    res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-cache, no-store, no-transform',
+      'connection': 'keep-alive',
+      'x-accel-buffering': 'no',
+    })
+    // Retry hint for any auto-reconnect machinery on the client side.
+    // The production client (client/sync/sse-transport.ts) does its own
+    // reconnect via the outer socket-transport loop, so this is just
+    // defence in depth.
+    res.write('retry: 1000\n\n')
+  }
+
+  function createSession(res: ServerResponse, req: HttpRequest): { sid: string; session: SseSession } | null {
+    if (sessions.size >= maxSessions) {
+      if (debug) console.warn(`sse: refused open — sessions ${sessions.size} >= ${maxSessions}`)
+      return null
+    }
+    writeSseHeaders(res)
+    const sid = randomId()
+    const session = new SseSession(res)
+    sessions.set(sid, session)
+    armIdleTimer(sid, session)
+    session.on('close', () => { dropSession(sid) })
+    // Announce the continuation token BEFORE the dispatcher emits its
+    // `challenge` frame so the client latches the id first and the
+    // protocol-level challenge lands on a stream the client is already
+    // tracking. Both ride the same response — order is a wire-shape
+    // nicety, not a correctness requirement (events are independent).
+    session.writeEvent('session', sid)
+    // Hand the session to the shared WS connection setup so it joins
+    // the same Peer / dispatcher / hub lifecycle as a real WebSocket.
+    // `setupPeerConnection` sends the protocol `challenge` frame as
+    // its first action; that re-uses the normal default-named SSE
+    // message channel.
+    setupPeerConnection(session as unknown as WebSocket, req, peerDeps)
+    return { sid, session }
+  }
+
+  // Drives a POST body's `password` and `frames` through the shared
+  // dispatcher. The dispatcher's `ping` / `authenticate` fast paths
+  // handle the trivial cases inline; everything else spawns a tracked
+  // handler. We synthesise one synthetic frame per inbound bit so the
+  // dispatcher reads identically whether it's reading WS frames or
+  // SSE POST batches.
+  function dispatchBody(session: SseSession, body: SseBody): void {
+    // Password → synthetic `authenticate` frame so the shared
+    // dispatcher's existing fast path runs unchanged. Client caches
+    // the password and re-sends on every POST, so the first POST
+    // after a session takeover re-authenticates silently on the new
+    // replica without an extra round-trip.
+    if (typeof body.password === 'string' && body.password.length > 0) {
+      const buf = Buffer.from(JSON.stringify({ type: 'authenticate', password: body.password }), 'utf8')
+      session.receiveMessage(buf)
+    }
+    if (Array.isArray(body.frames)) {
+      for (const frame of body.frames) {
+        if (!frame || typeof frame !== 'object') continue
+        const buf = Buffer.from(JSON.stringify(frame), 'utf8')
+        session.receiveMessage(buf)
+      }
+    }
+  }
+
+  function handlePost(req: HttpRequest, res: ServerResponse, sidFromUrl: string | null): void {
+    if (isShuttingDown()) {
+      res.writeHead(503, { 'content-type': 'application/json', 'connection': 'close' })
+      res.end(JSON.stringify({ error: 'shutting-down' }))
+      return
+    }
+    // Bound the body the same way `WebSocketServer({ maxPayload })`
+    // bounds a WS frame. Slurp into a single buffer rather than
+    // streaming — every protocol frame fits comfortably under
+    // `maxBodyBytes` (4 MiB) and the dispatcher takes one buffer at a
+    // time anyway. `content-length` may be missing on chunked-encoded
+    // requests; rely on the accumulating size check.
+    const chunks: Buffer[] = []
+    let total = 0
+    let aborted = false
+    req.on('data', (chunk: Buffer) => {
+      if (aborted) return
+      total += chunk.length
+      if (total > maxBodyBytes) {
+        aborted = true
+        if (debug) console.warn(`sse: POST body too large (${total} > ${maxBodyBytes})`)
+        res.writeHead(413, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ error: 'too-large' }))
+        try { req.destroy() } catch {}
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      if (aborted) return
+      // Re-check shutdown: the entry gate at handlePost runs at request
+      // arrival, but the body read is async — a slow upload that
+      // started pre-SIGTERM can fire 'end' AFTER the lifecycle's
+      // sseSessions() close-loop has already iterated, and createSession
+      // would otherwise add a NEW session post-iteration that only
+      // gets force-killed by the terminate-grace timer (no graceful
+      // event:close frame). Bail with 503 so the client distinguishes
+      // shutdown from a transport error and short-circuits backoff.
+      if (isShuttingDown()) {
+        res.writeHead(503, { 'content-type': 'application/json', 'connection': 'close' })
+        res.end(JSON.stringify({ error: 'shutting-down' }))
+        return
+      }
+      let body: SseBody = {}
+      if (chunks.length > 0) {
+        try {
+          const parsed: unknown = JSON.parse(Buffer.concat(chunks, total).toString('utf8'))
+          if (parsed && typeof parsed === 'object') body = parsed as SseBody
+        } catch (err) {
+          if (debug) console.warn('sse: malformed POST body:', errMsg(err))
+          res.writeHead(400, { 'content-type': 'application/json' })
+          res.end(JSON.stringify({ error: 'bad-json' }))
+          return
+        }
+      }
+      // Look up the session by id (if the client sent one). If found
+      // and alive, attach the new response and dispatch. If not (or
+      // session is closed), mint a fresh one — the response stream
+      // carries the new id as the first `session` event so the client
+      // switches over on the next POST.
+      //
+      // Attach-then-write ordering: attachResponse runs FIRST and only
+      // on success do we writeSseHeaders. If attachResponse returns
+      // false (today only when the session transitions out of OPEN
+      // between the lookup and the attach — a future backpressure /
+      // takeover-rate path could surface that legitimately) we fall
+      // through to createSession with `res` still header-virgin, so
+      // the new session can writeSseHeaders without ERR_HTTP_HEADERS_SENT.
+      let session: SseSession | null = null
+      let sid: string | null = null
+      if (sidFromUrl) {
+        const existing = sessions.get(sidFromUrl)
+        if (existing && existing.readyState === existing.OPEN && existing.attachResponse(res)) {
+          writeSseHeaders(res)
+          session = existing
+          sid = sidFromUrl
+          armIdleTimer(sid, session)
+        }
+      }
+      if (!session) {
+        const created = createSession(res, req)
+        if (!created) {
+          // Cap exceeded; createSession already logged. Response
+          // headers not yet written by writeSseHeaders, so send a
+          // 503 JSON instead.
+          res.writeHead(503, { 'content-type': 'application/json', 'connection': 'close' })
+          res.end(JSON.stringify({ error: 'too-many-sessions' }))
+          return
+        }
+        session = created.session
+        sid = created.sid
+      }
+      dispatchBody(session, body)
+      // Do NOT res.end() — the response stays open as the session's
+      // downstream channel until the next POST takes over (or the
+      // client disconnects).
+    })
+    req.on('error', (err) => {
+      if (debug) console.warn('sse: POST stream error:', errMsg(err))
+      if (res.headersSent) {
+        try { res.destroy() } catch {}
+      } else {
+        try { res.writeHead(400, { 'content-type': 'application/json' }).end(JSON.stringify({ error: 'bad-request' })) } catch {}
+      }
+    })
+  }
+
+  function handle(req: HttpRequest, res: ServerResponse): boolean {
+    if (typeof req.url !== 'string') return false
+    const [path, query] = req.url.split('?', 2)
+    if (path !== SSE_OPEN_PATH) return false
+    if (req.method !== 'POST') {
+      // `connection: close` so a probing client (e.g. accidental GET)
+      // can't pipeline N more 405s on the same keep-alive socket.
+      // Sibling 503 paths set this for the same reason.
+      res.writeHead(405, { 'content-type': 'application/json', 'allow': 'POST', 'connection': 'close' })
+      res.end(JSON.stringify({ error: 'method-not-allowed' }))
+      return true
+    }
+    const sid = parseSidQuery(query)
+    handlePost(req, res, sid)
+    return true
+  }
+
+  return { handle, sessions: () => sessions.values() }
+}
+
+// Bare-bones query parse for `id=<base64url>`. Avoids URLSearchParams
+// (which decodes percent-escapes) — `randomId()` mints a 22-char
+// base64url string, and the client echoes it back unchanged, so no
+// escapes are possible on the legitimate path. The {1,64} bound is a
+// deliberately lenient sanity gate: anything outside the base64url
+// alphabet is rejected (and a missing id is treated as "no id"); a
+// client that sent a sid this regex doesn't recognise just gets a
+// fresh session minted by createSession, no failure mode. The wide
+// length window means a future randomId-length change here doesn't
+// silently break old clients that round-trip a longer or shorter
+// token. Returns null on missing / malformed.
+function parseSidQuery(query: string | undefined): string | null {
+  if (typeof query !== 'string') return null
+  for (const part of query.split('&')) {
+    const eq = part.indexOf('=')
+    if (eq <= 0) continue
+    if (part.slice(0, eq) !== 'id') continue
+    const v = part.slice(eq + 1)
+    if (!/^[A-Za-z0-9_-]{1,64}$/u.test(v)) return null
+    return v
+  }
+  return null
+}

package/server/sse-session.ts

@@ -0,0 +1,202 @@
+// Per-connection state for the SSE+POST fallback. Each session pins to
+// the *latest* POST's response stream — the previous POST's response
+// is closed when a new POST takes over. This shape sidesteps sticky-
+// routing in multi-replica deployments: a POST that lands on a
+// replica that doesn't know the session id mints a fresh session with
+// a new id (returned via the first `session` event); the client then
+// continues against the new id with all subsequent POSTs. Subscriptions
+// and auth state ride re-sendable signed frames + a client-cached
+// password, so the new replica reconstructs locally.
+//
+// Mimics the subset of `ws.WebSocket` that `setupPeerConnection` (in
+// ./ws-server.ts), the hub (./hub.ts) and the lifecycle shutdown loop
+// (./lifecycle.ts) read: `readyState` + `OPEN`/`CLOSING` constants,
+// `send` / `close` / `terminate` / `ping`, the `bufferedAmount`
+// backpressure signal, and the `message` / `close` / `error` / `pong`
+// EventEmitter surface. The per-connection dispatcher is single-
+// sourced — it doesn't know whether it's talking to a real WebSocket
+// or this adapter.
+//
+// Wire shape: each outbound frame becomes a single SSE `data:` field.
+// The dispatcher emits JSON via `JSON.stringify` (no embedded newlines
+// after that round-trip), so a single-line `data:` is enough; we still
+// split-on-newline defensively for any future caller that hands raw
+// multi-line text. Inbound frames are injected via `receiveMessage`
+// after the POST plane reads the body.
+
+import { EventEmitter } from 'node:events'
+import type { Buffer } from 'node:buffer'
+import type { ServerResponse } from 'node:http'
+
+export class SseSession extends EventEmitter {
+  static readonly CONNECTING = 0
+  static readonly OPEN = 1
+  static readonly CLOSING = 2
+  static readonly CLOSED = 3
+  // Per-instance constants so `socket.OPEN` reads identically to the
+  // `ws.WebSocket` shape the dispatcher and hub strict-compare against.
+  readonly CONNECTING = SseSession.CONNECTING
+  readonly OPEN = SseSession.OPEN
+  readonly CLOSING = SseSession.CLOSING
+  readonly CLOSED = SseSession.CLOSED
+
+  readyState: number = SseSession.OPEN
+  // The current downstream stream the session writes to. Each POST
+  // replaces this; broadcasts and ack frames flow on the latest one.
+  // Null between POSTs is *only* a transient state during swap — the
+  // session is created with a response in hand and the swap is
+  // synchronous from the dispatcher's perspective.
+  private currentRes: ServerResponse | null
+
+  constructor(res: ServerResponse) {
+    super()
+    this.currentRes = res
+    this.wireResponse(res)
+  }
+
+  // Wire the close / error events on a freshly-attached response. The
+  // close event only matters for the *current* response — a previous
+  // response's close (after it was swapped out) is not a session-level
+  // signal. Same guard applies to error: a TCP-level error during
+  // res.end() flush on a swapped-out response would otherwise emit a
+  // spurious session 'error' that operators read as a real transport
+  // failure on a healthy session.
+  private wireResponse(res: ServerResponse): void {
+    res.on('close', () => {
+      // Only the *current* response's close terminates the session. A
+      // swapped-out previous response closes naturally during takeover
+      // and must not knock the session offline.
+      if (res !== this.currentRes) return
+      if (this.readyState === SseSession.CLOSED) return
+      this.readyState = SseSession.CLOSED
+      this.currentRes = null
+      this.emit('close')
+    })
+    res.on('error', (err: Error) => {
+      // Same identity guard as close: drained-out previous responses
+      // may emit RST/EPIPE during flush and we don't want those to
+      // pseudo-fail the healthy session that's now on a new response.
+      if (res !== this.currentRes) return
+      this.emit('error', err)
+    })
+  }
+
+  // Swap in a new response (the latest POST's body). The previous
+  // response is end()ed cleanly so the client's reader sees EOF and
+  // stops draining; the takeover-grace handling for in-flight buffered
+  // bytes is on the client side (it keeps reading the old stream until
+  // EOF before switching). Returns true when the session was alive and
+  // the swap happened; false when the session is closed and the new
+  // response should be ended by the caller.
+  attachResponse(res: ServerResponse): boolean {
+    if (this.readyState !== SseSession.OPEN) return false
+    const prev = this.currentRes
+    this.currentRes = res
+    this.wireResponse(res)
+    // End the previous stream AFTER the new one is wired so any
+    // broadcast racing the swap lands on the new response, not on the
+    // half-closed old one. `end()` flushes Node's send buffer before
+    // sending FIN — frames already written drain to the client.
+    if (prev) { try { prev.end() } catch {} }
+    return true
+  }
+
+  // `hub.sendRaw` consults this before each send to decide whether to
+  // terminate (slow / blackholed peer). `writableLength` is the count
+  // of bytes queued in Node's HTTP stream that haven't drained to the
+  // kernel yet — the SSE-channel equivalent of `ws`'s `bufferedAmount`.
+  get bufferedAmount(): number {
+    return this.currentRes?.writableLength ?? 0
+  }
+
+  // Encodes one JSON frame as a single SSE event. Splits on `\n` so a
+  // multi-line payload still produces a well-formed event (each `data:`
+  // line is concatenated with `\n` by the SSE parser on the client),
+  // but `JSON.stringify` output won't trigger that branch.
+  send(payload: string | Buffer): void {
+    if (this.readyState !== SseSession.OPEN) return
+    const res = this.currentRes
+    if (!res) return
+    const text = typeof payload === 'string' ? payload : payload.toString('utf8')
+    const lines = text.split('\n')
+    const wire = `${lines.map((l) => `data: ${l}`).join('\n')}\n\n`
+    try { res.write(wire) } catch {}
+  }
+
+  // Writes a named SSE event (e.g. `session` for the continuation token
+  // handshake). Used by sse-server.ts on session creation; not part of
+  // the WebSocket-shaped surface and never called by the shared
+  // dispatcher.
+  writeEvent(event: string, data: string): void {
+    if (this.readyState !== SseSession.OPEN) return
+    const res = this.currentRes
+    if (!res) return
+    const lines = data.split('\n')
+    const body = `${lines.map((l) => `data: ${l}`).join('\n')}`
+    try { res.write(`event: ${event}\n${body}\n\n`) } catch {}
+  }
+
+  // Lifecycle's graceful-shutdown loop calls this with `(1001, '…')` to
+  // signal a server-initiated close. SSE has no native close code, so
+  // we emit a structured `close` event with the WS-style `{ code,
+  // reason }` payload — the client's transport reads it and bypasses
+  // its reconnect backoff (parity with the WS 1001 path).
+  //
+  // emit('close') is fired EXPLICITLY here, not via the res.on('close')
+  // listener: that listener short-circuits on `readyState === CLOSED`
+  // (so a later async res-close after we've flipped state doesn't
+  // double-emit), which means without the explicit emit here neither
+  // sse-server's dropSession cleanup nor setupPeerConnection's
+  // unsubscribeAll/peers.delete would run on any server-initiated
+  // teardown — sessions / hub.subscribers / idleTimers would leak per
+  // close. The wireResponse guard then ensures the later async fire
+  // is a no-op.
+  close(code?: number, reason?: string): void {
+    if (this.readyState === SseSession.CLOSED) return
+    const res = this.currentRes
+    if (this.readyState === SseSession.OPEN && code != null && res) {
+      try { res.write(`event: close\ndata: ${JSON.stringify({ code, reason: reason ?? '' })}\n\n`) } catch {}
+    }
+    this.readyState = SseSession.CLOSING
+    if (res) { try { res.end() } catch {} }
+    this.currentRes = null
+    this.readyState = SseSession.CLOSED
+    this.emit('close')
+  }
+
+  // Force-tear without flushing — mirrors `ws.terminate()`. Hub's
+  // backpressure path and the lifecycle's terminate-grace timer call
+  // this to drop unresponsive peers. Same explicit `emit('close')`
+  // story as close() above — without it, the wireResponse guard would
+  // swallow the later async res-close and the cleanup callbacks
+  // (dropSession, peers.delete, unsubscribeAll) would never run.
+  terminate(): void {
+    if (this.readyState === SseSession.CLOSED) return
+    this.readyState = SseSession.CLOSED
+    const res = this.currentRes
+    this.currentRes = null
+    if (res) { try { res.destroy() } catch {} }
+    this.emit('close')
+  }
+
+  // The heartbeat sweep ping()s every WS client to detect dead sockets
+  // via the unanswered-pong path. SSE has no `pong` equivalent, so we
+  // write a comment line that keeps the channel alive across proxies
+  // without expecting a reply. The per-session idle timeout in
+  // sse-server.ts owns the dead-client detection.
+  ping(): void {
+    if (this.readyState !== SseSession.OPEN) return
+    const res = this.currentRes
+    if (!res) return
+    try { res.write(':\n\n') } catch {}
+  }
+
+  // Injects a client-to-server frame from the POST plane into the same
+  // `message` event the dispatcher already listens for on real WSs.
+  // `isBinary=false` because the SSE+POST plane is JSON-only by
+  // contract — the binary-frame drop in the dispatcher reads this.
+  receiveMessage(data: Buffer): void {
+    if (this.readyState !== SseSession.OPEN) return
+    this.emit('message', data, false)
+  }
+}

package/server/sync-handlers.ts

@@ -29,6 +29,13 @@ export type SyncHandlersDeps = {
   handle: Handle
   send: (socket: WebSocket, msg: object) => void
   broadcast: (tag: string, msg: object, except: WebSocket | null) => void
+  // Cross-instance pub/sub for live broadcasts. Fired alongside the
+  // local `broadcast` after a successful commit so peers on OTHER
+  // server instances see the new revision in real time. Carries only
+  // `(tag, revisionId)` — the receiver re-fetches the row from
+  // workspace_revision because the ciphertext can exceed the bus's
+  // payload budget. Optional: a SQLite deployment passes a no-op.
+  publishRevision: (tag: string, revisionId: string) => void
   subscribe: (socket: WebSocket, tag: string) => void
   getNonce: (socket: WebSocket) => string | undefined
   requiresAuth: (socket: WebSocket) => boolean
@@ -53,7 +60,7 @@ export type SyncHandlers = {
 }
 
 export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
-  const { handle, send, broadcast, subscribe, getNonce, requiresAuth, sendUnauthorized, workspaceExists, objstoreResources, debug } = deps
+  const { handle, send, broadcast, publishRevision, subscribe, getNonce, requiresAuth, sendUnauthorized, workspaceExists, objstoreResources, debug } = deps
 
   // Typed wrapper for the three `workspace-save-error` emit sites
   // (too-large at handleSave, stale-base after the catch-up, busy at
@@ -242,6 +249,15 @@ export function createSyncHandlers(deps: SyncHandlersDeps): SyncHandlers {
         signature: msg.signature,
       }],
     }, socket)
+    // Cross-instance fan-out. The bus payload carries only the revision
+    // id — peers on OTHER instances re-fetch the row from
+    // workspace_revision to compose their local `workspace-state`. Sized
+    // for the bus's 8 KB payload budget, which can't carry a 2 MiB
+    // ciphertext. SQLite mode passes a no-op; Neon mode publishes via
+    // pg_notify. Best-effort: a dropped publish only means peers on
+    // other instances miss the live push, but they still catch up via
+    // the shared DB on their next subscribe / reconnect.
+    publishRevision(tag, id)
   }
 
   async function handleSubscribe(socket: WebSocket, msg: SubscribeMsg): Promise<void> {