@ultimat3/realtime 20.2.1 → 22.0.0

package/src/server.ts

@@ -1,7 +1,7 @@
 // The SERVER half of the public API: the bus, the Postgres replication path, the sync node and the
 // live-query registry it fans out through. Split from `index.ts` because `nats` require()s
 // `stream/web` and the WAL decoder is a Postgres client — one barrel carrying both made the browser
-// island `useLive` promises unbuildable. Every name here has exactly one home; the shared
+// island realtime promises unbuildable. Every name here has exactly one home; the shared
 // vocabulary (the wire, the errors, `Row`, the backoff) stays on `@ultimat3/realtime`.
 
 // ---- the retained change window one node fans out from ------------------------------------------
@@ -38,14 +38,10 @@ export {
 export {
   ChannelHub,
   type ChannelHubOptions,
-  channelFrame,
   DEFAULT_MAX_TOPICS_PER_NODE,
-  type Topic,
-  type TopicGuard,
-  type TopicGuardArgs,
-  type TopicGuardResult,
-  topic,
 } from './channel';
+export { type ChannelDescription, describeChannels } from './channel-describe';
+export { RealtimeTopologyError } from './errors';
 export {
   InProcessTransport,
   type InProcessTransportOptions,
@@ -67,6 +63,11 @@ export {
   LiveQueryRegistry,
   type LiveQueryRegistryOptions,
 } from './live-query';
+export {
+  type LiveReplicator,
+  type LiveReplicatorOptions,
+  startLiveReplicator,
+} from './live-replicator';
 export {
   applyToWindow,
   type BridgeResult,
@@ -114,7 +115,7 @@ export { openNatsClient } from './nats-lib-client';
 export { NatsTransport, type NatsTransportOptions } from './nats-transport';
 export { PgAdvisoryLock, type PgAdvisoryLockOptions } from './pg-advisory-lock';
 // ---- the postgres replication path ------------------------------------------------------------
-export { camel, entityRow } from './pg-entity-row';
+export { entityRow } from './pg-entity-row';
 export {
   changeLsn,
   commitPositionOf,
@@ -171,16 +172,15 @@ export {
   actorIdOf,
   CLOSE,
   DEFAULT_FRAME_BURST,
-  DEFAULT_IDLE_TIMEOUT_MS,
   DEFAULT_MAX_BUFFERED_BYTES,
   DEFAULT_MAX_FRAMES_PER_SECOND,
-  idleSweepPeriodMs,
   SocketRegistry,
   type SocketRegistryOptions,
   SyncSocket,
   type SyncSocketOptions,
   type WsLike,
 } from './socket';
+export { DEFAULT_IDLE_TIMEOUT_MS, idleSweepPeriodMs } from './socket-idle';
 export type {
   GateFailed,
   GateStage,
@@ -200,7 +200,6 @@ export {
   createFrameRouter,
   type FrameRouter,
   type FrameRouterOptions,
-  type MutationHandler,
 } from './sync-frames';
 export {
   type ListenOptions,

package/src/socket-drops.ts

@@ -0,0 +1,30 @@
+// How many dropped frames close a socket: more than `maxDroppedFrames` inside one window, never a
+// lifetime count. Split from `socket.ts`, which counts the drops; this decides what they mean.
+
+/**
+ * The window `maxDroppedFrames` is counted over. Ten seconds: long enough that a burst of
+ * backpressure drops closes a socket that cannot keep up, short enough that a connection open for
+ * hours is never closed for a lifetime's worth of isolated drops.
+ */
+export const DROP_WINDOW_MS = 10_000;
+
+/**
+ * The instants of the drops inside the current window. A burst of backpressure drops closes a
+ * socket that cannot keep up; the same number spread over a connection open for hours is a flaky
+ * link the cursor repairs, and closing for it was a healthy socket lost after 33 lifetime drops.
+ */
+export class DropWindow {
+  readonly #max: number;
+  readonly #recent: number[] = [];
+
+  constructor(max: number) {
+    this.#max = max;
+  }
+
+  /** Records one drop at `now` (monotonic ms) and answers whether the window is over its ceiling. */
+  overflowed(now: number): boolean {
+    this.#recent.push(now);
+    while ((this.#recent[0] ?? now) <= now - DROP_WINDOW_MS) this.#recent.shift();
+    return this.#recent.length > this.#max;
+  }
+}

package/src/socket-engine.ts

@@ -0,0 +1,344 @@
+// The socket engine (plan 101, slice 11): ONE sync socket shared by every tab of an origin and
+// principal, talking to each tab only over a `MessagePort`. Host-agnostic — the SharedWorker entry
+// and the in-page fallback run this same code. Each tab keeps its own `LiveClient` and store; to
+// it, its port IS a socket. This file is the socket's lifecycle — dial, beat, redial, reap; the
+// multiplexing (one membership per topic, frames routed per port) is `socket-routes.ts`.
+
+import { type Clock, finiteOption, systemClock } from '@ultimat3/core/page';
+import type { ClientSocket } from './client-contract';
+import { DEFAULT_HEARTBEAT_MS, Heartbeat } from './client-heartbeat';
+import type { SyncTarget } from './page-store';
+import type { AttachedPort, PortLike, PortMessage } from './socket-port';
+import { PortRouter } from './socket-routes';
+import { decode, encode, type Frame, PROTOCOL_VERSION } from './sync-protocol';
+import {
+  type BackoffPolicy,
+  browserBackoff,
+  policyDelay,
+  type Rng,
+  type Scheduler,
+  timeoutScheduler,
+} from './thundering-herd';
+
+// The port seam is its own module; these are the names every host already imports from here.
+export { messagePort, type PortLike, type PortMessage } from './socket-port';
+
+export interface SocketEngineOptions {
+  /** Dials the real socket. Production: `browserSocket(dialUrl(target))`. */
+  readonly dial: (target: SyncTarget) => ClientSocket;
+  readonly scheduler?: Scheduler;
+  readonly clock?: Clock;
+  readonly backoff?: BackoffPolicy;
+  readonly rng?: Rng;
+  /** The engine's own beat on the real socket, and the unit a silent port is reaped in. */
+  readonly heartbeatMs?: number;
+}
+
+/** A tab beats every heartbeat; three missed beats and its port is reaped — a tab has no close. */
+export const REAP_AFTER_BEATS = 3;
+
+export class SocketEngine {
+  readonly #options: SocketEngineOptions;
+  readonly #clock: Clock;
+  readonly #schedule: Scheduler;
+  readonly #beatMs: number;
+  readonly #ports = new Map<number, AttachedPort>();
+  readonly #router: PortRouter;
+  readonly #heartbeat: Heartbeat;
+  #next = 1;
+  #target: SyncTarget | null = null;
+  #socket: ClientSocket | null = null;
+  #up = false;
+  #attempt = 0;
+  #reconnect: (() => void) | null = null;
+  #reaper: (() => void) | null = null;
+  #hello: Frame | null = null;
+  #update: string | null = null;
+
+  constructor(options: SocketEngineOptions) {
+    this.#options = options;
+    this.#clock = options.clock ?? systemClock;
+    this.#schedule = options.scheduler ?? timeoutScheduler;
+    this.#beatMs = finiteOption(
+      'SocketEngine',
+      'heartbeatMs',
+      options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS,
+    );
+    this.#heartbeat = new Heartbeat({
+      intervalMs: this.#beatMs,
+      schedule: this.#schedule,
+      now: () => this.#now(),
+      beat: () => this.#beat(),
+      onSilence: () => this.#lost(),
+    });
+    this.#router = new PortRouter({
+      send: (frame) => this.#send(frame),
+      post: (attached, message) => this.#post(attached, message),
+      port: (id) => this.#ports.get(id),
+      ports: () => this.#ports.values(),
+    });
+  }
+
+  /** Ports attached right now. Tests and the worker's own diagnostics read it. */
+  get ports(): number {
+    return this.#ports.size;
+  }
+
+  attach(port: PortLike): void {
+    const attached: AttachedPort = {
+      id: this.#next++,
+      port,
+      open: false,
+      asked: false,
+      lastSeen: this.#now(),
+      topics: new Set(),
+      lives: new Map(),
+    };
+    this.#ports.set(attached.id, attached);
+    port.onmessage = (event) => this.#fromPort(attached, event.data);
+    this.#armReaper();
+  }
+
+  #fromPort(attached: AttachedPort, message: unknown): void {
+    if (!this.#ports.has(attached.id) || typeof message !== 'object' || message === null) return;
+    attached.lastSeen = this.#now();
+    const typed = message as PortMessage;
+    if (typed.t === 'open') {
+      const arriving = !attached.asked;
+      attached.open = true;
+      attached.asked = true;
+      this.#target ??= typed.target;
+      if (this.#up) {
+        this.#post(attached, { t: 'open', target: typed.target });
+        return;
+      }
+      // A page arriving is a fresh reason to believe the node is back (a reload, a deploy): the
+      // wait an earlier page's failures built up is not this page's to inherit.
+      if (arriving && this.#socket === null) this.#restartCurve();
+      this.#dial();
+      return;
+    }
+    if (typed.t === 'close') {
+      // The tab closed its virtual socket — a redial on the same port. Its wants go; the port stays.
+      this.#router.release(attached);
+      attached.open = false;
+      return;
+    }
+    if (typed.t === 'bye') {
+      this.#detach(attached);
+      return;
+    }
+    if (typed.t === 'frame' && this.#up) this.#fromTab(attached, typed.data);
+  }
+
+  #fromTab(attached: AttachedPort, data: string): void {
+    let frame: Frame;
+    try {
+      frame = decode(data);
+    } catch {
+      return;
+    }
+    if (frame.type === 'hello') {
+      // The tab's beat is this engine's ping: answer it, and add the one thing a beat learns.
+      this.#post(attached, { t: 'frame', data: encode(this.#helloReply()) });
+      if (this.#update !== null) {
+        const update: Frame = {
+          type: 'update-available',
+          v: PROTOCOL_VERSION,
+          buildId: this.#update,
+        };
+        this.#post(attached, { t: 'frame', data: encode(update) });
+      }
+      return;
+    }
+    if (frame.type === 'subscribe') this.#router.subscribe(attached, frame);
+  }
+
+  /** Release the port itself: a tab that said `bye`, or one silent for three beats. */
+  #detach(attached: AttachedPort): void {
+    if (!this.#ports.delete(attached.id)) return;
+    this.#router.release(attached);
+    attached.port.onmessage = null;
+    attached.port.close?.();
+    if (this.#ports.size === 0) this.#shutdown();
+  }
+
+  #fromServer(data: string): void {
+    let frame: Frame;
+    try {
+      frame = decode(data);
+    } catch {
+      return;
+    }
+    switch (frame.type) {
+      case 'hello':
+        this.#hello = frame;
+        return;
+      case 'snapshot':
+      case 'patch':
+      case 'ack':
+      case 'records':
+      case 'replay-gap':
+      case 'events':
+        this.#router.route(frame, data);
+        return;
+      case 'update-available':
+        this.#update = frame.buildId;
+        for (const attached of this.#ports.values()) this.#post(attached, { t: 'frame', data });
+        return;
+      case 'reconnect':
+        // The node assigned this socket its slot in a drain spread: honour it, once, for everyone.
+        this.#lost(frame.afterMs);
+        return;
+      case 'subscribe':
+        return;
+    }
+  }
+
+  #dial(): void {
+    if (this.#socket !== null || this.#reconnect !== null || this.#target === null) return;
+    const target = this.#target;
+    let socket: ClientSocket;
+    try {
+      socket = this.#options.dial(target);
+    } catch {
+      this.#scheduleReconnect(null);
+      return;
+    }
+    this.#socket = socket;
+    socket.onOpen(() => {
+      if (this.#socket !== socket) return;
+      this.#up = true;
+      this.#attempt = 0;
+      socket.send(encode(this.#ownHello()));
+      this.#heartbeat.start(this.#now());
+      for (const attached of this.#ports.values()) {
+        if (attached.open) this.#post(attached, { t: 'open', target });
+      }
+    });
+    socket.onMessage((data) => {
+      if (this.#socket !== socket) return;
+      this.#heartbeat.saw(this.#now());
+      this.#fromServer(data);
+    });
+    socket.onClose(() => {
+      if (this.#socket !== socket) return;
+      this.#lost();
+    });
+  }
+
+  /**
+   * The real socket is gone. Every tab's virtual socket closes with it, and each tab's own client
+   * re-opens and resubscribes FROM ITS CURSORS — the engine keeps no subscription state across a
+   * reconnect, so there is nothing here to go stale.
+   */
+  #lost(afterMs: number | null = null): void {
+    const socket = this.#socket;
+    this.#socket = null;
+    this.#up = false;
+    this.#heartbeat.stop();
+    socket?.close(1000, 'engine reconnect');
+    this.#router.clear();
+    for (const attached of this.#ports.values()) {
+      if (attached.open) this.#post(attached, { t: 'close', code: 1006 });
+      attached.open = false;
+    }
+    if (this.#ports.size > 0) this.#scheduleReconnect(afterMs);
+  }
+
+  #scheduleReconnect(afterMs: number | null): void {
+    if (this.#reconnect !== null) return;
+    const rng = this.#options.rng ?? Math.random;
+    const delay =
+      // `#attempt` counts reconnects already scheduled, from 0; the wait being armed is the next one.
+      afterMs ?? policyDelay(this.#options.backoff ?? browserBackoff, this.#attempt + 1, rng);
+    this.#attempt += 1;
+    this.#reconnect = this.#schedule(() => {
+      this.#reconnect = null;
+      // Dialled only for a tab that is asking: a tab re-asks through its own client's timer.
+      if ([...this.#ports.values()].some((attached) => attached.open)) this.#dial();
+    }, delay);
+  }
+
+  #restartCurve(): void {
+    this.#reconnect?.();
+    this.#reconnect = null;
+    this.#attempt = 0;
+  }
+
+  /**
+   * No page left. A SharedWorker can outlive its last page for a moment and be handed the next
+   * one, so NOTHING a page brought survives here: not the curve, and not the target — a page of
+   * the next build would otherwise dial with the old build id and be told to update forever.
+   */
+  #shutdown(): void {
+    this.#restartCurve();
+    this.#target = null;
+    this.#hello = null;
+    this.#update = null;
+    this.#reaper?.();
+    this.#reaper = null;
+    const socket = this.#socket;
+    this.#socket = null;
+    this.#up = false;
+    this.#heartbeat.stop();
+    socket?.close(1000, 'no tab left');
+  }
+
+  /**
+   * A silent port, released — and TOLD first. Silent is usually a closed tab, but a hidden tab the
+   * browser throttled is silent too, and it was released without a word: its virtual socket stayed
+   * "open" over a port nobody read, and that tab's realtime was dead until a reload. Told, its
+   * client goes offline and redials, and the page re-hosts (`socket-host.ts`'s `rehosting`).
+   */
+  #reap(attached: AttachedPort): void {
+    if (attached.open) this.#post(attached, { t: 'close', code: 1006 });
+    this.#detach(attached);
+  }
+
+  /** A `MessagePort` has no close event: a port silent for three beats is a closed tab. */
+  #armReaper(): void {
+    if (this.#reaper !== null) return;
+    this.#reaper = this.#schedule(() => {
+      this.#reaper = null;
+      const cutoff = this.#now() - REAP_AFTER_BEATS * this.#beatMs;
+      for (const attached of [...this.#ports.values()]) {
+        if (attached.lastSeen < cutoff) this.#reap(attached);
+      }
+      if (this.#ports.size > 0) this.#armReaper();
+    }, this.#beatMs);
+  }
+
+  #beat(): void {
+    this.#send(this.#ownHello());
+    this.#router.announce();
+  }
+
+  /** What this engine says to the node: the build every tab of it was rendered by. */
+  #ownHello(): Frame {
+    return {
+      type: 'hello',
+      v: PROTOCOL_VERSION,
+      buildId: this.#target?.buildId ?? '',
+      sessionId: null,
+      actorId: null,
+    };
+  }
+
+  /** What a tab's beat is answered with: the node's own hello once there is one. */
+  #helloReply(): Frame {
+    return this.#hello ?? this.#ownHello();
+  }
+
+  #send(frame: Frame): void {
+    if (this.#up) this.#socket?.send(encode(frame));
+  }
+
+  #post(attached: AttachedPort, message: PortMessage): void {
+    attached.port.postMessage(message);
+  }
+
+  #now(): number {
+    return this.#clock.now().getTime();
+  }
+}

package/src/socket-host.ts

@@ -0,0 +1,225 @@
+// The tab side of the page's one socket (plan 101, slice 11): pick the host — a `SharedWorker`
+// shared by every tab of this origin and principal, or the in-page engine when there is none —
+// and hand the tab's `LiveClient` a socket that is really a `MessagePort`. One engine, one
+// protocol, under both hosts: the fallback costs a socket per tab and nothing else.
+
+import { browserSocket, dialUrl } from './browser-socket';
+import type { ClientSocket } from './client-contract';
+import type { SyncTarget } from './page-store';
+import { messagePort, type PortLike, SocketEngine } from './socket-engine';
+import { type Scheduler, timeoutScheduler } from './thundering-herd';
+
+export interface SocketHostOptions {
+  /** The built worker script (`<meta name="ultimate-sync-worker">`); absent = in-page host. */
+  readonly workerUrl?: string | undefined;
+  /** The principal the page acts for: one worker per principal, never a shared socket across two. */
+  readonly scope: string | null;
+  /** The build the page was rendered by: one worker per build, too. See `workerName`. */
+  readonly buildId?: string | undefined;
+  /** Injected for tests; production reads the globals. */
+  readonly sharedWorker?: SharedWorkerLike | undefined;
+  readonly inPageEngine?: () => SocketEngine;
+}
+
+export type SharedWorkerLike = new (
+  url: string,
+  options: { name: string },
+) => { port: MessagePort };
+
+export interface SocketHost {
+  /** `'worker'` or `'in-page'` — which host this page ended up on. */
+  readonly kind: 'worker' | 'in-page';
+  /** A fresh virtual socket over the port — what `LiveClient`'s `connect` option returns. */
+  socket(target: SyncTarget): ClientSocket;
+  /** The tab is going away: release the port in the engine. */
+  bye(): void;
+}
+
+/**
+ * The worker's name carries the scope, so two principals in two tabs get two workers — and the
+ * BUILD, so two builds do too. A SharedWorker keeps the first tab's build id for its whole life, so
+ * a tab of the new build joined the old engine and was told "update available" about itself.
+ */
+export function workerName(scope: string | null, buildId: string | undefined): string {
+  return `ultimate-sync:${encodeURIComponent(scope ?? '')}:${encodeURIComponent(buildId ?? '')}`;
+}
+
+export function openHost(options: SocketHostOptions): SocketHost {
+  const worker = options.workerUrl === undefined ? undefined : workerPort(options);
+  if (worker !== undefined) return hostOver(worker, 'worker');
+  const channel = new MessageChannel();
+  const engine =
+    options.inPageEngine?.() ??
+    new SocketEngine({ dial: (target) => browserSocket(dialUrl(target)) });
+  engine.attach(messagePort(channel.port1));
+  return hostOver(messagePort(channel.port2), 'in-page');
+}
+
+/** `undefined` whenever a worker cannot be had — absent, sandboxed, or refused by the browser. */
+function workerPort(options: SocketHostOptions): PortLike | undefined {
+  const Worker =
+    options.sharedWorker ??
+    (typeof SharedWorker === 'function' ? (SharedWorker as SharedWorkerLike) : undefined);
+  if (Worker === undefined || options.workerUrl === undefined) return undefined;
+  try {
+    return messagePort(
+      new Worker(options.workerUrl, { name: workerName(options.scope, options.buildId) }).port,
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+function hostOver(port: PortLike, kind: 'worker' | 'in-page'): SocketHost {
+  let current: VirtualSocket | null = null;
+  port.onmessage = (event) => current?.receive(event.data);
+  return {
+    kind,
+    socket: (target) => {
+      current = new VirtualSocket(port, target);
+      return current;
+    },
+    bye: () => {
+      current = null;
+      port.postMessage({ t: 'bye' });
+      port.close?.();
+    },
+  };
+}
+
+/** The tab's socket: one `open`, frames both ways, one `close` — over the host's port. */
+class VirtualSocket implements ClientSocket {
+  readonly #port: PortLike;
+  #open: (() => void) | null = null;
+  #message: ((data: string) => void) | null = null;
+  #closed: ((code: number) => void) | null = null;
+  #live = true;
+
+  constructor(port: PortLike, target: SyncTarget) {
+    this.#port = port;
+    port.postMessage({ t: 'open', target });
+  }
+
+  send(data: string): void {
+    if (this.#live) this.#port.postMessage({ t: 'frame', data });
+  }
+
+  close(): void {
+    if (!this.#live) return;
+    this.#live = false;
+    this.#port.postMessage({ t: 'close', code: 1000 });
+  }
+
+  onOpen(handler: () => void): void {
+    this.#open = handler;
+  }
+
+  onMessage(handler: (data: string) => void): void {
+    this.#message = handler;
+  }
+
+  onClose(handler: (code: number) => void): void {
+    this.#closed = handler;
+  }
+
+  receive(message: unknown): void {
+    if (!this.#live || typeof message !== 'object' || message === null) return;
+    const typed = message as { t?: unknown; data?: unknown; code?: unknown };
+    if (typed.t === 'open') this.#open?.();
+    else if (typed.t === 'frame' && typeof typed.data === 'string') this.#message?.(typed.data);
+    else if (typed.t === 'close') {
+      this.#live = false;
+      this.#closed?.(typeof typed.code === 'number' ? typed.code : 1006);
+    }
+  }
+}
+
+/** A host that can be replaced under the page's one client. */
+export interface RehostingHost extends SocketHost {
+  /** Say bye to the current host and build a new one — the next `socket()` dials through it. */
+  rehost(): void;
+}
+
+export interface RehostingOptions {
+  /** How long a virtual socket may wait for `open` before its host is presumed dead. */
+  readonly openTimeoutMs: number;
+  readonly schedule?: Scheduler | undefined;
+}
+
+/**
+ * The page's host, replaceable. A port the engine reaped (a throttled hidden tab), or one the tab
+ * itself said `bye` on at `pagehide` before a bfcache restore, is a port nobody reads: the virtual
+ * socket over it waited for `open` forever and the tab's realtime was dead until a reload. So an
+ * `open` unanswered by `openTimeoutMs` closes that socket (1006, which the client redials on) and
+ * re-hosts on a fresh port; `page-socket.ts` also re-hosts on a bfcache `pageshow`.
+ */
+export function rehosting(make: () => SocketHost, options: RehostingOptions): RehostingHost {
+  const schedule = options.schedule ?? timeoutScheduler;
+  let current = make();
+  const self: RehostingHost = {
+    get kind(): 'worker' | 'in-page' {
+      return current.kind;
+    },
+    socket: (target) => {
+      const inner = current.socket(target);
+      return watchOpen(inner, schedule, options.openTimeoutMs, () => self.rehost());
+    },
+    bye: () => current.bye(),
+    rehost: () => {
+      current.bye();
+      current = make();
+    },
+  };
+  return self;
+}
+
+/** `inner`, with a deadline on its `open`: missed, the host is re-made and the socket closes. */
+function watchOpen(
+  inner: ClientSocket,
+  schedule: Scheduler,
+  ms: number,
+  rehost: () => void,
+): ClientSocket {
+  let opened: (() => void) | null = null;
+  let closed: ((code: number) => void) | null = null;
+  let settled = false;
+  const disarm = schedule(() => {
+    if (settled) return;
+    settled = true;
+    rehost();
+    closed?.(1006);
+  }, ms);
+  inner.onOpen(() => {
+    if (settled) return;
+    settled = true;
+    disarm();
+    opened?.();
+  });
+  inner.onClose((code) => {
+    if (!settled) {
+      settled = true;
+      disarm();
+    }
+    closed?.(code);
+  });
+  return {
+    get bufferedAmount(): number {
+      return inner.bufferedAmount ?? 0;
+    },
+    send: (data) => inner.send(data),
+    close: (code, reason) => {
+      if (!settled) {
+        settled = true;
+        disarm();
+      }
+      inner.close(code, reason);
+    },
+    onOpen: (handler) => {
+      opened = handler;
+    },
+    onMessage: (handler) => inner.onMessage(handler),
+    onClose: (handler) => {
+      closed = handler;
+    },
+  };
+}

package/src/socket-idle.ts

@@ -0,0 +1,21 @@
+// The application idle budget a sync node evicts a silent socket on, and how often it asks. Split
+// from `socket.ts` at its line ceiling.
+
+/**
+ * How long a socket may route no frame before `sync-node` evicts it. It is an APPLICATION
+ * inactivity budget and not Bun's transport one: Bun's `idleTimeout` is renewed by its own
+ * ping/pong, so a client whose TCP stack still answers pings while its frame loop is wedged holds
+ * its grant, its subscriptions and its topic membership forever. A beating client sends a `hello`
+ * every `DEFAULT_HEARTBEAT_MS` (15s), so this is eight missed beats.
+ */
+export const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
+
+/**
+ * How often to ask. A quarter of the budget, floored at a second: a socket is evicted within 25%
+ * of its window of going quiet, and a node holding 50,000 of them pays one pass over the table
+ * four times per window rather than once a second. Derived rather than configured — a second knob
+ * is a second number that can disagree with the one it is a fraction of.
+ */
+export function idleSweepPeriodMs(idleTimeoutMs: number): number {
+  return Math.max(1_000, Math.floor(idleTimeoutMs / 4));
+}