@ultimat3/realtime 1.2.0 → 3.0.0

package/src/client-frames.ts

@@ -0,0 +1,175 @@
+// What a RECEIVED frame does to client state — the mirror of `sync-node.ts`'s inbound handler,
+// and the only inbound surface `client.ts` exposes. `ClientFrameTarget` is the point: it names
+// every piece of the client a frame may touch, so the blast radius of a new frame kind is a
+// reviewable list rather than "whatever the router could reach through `this`".
+
+import { advance } from './cursor';
+import type { JsonObject, JsonValue } from './json';
+import type { Registration, RowWindows } from './live-rows';
+import type { LocalStore, TableMap } from './local-store';
+import type { OfflineQueue } from './offline-queue';
+import { type RebaseLog, reconcile, rollbackMutation } from './rebase';
+import type { Frame, PresenceMember } from './sync-protocol';
+
+/** Declared with the window it projects; re-exported here because the router is what writes it. */
+export type { LiveState, Registration } from './live-rows';
+
+/**
+ * Everything an inbound frame is allowed to reach. Narrow on purpose — a router that took the
+ * client itself could touch the reconnect timer, the socket and the outbound path, none of which
+ * a received frame has any business writing.
+ */
+export interface ClientFrameTarget<T extends TableMap = TableMap> {
+  registration(sid: string): Registration | undefined;
+  /** The projection every live window renders through. Rows live in its map, never on a frame. */
+  readonly windows: RowWindows;
+  topicHandlers(topic: string): ReadonlySet<(message: JsonObject) => void> | undefined;
+  readonly queue: OfflineQueue | undefined;
+  readonly store: LocalStore<T> | undefined;
+  readonly log: RebaseLog<T> | undefined;
+  /** The client's clock. A cursor carries `at`, and nothing here may read `Date.now()`. */
+  now(): number;
+  /** A newer build is live; the app decides when to reload. */
+  setUpdate(buildId: string | null): void;
+  /** The node assigned this socket its own delay before closing it. */
+  scheduleReconnect(afterMs: number | null): void;
+  closeSocket(code: number, reason: string): void;
+  notifyQueueChange(): void;
+  /** Where a promise nobody awaits reports its failure. The client's `onError`, never a swallow. */
+  detach(work: Promise<unknown>): void;
+}
+
+/**
+ * The server refused a mutation: undo its optimistic half. Tier 2 has neither a store nor a log,
+ * so there is nothing optimistic to undo and the queue entry is the whole record.
+ */
+function rollbackFailed<T extends TableMap>(key: string, target: ClientFrameTarget<T>): void {
+  const store = target.store;
+  const log = target.log;
+  if (!store || !log) return;
+  // One batch for the whole undo: the rollback and every mutator replayed behind it are one
+  // frame's worth of change, so a live window holding those rows renders once.
+  store.identity.batch(() => {
+    rollbackMutation({ store, log, key });
+  });
+}
+
+/**
+ * The server took it, so the write is no longer optimistic: the journal goes (there is nothing to
+ * roll back TO any more — this write is what the server has) and the rebase entry goes with it, or
+ * every later reconcile replays a mutation the server already applied, over rows that have moved
+ * on. The row itself stays exactly as the twin left it — an accepted write does not flicker.
+ *
+ * Both calls are no-ops for a key nothing holds, which is what makes this safe as the tail of the
+ * `rebase` + `ack` pair: the rebase in front of it has already reconciled and dropped the same key.
+ */
+function commitAccepted<T extends TableMap>(key: string, target: ClientFrameTarget<T>): void {
+  target.store?.commit(key);
+  target.log?.drop(key);
+}
+
+/** Presence members cross the topic channel as plain JSON, like every other channel message. */
+function memberJson(member: PresenceMember): JsonValue {
+  return { id: member.id, actorId: member.actorId, meta: member.meta, updatedAt: member.updatedAt };
+}
+
+export function applyFrame<T extends TableMap>(frame: Frame, target: ClientFrameTarget<T>): void {
+  switch (frame.type) {
+    case 'snapshot': {
+      const registration = target.registration(frame.sid);
+      if (!registration) return;
+      // The entity is the server's, and it is what upgrades this window from its own private scope
+      // to the one every other query over the same entity shares.
+      target.windows.snapshot(registration, frame.entity ?? null, frame.rows);
+      registration.cursor = frame.cursor;
+      registration.setCursor(frame.cursor);
+      registration.setState('live');
+      return;
+    }
+    case 'patch': {
+      const registration = target.registration(frame.sid);
+      if (registration) {
+        target.windows.patch(registration, frame.patches);
+        // The cursor moves with the patches, not only with a snapshot. Left behind, `cursor.at`
+        // froze at the last snapshot and `shouldResnapshot`'s lag check answered "re-snapshot" for
+        // every client connected longer than `maxLagMs` — the delta resume the retained change
+        // window exists for, dead exactly during the deploy storm it was built for. An empty lsn
+        // is a tier-1 channel frame's, so it never rewinds one.
+        if (registration.cursor && frame.lsn !== '') {
+          const next = advance(registration.cursor, frame.patches, frame.lsn, target.now());
+          registration.cursor = next;
+          registration.setCursor(next);
+        }
+        registration.setState('live');
+        return;
+      }
+      // No registration: it is a tier-1 channel message on `sid = topic`.
+      const handlers = target.topicHandlers(frame.sid);
+      if (!handlers) return;
+      for (const patch of frame.patches) {
+        if (patch.row === null) continue;
+        for (const handler of handlers) handler(patch.row);
+      }
+      return;
+    }
+    case 'ack': {
+      const queue = target.queue;
+      // A refused mutation is not a mutation: its optimistic twin has to come off the screen, and
+      // its rebase entry has to leave the log, or a denied write stays rendered forever and every
+      // later reconcile replays it. `ref` is the mutation key — the same key the `mutate` frame
+      // carried — which is what makes both halves reachable from one frame.
+      if (frame.error) rollbackFailed(frame.ref, target);
+      else commitAccepted(frame.ref, target);
+      // `ack`/`fail` mutate the queue synchronously and persist asynchronously; chaining rather
+      // than notifying right after the call keeps this correct even if that ordering ever
+      // changes, and it still fires exactly once the persisted write actually lands.
+      const settled = frame.error ? queue?.fail(frame.ref, frame.error) : queue?.ack(frame.ref);
+      if (settled) target.detach(settled.then(() => target.notifyQueueChange()));
+      return;
+    }
+    case 'rebase': {
+      const store = target.store;
+      const log = target.log;
+      if (!store || !log) return;
+      // One batch for the whole reconcile — a rollback, server truth and every replayed mutator
+      // are one frame's worth of change, so a live window holding those rows renders once.
+      store.identity.batch(() => {
+        reconcile({
+          store,
+          log,
+          ack: {
+            key: frame.key,
+            entity: frame.entity,
+            id: frame.row?.id ?? frame.key,
+            row: frame.row,
+          },
+        });
+      });
+      return;
+    }
+    case 'reconnect': {
+      // Order is load-bearing: arming first is what makes the close this triggers keep the delay
+      // the node assigned to *this* socket instead of falling back to a local backoff.
+      target.scheduleReconnect(frame.afterMs);
+      target.closeSocket(1001, frame.reason);
+      return;
+    }
+    case 'update-available': {
+      target.setUpdate(frame.buildId);
+      return;
+    }
+    case 'presence': {
+      const handlers = target.topicHandlers(frame.topic);
+      if (!handlers) return;
+      const message: JsonObject = { op: frame.op, members: frame.members.map(memberJson) };
+      for (const handler of handlers) handler(message);
+      return;
+    }
+    case 'hello':
+    case 'subscribe':
+    case 'mutate':
+      // Client-authored frames: never received. Ignored rather than thrown, so a future
+      // bidirectional use of the same kind cannot break an old client.
+      return;
+  }
+}

