@ultimat3/realtime 20.2.1 → 21.0.0

package/src/wire-channel.ts

@@ -0,0 +1,116 @@
+// Decoding the channel frames (plan 101, slices 09–10): `records` writes the page store, `events`
+// never does, `replay-gap` is the node's verdict that a socket lost a `records` frame. Held to the
+// same ceilings as every other kind — a `records` frame is rows a socket could otherwise size.
+
+import { isWriteDigest, type Row, WRITE_DIGEST_LENGTH } from '@ultimat3/core/page';
+import type {
+  ChannelAdopt,
+  ChannelEventsFrame,
+  ChannelRecordsFrame,
+  ChannelRemove,
+  ChannelSince,
+  ChannelSubscribeTarget,
+  ReplayGapFrame,
+} from './channel-wire';
+import { isJsonObject, type JsonObject } from './json';
+import { fail, list, num, object, str } from './wire-read';
+import { FRAME_LIMITS, PROTOCOL_VERSION } from './wire-version';
+
+export function records(parsed: JsonObject): ChannelRecordsFrame {
+  const base = {
+    type: 'records',
+    v: PROTOCOL_VERSION,
+    channel: str(parsed, 'channel'),
+    seq: num(parsed, 'seq'),
+    epoch: str(parsed, 'epoch'),
+  } as const;
+  const adopt = parsed['adopt'] === undefined ? undefined : adoptOf(parsed['adopt']);
+  const remove = parsed['remove'] === undefined ? undefined : removeOf(parsed['remove']);
+  const write = parsed['write'];
+  if (write !== undefined && !isWriteDigest(write)) {
+    throw fail(`records.write must be a ${WRITE_DIGEST_LENGTH}-character lowercase hex digest`);
+  }
+  return {
+    ...base,
+    ...(adopt === undefined ? {} : { adopt }),
+    ...(remove === undefined ? {} : { remove }),
+    ...(write === undefined ? {} : { write }),
+  };
+}
+
+export function events(parsed: JsonObject): ChannelEventsFrame {
+  return {
+    type: 'events',
+    v: PROTOCOL_VERSION,
+    channel: str(parsed, 'channel'),
+    event: object(parsed['event']),
+  };
+}
+
+export function replayGap(parsed: JsonObject): ReplayGapFrame {
+  return {
+    type: 'replay-gap',
+    v: PROTOCOL_VERSION,
+    channel: str(parsed, 'channel'),
+    epoch: str(parsed, 'epoch'),
+  };
+}
+
+/** `subscribe.target` for a declared channel: a name, string params (capped), an optional resume. */
+export function channelTarget(value: JsonObject): ChannelSubscribeTarget {
+  const raw = object(value['params'] ?? {});
+  const entries = Object.entries(raw);
+  if (entries.length > FRAME_LIMITS.channelParams) {
+    throw fail(
+      `channel params carry ${entries.length}, over the limit of ${FRAME_LIMITS.channelParams}`,
+    );
+  }
+  const params: Record<string, string> = {};
+  for (const [key, param] of entries) {
+    if (typeof param !== 'string') throw fail(`channel param "${key}" must be a string`);
+    params[key] = param;
+  }
+  const base = { kind: 'channel', channel: str(value, 'channel'), params } as const;
+  return value['since'] === undefined || value['since'] === null
+    ? base
+    : { ...base, since: sinceOf(value['since']) };
+}
+
+function sinceOf(value: unknown): ChannelSince {
+  if (!isJsonObject(value)) throw fail('channel since must be an object');
+  const seq = num(value, 'seq');
+  if (!Number.isInteger(seq) || seq < 0) throw fail('channel since.seq must be a whole number');
+  return { epoch: str(value, 'epoch'), seq };
+}
+
+/** type → key → row. Every row an object, and the whole frame under the snapshot row ceiling. */
+function adoptOf(value: unknown): ChannelAdopt {
+  if (!isJsonObject(value)) throw fail('records.adopt must be an object');
+  let total = 0;
+  const out: Record<string, Readonly<Record<string, Row>>> = {};
+  for (const [type, keyed] of Object.entries(value)) {
+    if (!isJsonObject(keyed)) throw fail(`records.adopt.${type} must be an object`);
+    const rows: Record<string, Row> = {};
+    for (const [key, row] of Object.entries(keyed)) {
+      total += 1;
+      if (total > FRAME_LIMITS.rows) {
+        throw fail(`records.adopt carries more than ${FRAME_LIMITS.rows} rows`);
+      }
+      rows[key] = object(row);
+    }
+    out[type] = rows;
+  }
+  return out;
+}
+
+function removeOf(value: unknown): ChannelRemove {
+  if (!isJsonObject(value)) throw fail('records.remove must be an object');
+  const out: Record<string, readonly string[]> = {};
+  for (const type of Object.keys(value)) {
+    out[type] = list(value, type, FRAME_LIMITS.rows, `records.remove.${type}`).map((key) => {
+      if (typeof key !== 'string') throw fail(`records.remove.${type} must hold strings`);
+      return key;
+    });
+  }
+  return out;
+}

