@ultimat3/realtime 24.0.0 → 25.1.0

package/src/nats-subscriptions.ts

@@ -0,0 +1,63 @@
+// Single responsibility: the transport's kept list of live subscriptions, so a client the library
+// closed for good can be replaced and every subscription bound again on the new one. The library's
+// own reconnect never reaches this list — it re-establishes the SAME client's subscriptions — so a
+// subscription is bound once per client and a re-bind can never double a delivery.
+
+import type { NatsClient, NatsMessageHandler, NatsSubscription } from './nats-client';
+
+interface Kept {
+  readonly subject: string;
+  readonly deliver: NatsMessageHandler;
+  /** The binding on the current client; `undefined` once that client is gone or the bind failed. */
+  live: NatsSubscription | undefined;
+}
+
+/** A refused bind, handed back rather than thrown: one bad subject must not strand the others. */
+export interface BindFailure {
+  readonly subject: string;
+  readonly error: unknown;
+}
+
+export class NatsSubscriptions {
+  readonly #kept = new Set<Kept>();
+
+  /**
+   * Binds on `client` first and keeps it only once bound: a subscribe the client refused is the
+   * caller's error, and keeping it would re-try a refusal on every re-dial. Returns the release.
+   */
+  add(
+    client: NatsClient,
+    subject: string,
+    deliver: NatsMessageHandler,
+    bind: (call: () => NatsSubscription) => NatsSubscription,
+  ): () => void {
+    const kept: Kept = { subject, deliver, live: undefined };
+    kept.live = bind(() => client.subscribe(subject, deliver));
+    this.#kept.add(kept);
+    return () => {
+      if (!this.#kept.delete(kept)) return;
+      const live = kept.live;
+      kept.live = undefined;
+      live?.unsubscribe();
+    };
+  }
+
+  /** The client is gone, and every binding with it. Nothing is unsubscribed: there is no wire. */
+  orphan(): void {
+    for (const kept of this.#kept) kept.live = undefined;
+  }
+
+  /** Every kept subscription, bound on a NEW client. Returns the ones it refused. */
+  bindAll(client: NatsClient): readonly BindFailure[] {
+    const failures: BindFailure[] = [];
+    for (const kept of this.#kept) {
+      if (kept.live !== undefined) continue;
+      try {
+        kept.live = client.subscribe(kept.subject, kept.deliver);
+      } catch (error) {
+        failures.push({ subject: kept.subject, error });
+      }
+    }
+    return failures;
+  }
+}

package/src/nats-transport.ts

@@ -1,7 +1,8 @@
 // Single responsibility: the production `Transport` — core NATS for fanout, JetStream KV for the
 // shared presence sets. The client underneath owns the wire and the reconnect, including
-// re-establishing subscriptions, which is what makes a `sync` node stateless: a lost connection is
-// re-dialled and re-subscribed underneath the caller, and this file keeps no socket state at all.
+// re-establishing subscriptions, which is what makes a `sync` node stateless. The one loss it does
+// not own is its own end: a client closed for good once its reconnect budget is spent is replaced
+// here, on our backoff, and every kept subscription is bound again on the new one.
 
 import {
   type Clock,
@@ -18,6 +19,7 @@ import { parseNatsUrl } from './nats-client';
 import { ensureKvBucket } from './nats-jetstream';
 import { NatsKvSet } from './nats-kv';
 import { openNatsClient } from './nats-open';
+import { NatsSubscriptions } from './nats-subscriptions';
 import { type BackoffPolicy, defaultBackoff, policyDelay, type Rng } from './thundering-herd';
 
 const encoder = new TextEncoder();
@@ -55,6 +57,10 @@ export class NatsTransport implements Transport {
   #dialing: Promise<NatsClient> | undefined;
   #retries = 0;
   #closed = false;
+  /** Set while a client the library gave up on is being replaced; the attempt in flight. */
+  #redialing: number | undefined;
+  #wakeRedial: (() => void) | undefined;
+  readonly #subscriptions = new NatsSubscriptions();
   readonly #reconnectListeners = new Set<() => void>();
 
   constructor(options: NatsTransportOptions) {
@@ -98,23 +104,26 @@ export class NatsTransport implements Transport {
   }
 
   /**
-   * The subscription is the client's to keep: it survives a drop and comes back with the reconnect,
-   * so there is no intent map here to re-bind from — and therefore no way for a re-bind to run
-   * twice and double every change on the subject.
+   * A drop is the client's to recover: the subscription comes back with the library's reconnect,
+   * untouched by this file. It is also KEPT here, for the one loss the library does not recover —
+   * a client closed for good — and bound once on its replacement, never twice on one client.
    */
   async subscribe(subject: string, handler: TransportHandler): Promise<TransportSubscription> {
     const client = await this.#ensure();
     // Same seam as `publish`: a permissions violation on the subject is refused here, not later.
-    const live = this.#translating(`subscribe to ${subject}`, () =>
-      client.subscribe(subject, (message) => {
+    const release = this.#subscriptions.add(
+      client,
+      subject,
+      (message) => {
         try {
           handler(decoder.decode(message.payload), message.subject);
         } catch (error) {
           this.#report(error, message.subject);
         }
-      }),
+      },
+      (call) => this.#translating(`subscribe to ${subject}`, call),
     );
-    return { subject, unsubscribe: () => live.unsubscribe() };
+    return { subject, unsubscribe: release };
   }
 
   /**
@@ -132,6 +141,7 @@ export class NatsTransport implements Transport {
 
   async close(): Promise<void> {
     this.#closed = true;
+    this.#wakeRedial?.();
     const client = this.#client;
     this.#client = undefined;
     await client?.close();
@@ -141,7 +151,9 @@ export class NatsTransport implements Transport {
    * One dial, shared by every caller that races it. A client that has already been handed out is
    * reused whatever its state: while it is reconnecting the library is re-establishing that same
    * connection and its subscriptions, and a second dial alongside it would double every delivery.
-   * A budget that ran out is a readiness failure, not a reason to start an unbounded retry here.
+   * A client closed for good is not handed out: `#lost` clears it and `#redial` replaces it, and a
+   * caller that lands meanwhile is refused at once rather than parked behind a dial that may take
+   * the library's whole connect budget.
    */
   #ensure(): Promise<NatsClient> {
     if (this.#closed) {
@@ -151,6 +163,19 @@ export class NatsTransport implements Transport {
     }
     const current = this.#client;
     if (current !== undefined) return Promise.resolve(current);
+    if (this.#redialing !== undefined) {
+      return Promise.reject(
+        new TransportUnavailableError({
+          transport: this.name,
+          reason: `the connection closed once its reconnect budget was spent, and re-dial attempt ${this.#redialing} is in progress`,
+        }),
+      );
+    }
+    return this.#dialOnce();
+  }
+
+  /** One dial, shared by every caller that races it. */
+  #dialOnce(): Promise<NatsClient> {
     this.#dialing ??= this.#dial().finally(() => {
       this.#dialing = undefined;
     });
@@ -164,6 +189,10 @@ export class NatsTransport implements Transport {
    * leaking one per retry.
    */
   async #dial(): Promise<NatsClient> {
+    // The client is only known once the dial resolves, and the library may give up on it before
+    // the bucket is asserted: both cases are caught by identity, never by a flag on the transport.
+    let opened: NatsClient | undefined;
+    let closedEarly = false;
     const client = await this.#connect({
       url: this.#options.url,
       name: 'ultimate',
@@ -173,9 +202,19 @@ export class NatsTransport implements Transport {
       reconnectDelay: () => policyDelay(this.#backoff, ++this.#retries, this.#rng),
       onError: (error) => this.#report(error, this.name),
       onReconnect: () => this.#recovered(),
+      onClosed: () => {
+        if (opened === undefined) closedEarly = true;
+        else this.#lost(opened);
+      },
     });
     try {
       await this.#ensureBucket(client);
+      if (closedEarly) {
+        throw new TransportUnavailableError({
+          transport: this.name,
+          reason: 'the connection closed for good while the KV bucket was being asserted',
+        });
+      }
       // `close()` can land while a dial is in flight, and it only closes what it can see:
       // publishing now would leave a connection open that nothing will ever close again.
       if (this.#closed) {
@@ -188,11 +227,76 @@ export class NatsTransport implements Transport {
       await client.close();
       throw error;
     }
+    opened = client;
     this.#client = client;
     this.#retries = 0;
     return client;
   }
 
+  /**
+   * The library spent its reconnect budget and closed the client. Handing it out again is a node
+   * that refuses every publish until somebody restarts it — and the liveness probe never asks the
+   * bus — so it is forgotten here and replaced in the background, subscriptions included.
+   */
+  #lost(client: NatsClient): void {
+    if (this.#closed || this.#client !== client) return;
+    this.#client = undefined;
+    this.#subscriptions.orphan();
+    this.#report(
+      new TransportUnavailableError({
+        transport: this.name,
+        reason: 'the connection closed once its reconnect budget was spent; re-dialling',
+      }),
+      this.name,
+    );
+    void this.#redial();
+  }
+
+  /**
+   * Re-dial until a client is up or the transport is closed. Bounded by our backoff between
+   * attempts (capped at the policy's `maxMs`), and each attempt is itself a library dial with its
+   * own budget, so a long outage costs one dial per interval rather than a spin. A dial that lands
+   * re-binds every kept subscription and is announced: changes published in the gap are gone.
+   */
+  async #redial(): Promise<void> {
+    if (this.#redialing !== undefined) return;
+    try {
+      for (let attempt = 1; !this.#closed && this.#client === undefined; attempt += 1) {
+        this.#redialing = attempt;
+        try {
+          const client = await this.#dialOnce();
+          // Coded like a first subscribe's refusal; the subscription stays kept for the next client.
+          for (const failure of this.#subscriptions.bindAll(client)) {
+            this.#report(
+              this.#coded(`re-subscribe to ${failure.subject}`, failure.error),
+              failure.subject,
+            );
+          }
+          this.#announce();
+        } catch (error) {
+          if (this.#closed) return;
+          this.#report(error, this.name);
+          await this.#pause(policyDelay(this.#backoff, attempt, this.#rng));
+        }
+      }
+    } finally {
+      this.#redialing = undefined;
+    }
+  }
+
+  /** A wait `close()` can cut short, so a closed transport never holds a timer for `maxMs`. */
+  #pause(ms: number): Promise<void> {
+    return new Promise((resolve) => {
+      const done = (): void => {
+        clearTimeout(timer);
+        this.#wakeRedial = undefined;
+        resolve();
+      };
+      const timer = setTimeout(done, ms);
+      this.#wakeRedial = done;
+    });
+  }
+
   #ensureBucket(client: NatsClient): Promise<void> {
     return ensureKvBucket(
       client,
@@ -216,6 +320,10 @@ export class NatsTransport implements Transport {
     if (client === undefined) return;
     // Not awaited: the library calls this from its status loop. The failure has one place to go.
     void this.#ensureBucket(client).catch((error: unknown) => this.#report(error, this.name));
+    this.#announce();
+  }
+
+  #announce(): void {
     for (const listener of [...this.#reconnectListeners]) {
       try {
         listener();
@@ -236,14 +344,18 @@ export class NatsTransport implements Transport {
     try {
       return call();
     } catch (error) {
-      if (isUltimateError(error)) throw error;
-      throw new TransportUnavailableError({
-        transport: this.name,
-        reason: `${what} was refused: ${renderThrowable(error)}`,
-      });
+      throw this.#coded(what, error);
     }
   }
 
+  #coded(what: string, error: unknown): unknown {
+    if (isUltimateError(error)) return error;
+    return new TransportUnavailableError({
+      transport: this.name,
+      reason: `${what} was refused: ${renderThrowable(error)}`,
+    });
+  }
+
   /**
    * Every background failure lands here — a lost connection, a throwing subscriber, an exhausted
    * reconnect. Dropping it when the caller passed no handler is what turns "no changes arrive"

package/src/offline-queue.ts

@@ -69,6 +69,11 @@ export class MemoryQueueStore implements QueueStore {
   }
 }
 
+/** The one way to build the in-process queue store; the class is a type in the barrel only (`X_FACTORY_NAME_SPELLING`). */
+export function memoryQueueStore(): MemoryQueueStore {
+  return new MemoryQueueStore();
+}
+
 export interface DrainReport {
   readonly sent: number;
   readonly collapsed: number;

package/src/page-errors.ts

@@ -1,9 +1,8 @@
 // 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.
+// store. Apart from `errors.ts` for bytes: that module holds the sync node's refusal classes, which
+// no island constructs. The codes and their titles are `error-titles.ts` (the module
+// `package.json`'s `sideEffects` names, imported bare by the barrel), so a code constructed here is
+// titled wherever the barrel was reached. This module runs nothing at import.
 
 import { renderFixShellArg } from '@ultimat3/core/page';
 import { RealtimeError } from './realtime-error';
@@ -36,8 +35,8 @@ export class RebaseConflictError extends RealtimeError {
 }
 
 /**
- * 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
+ * A hook ran IN A BROWSER in an island bundle whose bootstrap never called `installRealtime()`,
+ * or before the page runtime (`page-runtime.ts`, carried by the page boot) was installed. 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,
@@ -47,8 +46,8 @@ 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",
+      cause: `${args.hook}() ran in a browser island whose bundle never called installRealtime(), or on a page whose runtime (@ultimat3/realtime/boot) never loaded`,
+      fix: "x build   # the island bootstrap installs it; a hand-built island imports '@ultimat3/realtime/boot' (the page runtime) and calls installRealtime({ signal: createSignal }) from '@ultimat3/realtime' before its first render",
     });
   }
 }

package/src/page-outbox.ts

@@ -17,7 +17,7 @@ import {
 import type { LocalStore } from './local-store-idb';
 import { pageLocalStore, scopeKey } from './local-store-idb';
 import type { DrainReport, QueuedMutation, QueueState, QueueStore } from './offline-queue';
-import { MemoryQueueStore, OfflineQueue, toQueueError } from './offline-queue';
+import { memoryQueueStore, OfflineQueue, toQueueError } from './offline-queue';
 import { OUTBOX_KEY, type OutboxEntry, type OutboxHandle, type OutboxHost } from './outbox-slot';
 import { LocalStoreUnavailableError, OfflineQueueAbandonedError } from './page-errors';
 import { peekPageRealtime } from './page-store';
@@ -74,7 +74,7 @@ interface Held {
   readonly scope: string | undefined;
 }
 
-export function createOutbox(options: OutboxOptions): PageOutbox {
+export function localOutbox(options: OutboxOptions): PageOutbox {
   const principal =
     options.principal ?? ((): ClientScope['principal'] => pageClient().scope.principal);
   const send = options.send ?? sendOverHttp;
@@ -103,7 +103,7 @@ export function createOutbox(options: OutboxOptions): PageOutbox {
       queue = await OfflineQueue.open(queueStore(await options.local, scope));
     } catch (error) {
       unavailable('the outbox could not be opened', error);
-      queue = await OfflineQueue.open(new MemoryQueueStore());
+      queue = await OfflineQueue.open(memoryQueueStore());
     }
     // The principal left while the disk was being read: this queue is the one that left with it,
     // and the handler that saw the change has already chained the next open.
@@ -255,7 +255,7 @@ export function createOutbox(options: OutboxOptions): PageOutbox {
 
 /** Persisted under the principal; an UNSCOPED page queues in memory only, and loses it on reload. */
 function queueStore(local: LocalStore, scope: string | undefined): QueueStore {
-  if (scope === undefined) return new MemoryQueueStore();
+  if (scope === undefined) return memoryQueueStore();
   return {
     load: async (): Promise<QueueState> =>
       (await local.queue(scope)) ?? { mutations: [], nextSeq: 1 },
@@ -326,7 +326,7 @@ export function pageOutbox(options: Pick<OutboxOptions, 'beforeEnqueue'> = {}):
   const existing = host[OUTBOX_KEY];
   // Only this function writes the slot, so what it holds is always a `PageOutbox`.
   if (existing !== undefined) return existing as PageOutbox;
-  const outbox = createOutbox({ local: pageLocalStore(), beforeEnqueue: options.beforeEnqueue });
+  const outbox = localOutbox({ local: pageLocalStore(), beforeEnqueue: options.beforeEnqueue });
   Object.defineProperty(host, OUTBOX_KEY, { value: outbox, configurable: true });
   if (Reflect.has(globalThis, 'document')) {
     listenForDrain(outbox);

package/src/page-runtime-wait.ts

@@ -0,0 +1,72 @@
+// What a realtime island waits on before its first hook runs: the page runtime, installed ONCE per
+// page. A document the server rendered for a principal carries it in the page boot (a deferred
+// classic script); every other document — a static export, an anonymous page, an app with no sync
+// node — gets it from the runtime chunk the island loads itself. Never both, never twice.
+
+import { deferredScriptsPending, peekPageRealtime } from './page-store';
+
+export interface AwaitPageRuntimeOptions {
+  /**
+   * The path every page boot is served under (`/_x/page-boot/`). A `<script>` whose `src` starts
+   * with it is the boot this document carries, and the runtime is coming with it.
+   */
+  readonly boot: string;
+  /** Imports the runtime chunk — only on a page whose boot is absent, or never ran. */
+  readonly load: () => Promise<unknown>;
+}
+
+type Listenable = {
+  addEventListener(type: string, listener: () => void, options?: { once?: boolean }): void;
+};
+
+const installed = (): boolean => {
+  const page = peekPageRealtime();
+  return page?.store !== undefined && page.services !== undefined;
+};
+
+/**
+ * Resolves once the page runtime is installed. An island can be imported while the parser still
+ * waits on the deferred boot (the idle callback fires first), so a boot that may still run is
+ * waited for — its `load`, its `error`, or DOMContentLoaded, which fires after every deferred
+ * script — and a page it never installed the runtime on loads the chunk. Never on a FUTURE event
+ * once the deferred scripts are done: a boot that failed before the island asked fires none again.
+ */
+export async function awaitPageRuntime(options: AwaitPageRuntimeOptions): Promise<void> {
+  if (installed()) return;
+  const boot = bootElement(options.boot);
+  if (boot !== undefined) await firstOf(boot);
+  if (!installed()) await options.load();
+}
+
+/** The page boot's `<script>` while it may still run; `undefined` once it cannot, or with none. */
+function bootElement(prefix: string): Listenable | undefined {
+  const doc: unknown = Reflect.get(globalThis, 'document');
+  if (typeof doc !== 'object' || doc === null) return undefined;
+  // Every deferred script has run: a boot that installed nothing failed, and is not coming.
+  if (!deferredScriptsPending()) return undefined;
+  const query: unknown = Reflect.get(doc, 'querySelector');
+  // A partial document (a component test's stand-in) has no query surface: no tag, no boot.
+  if (typeof query !== 'function') return undefined;
+  const found: unknown = Reflect.apply(query, doc, [`script[src^="${prefix}"]`]);
+  return isListenable(found) ? found : undefined;
+}
+
+function isListenable(value: unknown): value is Listenable {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'addEventListener') === 'function'
+  );
+}
+
+/** The boot ran, failed, or every deferred script is done — whichever comes first. */
+function firstOf(boot: Listenable): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const done = (): void => resolve();
+    boot.addEventListener('load', done, { once: true });
+    boot.addEventListener('error', done, { once: true });
+    const doc: unknown = Reflect.get(globalThis, 'document');
+    if (isListenable(doc)) doc.addEventListener('DOMContentLoaded', done, { once: true });
+    if (typeof addEventListener === 'function') addEventListener('load', done, { once: true });
+  });
+}

package/src/page-runtime.ts

@@ -0,0 +1,32 @@
+// The page runtime: the ONE record store, the socket stack, the query client and core's transport
+// behind every hook, installed once per page onto the page object (`page-store.ts`). Never in an
+// island: the page boot carries it where the server renders one, and the CLI builds it as the
+// runtime chunk an island loads where it does not (`packages/cli/src/island-realtime.ts`).
+
+import { clientTransport, onRescope, pageClient } from '@ultimat3/core/page';
+import { queryClientMethodFor } from '@ultimat3/query/client';
+import { pageSocket } from './page-socket';
+import { type InstalledPage, pageRealtime } from './page-store';
+import { RecordStore } from './record-store';
+
+/**
+ * Get-or-install, idempotent: the boot and the runtime chunk may both run on one page (a boot that
+ * arrived after its island gave up on it), and whichever runs second adopts what the first built.
+ * Installs the store as core's `RecordSink`, so every HTTP answer's records land in it.
+ */
+export function installPageRuntime(): InstalledPage {
+  const page = pageRealtime();
+  const store = page.store;
+  if (store !== undefined && page.services !== undefined) return page as InstalledPage;
+  const created = store ?? new RecordStore();
+  page.store = created;
+  page.services = {
+    socket: pageSocket,
+    read: (name) => queryClientMethodFor(name, { baseUrl: '' }),
+    send: clientTransport,
+  };
+  pageClient().store = created;
+  // A new principal sees nothing of the previous one: every record goes, in memory, at once.
+  onRescope(() => created.clear());
+  return page as InstalledPage;
+}

package/src/page-socket.ts

@@ -1,6 +1,6 @@
-// The page's ONE socket: built on the first live or channel hook, by whichever island bundle asks
-// first, and shared by every other one through the page state. A form-only island never imports
-// this module, so it ships none of the connection lifecycle.
+// The page's ONE socket: built on the first live or channel hook, and shared by every island
+// through the page state. Part of the page runtime (`page-runtime.ts`), so no island bundle carries
+// the connection lifecycle: a hook reaches it as `services.socket`, off the page object.
 
 import { onRescope, pageClient } from '@ultimat3/core/page';
 import { queryClientMethodFor } from '@ultimat3/query/client';
@@ -8,7 +8,7 @@ import { LiveClient } from './client';
 import { DEFAULT_HEARTBEAT_MS } from './client-heartbeat';
 import { peekOutbox } from './outbox-slot';
 import { SyncUnconfiguredError } from './page-errors';
-import { pageRealtime } from './page-store';
+import { installedPage } from './page-store';
 import {
   openHost,
   type RehostingHost,
@@ -20,7 +20,7 @@ import { pageSyncTarget, syncWorkerFromMeta } from './sync-meta';
 
 /** Get-or-create, and connect on creation. `hook` names the caller in the refusal. */
 export function pageSocket(hook: string): LiveClient {
-  const page = pageRealtime();
+  const page = installedPage(hook);
   // Its one writer is below, so the stored value is always this class — from SOME bundle's copy,
   // which is why it is read structurally and never checked with `instanceof`.
   if (page.socket !== undefined) return page.socket as LiveClient;
@@ -110,17 +110,8 @@ export function resetPageSocket(
   hosts = options.openHost ?? openHost;
 }
 
-/**
- * Whether this page holds a socket — `false` on a server render and before any live hook ran.
- * The guard a component with a static fallback asks (an offline banner, an update prompt).
- */
-export function hasPageSocket(): boolean {
-  const host = globalThis as { [key: symbol]: unknown };
-  const page = host[Symbol.for('ultimate.realtime')];
-  return (
-    typeof page === 'object' && page !== null && (page as { socket?: unknown }).socket !== undefined
-  );
-}
+/** Where `hasPageSocket` lives, re-exported for the callers that reach it from here. */
+export { hasPageSocket } from './page-store';
 
 function hostFor(scope: string | null, buildId: string): SocketHost {
   const workerUrl =