@ultimat3/realtime 24.0.0 → 25.1.0

package/src/subscription-count.ts

@@ -0,0 +1,151 @@
+// One cap that spans sockets: live subscriptions counted per KEY (a tenant, an actor), held plus
+// reserved, with the key each socket was counted under remembered. Split from
+// `subscription-book.ts` so the tenant cap and the actor cap are one mechanism, not two copies.
+
+import { SubscriptionLimitError } from './errors';
+import type { SyncSocket } from './socket';
+
+export interface CappedCountInit {
+  /** Which key a socket's subscriptions count against, or `null` for none (uncapped here). */
+  readonly principalOf: (socket: SyncSocket) => string | null;
+  /** `undefined` counts without refusing — the tenant cap's opt-out. Screened by the caller. */
+  readonly max: number | undefined;
+  readonly scope: 'tenant' | 'actor';
+  readonly knob: string;
+}
+
+/**
+ * Every question answered from a `Map`, never a scan: the cap is asked on every subscribe frame,
+ * and walking the node's subscriptions for it was one socket consuming the node.
+ */
+export class CappedCount {
+  readonly #init: CappedCountInit;
+  readonly #held = new Map<string, number>();
+  readonly #claimed = new Map<string, number>();
+  /**
+   * The key 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 key that was never incremented and leave the old one counting forever.
+   */
+  readonly #principalOfSocket = new Map<string, string>();
+
+  constructor(init: CappedCountInit) {
+    this.#init = init;
+  }
+
+  count(key: string): number {
+    return this.#held.get(key) ?? 0;
+  }
+
+  /** The key a socket counts under: the remembered one, or what its actor says now. */
+  principalFor(socket: SyncSocket): string | null {
+    return this.#principalOfSocket.get(socket.id) ?? this.#init.principalOf(socket);
+  }
+
+  /** Claims count: a subscribe past this check has already committed the node to its work. */
+  assert(socket: SyncSocket): void {
+    const max = this.#init.max;
+    const key = this.principalFor(socket);
+    if (max === undefined || key === null) return;
+    if (this.count(key) + (this.#claimed.get(key) ?? 0) >= max) {
+      throw new SubscriptionLimitError({
+        scope: this.#init.scope,
+        id: key,
+        limit: max,
+        knob: this.#init.knob,
+      });
+    }
+  }
+
+  /** A reservation, given back to the key that took it even if the socket re-keys meanwhile. */
+  claim(socket: SyncSocket): { readonly principal: string | null; readonly release: () => void } {
+    const key = this.principalFor(socket);
+    if (key === null) return { principal: key, release: () => undefined };
+    bump(this.#claimed, key, 1);
+    return { principal: key, release: () => bump(this.#claimed, key, -1) };
+  }
+
+  /**
+   * A subscribe reserved under `claimedPrincipal` is attaching, and its socket now counts under another
+   * key (a re-auth landed while it was in flight): it joins the new key only if that key has room —
+   * the check the new key never got at reserve time.
+   */
+  assertIfMoved(socket: SyncSocket, claimedPrincipal: string | null): void {
+    if (this.principalFor(socket) !== claimedPrincipal) this.assert(socket);
+  }
+
+  /**
+   * How many of a socket's `held` subscriptions the key it is about to move to cannot take — `0`
+   * when it is not moving or there is room. A re-auth refuses that many rather than carrying a key
+   * past its cap: moving 128 onto a principal at 1,000 was 1,128, and filling an address then
+   * signing in was a way to repeat it.
+   */
+  overflowOnRekey(socket: SyncSocket, held: number): number {
+    const max = this.#init.max;
+    const after = this.#init.principalOf(socket);
+    if (max === undefined || after === null || held === 0) return 0;
+    if (after === (this.#principalOfSocket.get(socket.id) ?? null)) return 0;
+    const room = max - this.count(after) - (this.#claimed.get(after) ?? 0);
+    return Math.max(0, held - Math.max(0, room));
+  }
+
+  /** The refusal this cap answers for the key `socket` would count under. */
+  refusalFor(socket: SyncSocket): SubscriptionLimitError {
+    return new SubscriptionLimitError({
+      scope: this.#init.scope,
+      id: this.#init.principalOf(socket) ?? 'unknown',
+      limit: this.#init.max ?? 0,
+      knob: this.#init.knob,
+    });
+  }
+
+  /** The socket closed: nothing it remembers may outlive it. */
+  forget(socketId: string): void {
+    this.#principalOfSocket.delete(socketId);
+  }
+
+  /** Sockets this cap still remembers a key for — bounded by sockets that hold a subscription. */
+  get remembered(): number {
+    return this.#principalOfSocket.size;
+  }
+
+  added(socket: SyncSocket): void {
+    const key = this.principalFor(socket);
+    if (key === null) return;
+    this.#principalOfSocket.set(socket.id, key);
+    bump(this.#held, key, 1);
+  }
+
+  /** `emptied`: the socket now holds nothing, so its remembered key goes too. */
+  deleted(socketId: string, emptied: boolean): void {
+    const key = this.#principalOfSocket.get(socketId);
+    if (key === undefined) return;
+    bump(this.#held, key, -1);
+    if (emptied) this.#principalOfSocket.delete(socketId);
+  }
+
+  /** A re-auth moved the socket to another key: its `held` subscriptions move with it. */
+  reassign(socket: SyncSocket, held: number): void {
+    // Holding nothing, there is nothing to move and nothing to remember: `keyFor` falls back to
+    // the actor's key. Stored anyway, a re-auth on an idle socket was an entry nothing deleted.
+    if (held === 0) {
+      this.#principalOfSocket.delete(socket.id);
+      return;
+    }
+    const before = this.#principalOfSocket.get(socket.id) ?? null;
+    const after = this.#init.principalOf(socket);
+    if (before === after) return;
+    if (before !== null) bump(this.#held, before, -held);
+    if (after === null) this.#principalOfSocket.delete(socket.id);
+    else {
+      this.#principalOfSocket.set(socket.id, after);
+      if (held > 0) bump(this.#held, after, held);
+    }
+  }
+}
+
+function bump(map: Map<string, number>, key: string, by: number): void {
+  const next = (map.get(key) ?? 0) + by;
+  if (next > 0) map.set(key, next);
+  else map.delete(key);
+}

package/src/sync-actor-change.ts

@@ -0,0 +1,56 @@
+// What a socket's re-decided grant does to it: the hub re-asks every channel seat under the new
+// actor (each one it drops is refused under its sid, and left in presence), and the registry
+// re-decides every live subscription. Split from `sync-node.ts` at its size ceiling.
+
+import type { Actor } from '@ultimat3/core';
+import type { ChannelHub, Topic } from './channel';
+import type { ChannelSids } from './channel-sids';
+import { detach } from './detach';
+import { TopicForbiddenError } from './errors';
+import type { LiveQueryRegistry } from './live-query';
+import { refuseSubscription } from './live-refusal';
+import type { PresenceRegistry } from './presence';
+import type { SocketRegistry } from './socket';
+
+export interface ActorChangeDeps {
+  readonly sockets: SocketRegistry;
+  readonly hub: ChannelHub;
+  readonly registry: LiveQueryRegistry;
+  readonly channelSids: ChannelSids;
+  readonly presence: PresenceRegistry | undefined;
+}
+
+/** The `onActor` a grant sweep calls once per socket whose grant was refreshed. */
+export function actorChangeHandler(
+  deps: ActorChangeDeps,
+): (socketId: string, actor: Actor) => Promise<void> {
+  const hasRoster = (name: Topic): boolean => deps.hub.channelOf(name)?.channel.events === true;
+  return async (socketId, actor) => {
+    const socket = deps.sockets.get(socketId);
+    if (!socket) return;
+    const rooms = new Set(deps.hub.topicsOf(socket).filter(hasRoster));
+    // The hub sets `socket.actor` and drops the topics this actor may no longer read; the
+    // registry re-decides every live subscription (refusing each one it drops under its sid)
+    // and desyncs the survivors, so the next delivery re-snapshots them under the new
+    // authority rather than the old window.
+    for (const name of await deps.hub.onActorChange(socket, actor)) {
+      // A dropped seat is SAID: unsaid, the client kept rendering the channel as live.
+      const sid = deps.channelSids.sidOf(socket, name);
+      deps.channelSids.delete(socket, name);
+      if (sid !== undefined) {
+        refuseSubscription(
+          socket,
+          sid,
+          new TopicForbiddenError({
+            topic: name,
+            actorId: socket.actorId,
+            reason: 'the session changed and the channel policy no longer admits it',
+          }),
+        );
+      }
+      if (deps.presence && rooms.has(name))
+        detach(deps.presence.leave(name, socket.id), 'presence.leave', name);
+    }
+    await deps.registry.reauthorize(socket);
+  };
+}

package/src/sync-bus-handlers.ts

@@ -0,0 +1,131 @@
+// What a sync node does with the change bus: one change in, fanned to the live queries and the
+// declared channels; a gap or a reconnect, answered by invalidating both; and one producer KIND
+// per table, the other's envelopes dropped. Split out of `sync-node.ts` so the node's lifecycle
+// (start, stop, drain) stays readable in one file.
+
+import { logger } from '@ultimat3/core';
+import type { ChannelHub } from './channel';
+import { detach } from './detach';
+import type { LiveQueryRegistry } from './live-query';
+import { RealtimeError } from './realtime-error';
+import {
+  type ChangeEnvelope,
+  type EnvelopeSource,
+  parseEnvelope,
+  type SeqGapDetector,
+} from './replicator-envelope';
+
+export interface SyncBus {
+  readonly registry: LiveQueryRegistry;
+  readonly hub: ChannelHub;
+  readonly gaps: SeqGapDetector;
+  readonly producers: ProducerKinds;
+}
+
+/**
+ * The WAL replicator and a `recordPublisher` both carrying one table is every committed row twice
+ * on every channel. Logged, never thrown: the bus handler must keep serving every other table.
+ */
+export class ProducerConflictError extends RealtimeError {
+  constructor(args: { table: string; kept: EnvelopeSource; dropped: EnvelopeSource }) {
+    super({
+      code: 'X_REALTIME_PRODUCER_CONFLICT',
+      cause:
+        `table "${args.table}" is carried by the ${args.kept} and also by a ${args.dropped}, so ` +
+        `every committed row would reach its channels twice; this node keeps the ${args.kept} ` +
+        `(seen first) and drops the ${args.dropped}'s changes`,
+      // One fix for both orders: the replicator carries every entity table it can see, so the
+      // publisher is the half that can let go of one.
+      fix: `recordPublisher({ entities: [/* every entity but table ${args.table}'s */] })   # where the replicator runs: it already carries every committed row; then restart the sync node`,
+    });
+  }
+}
+
+/**
+ * Which producer kind carries each table, decided by the first envelope this node reads for it and
+ * kept for the node's life. The other kind's envelopes for that table are dropped and the conflict
+ * said once per table (`X_REALTIME_PRODUCER_CONFLICT`). The `x dev` bridge is no producer here: it
+ * delivers in-process and stands in for the replicator, skipping a claimed table itself.
+ */
+export class ProducerKinds {
+  readonly #kinds = new Map<string, EnvelopeSource>();
+  readonly #said = new Set<string>();
+
+  /** `true` when this envelope's producer kind is the one its table is carried by. */
+  admit(envelope: ChangeEnvelope): boolean {
+    const table = envelope.change.table;
+    const kind = envelope.source ?? 'replicator';
+    const kept = this.#kinds.get(table);
+    if (kept === undefined) {
+      this.#kinds.set(table, kind);
+      return true;
+    }
+    if (kept === kind) return true;
+    if (!this.#said.has(table)) {
+      this.#said.add(table);
+      const conflict = new ProducerConflictError({ table, kept, dropped: kind });
+      // FIELDS, never interpolation, and the message is the CODE alone (`pg-preflight.ts`).
+      logger.warn(conflict.code, {
+        cause: conflict.cause,
+        fix: conflict.fix,
+        table,
+        kept,
+        dropped: kind,
+      });
+    }
+    return false;
+  }
+}
+
+/** The handler a node subscribes to `CHANGE_SUBJECT_ALL` with. */
+export function changeHandler(bus: SyncBus): (payload: string) => void {
+  return (payload) => {
+    const envelope = parseEnvelope(payload);
+    if (!envelope) return;
+    // Before the gap detector: a dropped producer's sequence is no stream this node follows.
+    if (!bus.producers.admit(envelope)) return;
+    // Fanout is at-most-once over core NATS, so a reconnect is changes this node never saw.
+    // Nothing downstream could notice: no window's lsn moved, so no cursor moved, so nothing
+    // ever asked for a re-snapshot. A gap invalidates every window here instead, and the
+    // subscribers are re-served on the next change to each query.
+    const replicated = envelope.source !== 'publisher';
+    if (bus.gaps.observe(envelope)) {
+      // A publisher's lost change was never a window's (below), so only the channels re-read.
+      const marked = replicated ? bus.registry.invalidate() : 0;
+      // Channels too: their seq is minted from what this node sees, so the hole is invisible
+      // to a ring that would otherwise replay across it as complete history.
+      const channelGaps = bus.hub.invalidate();
+      logger.warn('live.change_gap', {
+        table: envelope.change.table,
+        desynced: marked,
+        channelGaps,
+      });
+    }
+    // Not awaited: the bus handler must return before the next change, and ordering is the
+    // registry's — one serial lane per query id. What this call site owes is the failure. An
+    // unhandled rejection here is a fanout that reached nobody, reported as a dead process.
+    // A publisher's change has no commit position (its lsn orders nothing across processes), and
+    // a window refuses a change below its own lsn as stale: fed one, a live query would drop rows
+    // silently. Channels mint their own seq, so they take it (`record-publisher.ts`).
+    if (replicated) {
+      detach(bus.registry.deliver(envelope.change), 'live.deliver', envelope.change.table);
+    }
+    // The same stream feeds the declared channels: a write names no channel (axiom 2), and the
+    // hub turns this change into `records` frames on every channel it touches.
+    bus.hub.deliverChange(envelope.change);
+  };
+}
+
+/**
+ * A bus that reconnected is changes this node never saw, and the gap detector only notices on the
+ * NEXT message: with no later write, every window and cursor here stayed behind and every new
+ * subscriber joined the stale window. Said by the transport, repaired now.
+ */
+export function reconnectHandler(bus: SyncBus): () => void {
+  return () => {
+    bus.gaps.forget();
+    const marked = bus.registry.invalidate();
+    const channelGaps = bus.hub.invalidate();
+    logger.warn('live.bus_reconnected', { desynced: marked, channelGaps });
+  };
+}

package/src/sync-frames.ts

@@ -47,7 +47,7 @@ export function ackRefOf(frame: Frame | null, socketId: string): string {
   return socketId;
 }
 
-export function createFrameRouter(options: FrameRouterOptions): FrameRouter {
+export function frameRouter(options: FrameRouterOptions): FrameRouter {
   const presence = options.presence;
   const channelSids = options.channelSids ?? new ChannelSids();
 

package/src/sync-node-bounds.ts

@@ -82,7 +82,7 @@ export function syncNodeBounds(options: SyncNodeNumericOptions): SyncNodeBounds
  * that `SyncSocket` — not this module — owns the default of.
  *
  * They were screened only in `SyncSocket`'s constructor, which Bun runs inside `websocket.open`,
- * which Bun runs SYNCHRONOUSLY inside `server.upgrade`. Measured: `createSyncNode` did not throw,
+ * which Bun runs SYNCHRONOUSLY inside `server.upgrade`. Measured: `syncNode` did not throw,
  * `/healthz` and `/readyz` both answered, `ready` was true, and every upgrade threw `X_INVARIANT`
  * with the node holding zero sockets — a misconfiguration that fails per connection instead of at
  * boot, and each of those throws leaked the grant `handleUpgrade` records before the upgrade.

package/src/sync-node-contract.ts

@@ -1,4 +1,4 @@
-// What a `sync` node IS, as types: the options `createSyncNode` takes, the node it returns and the
+// What a `sync` node IS, as types: the options `syncNode` takes, the node it returns and the
 // socket Bun hands its handlers. Apart from `sync-node.ts` so the lifecycle there stays under the
 // file ceiling, and so a host can name the shapes without reading the lifecycle.
 
@@ -33,7 +33,7 @@ export interface SyncNodeOptions {
   /**
    * When a socket starts dropping frames, and how many drops close it. On `SyncSocket` too, but
    * this node builds every socket it holds — so unforwarded they were reachable only by abandoning
-   * `createSyncNode`, and a dropped channel frame is the one loss nothing replays.
+   * `syncNode`, and a dropped channel frame is the one loss nothing replays.
    */
   readonly maxBufferedBytes?: number;
   readonly maxDroppedFrames?: number;
@@ -65,6 +65,12 @@ export interface SyncNodeOptions {
    * server reached through a forwarded host; never a container, where `Host` is the caller's.
    */
   readonly admitReachedOrigin?: boolean;
+  /**
+   * The caller's address from the upgrade request — the boot injects `@ultimat3/http`'s
+   * `clientAddress()` under the deployment's `TRUSTED_PROXY_HOPS`. Absent, the socket's own
+   * address. It keys an anonymous subscriber's live rate limit (`UpgradeDeps.clientAddressOf`).
+   */
+  readonly clientAddressOf?: (request: Request, socketAddress: string | null) => string | null;
   /**
    * Peers this node's own `/healthz` and `/readyz` tell the whole report to: address classes
    * (`loopback`, `private`, …) or exact IP literals — the app's `http.healthDetailPeers`. Defaults
@@ -84,6 +90,12 @@ export interface SyncNodeOptions {
   /** WS endpoint. One path, no negotiation — the protocol version lives in the frames. */
   readonly path?: string;
   readonly drainSpreadMs?: number;
+  /**
+   * Sockets one principal — an actor, or an anonymous caller's network (IPv4, IPv6 /64) — may hold
+   * on this node. Default `DEFAULT_MAX_SOCKETS_PER_ACTOR` (16); the boot passes the app's
+   * `realtime.maxSocketsPerActor`. The next upgrade is 429 `X_SOCKET_LIMIT`.
+   */
+  readonly maxSocketsPerActor?: number;
 }
 
 export interface SyncNode {
@@ -91,6 +103,8 @@ export interface SyncNode {
   readonly ready: boolean;
   /** The one path it answers an upgrade on: a HOST has to route it, and must not restate it. */
   readonly path: string;
+  /** Sockets one principal (`actor:<id>` / `address:<network>`) holds here — the cap's count. */
+  principalSockets(principal: string): number;
   start(): Promise<void>;
   /**
    * Refuse new connections, keep every one this node holds. The SIGTERM `accept` phase calls it —