package/src/wire-read.ts

@@ -0,0 +1,86 @@
+// The decoder's primitives: every field a frame carries is read through one of these, and every
+// refusal is `X_PROTOCOL_VERSION` with the field named. Shared by `sync-protocol.ts` and
+// `wire-channel.ts`, so the channel frames are held to the same ceilings as every other kind.
+
+import { isJsonObject, type JsonObject, type JsonValue } from './json';
+import { ProtocolVersionError } from './page-errors';
+import { FRAME_LIMITS, PROTOCOL_VERSION } from './wire-version';
+
+export function fail(detail: string): ProtocolVersionError {
+  return new ProtocolVersionError({ got: detail, expected: PROTOCOL_VERSION, detail });
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export 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;
+}
+
+/**
+ * An array field, with the ceiling the caller had to choose. `max` is required rather than
+ * defaulted: a new list field on a new frame is a new thing an authenticated socket can make
+ * arbitrarily large, and a default would let one ship without anyone deciding its size.
+ */
+export function list(obj: JsonObject, key: string, max: number, label = key): JsonValue[] {
+  const value = obj[key];
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw fail(`field "${label}" must be an array`);
+  if (value.length > max) {
+    throw fail(`field "${label}" carries ${value.length} entries, over the limit of ${max}`);
+  }
+  return value;
+}
+
+/**
+ * A client-supplied value, walked ITERATIVELY to its limits. Iteratively because the thing being
+ * refused is a stack overflow: `queryHash` -> `canonicalJson` recurses over exactly this value, so a
+ * depth check that recursed would be the same crash one frame earlier.
+ */
+export function bounded(value: JsonValue, label: string): JsonValue {
+  const stack: { node: JsonValue; depth: number }[] = [{ node: value, depth: 1 }];
+  let seen = 0;
+  while (stack.length > 0) {
+    // `pop` cannot answer undefined here — the loop guard is the length — and the check is what
+    // makes that readable to the compiler without a cast.
+    const next = stack.pop();
+    if (next === undefined) break;
+    seen += 1;
+    if (seen > FRAME_LIMITS.inputNodes) {
+      throw fail(`field "${label}" holds more than ${FRAME_LIMITS.inputNodes} values`);
+    }
+    if (next.depth > FRAME_LIMITS.inputDepth) {
+      throw fail(`field "${label}" is nested deeper than ${FRAME_LIMITS.inputDepth}`);
+    }
+    if (next.node === null || typeof next.node !== 'object') continue;
+    const children = Array.isArray(next.node) ? next.node : Object.values(next.node);
+    for (const child of children) stack.push({ node: child, depth: next.depth + 1 });
+  }
+  return value;
+}
+
+export function object(value: unknown): JsonObject {
+  if (!isJsonObject(value)) throw fail('expected a JSON object');
+  return value;
+}

package/src/wire-version.ts

