@ultimat3/realtime 1.0.0

package/src/sync-protocol.ts

@@ -0,0 +1,376 @@
+// The wire. One protocol for all three tiers: a channel subscribe, a live-query subscribe, and an
+// offline mutation drain are frames in the same union. Moving a route from tier 2 to tier 3 is a
+// config flag (`persist: true`), never a new protocol — that promise is enforced here.
+
+import type { LiveCursor } from './cursor';
+import { ProtocolVersionError } from './errors';
+import {
+  isJsonObject,
+  isRow,
+  type JsonObject,
+  type JsonValue,
+  type Row,
+  type RowPatch,
+} from './json';
+
+export const PROTOCOL_VERSION = 1;
+
+export type ConflictStrategyName = 'server-wins' | 'last-write-wins' | 'custom';
+
+export interface WireError {
+  readonly code: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs?: string;
+}
+
+export interface PresenceMember {
+  readonly id: string;
+  readonly actorId: string | null;
+  readonly meta: JsonObject;
+  /** Client-supplied logical time; last write wins per member on ties-free comparison. */
+  readonly updatedAt: number;
+}
+
+export type SubscribeTarget =
+  | { readonly kind: 'topic'; readonly topic: string }
+  | {
+      /**
+       * Client -> server, `qid` carries the *query name*; the server derives the real qid from
+       * (name, input) so a client can never pick its own fanout key. Server -> client it is the
+       * derived qid, which is also what the cursor is keyed by.
+       */
+      readonly kind: 'query';
+      readonly qid: string;
+      readonly input: JsonValue;
+      readonly cursor: LiveCursor | null;
+    };
+
+export interface HelloFrame {
+  readonly type: 'hello';
+  readonly v: number;
+  readonly buildId: string;
+  /** Server-assigned on the reply, `null` on the client's opening frame. */
+  readonly sessionId: string | null;
+  readonly actorId: string | null;
+  readonly resume: readonly LiveCursor[];
+}
+
+export interface SubscribeFrame {
+  readonly type: 'subscribe';
+  readonly v: number;
+  readonly op: 'add' | 'drop';
+  readonly sid: string;
+  readonly target: SubscribeTarget;
+}
+
+export interface SnapshotFrame {
+  readonly type: 'snapshot';
+  readonly v: number;
+  readonly sid: string;
+  readonly rows: readonly Row[];
+  readonly cursor: LiveCursor;
+}
+
+export interface PatchFrame {
+  readonly type: 'patch';
+  readonly v: number;
+  readonly sid: string;
+  readonly patches: readonly RowPatch[];
+  readonly lsn: string;
+}
+
+export interface MutateFrame {
+  readonly type: 'mutate';
+  readonly v: number;
+  /** Idempotency key. The server collapses repeats; the client never renumbers. */
+  readonly key: string;
+  readonly seq: number;
+  readonly name: string;
+  readonly input: JsonValue;
+}
+
+export interface AckFrame {
+  readonly type: 'ack';
+  readonly v: number;
+  /** Mutation key or subscription id being acknowledged. */
+  readonly ref: string;
+  readonly lsn: string | null;
+  readonly error: WireError | null;
+}
+
+export interface RebaseFrame {
+  readonly type: 'rebase';
+  readonly v: number;
+  readonly key: string;
+  readonly entity: string;
+  readonly strategy: ConflictStrategyName;
+  /** Server truth for the row the mutation touched; `null` when the server deleted it. */
+  readonly row: Row | null;
+}
+
+export interface PresenceFrame {
+  readonly type: 'presence';
+  readonly v: number;
+  readonly topic: string;
+  readonly op: 'join' | 'leave' | 'update' | 'sync';
+  readonly members: readonly PresenceMember[];
+}
+
+export interface ReconnectFrame {
+  readonly type: 'reconnect';
+  readonly v: number;
+  /** Server-assigned delay. Clients must honour it so a drain redistributes instead of stampeding. */
+  readonly afterMs: number;
+  readonly reason: 'drain' | 'overload' | 'rebalance';
+}
+
+export interface UpdateAvailableFrame {
+  readonly type: 'update-available';
+  readonly v: number;
+  readonly buildId: string;
+}
+
+export type Frame =
+  | HelloFrame
+  | SubscribeFrame
+  | SnapshotFrame
+  | PatchFrame
+  | MutateFrame
+  | AckFrame
+  | RebaseFrame
+  | PresenceFrame
+  | ReconnectFrame
+  | UpdateAvailableFrame;
+
+export type FrameKind = Frame['type'];
+
+export const FRAME_KINDS: readonly FrameKind[] = [
+  'hello',
+  'subscribe',
+  'snapshot',
+  'patch',
+  'mutate',
+  'ack',
+  'rebase',
+  'presence',
+  'reconnect',
+  'update-available',
+];
+
+export function encode(frame: Frame): string {
+  return JSON.stringify(frame);
+}
+
+/** Narrow `unknown` to a `Frame` or throw `X_PROTOCOL_VERSION`. No frame is trusted unvalidated. */
+export function decode(raw: string | Uint8Array): Frame {
+  const text = typeof raw === 'string' ? raw : new TextDecoder().decode(raw);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw fail('frame is not JSON');
+  }
+  if (!isJsonObject(parsed)) throw fail('frame is not an object');
+  const version = parsed['v'];
+  if (version !== PROTOCOL_VERSION) {
+    throw new ProtocolVersionError({ got: version, expected: PROTOCOL_VERSION });
+  }
+  const kind = parsed['type'];
+  switch (kind) {
+    case 'hello':
+      return {
+        type: 'hello',
+        v: PROTOCOL_VERSION,
+        buildId: str(parsed, 'buildId'),
+        sessionId: nullableStr(parsed, 'sessionId'),
+        actorId: nullableStr(parsed, 'actorId'),
+        resume: list(parsed, 'resume').map(cursor),
+      };
+    case 'subscribe':
+      return {
+        type: 'subscribe',
+        v: PROTOCOL_VERSION,
+        op: pick(parsed, 'op', ['add', 'drop'] as const),
+        sid: str(parsed, 'sid'),
+        target: target(parsed['target']),
+      };
+    case 'snapshot':
+      return {
+        type: 'snapshot',
+        v: PROTOCOL_VERSION,
+        sid: str(parsed, 'sid'),
+        rows: list(parsed, 'rows').map(row),
+        cursor: cursor(parsed['cursor']),
+      };
+    case 'patch':
+      return {
+        type: 'patch',
+        v: PROTOCOL_VERSION,
+        sid: str(parsed, 'sid'),
+        patches: list(parsed, 'patches').map(patch),
+        lsn: str(parsed, 'lsn'),
+      };
+    case 'mutate':
+      return {
+        type: 'mutate',
+        v: PROTOCOL_VERSION,
+        key: str(parsed, 'key'),
+        seq: num(parsed, 'seq'),
+        name: str(parsed, 'name'),
+        input: parsed['input'] ?? null,
+      };
+    case 'ack':
+      return {
+        type: 'ack',
+        v: PROTOCOL_VERSION,
+        ref: str(parsed, 'ref'),
+        lsn: nullableStr(parsed, 'lsn'),
+        error: wireError(parsed['error']),
+      };
+    case 'rebase':
+      return {
+        type: 'rebase',
+        v: PROTOCOL_VERSION,
+        key: str(parsed, 'key'),
+        entity: str(parsed, 'entity'),
+        strategy: pick(parsed, 'strategy', ['server-wins', 'last-write-wins', 'custom'] as const),
+        row: parsed['row'] === null ? null : row(parsed['row']),
+      };
+    case 'presence':
+      return {
+        type: 'presence',
+        v: PROTOCOL_VERSION,
+        topic: str(parsed, 'topic'),
+        op: pick(parsed, 'op', ['join', 'leave', 'update', 'sync'] as const),
+        members: list(parsed, 'members').map(member),
+      };
+    case 'reconnect':
+      return {
+        type: 'reconnect',
+        v: PROTOCOL_VERSION,
+        afterMs: num(parsed, 'afterMs'),
+        reason: pick(parsed, 'reason', ['drain', 'overload', 'rebalance'] as const),
+      };
+    case 'update-available':
+      return { type: 'update-available', v: PROTOCOL_VERSION, buildId: str(parsed, 'buildId') };
+    default:
+      throw fail(`unknown frame type ${JSON.stringify(kind)}`);
+  }
+}
+
+/** Project any thrown value onto the wire without losing the error contract's three fields. */
+export function toWireError(error: unknown): WireError {
+  const shape = error as { code?: unknown; cause?: unknown; fix?: unknown; docs?: unknown } | null;
+  const code = typeof shape?.code === 'string' ? shape.code : 'X_PROTOCOL_VERSION';
+  const cause = typeof shape?.cause === 'string' ? shape.cause : String(error);
+  const fix = typeof shape?.fix === 'string' ? shape.fix : 'x doctor realtime';
+  return typeof shape?.docs === 'string'
+    ? { code, cause, fix, docs: shape.docs }
+    : { code, cause, fix };
+}
+
+function fail(detail: string): ProtocolVersionError {
+  return new ProtocolVersionError({ got: detail, expected: PROTOCOL_VERSION, detail });
+}
+
+function str(obj: JsonObject, key: string): string {
+  const value = obj[key];
+  if (typeof value !== 'string') throw fail(`field "${key}" must be a string`);
+  return value;
+}
+
+function nullableStr(obj: JsonObject, key: string): string | null {
+  const value = obj[key];
+  if (value === null || value === undefined) return null;
+  if (typeof value !== 'string') throw fail(`field "${key}" must be a string or null`);
+  return value;
+}
+
+function num(obj: JsonObject, key: string): number {
+  const value = obj[key];
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw fail(`field "${key}" must be a finite number`);
+  }
+  return value;
+}
+
+function pick<T extends string>(obj: JsonObject, key: string, allowed: readonly T[]): T {
+  const value = str(obj, key);
+  const found = allowed.find((candidate) => candidate === value);
+  if (found === undefined) throw fail(`field "${key}" must be one of ${allowed.join('|')}`);
+  return found;
+}
+
+function list(obj: JsonObject, key: string): JsonValue[] {
+  const value = obj[key];
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw fail(`field "${key}" must be an array`);
+  return value;
+}
+
+function row(value: unknown): Row {
+  if (!isRow(value)) throw fail('row must be an object with a string "id"');
+  return value;
+}
+
+function cursor(value: unknown): LiveCursor {
+  if (!isJsonObject(value)) throw fail('cursor must be an object');
+  return {
+    qid: str(value, 'qid'),
+    lsn: str(value, 'lsn'),
+    digest: str(value, 'digest'),
+    ids: list(value, 'ids').map((id) => {
+      if (typeof id !== 'string') throw fail('cursor.ids must be strings');
+      return id;
+    }),
+    count: num(value, 'count'),
+    at: num(value, 'at'),
+  };
+}
+
+function patch(value: unknown): RowPatch {
+  if (!isJsonObject(value)) throw fail('patch must be an object');
+  const base = {
+    op: pick(value, 'op', ['insert', 'update', 'delete'] as const),
+    id: str(value, 'id'),
+    row: value['row'] === null || value['row'] === undefined ? null : object(value['row']),
+    lsn: str(value, 'lsn'),
+  };
+  return value['index'] === undefined ? base : { ...base, index: num(value, 'index') };
+}
+
+function member(value: unknown): PresenceMember {
+  if (!isJsonObject(value)) throw fail('presence member must be an object');
+  return {
+    id: str(value, 'id'),
+    actorId: nullableStr(value, 'actorId'),
+    meta: object(value['meta'] ?? {}),
+    updatedAt: num(value, 'updatedAt'),
+  };
+}
+
+function target(value: unknown): SubscribeTarget {
+  if (!isJsonObject(value)) throw fail('subscribe.target must be an object');
+  const kind = pick(value, 'kind', ['topic', 'query'] as const);
+  if (kind === 'topic') return { kind, topic: str(value, 'topic') };
+  return {
+    kind,
+    qid: str(value, 'qid'),
+    input: value['input'] ?? null,
+    cursor:
+      value['cursor'] === null || value['cursor'] === undefined ? null : cursor(value['cursor']),
+  };
+}
+
+function object(value: unknown): JsonObject {
+  if (!isJsonObject(value)) throw fail('expected a JSON object');
+  return value;
+}
+
+function wireError(value: unknown): WireError | null {
+  if (value === null || value === undefined) return null;
+  if (!isJsonObject(value)) throw fail('ack.error must be an object or null');
+  const base = { code: str(value, 'code'), cause: str(value, 'cause'), fix: str(value, 'fix') };
+  return value['docs'] === undefined ? base : { ...base, docs: str(value, 'docs') };
+}

