@ultimat3/realtime 20.2.1 → 22.0.0

package/src/offline-queue.ts

@@ -9,9 +9,9 @@
 //      to a socket and nothing more, so a drained mutation is `inflight` — not `acked` — until an
 //      `ack`/`fail` frame settles it, or a lost connection returns it to the queue.
 
-import { renderThrowable, stringField } from '@ultimat3/core';
+import { renderThrowable, stringField } from '@ultimat3/core/page';
 import type { JsonValue } from './json';
-import { type Frame, PROTOCOL_VERSION, type WireError } from './sync-protocol';
+import type { WireError } from './sync-protocol';
 
 export type MutationStatus = 'pending' | 'inflight' | 'acked' | 'failed';
 
@@ -33,21 +33,38 @@ export interface QueueState {
   readonly nextSeq: number;
 }
 
-/** Durability seam: OPFS/IndexedDB in the browser, memory in tests. */
+/**
+ * One change to the durable queue: these entries written BY KEY, these keys deleted, and the
+ * sequence floor. Never the whole queue — two tabs of one user share the store, and a whole-queue
+ * save let the last tab to save erase the other's queued write.
+ */
+export interface QueueChange {
+  readonly puts: readonly QueuedMutation[];
+  readonly deletes: readonly string[];
+  readonly nextSeq: number;
+}
+
+/** Durability seam: IndexedDB in the browser (`page-outbox.ts`), memory in tests. */
 export interface QueueStore {
   load(): Promise<QueueState>;
-  save(state: QueueState): Promise<void>;
+  write(change: QueueChange): Promise<void>;
 }
 
 export class MemoryQueueStore implements QueueStore {
-  #state: QueueState = { mutations: [], nextSeq: 1 };
+  readonly #mutations = new Map<string, QueuedMutation>();
+  #nextSeq = 1;
 
   async load(): Promise<QueueState> {
-    return this.#state;
+    return {
+      mutations: [...this.#mutations.values()].map((m) => ({ ...m })),
+      nextSeq: this.#nextSeq,
+    };
   }
 
-  async save(state: QueueState): Promise<void> {
-    this.#state = { mutations: state.mutations.map((m) => ({ ...m })), nextSeq: state.nextSeq };
+  async write(change: QueueChange): Promise<void> {
+    for (const key of change.deletes) this.#mutations.delete(key);
+    for (const mutation of change.puts) this.#mutations.set(mutation.key, { ...mutation });
+    this.#nextSeq = Math.max(this.#nextSeq, change.nextSeq);
   }
 }
 
@@ -81,9 +98,37 @@ export class OfflineQueue {
     this.#nextSeq = state.nextSeq;
   }
 
-  /** Rehydrates from durable storage, so a reload resumes the same queue with the same sequence. */
+  /**
+   * Rehydrates from durable storage, so a reload resumes the same queue with the same sequence.
+   *
+   * An `inflight` entry on disk belonged to a page that is gone, so it goes back to `pending`. Left
+   * as it was, `#sendable` skipped it forever — no ack was coming to a page that no longer exists —
+   * and every later write overtook it. The replay carries its idempotency key, so a write the old
+   * page did get through is answered from the action's idempotency store, never applied twice.
+   */
   static async open(store: QueueStore): Promise<OfflineQueue> {
-    return new OfflineQueue(store, await store.load());
+    const queue = new OfflineQueue(store, await store.load());
+    await queue.#reclaimInflight();
+    return queue;
+  }
+
+  /**
+   * Re-reads the durable queue, which another tab of the same user may have written since this one
+   * opened. Call ONLY while this queue is the one draining — `page-outbox.ts` holds a Web Lock for
+   * exactly that — because it reclaims every `inflight` entry as `pending`: with the lock held, no
+   * other pass can have one on the wire.
+   */
+  async reload(): Promise<void> {
+    const state = await this.#store.load();
+    this.#mutations = state.mutations.map((mutation) => ({ ...mutation }));
+    this.#nextSeq = Math.max(this.#nextSeq, state.nextSeq);
+    await this.#reclaimInflight();
+  }
+
+  async #reclaimInflight(): Promise<void> {
+    const reclaimed = this.#mutations.filter((mutation) => mutation.status === 'inflight');
+    for (const mutation of reclaimed) mutation.status = 'pending';
+    if (reclaimed.length > 0) await this.#persist(reclaimed);
   }
 
   get size(): number {
@@ -131,8 +176,10 @@ export class OfflineQueue {
     // UI — collapsing onto it makes an explicit idempotency key unusable for the rest of the
     // session, because nothing ever retries a denial. Re-issuing one is a NEW intent, so the old
     // entry is dropped and this one takes a new sequence at the back of the queue.
-    if (existing)
-      this.#mutations = this.#mutations.filter((candidate) => candidate.key !== args.key);
+    // By identity: `existing` IS the entry for this key, found above — no second key comparison.
+    if (existing) this.#mutations = this.#mutations.filter((entry) => entry !== existing);
+    // Another tab of the same user may have taken sequence numbers since this one loaded.
+    this.#nextSeq = Math.max(this.#nextSeq, (await this.#store.load()).nextSeq);
     const mutation: QueuedMutation = {
       key: args.key,
       seq: this.#nextSeq,
@@ -145,7 +192,7 @@ export class OfflineQueue {
     };
     this.#nextSeq += 1;
     this.#mutations.push(mutation);
-    await this.#persist();
+    await this.#persist([mutation]);
     return mutation;
   }
 
@@ -190,12 +237,14 @@ export class OfflineQueue {
   async requeueInflight(): Promise<number> {
     this.#epoch += 1;
     let returned = 0;
+    const back: QueuedMutation[] = [];
     for (const mutation of this.#mutations) {
       if (mutation.status !== 'inflight') continue;
       mutation.status = 'pending';
       returned += 1;
+      back.push(mutation);
     }
-    if (returned > 0) await this.#persist();
+    if (returned > 0) await this.#persist(back);
     return returned;
   }
 
@@ -204,8 +253,9 @@ export class OfflineQueue {
     const mutation = this.find(key);
     if (!mutation) return;
     mutation.status = 'acked';
-    this.#mutations = this.#mutations.filter((candidate) => candidate.key !== key);
-    await this.#persist();
+    // By identity: `find` already matched it, and a second comparison of the key is the same question.
+    this.#mutations = this.#mutations.filter((entry) => entry !== mutation);
+    await this.#persist([], [key]);
   }
 
   /** Terminal failure (policy denial, validation): kept for the UI, never retried blindly. */
@@ -214,7 +264,7 @@ export class OfflineQueue {
     if (!mutation) return;
     mutation.status = 'failed';
     mutation.error = error;
-    await this.#persist();
+    await this.#persist([mutation]);
   }
 
   /**
@@ -251,6 +301,7 @@ export class OfflineQueue {
       return { sent: 0, collapsed: this.#collapsed, remaining: 0, stoppedAt: null };
     }
     let sent = 0;
+    const touched: QueuedMutation[] = [];
     for (const mutation of sendable) {
       // The connection this pass was draining into is gone, and `requeueInflight` has already
       // handed back what was on it. Everything left stays `pending` for the pass the next
@@ -268,6 +319,7 @@ export class OfflineQueue {
       if (!this.#stillSendable(mutation)) continue;
       mutation.status = 'inflight';
       mutation.attempts += 1;
+      touched.push(mutation);
       try {
         await send(mutation);
         // Stays `inflight`. `send` resolving means the frame reached a socket — a browser
@@ -279,7 +331,7 @@ export class OfflineQueue {
       } catch (error) {
         mutation.status = 'pending';
         mutation.error = toQueueError(error);
-        await this.#persist();
+        await this.#persist([mutation]);
         return {
           sent,
           collapsed: this.#collapsed,
@@ -288,7 +340,9 @@ export class OfflineQueue {
         };
       }
     }
-    await this.#persist();
+    // Only what this pass touched AND the queue still holds: an entry the server settled during the
+    // pass was already deleted by `ack`, and writing it back would resurrect it.
+    await this.#persist(touched.filter((mutation) => this.#mutations.includes(mutation)));
     return {
       sent,
       collapsed: this.#collapsed,
@@ -298,36 +352,28 @@ export class OfflineQueue {
   }
 
   async clear(): Promise<void> {
+    const keys = this.#mutations.map((mutation) => mutation.key);
     this.#mutations = [];
-    await this.#persist();
+    await this.#persist([], keys);
   }
 
   /**
-   * A snapshot, never the live entries. `save` is a durable write — OPFS, IndexedDB — and it is
-   * allowed to await before it reads. Handed the array itself, a store that resolves after the next
-   * pass has moved on persists a status that was never true when it was called; `inflight` is the
-   * one a reload cannot recover from, because `#sendable` skips it and no ack is coming.
+   * Snapshots, never the live entries. `write` is a durable write — IndexedDB — and it is allowed
+   * to await before it reads. Handed an entry itself, a store that resolves after the next pass has
+   * moved on persists a status that was never true when it was called. BY KEY, never the whole
+   * queue: a second tab's entries are not this tab's to overwrite or delete.
    */
-  async #persist(): Promise<void> {
-    await this.#store.save({
-      mutations: this.#mutations.map((mutation) => ({ ...mutation })),
+  async #persist(puts: readonly QueuedMutation[], deletes: readonly string[] = []): Promise<void> {
+    await this.#store.write({
+      puts: puts.map((mutation) => ({ ...mutation })),
+      deletes,
       nextSeq: this.#nextSeq,
     });
   }
 }
 