@@ -0,0 +1,44 @@
+// The wire's version and its hard ceilings — a leaf, so every reader (`sync-protocol.ts`,
+// `wire-read.ts`, `wire-channel.ts`) shares one number and one table with no import cycle.
+
+import { CURSOR_ID_LIMIT } from './cursor';
+
+/**
+ * **3 since 21.0.0** (plan 101), when the socket stopped carrying writes: the `mutate` and
+ * `rebase` kinds are deleted, so a client one major behind sends a frame this node refuses with
+ * `X_PROTOCOL_VERSION` — its instruction is the rebuild that client needs. Writes are HTTP
+ * (`useMutation`). Slice 09's `records` frame reuses this bump; it does not take another.
+ *
+ * 2 since 2026-08-24, when `cursor.digest` and `cursor.count` were deleted. The version guards
+ * incompatibility, never novelty — an additive optional field (`snapshot.entity`) and a removed
+ * field read through `list()` (`hello.resume`) both stayed at 1, because `decode` is a whitelist
+ * and `list()` answers `[]` for an absent field. `cursor()` is the other kind of reader: it reads
+ * through `str`/`num`, which THROW on an absent field, so a cursor without those two is a frame a
+ * node or a client one deploy behind cannot read — in BOTH directions, since a cursor rides the
+ * client's `subscribe` and the node's `snapshot`. That is exactly what this number refuses, with
+ * one instruction instead of a per-frame "field \"digest\" must be a string".
+ */
+export const PROTOCOL_VERSION = 3;
+
+/**
+ * What one frame may contain. Hard ceilings a caller cannot widen — the shape
+ * `packages/mcp/src/query-limits.ts` uses — because every one of them is read off a socket the
+ * node has already paid for: an unbounded `cursor.ids` was consumed raw into a `Set`, and an
+ * `input` of arbitrary depth reached `canonicalJson`, which recurses.
+ *
+ * Every number clears what this node itself produces, or the decoder refuses its own frames on
+ * the next reconnect: `cursorIds` is `CURSOR_ID_LIMIT`, `patches` clears
+ * `defaultReconnectBudget.maxPatches`.
+ */
+export const FRAME_LIMITS = Object.freeze({
+  cursorIds: CURSOR_ID_LIMIT,
+  patches: 4_096,
+  rows: 10_000,
+  members: 4_096,
+  /** Nesting one `input` may reach. 32 is far past any query's real argument shape. */
+  inputDepth: 32,
+  /** Values one `input` may hold in total, so a flat-but-enormous object is refused too. */
+  inputNodes: 10_000,
+  /** Params one channel subscribe may name. A channel declares a handful; a client picks none. */
+  channelParams: 16,
+});

package/src/client-mutations.ts

@@ -1,114 +0,0 @@
-// The outbound mutation path: the optimistic twin, the durable queue entry, and the sender the
-// drain hands each frame to. One file because those are the three places a single intent is
-// recorded, and an intent that reaches two of them is the divergence tier 3 exists to prevent.
-
-import { uuid } from '@ultimat3/core';
-import type { ClientSocket, MutatorRef } from './client-contract';
-import { TransportUnavailableError } from './errors';
-import type { JsonValue } from './json';
-import type { LocalStore, TableMap } from './local-store';
-import { type MutationSender, mutateFrame, type OfflineQueue } from './offline-queue';
-import type { RebaseLog } from './rebase';
-import { encode, type Frame } from './sync-protocol';
-
-/**
- * Queued bytes past which the drain stops rather than adds. The same number the node uses at its
- * end of the socket (`DEFAULT_MAX_BUFFERED_BYTES`), and deliberately NOT imported from it: this is
- * browser code, and `socket.ts` is the node's socket registry, its metrics and its close codes —
- * one import pulls the whole server half into the tab's bundle to read an integer. The node's two
- * spellings were merged because they configure one buffer on one side; these are two sides.
- */
-export const MAX_BUFFERED_BYTES = 1024 * 1024;
-
-/** Everything the mutation path touches. Narrow on purpose, exactly like `ClientFrameTarget`. */
-export interface MutationDeps<T extends TableMap = TableMap> {
-  readonly store: LocalStore<T> | undefined;
-  readonly queue: OfflineQueue | undefined;
-  readonly log: RebaseLog<T> | undefined;
-  readonly now: () => number;
-  /** Read per send, never captured: the socket a drain started on may already be gone. */
-  socket(): ClientSocket | null;
-  send(frame: Frame): void;
-}
-
-/**
- * Record one intent everywhere it has to be recorded: the local store (so the UI moves now), the
- * rebase log (so it can be taken back) and the durable queue (so it survives the tab). Nothing is
- * sent here — `drain` is the only thing that puts a mutation on a socket, and with no queue at all
- * (tier 2) the frame goes straight out because there is nothing to drain it from later.
- */
-export async function recordMutation<T extends TableMap>(
-  deps: MutationDeps<T>,
-  mutator: MutatorRef<T>,
-  input: JsonValue,
-  key?: string,
-): Promise<void> {
-  const idempotencyKey = key ?? `${mutator.name}:${uuid()}`;
-  const { store, queue } = deps;
-  const local = mutator.local;
-  const existing = queue?.find(idempotencyKey);
-  const queued = await queue?.enqueue({
-    key: idempotencyKey,
-    name: mutator.name,
-    input,
-    at: deps.now(),
-  });
-  // Identity, not a second copy of the queue's collapse rule: `enqueue` hands back the SAME entry
-  // when it collapses and a new one when it does not. A repeated key is ONE intent whose twin is
-  // already applied — applying it again double-counts the write (a like becomes two) and replaces
-  // the log entry a rollback would have undone to the pre-mutation row.
-  const collapsed = existing !== undefined && queued === existing;
-  if (store && local && !collapsed) {
-    store.apply(idempotencyKey, (tx) => local(tx, input));
-    deps.log?.record({
-      key: idempotencyKey,
-      seq: queued?.seq ?? 0,
-      entity: mutator.entity ?? mutator.name,
-      strategy: mutator.conflict ?? 'server-wins',
-      apply: (tx) => local(tx, input),
-    });
-  }
-  if (queue) return;
-  deps.send(
-    mutateFrame({
-      key: idempotencyKey,
-      seq: 0,
-      name: mutator.name,
-      input,
-      enqueuedAt: deps.now(),
-      attempts: 0,
-      status: 'pending',
-      error: null,
-    }),
-  );
-}
-
-/**
- * The queue's sender. Throwing is how a sender declines: the queue keeps that mutation pending,
- * stops the pass rather than reordering the ones behind it, and the next drain resumes there.
- *
- * Backpressure is a decline and not a failure — the frames already queued in the tab are ones the
- * socket has not managed to write, so adding to them is how a client sends a burst it will never
- * see acknowledged. A socket that does not report `bufferedAmount` is treated as never backed up.
- */
-export function mutationSender<T extends TableMap>(deps: MutationDeps<T>): MutationSender {
-  return async (mutation) => {
-    const socket = deps.socket();
-    if (!socket) {
-      throw new TransportUnavailableError({
-        transport: 'websocket',
-        reason: 'the socket went away before this mutation reached it',
-        fix: 'it stays queued: await useMutationQueue().drain() once useConnection().online',
-      });
-    }
-    const buffered = socket.bufferedAmount ?? 0;
-    if (buffered > MAX_BUFFERED_BYTES) {
-      throw new TransportUnavailableError({
-        transport: 'websocket',
-        reason: `${buffered} bytes are already queued on this socket, over the ${MAX_BUFFERED_BYTES} ceiling`,
-        fix: 'it stays queued: await useMutationQueue().drain() once the socket has caught up',
-      });
-    }
-    socket.send(encode(mutateFrame(mutation)));
-  };
-}