package/src/thundering-herd.ts

@@ -0,0 +1,141 @@
+// The named risk, mitigated in code. A deploy drops N sockets at once; if every client reconnects
+// immediately the rolling restart becomes a self-inflicted outage that outlasts the deploy.
+//
+// Three mechanisms, in the order they fire:
+//   1. drainPlan()    — the draining node assigns each client a distinct delay slot before closing
+//   2. backoffDelay() — the client's own jittered retry, for failures nobody scheduled
+//   3. AcceptBudget   — the receiving node's token bucket, so recovery sheds instead of collapsing
+
+import { type Clock, systemClock } from '@ultimat3/core';
+import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
+
+/** Injected so tests are deterministic and `local` mutators stay replayable. */
+export type Rng = () => number;
+
+export type JitterMode = 'full' | 'equal' | 'none';
+
+export interface BackoffPolicy {
+  readonly baseMs: number;
+  readonly maxMs: number;
+  readonly factor: number;
+  readonly jitter: JitterMode;
+}
+
+/**
+ * `full` jitter by default: it is the only mode that actually decorrelates a herd. `equal` keeps a
+ * floor for latency-sensitive clients; `none` exists for tests and is never a production choice.
+ */
+export const defaultBackoff: BackoffPolicy = {
+  baseMs: 500,
+  maxMs: 30_000,
+  factor: 2,
+  jitter: 'full',
+};
+
+/** Attempt is 0-based. Result is always in `[0, maxMs]`. */
+export function backoffDelay(
+  attempt: number,
+  policy: BackoffPolicy = defaultBackoff,
+  rng: Rng = Math.random,
+): number {
+  const ceiling = Math.min(policy.maxMs, policy.baseMs * policy.factor ** Math.max(0, attempt));
+  switch (policy.jitter) {
+    case 'none':
+      return Math.round(ceiling);
+    case 'equal':
+      return Math.round(ceiling / 2 + (rng() * ceiling) / 2);
+    case 'full':
+      return Math.round(rng() * ceiling);
+  }
+}
+
+export type ReconnectReason = 'drain' | 'overload' | 'rebalance';
+
+export interface DrainPlanEntry {
+  readonly socketId: string;
+  readonly afterMs: number;
+}
+
+export interface DrainPlanOptions {
+  /** Window across which reconnects are spread. Must exceed the node's own drain grace period. */
+  readonly spreadMs?: number;
+  readonly rng?: Rng;
+}
+
+/**
+ * Slot assignment, not pure randomness: socket *i* of *n* is placed in its own `spreadMs/n` slot and
+ * jittered inside it. Pure randomness clusters; slots guarantee a uniform spread even for small n,
+ * which is what makes clients redistribute across the surviving nodes instead of all landing on one.
+ */
+export function drainPlan(
+  socketIds: readonly string[],
+  options: DrainPlanOptions = {},
+): DrainPlanEntry[] {
+  const spreadMs = options.spreadMs ?? 30_000;
+  const rng = options.rng ?? Math.random;
+  const total = socketIds.length;
+  if (total === 0) return [];
+  const slot = spreadMs / total;
+  return socketIds.map((socketId, index) => ({
+    socketId,
+    afterMs: Math.round(index * slot + rng() * slot),
+  }));
+}
+
+export function reconnectFrame(afterMs: number, reason: ReconnectReason): Frame {
+  return { type: 'reconnect', v: PROTOCOL_VERSION, afterMs, reason };
+}
+
+export interface AcceptBudgetOptions {
+  /** Sustained accepts per second per node during recovery. */
+  readonly perSecond: number;
+  /** Burst allowance, so a normal reconnect trickle is never delayed. */
+  readonly burst?: number;
+  readonly clock?: Clock;
+}
+
+/**
+ * Token bucket on the accept path. A node that cannot afford a new socket must say so with a
+ * `reconnect` frame carrying a delay — refusing without a delay just moves the herd next door.
+ */
+export class AcceptBudget {
+  readonly #perSecond: number;
+  readonly #burst: number;
+  readonly #clock: Clock;
+  #tokens: number;
+  #lastRefill: number;
+
+  constructor(options: AcceptBudgetOptions) {
+    this.#perSecond = Math.max(1, options.perSecond);
+    this.#burst = Math.max(1, options.burst ?? options.perSecond);
+    this.#clock = options.clock ?? systemClock;
+    this.#tokens = this.#burst;
+    this.#lastRefill = this.#clock.monotonic();
+  }
+
+  tryAccept(): boolean {
+    this.#refill();
+    if (this.#tokens < 1) return false;
+    this.#tokens -= 1;
+    return true;
+  }
+
+  /** Delay to hand a refused client, jittered so refusals do not re-synchronise the herd. */
+  retryAfterMs(rng: Rng = Math.random): number {
+    const base = Math.ceil(1000 / this.#perSecond);
+    return Math.round(base + rng() * base * 4);
+  }
+
+  get tokens(): number {
+    this.#refill();
+    return Math.floor(this.#tokens);
+  }
+
+  #refill(): void {
+    const now = this.#clock.monotonic();
+    const elapsed = now - this.#lastRefill;
+    if (elapsed <= 0) return;
+    this.#lastRefill = now;
+    this.#tokens = Math.min(this.#burst, this.#tokens + (elapsed / 1000) * this.#perSecond);
+  }
+}

package/src/transport-env.ts

@@ -0,0 +1,104 @@
+// Single responsibility: environment → fanout transport. The one place a boot decides whether this
+// process fans changes out inside its own heap or over NATS, so `x dev`, a `sync` container and any
+// custom host resolve it identically. The KV bucket and the presence TTL are decided here too:
+// the bucket's whole-stream age limit and `PresenceRegistry`'s TTL are the same number seen from
+// two sides, and a caller that had to pass each one separately could quietly set them apart.
+
+import type { Clock } from '@ultimat3/core';
+import type { Transport } from './fanout';
+import { InProcessTransport } from './fanout';
+import { assertBucket } from './nats-jetstream';
+import type { NatsStream, NatsTarget } from './nats-socket';
+import { NatsTransport } from './nats-transport';
+
+/** The keys read here, and nothing else. Named once so docs and tests cannot drift from the code. */
+export const TRANSPORT_ENV_KEYS = ['NATS_URL', 'NATS_KV_BUCKET'] as const;
+
+/**
+ * One bucket per deployment, not per cluster: two apps sharing a nats-server would otherwise share
+ * one presence namespace, and a room name that collided would list the other app's members.
+ */
+export const DEFAULT_PRESENCE_BUCKET = 'x_presence';
+
+/** Member TTL. A client heartbeats at a third of it, so one lost beat is never a false leave. */
+export const DEFAULT_PRESENCE_TTL_MS = 30_000;
+
+export type TransportEnvironment = Readonly<Record<string, string | undefined>>;
+
+export interface TransportSelection {
+  readonly transport: Transport;
+  /** `embedded` fans out in this process only; `external` reaches every node on the bus. */
+  readonly mode: 'embedded' | 'external';
+  /**
+   * Why this transport, in one line: the env key that selected it, or what to set to change it.
+   * A boot prints it, so "does this process reach the other nodes" is never a guess — and it is
+   * the env key rather than the URL, because a NATS url carries credentials.
+   */
+  readonly detail: string;
+  /** Null in embedded mode: nothing is stored on a bus, so there is no bucket to name. */
+  readonly bucket: string | null;
+  /** What `PresenceRegistry` must be given, so its TTL and the bucket's cannot disagree. */
+  readonly presenceTtlMs: number;
+  /**
+   * Dial now rather than on the first change nobody receives. Selection itself stays pure — it
+   * parses env and constructs, it does not touch a socket — so a boot can order its dials.
+   * Embedded resolves immediately: there is nothing to reach.
+   */
+  connect(): Promise<void>;
+}
+
+export interface SelectTransportOptions {
+  readonly presenceTtlMs?: number | undefined;
+  readonly clock?: Clock | undefined;
+  /** Injected so a boot — reconnect included — can be proven with no network. */
+  readonly open?: ((target: NatsTarget) => Promise<NatsStream>) | undefined;
+}
+
+const nonEmpty = (value: string | undefined): string | undefined =>
+  value === undefined || value.trim().length === 0 ? undefined : value.trim();
+
+/**
+ * No url means the in-process transport — the same "an unset variable means the embedded default"
+ * law the db, mail, storage and replication bindings follow. The bucket name is validated here
+ * rather than on first connect: a typo'd bucket is a boot that reports a healthy bus and then
+ * fails every presence write, which is the failure this whole selector exists to move earlier.
+ */
+export function selectTransport(
+  env: TransportEnvironment,
+  options: SelectTransportOptions = {},
+): TransportSelection {
+  const presenceTtlMs = options.presenceTtlMs ?? DEFAULT_PRESENCE_TTL_MS;
+  const url = nonEmpty(env['NATS_URL']);
+
+  if (url === undefined) {
+    const transport = new InProcessTransport(
+      options.clock === undefined ? {} : { clock: options.clock },
+    );
+    return {
+      transport,
+      mode: 'embedded',
+      detail: 'in-process fanout — set NATS_URL to reach the other nodes',
+      bucket: null,
+      presenceTtlMs,
+      connect: () => Promise.resolve(),
+    };
+  }
+
+  const bucket = nonEmpty(env['NATS_KV_BUCKET']) ?? DEFAULT_PRESENCE_BUCKET;
+  assertBucket(bucket);
+  const transport = new NatsTransport({
+    url,
+    bucket,
+    presenceTtlMs,
+    ...(options.clock === undefined ? {} : { clock: options.clock }),
+    ...(options.open === undefined ? {} : { open: options.open }),
+  });
+  return {
+    transport,
+    mode: 'external',
+    detail: 'NATS_URL',
+    bucket,
+    presenceTtlMs,
+    connect: () => transport.connect(),
+  };
+}