@ultimat3/realtime 20.2.1 → 22.0.0

package/src/client-channels.ts

@@ -0,0 +1,359 @@
+// The client's declared channels: one membership per topic however many components hold it, the
+// per-channel cursor that decides duplicate from new, and the catch-up read a `replay-gap` or a
+// new epoch triggers. `records` frames go to the store and nowhere else; `events` go to handlers.
+
+import { type PresenceEvent, readPresence } from './channel-presence';
+import type { JsonObject } from './json';
+import { carriedBy, type RecordKey } from './record-key';
+import type { RecordStore } from './record-store';
+import type {
+  ChannelEventsFrame,
+  ChannelRecordsFrame,
+  ReplayGapFrame,
+  SubscribeFrame,
+} from './sync-protocol';
+import { PROTOCOL_VERSION } from './wire-version';
+
+/** What a browser needs of a `channel()` declaration: its name, its topic rule, its catch-up read. */
+export interface ChannelRef<K extends string = string> {
+  readonly name: string;
+  readonly catchUp: string;
+  topic(params: Readonly<Record<K, string>>): string;
+}
+
+export type ChannelState = 'joining' | 'live' | 'catching-up' | 'offline' | 'failed';
+
+export interface ChannelHandlers {
+  /** An app's own ephemeral `events` frame on this channel. Never written to the store. */
+  readonly onEvent?: (event: JsonObject) => void;
+  /** A presence roster or delta — the `events` frames `readPresence` recognises. */
+  readonly onPresence?: (event: PresenceEvent) => void;
+}
+
+/** Everything the book reaches on the client. Narrow, like `ClientFrameTarget`. */
+export interface ChannelBookDeps {
+  readonly store: RecordStore;
+  send(frame: SubscribeFrame): void;
+  connected(): boolean;
+  /** Re-run the channel's catch-up read; its records land in the store through the transport. */
+  catchUp(query: string, params: Readonly<Record<string, string>>): Promise<unknown>;
+  report(error: unknown): void;
+  /**
+   * When a failed catch-up tries again on its own, on the client's reconnect curve. Absent, a
+   * failed read waits for the next open of the socket or the next gap.
+   */
+  readonly retry?: ((attempt: number, run: () => void) => () => void) | undefined;
+}
+
+interface Entry {
+  readonly topic: string;
+  readonly name: string;
+  readonly catchUp: string;
+  readonly params: Readonly<Record<string, string>>;
+  readonly holders: Set<ChannelHandlers>;
+  readonly listeners: Set<() => void>;
+  state: ChannelState;
+  error: unknown;
+  /** The epoch the cursor counts in; `null` before the first frame. */
+  epoch: string | null;
+  /** Highest seq with no hole below it — what a resubscribe resumes from. */
+  contiguous: number | null;
+  /** Applied seqs above `contiguous`: a replay that fills a hole is new, one above is a duplicate. */
+  readonly above: Set<number>;
+  /** Frames that arrived while the catch-up read was in flight, applied after it lands. */
+  buffered: ChannelRecordsFrame[] | null;
+  /**
+   * A gap announced while a read was in flight: one more read follows it, in this epoch (or the
+   * current one when the gap named none). A flag, never a count — the `coalesceReloads` shape.
+   */
+  again: { readonly epoch: string | undefined } | null;
+  /** The read is not in flight: it failed, and waits for a retry with `buffered` still held. */
+  waiting: boolean;
+  /** Consecutive failed reads — the retry curve's attempt number. */
+  failures: number;
+  /** Disarms the scheduled retry. */
+  disarm: (() => void) | null;
+}
+
+export interface ChannelMembership extends Disposable {
+  readonly topic: string;
+  state(): ChannelState;
+  error(): unknown;
+  onChange(listener: () => void): () => void;
+  release(): void;
+}
+
+export class ChannelBook {
+  readonly #deps: ChannelBookDeps;
+  readonly #byTopic = new Map<string, Entry>();
+
+  constructor(deps: ChannelBookDeps) {
+    this.#deps = deps;
+  }
+
+  /** Join (or share) one channel. N holders on one topic are ONE subscribe frame. */
+  hold<K extends string>(
+    ref: ChannelRef<K>,
+    params: Readonly<Record<K, string>>,
+    handlers: ChannelHandlers = {},
+  ): ChannelMembership {
+    const topic = ref.topic(params);
+    let entry = this.#byTopic.get(topic);
+    if (entry === undefined) {
+      entry = {
+        topic,
+        name: ref.name,
+        catchUp: ref.catchUp,
+        params,
+        holders: new Set(),
+        listeners: new Set(),
+        state: this.#deps.connected() ? 'joining' : 'offline',
+        error: undefined,
+        epoch: null,
+        contiguous: null,
+        above: new Set(),
+        buffered: null,
+        again: null,
+        waiting: false,
+        failures: 0,
+        disarm: null,
+      };
+      this.#byTopic.set(topic, entry);
+      if (this.#deps.connected()) this.#deps.send(this.#frame(entry, 'add', true));
+    }
+    const held = entry;
+    held.holders.add(handlers);
+    let open = true;
+    const release = (): void => {
+      if (!open) return;
+      open = false;
+      held.holders.delete(handlers);
+      if (held.holders.size > 0) return;
+      this.#byTopic.delete(topic);
+      held.disarm?.();
+      held.disarm = null;
+      this.#deps.send(this.#frame(held, 'drop', false));
+    };
+    return {
+      topic,
+      state: () => held.state,
+      error: () => held.error,
+      onChange: (listener) => {
+        held.listeners.add(listener);
+        return () => {
+          held.listeners.delete(listener);
+        };
+      },
+      release,
+      [Symbol.dispose]: release,
+    };
+  }
+
+  /** Every membership again, on a new socket — resuming from each cursor. */
+  resubscribe(): void {
+    for (const entry of this.#byTopic.values()) {
+      // A catch-up that failed retries on the new socket: the read is what it was waiting for.
+      if (entry.waiting) {
+        this.#deps.send(this.#frame(entry, 'add', true));
+        this.#read(entry);
+        continue;
+      }
+      this.#set(entry, 'joining');
+      this.#deps.send(this.#frame(entry, 'add', true));
+    }
+  }
+
+  /** The presence heartbeat: repeat each membership with NO `since`, so the node replays nothing. */
+  beat(): void {
+    for (const entry of this.#byTopic.values()) this.#deps.send(this.#frame(entry, 'add', false));
+  }
+
+  offline(): void {
+    for (const entry of this.#byTopic.values()) {
+      if (entry.state !== 'failed') this.#set(entry, 'offline');
+    }
+  }
+
+  /** The sid a channel is subscribed under — what a refusal `ack` names. */
+  refused(sid: string, error: unknown): boolean {
+    const entry = [...this.#byTopic.values()].find((candidate) => sidOf(candidate) === sid);
+    if (entry === undefined) return false;
+    entry.error = error;
+    this.#set(entry, 'failed');
+    return true;
+  }
+
+  records(frame: ChannelRecordsFrame): void {
+    const entry = this.#byTopic.get(frame.channel);
+    if (entry === undefined) return;
+    if (entry.buffered !== null) {
+      entry.buffered.push(frame);
+      return;
+    }
+    if (entry.epoch !== null && entry.epoch !== frame.epoch) {
+      // A new epoch: the node restarted or the client landed on another one. Its seqs mean
+      // nothing against ours, so the channel is re-read and this frame waits behind the read.
+      this.#catchUp(entry, [frame]);
+      return;
+    }
+    this.#apply(entry, frame);
+  }
+
+  gap(frame: ReplayGapFrame): void {
+    const entry = this.#byTopic.get(frame.channel);
+    if (entry === undefined) return;
+    this.#catchUp(entry, [], frame.epoch);
+  }
+
+  event(frame: ChannelEventsFrame): void {
+    const entry = this.#byTopic.get(frame.channel);
+    const presence = readPresence(frame.event);
+    for (const holder of entry?.holders ?? []) {
+      if (presence !== null) holder.onPresence?.(presence);
+      else holder.onEvent?.(frame.event);
+    }
+  }
+
+  /** Where a resubscribe resumes: the highest contiguous seq, in the epoch it counts in. */
+  since(topic: string): { readonly epoch: string; readonly seq: number } | undefined {
+    const entry = this.#byTopic.get(topic);
+    if (entry?.epoch === null || entry?.contiguous === null || entry === undefined)
+      return undefined;
+    return { epoch: entry.epoch, seq: entry.contiguous };
+  }
+
+  #apply(entry: Entry, frame: ChannelRecordsFrame): void {
+    if (entry.epoch === null) {
+      entry.epoch = frame.epoch;
+      entry.contiguous = frame.seq - 1;
+    }
+    const contiguous = entry.contiguous ?? frame.seq - 1;
+    // A duplicate is dropped; a replayed seq filling a hole is new. A numeric hole on its own is
+    // never a gap — a row this socket may not see is skipped for it; only `replay-gap` is.
+    if (frame.seq <= contiguous || entry.above.has(frame.seq)) return;
+    const store = this.#deps.store;
+    store.batch(() => {
+      for (const [type, rows] of Object.entries(frame.adopt ?? {})) store.adopt(type, rows);
+      for (const [type, keys] of Object.entries(frame.remove ?? {})) store.remove(type, keys);
+      // This page's own write, echoed: settled in the same batch as its rows, so its twin is
+      // never replayed over the truth that already holds it.
+      if (frame.write !== undefined) {
+        const carried = new Set<RecordKey>();
+        carriedBy({ records: frame.adopt ?? {}, removed: frame.remove ?? {} }, carried);
+        store.settleWrite(frame.write, carried);
+      }
+    });
+    entry.above.add(frame.seq);
+    let next = contiguous;
+    while (entry.above.delete(next + 1)) next += 1;
+    entry.contiguous = next;
+    if (entry.state !== 'live') this.#set(entry, 'live');
+  }
+
+  /**
+   * Re-read the channel through its catch-up query, holding every frame that arrives meanwhile;
+   * then apply those, in order, over the read. The cursor restarts in the new epoch.
+   *
+   * A gap that lands DURING the read is not dropped: it earns one more read after this one (it
+   * was ignored, and the hole it announced was never repaired).
+   */
+  #catchUp(entry: Entry, pending: ChannelRecordsFrame[], epoch?: string): void {
+    if (entry.buffered !== null) {
+      entry.buffered.push(...pending);
+      if (pending.length === 0) entry.again = { epoch: epoch ?? entry.again?.epoch };
+      // No read in flight — the last one failed — so this gap is the retry, now.
+      if (entry.waiting) this.#read(entry);
+      return;
+    }
+    entry.buffered = [...pending];
+    this.#restart(entry, epoch ?? pending[0]?.epoch ?? entry.epoch);
+    this.#read(entry);
+  }
+
+  /** The cursor, reset into `epoch`: every seq before the read is the read's to answer. */
+  #restart(entry: Entry, epoch: string | null): void {
+    entry.epoch = epoch;
+    entry.contiguous = null;
+    entry.above.clear();
+  }
+
+  #read(entry: Entry): void {
+    entry.waiting = false;
+    entry.error = undefined;
+    entry.disarm?.();
+    entry.disarm = null;
+    this.#set(entry, 'catching-up');
+    this.#deps.catchUp(entry.catchUp, entry.params).then(
+      () => this.#drain(entry),
+      (error: unknown) => {
+        this.#deps.report(error);
+        // NOT live: the frames held behind the read would land over a store it never refreshed.
+        // Failed, the error exposed, and the frames still held for the retry — which the next
+        // open of the socket runs (`resubscribe`), or the next gap.
+        entry.waiting = true;
+        entry.error = error;
+        entry.failures += 1;
+        if (this.#byTopic.get(entry.topic) !== entry) return;
+        this.#set(entry, 'failed');
+        entry.disarm =
+          this.#deps.retry?.(entry.failures, () => {
+            entry.disarm = null;
+            if (entry.waiting && this.#byTopic.get(entry.topic) === entry) this.#read(entry);
+          }) ?? null;
+      },
+    );
+  }
+
+  #drain(entry: Entry): void {
+    const held = entry.buffered ?? [];
+    // A newer epoch arrived while the read was in flight (the node restarted mid-read): the read
+    // answered for the OLD one, so it is re-read in the new one, keeping only that epoch's frames.
+    // `#drain` used to discard them, and the rows they carried with them.
+    const newer = held.find((frame) => frame.epoch !== entry.epoch);
+    if (entry.again !== null || newer !== undefined) {
+      const epoch = newer?.epoch ?? entry.again?.epoch ?? entry.epoch;
+      entry.again = null;
+      entry.buffered = held.filter((frame) => frame.epoch === epoch);
+      this.#restart(entry, epoch);
+      this.#read(entry);
+      return;
+    }
+    entry.buffered = null;
+    entry.failures = 0;
+    const current = [...held].sort((a, b) => a.seq - b.seq);
+    for (const frame of current) {
+      if (entry.contiguous === null) entry.contiguous = frame.seq - 1;
+      this.#apply(entry, frame);
+    }
+    if (entry.state === 'catching-up') this.#set(entry, 'live');
+  }
+
+  #set(entry: Entry, state: ChannelState): void {
+    entry.state = state;
+    for (const listener of entry.listeners) listener();
+  }
+
+  #frame(entry: Entry, op: 'add' | 'drop', resume: boolean): SubscribeFrame {
+    const since = resume && op === 'add' ? this.since(entry.topic) : undefined;
+    return {
+      type: 'subscribe',
+      v: PROTOCOL_VERSION,
+      op,
+      sid: sidOf(entry),
+      target: {
+        kind: 'channel',
+        channel: entry.name,
+        params: entry.params,
+        ...(since === undefined ? {} : { since }),
+      },
+    };
+  }
+}
+
+/** A channel membership's sid is its topic behind this — what the socket engine routes on too. */
+export const CHANNEL_SID_PREFIX = 'channel:';
+
+/** One sid per topic: re-sending it after a reconnect is the same membership, not a second one. */
+function sidOf(entry: Entry): string {
+  return `${CHANNEL_SID_PREFIX}${entry.topic}`;
+}