package/src/client-heartbeat.ts

@@ -0,0 +1,77 @@
+// The client's liveness pass: re-announce this socket before the node forgets it, and notice a
+// socket that has stopped answering. A policy (when to beat, when to give up), not a wire detail —
+// which is why it is here and not inside `client.ts`'s connection lifecycle.
+
+import type { Scheduler } from './thundering-herd';
+
+/**
+ * The same 15s as `realtime.heartbeatMs` in `@ultimat3/core`'s config, restated rather than read:
+ * that value is server configuration and this is browser code, so the client cannot reach it. The
+ * two are kept equal on purpose — a node's presence TTL is sized against this interval.
+ */
+export const DEFAULT_HEARTBEAT_MS = 15_000;
+
+export interface HeartbeatOptions {
+  /** `0` (or less) disables the pass entirely — the shape a test that owns the clock wants. */
+  readonly intervalMs: number;
+  readonly schedule: Scheduler;
+  readonly now: () => number;
+  /** Re-announces this socket. Called only while the socket is still answering. */
+  readonly beat: () => void;
+  /** Two windows of silence: the socket is half-open and only this client can end it. */
+  readonly onSilence: () => void;
+}
+
+/**
+ * One armed tick at a time, re-armed by itself. It is deliberately NOT an interval: the reconnect
+ * timer is the same injected `Scheduler` seam, and a client is either beating on a live socket or
+ * backing off towards a new one — never both, so one armed timer is the whole mechanism.
+ */
+export class Heartbeat {
+  readonly #options: HeartbeatOptions;
+  #cancel: (() => void) | null = null;
+  #lastSeen = 0;
+
+  constructor(options: HeartbeatOptions) {
+    this.#options = options;
+  }
+
+  /** The socket is up. `now` seeds the silence window, so the first tick judges this connection. */
+  start(now: number): void {
+    this.stop();
+    if (this.#options.intervalMs <= 0) return;
+    this.#lastSeen = now;
+    this.#arm();
+  }
+
+  /** A frame arrived. Anything counts: the point is that bytes still cross in this direction. */
+  saw(now: number): void {
+    this.#lastSeen = now;
+  }
+
+  stop(): void {
+    const cancel = this.#cancel;
+    this.#cancel = null;
+    cancel?.();
+  }
+
+  #arm(): void {
+    this.#cancel = this.#options.schedule(() => {
+      this.#cancel = null;
+      this.#tick();
+    }, this.#options.intervalMs);
+  }
+
+  #tick(): void {
+    const now = this.#options.now();
+    // Two windows, not one: a beat and the answer to it share the window they were sent in, so a
+    // single quiet interval is a slow round trip and not a dead socket. Nothing is re-armed after
+    // a silence — `onSilence` drops the socket, and the next `start()` is the next connection's.
+    if (now - this.#lastSeen > this.#options.intervalMs * 2) {
+      this.#options.onSilence();
+      return;
+    }
+    this.#options.beat();
+    this.#arm();
+  }
+}

package/src/client-mutations.ts

@@ -0,0 +1,114 @@
+// 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

@@ -0,0 +1,54 @@
+// 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()];
+  }
+}