package/src/client-topics.ts

@@ -1,54 +0,0 @@
-// The client's channel book: which handlers hold which topic, and the one frame that announces a
-// membership. Split out of `client.ts` because the announcement has two callers that must never
-// disagree — `subscribe()` and the reconnect replay — and one of them was missing.
-
-import type { Topic } from './channel';
-import type { JsonObject } from './json';
-import { PROTOCOL_VERSION, type SubscribeFrame } from './sync-protocol';
-
-export type TopicHandler = (message: JsonObject) => void;
-
-/**
- * The membership frame. `sid` is the topic itself: a channel subscription is identified by what it
- * is subscribed to, so re-sending it after a reconnect re-establishes the same membership rather
- * than a second one — and on the node, sending it again IS the presence heartbeat.
- */
-export function topicSubscribeFrame(name: string, op: 'add' | 'drop'): SubscribeFrame {
-  return {
-    type: 'subscribe',
-    v: PROTOCOL_VERSION,
-    op,
-    sid: name,
-    target: { kind: 'topic', topic: name },
-  };
-}
-
-/** Topic -> the handlers holding it. One entry per topic, however many components subscribed. */
-export class TopicBook {
-  readonly #topics = new Map<string, Set<TopicHandler>>();
-
-  add(name: Topic, handler: TopicHandler): void {
-    const handlers = this.#topics.get(name) ?? new Set<TopicHandler>();
-    handlers.add(handler);
-    this.#topics.set(name, handlers);
-  }
-
-  /** True when that was the last holder, so the caller is the one that sends the drop frame. */
-  remove(name: Topic, handler: TopicHandler): boolean {
-    const handlers = this.#topics.get(name);
-    if (!handlers) return false;
-    handlers.delete(handler);
-    if (handlers.size > 0) return false;
-    this.#topics.delete(name);
-    return true;
-  }
-
-  handlers(name: string): ReadonlySet<TopicHandler> | undefined {
-    return this.#topics.get(name);
-  }
-
-  /** Every membership this client still holds — what a reconnect has to re-announce. */
-  names(): readonly string[] {
-    return [...this.#topics.keys()];
-  }
-}