package/src/client-contract.ts

@@ -1,42 +1,45 @@
 // What a client IS, as types: the injected seams, the options, and the handles a subscription
-// gives back. Declared apart from the client that implements them for the same reason
-// `live-contract.ts` is — the hooks, the typed projection, the type pins and the mutation path all
-// need these shapes, and none of them needs the connection lifecycle that runs underneath.
+// gives back. Declared apart from the client that implements them, so a hook module can name the
+// shapes without importing the connection lifecycle underneath — and the bytes that come with it.
 
-import type { Clock } from '@ultimat3/core';
+import type { Clock, Row } from '@ultimat3/core/page';
 import type { LiveCursor } from './cursor';
-import type { JsonValue, Row } from './json';
 import type { LiveState } from './live-rows';
-import type { LocalStore, LocalTx, TableMap } from './local-store';
-import type { OfflineQueue } from './offline-queue';
-import type { ConflictStrategy, RebaseLog } from './rebase';
+import type { RecordStore } from './record-store';
 import type { BackoffPolicy, Rng, Scheduler } from './thundering-herd';
 
-/** Injected reactive primitive. `createSignal` from Solid satisfies this exactly. */
+/**
+ * A reactive primitive: `createSignal` narrowed to two functions. Installed PER ISLAND BUNDLE
+ * (`installRealtime`), because every island carries its own solid-js and a signal made by one
+ * bundle's copy is invisible to another's effects.
+ */
 export type SignalFactory = <T>(initial: T) => [get: () => T, set: (next: T) => void];
 
