@ultimat3/realtime 1.2.0 → 3.0.0

package/src/subscription-book.ts

@@ -0,0 +1,237 @@
+// Who holds which subscription, and the composite identity that makes that answerable. A `sid`
+// is CLIENT data — unique only to the socket that chose it — so every lookup here takes the
+// owner too, and the per-socket and per-tenant caps are answered from this book because it is
+// the only thing that knows what exists. Every question it answers is indexed, never scanned.
+
+import type { Actor } from '@ultimat3/core';
+import { SubscriptionIdTakenError, SubscriptionLimitError } from './errors';
+import type { LiveSubscription } from './live-contract';
+import type { SyncSocket } from './socket';
+
+/**
+ * A slot taken synchronously at the top of `subscribe` and given back when it has either become a
+ * subscription or failed. It exists because every cap here is answered from what the book HOLDS,
+ * and a subscribe does not hold anything until three awaits later: one WebSocket write carrying N
+ * subscribe frames is dispatched concurrently, so N of them read `size === 0` and every cap is
+ * bypassed by batching. Releasing twice is a no-op — the caller's `finally` runs once per path.
+ */
+export interface SubscriptionSlot {
+  release(): void;
+}
+
+/**
+ * The identity of one subscription. `\u0000` because a socket id and a sid are both opaque
+ * strings and nothing else can appear in one, so no pair of them can collide with another.
+ */
+export function subscriptionKey(socketId: string, sid: string): string {
+  return `${socketId}\u0000${sid}`;
+}
+
+export interface SubscriptionCaps {
+  readonly maxPerSocket?: number;
+  readonly maxPerTenant?: number;
+  readonly tenantOf?: (actor: Actor | null) => string | null;
+}
+
+/** Sockets may open this many live queries before `X_SUBSCRIPTION_LIMIT`. */
+export const DEFAULT_MAX_PER_SOCKET = 128;
+
+/**
+ * Every live subscription on this node, keyed by `(socket, sid)`.
+ *
+ * Keyed by the sid alone, socket B reusing socket A's sid overwrote A's entry — A's subscription
+ * stayed in its query entry's `subscribers` map, unreachable, so `unsubscribeSocket(A)` freed
+ * nothing and that entry's matcher and shared window were pinned for the process's life, fanning
+ * every change out to a dead socket. A `drop` frame from B likewise ended A's stream with no
+ * error either side.
+ *
+ * **Two secondary indexes, because both of this book's sweeps run once per socket.** `ofSocket`
+ * copied the node's whole map and filtered it, so a teardown or a re-auth pass cost
+ * `sockets x subscriptions` — 100,000 entries measured at 17.7s of blocking work, with no
+ * attacker capability required: a deploy, a network blip or a batch of grants expiring together
+ * is the trigger. The per-tenant cap walked the same map on every subscribe FRAME (7.96 ms each
+ * at that size), which is one authenticated socket consuming the node. Both are `Map` reads now,
+ * maintained in `add`/`delete` — the shape `lru.ts` and `presence.ts` already use.
+ */
+export class SubscriptionBook {
+  readonly #bySid = new Map<string, LiveSubscription>();
+  /** socket id -> its sids. The drop list on close, the retry list on re-auth. */
+  readonly #bySocket = new Map<string, Set<string>>();
+  /** tenant -> live subscriptions held by its sockets. The per-tenant cap's whole answer. */
+  readonly #perTenant = new Map<string, number>();
+  /**
+   * The tenant each socket's subscriptions were counted under. Remembered rather than re-derived,
+   * because `socket.actor` is replaced by a re-auth: deriving it again at `delete` time would
+   * decrement a tenant that was never incremented and leave the old one counting forever.
+   */
+  readonly #tenantOfSocket = new Map<string, string>();
+  /** sids a socket has claimed but not yet attached. Empty between subscribes, so it never grows. */
+  readonly #claimedBySocket = new Map<string, Set<string>>();
+  /** The same claims counted per tenant, because that cap spans sockets and a lane cannot see it. */
+  readonly #claimedPerTenant = new Map<string, number>();
+  readonly #caps: SubscriptionCaps;
+
+  constructor(caps: SubscriptionCaps = {}) {
+    this.#caps = caps;
+  }
+
+  get(socketId: string, sid: string): LiveSubscription | undefined {
+    return this.#bySid.get(subscriptionKey(socketId, sid));
+  }
+
+  has(socketId: string, sid: string): boolean {
+    return this.#bySid.has(subscriptionKey(socketId, sid));
+  }
+
+  add(subscription: LiveSubscription): void {
+    const socketId = subscription.socket.id;
+    const key = subscriptionKey(socketId, subscription.sid);
+    // A re-add is the one thing that could double-count a tenant, so it is refused here rather
+    // than relied on not to happen: `subscribe` already answers `X_SUBSCRIPTION_ID_TAKEN`.
+    if (this.#bySid.has(key)) return;
+    this.#bySid.set(key, subscription);
+    const sids = this.#bySocket.get(socketId);
+    if (sids) sids.add(subscription.sid);
+    else this.#bySocket.set(socketId, new Set([subscription.sid]));
+    const tenant = this.#tenantFor(subscription.socket);
+    if (tenant === null) return;
+    this.#tenantOfSocket.set(socketId, tenant);
+    this.#perTenant.set(tenant, (this.#perTenant.get(tenant) ?? 0) + 1);
+  }
+
+  delete(socketId: string, sid: string): void {
+    if (!this.#bySid.delete(subscriptionKey(socketId, sid))) return;
+    const sids = this.#bySocket.get(socketId);
+    sids?.delete(sid);
+    const empty = sids === undefined || sids.size === 0;
+    if (empty) this.#bySocket.delete(socketId);
+    const tenant = this.#tenantOfSocket.get(socketId);
+    if (tenant === undefined) return;
+    this.#bump(tenant, -1);
+    if (empty) this.#tenantOfSocket.delete(socketId);
+  }
+
+  /** A copy, because every caller mutates the book while walking it. */
+  all(): readonly LiveSubscription[] {
+    return [...this.#bySid.values()];
+  }
+
+  /** One socket's subscriptions — the drop list when it closes, the retry list when it reauths. */
+  ofSocket(socketId: string): readonly LiveSubscription[] {
+    const sids = this.#bySocket.get(socketId);
+    if (!sids) return [];
+    const out: LiveSubscription[] = [];
+    for (const sid of sids) {
+      const subscription = this.#bySid.get(subscriptionKey(socketId, sid));
+      if (subscription) out.push(subscription);
+    }
+    return out;
+  }
+
+  /** Live subscriptions counted against one tenant. The metric the cap reads. */
+  tenantCount(tenant: string): number {
+    return this.#perTenant.get(tenant) ?? 0;
+  }
+
+  /**
+   * A re-auth moved this socket to another tenant, so its subscriptions move with it. Without
+   * this the count the cap reads drifts from the book for the rest of the process — one tenant
+   * refused for subscriptions it does not hold, another admitted past its cap.
+   */
+  retenant(socket: SyncSocket): void {
+    const held = this.#bySocket.get(socket.id)?.size ?? 0;
+    const before = this.#tenantOfSocket.get(socket.id) ?? null;
+    const after = this.#caps.tenantOf?.(socket.actor) ?? null;
+    if (before === after) return;
+    if (before !== null) this.#bump(before, -held);
+    if (after === null) this.#tenantOfSocket.delete(socket.id);
+    else {
+      this.#tenantOfSocket.set(socket.id, after);
+      if (held > 0) this.#perTenant.set(after, (this.#perTenant.get(after) ?? 0) + held);
+    }
+  }
+
+  /**
+   * Refuse a subscribe that would exceed a cap. Load shedding, not a crash: both scopes throw
+   * `X_SUBSCRIPTION_LIMIT` naming which one refused, so the fix line points at one knob.
+   *
+   * Claims count, because the thing being bounded is work that starts before it is held: a
+   * subscribe that has passed this check and is awaiting its snapshot has already committed this
+   * node to an entry, a matcher and a read.
+   */
+  assertCapacity(socket: SyncSocket): void {
+    const perSocket = this.#caps.maxPerSocket ?? DEFAULT_MAX_PER_SOCKET;
+    const claimed = this.#claimedBySocket.get(socket.id)?.size ?? 0;
+    if (socket.queries.size + claimed >= perSocket) {
+      throw new SubscriptionLimitError({
+        scope: 'socket',
+        id: socket.id,
+        limit: perSocket,
+        knob: 'maxPerSocket',
+      });
+    }
+    const perTenant = this.#caps.maxPerTenant;
+    const tenant = this.#tenantFor(socket);
+    if (perTenant === undefined || tenant === null) return;
+    if (this.tenantCount(tenant) + (this.#claimedPerTenant.get(tenant) ?? 0) >= perTenant) {
+      throw new SubscriptionLimitError({
+        scope: 'tenant',
+        id: tenant,
+        limit: perTenant,
+        knob: 'maxPerTenant',
+      });
+    }
+  }
+
+  /**
+   * Take the slot this subscribe is going to fill — the sid and the two caps — before it awaits
+   * anything. Every refusal a subscribe can answer with is decided here, in one synchronous step,
+   * so N frames arriving in one write are N decisions against a count that already includes the
+   * ones still in flight.
+   *
+   * The sid is claimed here for the same reason: keyed by `(socket, sid)`, two concurrent frames
+   * reusing one sid both passed `has()` and the second attach replaced the first, stranding it
+   * inside its query entry where nothing can reach it again. The tenant is captured rather than
+   * re-derived — a re-auth may `retenant` this socket while the read is in flight, and the release
+   * has to give the slot back to the tenant that took it.
+   */
+  reserve(socket: SyncSocket, sid: string): SubscriptionSlot {
+    const socketId = socket.id;
+    if (this.has(socketId, sid) || this.#claimedBySocket.get(socketId)?.has(sid) === true) {
+      throw new SubscriptionIdTakenError({ sid, socketId });
+    }
+    this.assertCapacity(socket);
+    const claims = this.#claimedBySocket.get(socketId);
+    if (claims) claims.add(sid);
+    else this.#claimedBySocket.set(socketId, new Set([sid]));
+    const tenant = this.#tenantFor(socket);
+    if (tenant !== null) {
+      this.#claimedPerTenant.set(tenant, (this.#claimedPerTenant.get(tenant) ?? 0) + 1);
+    }
+    let released = false;
+    return {
+      release: (): void => {
+        if (released) return;
+        released = true;
+        const held = this.#claimedBySocket.get(socketId);
+        held?.delete(sid);
+        if (held !== undefined && held.size === 0) this.#claimedBySocket.delete(socketId);
+        if (tenant === null) return;
+        const next = (this.#claimedPerTenant.get(tenant) ?? 0) - 1;
+        if (next > 0) this.#claimedPerTenant.set(tenant, next);
+        else this.#claimedPerTenant.delete(tenant);
+      },
+    };
+  }
+
+  /** The tenant this socket's subscriptions are counted under: the remembered one, or the actor's. */
+  #tenantFor(socket: SyncSocket): string | null {
+    return this.#tenantOfSocket.get(socket.id) ?? this.#caps.tenantOf?.(socket.actor) ?? null;
+  }
+
+  #bump(tenant: string, by: number): void {
+    const next = (this.#perTenant.get(tenant) ?? 0) + by;
+    if (next > 0) this.#perTenant.set(tenant, next);
+    else this.#perTenant.delete(tenant);
+  }
+}

package/src/sync-auth.ts

@@ -0,0 +1,124 @@
+// Who a socket is, and for how long. The `sync` node evaluates no credential of its own — an app
+// supplies `authenticate`, exactly as it supplies `onMutate` — so this file owns the shape of that
+// answer, the per-node book that holds it, and the pass that re-decides one whose window has closed.
+
+import type { Actor, Clock } from '@ultimat3/core';
+
+/**
+ * One connection's identity. A grant, not an `Actor`, because a websocket outlives every credential
+ * that opened it: a token with a 15-minute TTL on a socket that stays up for hours is a subscription
+ * authorized once and served forever, which is the hole `expiresAt` closes.
+ *
+ * `refresh` is the app's, and the framework retains no credential of its own for it. That is the
+ * whole reason the seam is a closure: re-reading the upgrade `Request` would mean holding one per
+ * socket for the life of the connection, and an app that closes over a token string holds the two
+ * fields it actually needs. Omit it and an expired grant simply closes the socket — the client
+ * re-dials with a fresh credential, which is the safe default and costs one reconnect.
+ */
+export interface SyncGrant {
+  readonly actor: Actor;
+  /** Epoch ms this grant stops being true. Omitted = never re-decided on a clock. */
+  readonly expiresAt?: number;
+  /** Re-resolve this connection without a reconnect. `null` means the actor is gone. */
+  refresh?: () => Promise<SyncGrant | null>;
+}
+
+/**
+ * The app's answer to "who is dialling". Called once per upgrade, before `server.upgrade`, so a
+ * refused credential never costs a websocket. `null` is a decision (nobody may open this socket);
+ * a throw is a failure (nothing was decided) — the node answers those differently, because reading
+ * an auth backend timeout as a denial is the same class of bug as reading a dead pool as a row
+ * policy refusing a row.
+ */
+export type SyncAuthenticator = (request: Request) => Promise<SyncGrant | null>;
+
+/**
+ * The grants of the sockets on this node, keyed by socket id.
+ *
+ * Off `SyncSocket` on purpose: that object's budget is ~1KB per connection and it is the only
+ * per-socket allocation a million-socket node is costed against, so an auth lifetime — a closure,
+ * an expiry and an actor — lives beside the socket table instead of inside it. Empty, and costing
+ * nothing, on a node with no authenticator.
+ */
+export class GrantBook {
+  readonly #grants = new Map<string, SyncGrant>();
+
+  set(socketId: string, grant: SyncGrant): void {
+    this.#grants.set(socketId, grant);
+  }
+
+  get(socketId: string): SyncGrant | undefined {
+    return this.#grants.get(socketId);
+  }
+
+  delete(socketId: string): void {
+    this.#grants.delete(socketId);
+  }
+
+  get size(): number {
+    return this.#grants.size;
+  }
+
+  /** Grants whose window has closed. One with no `expiresAt` never appears here. */
+  expired(now: number): readonly (readonly [string, SyncGrant])[] {
+    const out: (readonly [string, SyncGrant])[] = [];
+    for (const [socketId, grant] of this.#grants) {
+      if (grant.expiresAt !== undefined && grant.expiresAt <= now) out.push([socketId, grant]);
+    }
+    return out;
+  }
+}
+
+export interface GrantSweepDeps {
+  readonly grants: GrantBook;
+  readonly clock: Clock;
+  /** The grant was renewed: re-decide every subscription this socket holds, under the new actor. */
+  onActor: (socketId: string, actor: Actor) => Promise<void>;
+  /** Nobody may hold this socket any longer. The caller closes it. */
+  onRevoked: (socketId: string) => void;
+  /** `refresh` raised instead of deciding. The grant is kept and retried on the next pass. */
+  onRefreshFailed?: (socketId: string, error: unknown) => void;
+}
+
+export interface GrantSweepResult {
+  readonly refreshed: number;
+  readonly revoked: number;
+  readonly failed: number;
+}
+
+/**
+ * One pass over the expired grants. The clock is injected because a re-auth only provable by
+ * sleeping is a re-auth no test proves — the same rule the client's reconnect timer already follows.
+ *
+ * A `refresh` that raises keeps its grant: a denial and a failure never share an answer here either,
+ * and signing every connected user out because the auth backend timed out is a bigger outage than
+ * the one it would be responding to. It stays expired, so the next pass retries it — and every
+ * failure is reported, because a socket that cannot be re-decided is not a socket anyone should
+ * discover from a graph of connection counts.
+ */
+export async function sweepGrants(deps: GrantSweepDeps): Promise<GrantSweepResult> {
+  const now = deps.clock.now().getTime();
+  let refreshed = 0;
+  let revoked = 0;
+  let failed = 0;
+  for (const [socketId, grant] of deps.grants.expired(now)) {
+    let next: SyncGrant | null;
+    try {
+      next = grant.refresh ? await grant.refresh() : null;
+    } catch (error) {
+      failed += 1;
+      deps.onRefreshFailed?.(socketId, error);
+      continue;
+    }
+    if (next === null) {
+      deps.grants.delete(socketId);
+      deps.onRevoked(socketId);
+      revoked += 1;
+      continue;
+    }
+    deps.grants.set(socketId, next);
+    await deps.onActor(socketId, next.actor);
+    refreshed += 1;
+  }
+  return { refreshed, revoked, failed };
+}

package/src/sync-frames.ts

@@ -0,0 +1,185 @@
+// What a RECEIVED frame does to server state — the mirror of `client-frames.ts`, and the only
+// inbound surface the `sync` node exposes. Every dependency is injected, so the router is
+// exercisable without a socket, a bus or a server.
+
+import type { ChannelHub } from './channel';
+import { topic as makeTopic } from './channel';
+import { FrameRateLimitError } from './errors';
+import { FrameLanes, laneKeyOf } from './frame-lanes';
+import type { JsonValue, Row } from './json';
+import type { LiveQueryRegistry } from './live-query';
+import { type PresenceRegistry, presenceFrame } from './presence';
+import type { SyncSocket } from './socket';
+import { type Frame, PROTOCOL_VERSION, toWireError } from './sync-protocol';
+
+/** Server-authoritative mutation execution. Injected: `sync` never owns business logic. */
+export type MutationHandler = (args: {
+  socket: SyncSocket;
+  name: string;
+  key: string;
+  seq: number;
+  input: JsonValue;
+}) => Promise<{ lsn?: string | null; entity?: string; row?: Row | null }>;
+
+export interface FrameRouterOptions {
+  readonly hub: ChannelHub;
+  readonly registry: LiveQueryRegistry;
+  readonly buildId: string;
+  readonly presence?: PresenceRegistry | undefined;
+  readonly onMutate?: MutationHandler | undefined;
+}
+
+export type FrameRouter = (socket: SyncSocket, frame: Frame) => Promise<void>;
+
+/**
+ * What a failure ack refers to. `ack.ref` is how a client finds the thing that failed —
+ * `queue.fail(frame.ref)` looks up a mutation by its idempotency key — so an ack built with the
+ * SOCKET id names a key no queue can hold and the whole rollback path is inert end to end: the
+ * optimistic write stays on screen and the mutation stays queued.
+ *
+ * The socket id is the answer for a frame nothing could read (a decode failure) and for the kinds
+ * that carry no reference of their own, because there is nothing else true to say.
+ */
+export function ackRefOf(frame: Frame | null, socketId: string): string {
+  if (frame === null) return socketId;
+  if (frame.type === 'mutate') return frame.key;
+  if (frame.type === 'subscribe') return frame.sid;
+  return socketId;
+}
+
+export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
+  const presence = options.presence;
+  // Weakly keyed, so one socket's lanes die with it and no close path has to remember them.
+  const lanes = new WeakMap<SyncSocket, FrameLanes>();
+
+  const routeFrame: FrameRouter = async (socket, frame) => {
+    // Before `touch()` and before every amplifier below it: a frame this node refuses to route
+    // must not also renew the idle window that would otherwise close a flooding socket.
+    if (!socket.frameBudget.tryAccept()) {
+      throw new FrameRateLimitError({
+        socketId: socket.id,
+        perSecond: socket.frameBudget.perSecond,
+      });
+    }
+    socket.touch();
+    const key = laneKeyOf(frame);
+    if (key === null) return await apply(socket, frame);
+    // Entered synchronously — an `async` body runs to its first await on the call — so the lane
+    // order is the order `sync-node.message` was called in, which is the order the bytes arrived.
+    const lane = lanes.get(socket) ?? new FrameLanes();
+    lanes.set(socket, lane);
+    return await lane.run(key, () => apply(socket, frame));
+  };
+  return routeFrame;
+
+  async function apply(socket: SyncSocket, frame: Frame): Promise<void> {
+    switch (frame.type) {
+      case 'hello': {
+        socket.send({
+          type: 'hello',
+          v: PROTOCOL_VERSION,
+          buildId: options.buildId,
+          sessionId: socket.id,
+          // The actor the upgrade resolved, so a client can render who the server thinks it is
+          // rather than who it thinks it sent.
+          actorId: socket.actorId,
+        });
+        if (socket.skewed) {
+          socket.send({ type: 'update-available', v: PROTOCOL_VERSION, buildId: options.buildId });
+        }
+        return;
+      }
+      case 'subscribe': {
+        if (frame.target.kind === 'topic') {
+          const name = makeTopic(...frame.target.topic.split('.'));
+          if (frame.op === 'drop') {
+            options.hub.unsubscribe(socket, name);
+            if (presence) await presence.leave(name, socket.id);
+            return;
+          }
+          await options.hub.subscribe(socket, name);
+          // Subscribing to a topic IS joining its presence set: presence has no frame of its own,
+          // so a second round trip saying "and I am here" would be a second way to do one thing,
+          // and a client that skipped it would be invisible in a room it is receiving from.
+          // Repeating the frame is therefore also the heartbeat — `join` re-`put`s the member.
+          if (presence) {
+            const roster = await presence.join(name, { id: socket.id, actorId: socket.actorId });
+            socket.send(presenceFrame(name, 'sync', roster.members, roster.total));
+          }
+          return;
+        }
+        if (frame.op === 'drop') {
+          // Scoped to this socket: a sid is client data, and an unscoped drop let one client
+          // end another's live stream by guessing — or reusing — its id.
+          options.registry.unsubscribe(socket.id, frame.sid);
+          return;
+        }
+        const { frame: reply } = await options.registry.subscribe({
+          socket,
+          name: frame.target.qid,
+          input: frame.target.input,
+          sid: frame.sid,
+          cursor: frame.target.cursor,
+        });
+        socket.send(reply);
+        return;
+      }
+      case 'mutate': {
+        if (!options.onMutate) {
+          socket.send({
+            type: 'ack',
+            v: PROTOCOL_VERSION,
+            ref: frame.key,
+            lsn: null,
+            error: toWireError({
+              code: 'X_NOT_IMPLEMENTED',
+              cause: 'this sync node was started without a mutation handler',
+              fix: 'pass onMutate to createSyncNode({ onMutate })',
+            }),
+          });
+          return;
+        }
+        const result = await options.onMutate({
+          socket,
+          name: frame.name,
+          key: frame.key,
+          seq: frame.seq,
+          input: frame.input,
+        });
+        // The rebase FIRST, and the ack last. The ack is the receipt, and a receipt is what
+        // retires the client's record of the mutation — its journal row and its rebase-log entry,
+        // both of which stay forever otherwise. A rebase that lands after that has no entry left
+        // to read the mutator's conflict strategy off (every merge silently becomes server-wins)
+        // and no sequence to decide which later optimistic writes to replay over server truth.
+        // These are two frames on one socket, so the order is the only coordination there is.
+        if (result.entity !== undefined) {
+          socket.send({
+            type: 'rebase',
+            v: PROTOCOL_VERSION,
+            key: frame.key,
+            entity: result.entity,
+            strategy: 'server-wins',
+            row: result.row ?? null,
+          });
+        }
+        socket.send({
+          type: 'ack',
+          v: PROTOCOL_VERSION,
+          ref: frame.key,
+          lsn: result.lsn ?? null,
+          error: null,
+        });
+        return;
+      }
+      // Server-authored frames are never received from a client.
+      case 'snapshot':
+      case 'patch':
+      case 'ack':
+      case 'rebase':
+      case 'presence':
+      case 'reconnect':
+      case 'update-available':
+        return;
+    }
+  }
+}

package/src/sync-listen.ts

@@ -0,0 +1,73 @@
+// Binding a `sync` node to a real socket, and to the process lifecycle. Kept out of `sync-node.ts`
+// so the node itself stays testable with no server: this file is the only place realtime calls
+// `Bun.serve`, and the only thing in the package that knows a port exists.
+
+import { markListening, onShutdown } from '@ultimat3/core';
+import type { SyncNode } from './sync-node';
+
+export interface ListenOptions {
+  readonly port?: number;
+}
+
+export interface SyncListener {
+  /** The bound websocket origin, e.g. `ws://localhost:3001`. With `port: 0` only the OS knows it. */
+  readonly url: string;
+  stop(): void;
+}
+
+/**
+ * Binds the node to `Bun.serve` and wires SIGTERM to `drain()`. Kept tiny so the node itself stays
+ * testable without a server.
+ */
+export function listenSyncNode(node: SyncNode, options: ListenOptions = {}): SyncListener {
+  const server = Bun.serve({
+    port: options.port ?? 3001,
+    fetch: node.fetch,
+    websocket: node.websocket,
+  });
+  // Same rule as @ultimat3/http: every socket the framework opens announces itself, so a request
+  // back to it is recognisably this process calling itself rather than egress.
+  const stopListening = markListening(server.url.origin);
+  // Two phases, because they answer two different questions. `accept` runs first on SIGTERM: the
+  // node stops taking new sockets and `/readyz` flips to 503, so the load balancer routes away
+  // while every socket this node already holds keeps its patch stream — registered with no phase,
+  // this landed in `close`, and until that last phase ran `fetch` went on upgrading new websockets
+  // onto a process that was going away. The same split `@ultimat3/http`, the worker and the
+  // scheduler already have.
+  //
+  // Both are unregistered by `stop()`: a hook left behind after the listener is gone drains a node
+  // that is already stopped, and the next process-wide shutdown hangs on it.
+  const stopAccepting = onShutdown(
+    'realtime:sync:accept',
+    () => {
+      node.stopAccepting();
+    },
+    { phase: 'accept' },
+  );
+  const unregister = onShutdown('realtime:sync', async () => {
+    await node.drain();
+    await node.stop();
+    server.stop();
+    stopListening();
+  });
+  return {
+    url: websocketOrigin(server.url),
+    stop: () => {
+      stopAccepting();
+      unregister();
+      server.stop();
+      stopListening();
+    },
+  };
+}
+
+/**
+ * The listener reports where it actually landed: a caller asking for `port: 0` cannot guess the
+ * port, and a guessed URL is a client that connects to someone else. Swapped on the URL's
+ * protocol, never on the string — a hostname is allowed to contain "http".
+ */
+function websocketOrigin(url: URL): string {
+  const ws = new URL(url);
+  ws.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+  return ws.origin;
+}