-export function mutateFrame(mutation: QueuedMutation): Frame {
-  return {
-    type: 'mutate',
-    v: PROTOCOL_VERSION,
-    key: mutation.key,
-    seq: mutation.seq,
-    name: mutation.name,
-    input: mutation.input,
-  };
-}
-
-function toQueueError(error: unknown): WireError {
+/** A thrown value as the queue records it — `code`, `cause`, `fix`, never a throw of its own. */
+export function toQueueError(error: unknown): WireError {
   return {
     // `stringField`, not `shape?.code`: the sender is a transport the app supplied, so the probe
     // for "did it throw a coded error" is itself a property read on an app value. A getter that

package/src/outbox-slot.ts

@@ -0,0 +1,31 @@
+// The page's outbox as an ISLAND reaches it: read off the page, never built. The page boot
+// (`boot.ts`) is the one module that constructs it — IndexedDB, the queue, the drain listeners —
+// so a writing island ships this reader and none of that (~7.5 kB it would otherwise carry).
+
+import type { JsonValue } from './json';
+
+export interface OutboxEntry {
+  /** The idempotency key the write was first attempted under — the SAME key on every replay. */
+  readonly key: string;
+  /** The mutator's action name; the replay POSTs to `actionPath(name)`. */
+  readonly name: string;
+  readonly input: JsonValue;
+}
+
+/** What a hook asks of the outbox the boot opened: queue a write, list them, replay them. */
+export interface OutboxHandle {
+  enqueue(entry: OutboxEntry): Promise<void>;
+  replay(): Promise<unknown>;
+  pending(): readonly OutboxEntry[];
+  /** Settles once the current principal's queue is open. */
+  readonly ready: Promise<void>;
+}
+
+/** Where the page keeps it: shared by every bundle on the page, as the record store is. */
+export const OUTBOX_KEY: unique symbol = Symbol.for('ultimate.outbox');
+export type OutboxHost = { [OUTBOX_KEY]?: OutboxHandle };
+
+/** The outbox the page boot opened, or `undefined` on a page with no boot (nothing persisted). */
+export function peekOutbox(): OutboxHandle | undefined {
+  return (globalThis as OutboxHost)[OUTBOX_KEY];
+}

package/src/page-errors.ts

@@ -0,0 +1,124 @@
+// The refusals a BROWSER can reach — the page store, the hooks, the socket's wire check, the local
+// store. Apart from `errors.ts` for bytes: that module registers the whole code table at import,
+// and an island that renders one record has no use for sixty titles. The codes stay in `errors.ts`
+// (its `registerErrorCodes()` is what `package.json`'s `sideEffects` names, anchored by the
+// barrel); in a browser that loaded no table a code titles itself from its name, and `code`,
+// `cause` and `fix` — what a reader acts on — are unchanged. This module runs nothing at import.
+
+import { renderFixShellArg } from '@ultimat3/core/page';
+import { RealtimeError } from './realtime-error';
+
+/**
+ * Client and server disagree on the wire format — a version mismatch or a malformed frame.
+ * Both are the same class of bug (a peer speaking a shape we do not have), so both get one code.
+ */
+export class ProtocolVersionError extends RealtimeError {
+  constructor(args: { got: unknown; expected: number; detail?: string }) {
+    super({
+      code: 'X_PROTOCOL_VERSION',
+      cause:
+        args.detail ??
+        `frame protocol version ${String(args.got)} is not the server version ${args.expected}`,
+      fix: 'x build && redeploy the client; the sync node sends `update-available` before it drains',
+    });
+  }
+}
+
+/** A rebase could not be resolved: `custom(merge)` returned nothing, or the base row vanished. */
+export class RebaseConflictError extends RealtimeError {
+  constructor(args: { key: string; entity: string; reason: string }) {
+    super({
+      code: 'X_REBASE_CONFLICT',
+      cause: `mutation ${args.key} on ${args.entity} could not be rebased: ${args.reason}`,
+      fix: "set conflict: 'server-wins' on the mutator, or return a row from custom(merge)",
+    });
+  }
+}
+
+/**
+ * A hook ran IN A BROWSER in an island bundle whose bootstrap never called `installRealtime()`.
+ * Per BUNDLE, not per page: every island carries its own copy of solid-js, so the signal factory a
+ * hook renders through has to be that island's own — the page-wide store cannot hold one.
+ *
+ * A server render is deliberately not this error: no DOM means no reactive runtime to install,
+ * and the hooks answer the honest server-render state instead.
+ */
+export class RealtimeUninstalledError extends RealtimeError {
+  constructor(args: { hook: string }) {
+    super({
+      code: 'X_REALTIME_UNINSTALLED',
+      cause: `${args.hook}() ran in a browser island whose bundle never called installRealtime()`,
+      fix: "x build   # the island bootstrap installs it; a hand-built island calls installRealtime({ signal: createSignal }) from '@ultimat3/realtime' before its first render",
+    });
+  }
+}
+
+/** A live hook needed the page's one socket, and nothing told this page where the sync node is. */
+export class SyncUnconfiguredError extends RealtimeError {
+  constructor(args: { hook: string }) {
+    super({
+      code: 'X_SYNC_UNCONFIGURED',
+      cause: `${args.hook}() needs the page socket, and installRealtime() was given no sync target`,
+      fix: "x build   # the island bootstrap passes it; a hand-built island calls installRealtime({ signal: createSignal, sync: { url, buildId } }) from '@ultimat3/realtime'",
+    });
+  }
+}
+
+/**
+ * A row reached the record store it cannot hold: not an object, or under no key. Dropped and
+ * reported, never partially merged — a keyless row would overwrite another record.
+ */
+export class RecordRejectedError extends RealtimeError {
+  constructor(args: { type: string; reason: string }) {
+    super({
+      code: 'X_RECORD_REJECTED',
+      cause: `a ${args.type === '' ? 'record' : `"${args.type}" record`} was rejected by the page's record store: ${args.reason}`,
+      fix: `x entities describe ${renderFixShellArg(args.type, '<entity>')} --json   # the primary key every row of it must carry; return whole rows from the handler that built this one`,
+    });
+  }
+}
+
+/**
+ * IndexedDB would not open (a private window, storage disabled), so the page keeps records and its
+ * outbox in memory. A WARNING, never thrown: a page must not break because it cannot remember, so
+ * `openLocalStore` hands this to its `warn` once and carries on.
+ */
+export class LocalStoreUnavailableError extends RealtimeError {
+  constructor(args: { reason: string }) {
+    super({
+      code: 'X_LOCAL_STORE_UNAVAILABLE',
+      cause: `the page's durable store could not open (${args.reason}), so records and queued writes live in memory and are lost on reload`,
+      fix: 'nothing to do in the app — allow site storage in the browser (a private window blocks it) and reload',
+    });
+  }
+}
+
+/**
+ * Something that can only mean "talk to the socket" ran on the server client — a mutation, a
+ * publish, a topic subscription, a dial. There is no socket during a server render and there never
+ * will be one: the document is built and sent, and the browser opens the connection.
+ *
+ * A refusal rather than a silent no-op, because both alternatives are worse. Queueing it would
+ * hold one process-wide queue on behalf of whichever request happened to render, and dropping it
+ * would make a write that never happened look like one that did.
+ */
+export class ServerRenderLiveError extends RealtimeError {
+  constructor(args: { operation: string }) {
+    super({
+      code: 'X_LIVE_SERVER_RENDER',
+      cause: `${args.operation} ran during a server render, where this app has no live socket`,
+      fix: 'move the call into an island: x g island <route-dir> --at <route-dir>, import from its mount(), declare island({ src })',
+    });
+  }
+}
+
+/** A resume cursor cannot be honoured and no snapshot path was supplied. */
+export class CursorStaleError extends RealtimeError {
+  constructor(args: { qid: string; lsn: string; reason: string }) {
+    super({
+      code: 'X_CURSOR_STALE',
+      cause: `cursor for query ${args.qid} at lsn ${args.lsn} cannot be resumed: ${args.reason}`,
+      fix: 'pass `snapshot` to resumeFrom() so the fallback path can re-snapshot instead of failing',
+    });
+  }
+}