-/** Injected socket, so tests drive the protocol without a network. */
+/**
+ * The socket seam. `browser-socket.ts` is the one production implementation — the only
+ * `new WebSocket` in the framework — and test harnesses supply their own. Not on the public API:
+ * an app never constructs a socket, the page does.
+ */
 export interface ClientSocket {
   send(data: string): void;
   close(code?: number, reason?: string): void;
   onOpen(handler: () => void): void;
   onMessage(handler: (data: string) => void): void;
   onClose(handler: (code: number) => void): void;
-  /**
-   * Bytes queued but not yet on the wire — `WebSocket.bufferedAmount`. Optional because a socket
-   * that cannot answer is treated as never backed up; supplying it is what lets the mutation drain
-   * stop instead of pushing a queue the tab is not draining into one it cannot see.
-   */
   readonly bufferedAmount?: number;
 }
 
-export interface LiveHandle<R extends Row = Row> extends Disposable {
-  /** The reactive accessor. In an app this is the Solid signal `useLive` returns. */
-  readonly rows: () => readonly R[];
-  readonly state: () => LiveState;
-  readonly cursor: () => LiveCursor | null;
+/** One live query's window, as plain reads plus a change listener — no reactive runtime here. */
+export interface LiveHandle<R extends object = Row> extends Disposable {
+  rows(): readonly R[];
+  state(): LiveState;
+  cursor(): LiveCursor | null;
+  /** What the node answered when it refused the subscription; `undefined` unless `failed`. */
+  error(): unknown;
+  /** Called after anything the reads above answer has moved. Returns the unsubscribe. */
+  onChange(listener: () => void): () => void;
   unsubscribe(): void;
-  /** The same call as `unsubscribe`, so `using sub = client.useLive(...)` just works. */
+  /** The same call as `unsubscribe`, so `using sub = client.subscribeLive(...)` just works. */
   [Symbol.dispose](): void;
 }
 
@@ -47,59 +50,26 @@ export interface LiveQueryRef {
   readonly name: string;
 }
 
-export interface MutatorRef<T extends TableMap = TableMap> {
-  readonly name: string;
-  /** Optimistic twin. Pure — no I/O, no Date.now(), no Math.random(). */
-  local?: (tx: LocalTx<T>, input: JsonValue) => void;
-  readonly entity?: string;
-  readonly conflict?: ConflictStrategy;
-}
-
-/**
- * What the HOOKS need a client to be — every member `hooks.ts` reads, and not one more.
- *
- * A structural interface rather than the `LiveClient` class, and the reason is measured: a value
- * import of that class from the hook seam put the whole connection lifecycle (heartbeat, topic
- * book, mutation sender, wire protocol, backoff) into every island that calls `useLive`, taking a
- * `useLive`-only browser chunk from 8,368 B to 26,571 B. The server render's client
- * (`server-render-client.ts`) satisfies this and imports no lifecycle at all, so the browser pays
- * nothing for a shape only the server uses. `type-pins.ts` pins that `LiveClient` still satisfies
- * it, so a member added there and not here is a build error rather than a hook that cannot see it.
- */
-export interface LiveClientLike<T extends TableMap = TableMap> {
-  readonly signal: SignalFactory;
-  readonly queue: OfflineQueue | undefined;
-  readonly connected: boolean;
-  readonly reconnectAt: () => number | null;
-  readonly appUpdateAvailable: () => string | null;
-  useLive<R extends Row>(query: LiveQueryRef, input: JsonValue): LiveHandle<R>;
-  mutate(mutator: MutatorRef<T>, input: JsonValue, key?: string): Promise<void>;
-  drain(): Promise<void>;
-  onQueueChange(listener: () => void): () => void;
-}
-
-export interface LiveClientOptions<T extends TableMap = TableMap> {
-  readonly signal: SignalFactory;
+export interface LiveClientOptions {
   /** Called for every connect attempt; returning a fresh socket keeps reconnect logic here. */
   readonly connect: () => ClientSocket;
   readonly buildId: string;
   readonly actorId?: string | null;
-  /** Tier 3 only. Without these, mutations are server-only and nothing is queued offline. */
-  readonly store?: LocalStore<T>;
-  readonly queue?: OfflineQueue;
-  readonly log?: RebaseLog<T>;
+  /** The page's record store every window renders out of. A client builds its own when absent. */
+  readonly store?: RecordStore;
+  /** Default `browserBackoff`: capped at `BROWSER_RECONNECT_MAX_MS`, never the server's 30s. */
   readonly backoff?: BackoffPolicy;
   readonly rng?: Rng;
   readonly clock?: Clock;
   /** How a pending reconnect is armed. Defaults to `setTimeout`; tests fire theirs by hand. */
   readonly scheduler?: Scheduler;
-  /**
-   * How often a live socket re-announces itself, in ms. `0` disables it. Defaults to
-   * `DEFAULT_HEARTBEAT_MS`, 15s. The one knob for the beat: `realtime.heartbeatMs` in
-   * `app.config.ts` was deleted 2026-08-19 because nothing read it, so this is not a restatement
-   * of a server value — browser code could never have reached one.
-   */
+  /** How often a live socket re-announces itself, in ms. `0` disables it. Default 15s. */
   readonly heartbeatMs?: number;
-  /** Where a dial failure inside the reconnect timer is reported. Defaults to `reportToConsole`. */
+  /** Where a failure nobody awaits is reported. Defaults to `console.error`. */
   readonly onError?: (error: unknown) => void;
+  /**
+   * A channel's catch-up read, re-run on `replay-gap` or a new epoch: the named query, through
+   * core's transport, so its records land in the store. `page-socket.ts` supplies the real one.
+   */
+  readonly catchUp: (query: string, params: Readonly<Record<string, string>>) => Promise<unknown>;
 }