@syncular/client 0.15.35 → 0.15.37

package/dist/realtime-supervisor.js

@@ -0,0 +1,452 @@
+const REALTIME_SUPERVISOR_KEY = Symbol.for('syncular.realtime-supervisor.v1');
+const DEFAULT_INITIAL_DELAY_MS = 1_000;
+const DEFAULT_MAXIMUM_DELAY_MS = 30_000;
+const MAXIMUM_CONFIGURED_DELAY_MS = 300_000;
+const UNSUPPORTED_SNAPSHOT = Object.freeze({
+    phase: 'unsupported',
+    attempt: 0,
+});
+function attachment(client) {
+    const candidate = Reflect.get(client, REALTIME_SUPERVISOR_KEY);
+    return candidate?.version === 1 && candidate.supervisor
+        ? candidate
+        : undefined;
+}
+function scheduleTimer(callback, delayMs) {
+    const timer = globalThis.setTimeout(callback, delayMs);
+    return () => globalThis.clearTimeout(timer);
+}
+function boundedDelay(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError('realtime supervisor delays must be positive safe integers');
+    }
+    return Math.min(value, MAXIMUM_CONFIGURED_DELAY_MS);
+}
+function eventTarget(value) {
+    const candidate = value;
+    return typeof candidate?.addEventListener === 'function' &&
+        typeof candidate.removeEventListener === 'function'
+        ? candidate
+        : undefined;
+}
+/** Browser/Tauri-webview connectivity evidence without importing DOM types. */
+export function browserConnectivitySignal(options = {}) {
+    const root = globalThis;
+    const events = options.events ?? eventTarget(globalThis);
+    const network = options.network ?? root.navigator;
+    const current = () => {
+        if (network?.onLine === true)
+            return 'online';
+        if (network?.onLine === false)
+            return 'offline';
+        return 'unknown';
+    };
+    return {
+        current,
+        subscribe(listener) {
+            if (events === undefined)
+                return () => undefined;
+            const notify = () => listener(current());
+            events.addEventListener('online', notify);
+            events.addEventListener('offline', notify);
+            return () => {
+                events.removeEventListener('online', notify);
+                events.removeEventListener('offline', notify);
+            };
+        },
+    };
+}
+/** Browser/Tauri-webview visibility evidence without importing DOM types. */
+export function documentLifecycleSignal(options = {}) {
+    const root = globalThis;
+    const document = options.document ?? root.document;
+    const events = options.events ?? eventTarget(document);
+    const classify = () => {
+        if (document?.visibilityState === 'visible')
+            return 'active';
+        if (document?.visibilityState === 'hidden')
+            return 'background';
+        return 'unknown';
+    };
+    let state = classify();
+    return {
+        current: () => state,
+        subscribe(listener) {
+            if (events === undefined)
+                return () => undefined;
+            const visibility = () => {
+                state = classify();
+                listener(state);
+            };
+            const background = () => {
+                state = 'background';
+                listener(state);
+            };
+            const active = () => {
+                state = classify() === 'background' ? 'background' : 'active';
+                listener(state);
+            };
+            events.addEventListener('visibilitychange', visibility);
+            events.addEventListener('pagehide', background);
+            events.addEventListener('pageshow', active);
+            return () => {
+                events.removeEventListener('visibilitychange', visibility);
+                events.removeEventListener('pagehide', background);
+                events.removeEventListener('pageshow', active);
+            };
+        },
+    };
+}
+/**
+ * Supported host policy for Syncular's explicit realtime transport. It owns
+ * exactly one connect attempt, runs an explicit catch-up round before claiming
+ * connected, retries transient loss with bounded exponential jitter, and
+ * suspends across offline, background, or protected-preflight state.
+ */
+export class RealtimeSupervisor {
+    #client;
+    #connectivity;
+    #lifecycle;
+    #protection;
+    #scheduleTimer;
+    #random;
+    #initialDelayMs;
+    #maximumDelayMs;
+    #listeners = new Set();
+    #started = false;
+    #initialized = false;
+    #stopped = false;
+    #connected = false;
+    #transportConnected = false;
+    #connecting = false;
+    #realtimeSupported = true;
+    #diagnosticConnectivity = 'unknown';
+    #diagnosticSecurity = 'unknown';
+    #attempt = 0;
+    #generation = 0;
+    #snapshot = { phase: 'idle', attempt: 0 };
+    #cancelRetry;
+    #unsubscribeDiagnostics;
+    #unsubscribeConnectivity;
+    #unsubscribeLifecycle;
+    #unsubscribeProtection;
+    constructor(client, options = {}) {
+        this.#client = client;
+        this.#connectivity = options.connectivity;
+        this.#lifecycle = options.lifecycle;
+        this.#protection = options.protection;
+        this.#scheduleTimer = options.schedule ?? scheduleTimer;
+        this.#random = options.random ?? Math.random;
+        this.#initialDelayMs = boundedDelay(options.initialDelayMs, DEFAULT_INITIAL_DELAY_MS);
+        this.#maximumDelayMs = Math.max(this.#initialDelayMs, boundedDelay(options.maximumDelayMs, DEFAULT_MAXIMUM_DELAY_MS));
+    }
+    snapshot() {
+        return this.#snapshot;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    start() {
+        if (this.#started || this.#stopped)
+            return;
+        this.#started = true;
+        this.#unsubscribeDiagnostics = this.#client.onDiagnostics((snapshot) => this.#observeDiagnostics(snapshot));
+        this.#unsubscribeConnectivity = this.#connectivity?.subscribe(() => this.#reconcileHostState());
+        this.#unsubscribeLifecycle = this.#lifecycle?.subscribe(() => this.#reconcileHostState());
+        this.#unsubscribeProtection = this.#protection?.subscribe(() => this.#reconcileHostState());
+        this.#reconcileHostState();
+        const generation = this.#generation;
+        void this.#initialize(generation);
+    }
+    stop() {
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
+        this.#generation += 1;
+        const disconnect = this.#connected || this.#transportConnected || this.#connecting;
+        this.#connected = false;
+        this.#transportConnected = false;
+        this.#connecting = false;
+        this.#attempt = 0;
+        this.#clearRetry();
+        this.#unsubscribeDiagnostics?.();
+        this.#unsubscribeConnectivity?.();
+        this.#unsubscribeLifecycle?.();
+        this.#unsubscribeProtection?.();
+        this.#publish({ phase: 'stopped', attempt: 0 });
+        if (disconnect)
+            this.#disconnect();
+    }
+    async #initialize(generation) {
+        let snapshot;
+        try {
+            snapshot = await this.#client.diagnosticsSnapshot();
+        }
+        catch {
+            // Protected or temporarily unavailable diagnostics must not become a
+            // startup dependency. Explicit host gates and the connect result remain.
+        }
+        if (generation !== this.#generation || this.#stopped)
+            return;
+        this.#initialized = true;
+        if (snapshot !== undefined)
+            this.#observeDiagnostics(snapshot, true);
+        this.#reconcileHostState();
+    }
+    #hostBlock() {
+        const protection = this.#protection?.current();
+        if (this.#diagnosticSecurity === 'preflight' ||
+            protection === 'preflight' ||
+            (this.#protection !== undefined && protection !== 'active')) {
+            return 'protected';
+        }
+        if (this.#diagnosticConnectivity === 'offline' ||
+            this.#connectivity?.current() === 'offline') {
+            return 'offline';
+        }
+        if (this.#lifecycle?.current() === 'background')
+            return 'background';
+        return undefined;
+    }
+    #canConnect() {
+        return (this.#initialized &&
+            !this.#stopped &&
+            this.#realtimeSupported &&
+            !this.#hostBlock());
+    }
+    #publish(snapshot) {
+        if (this.#snapshot.phase === snapshot.phase &&
+            this.#snapshot.attempt === snapshot.attempt &&
+            this.#snapshot.retryDelayMs === snapshot.retryDelayMs) {
+            return;
+        }
+        this.#snapshot = Object.freeze(snapshot);
+        for (const listener of this.#listeners) {
+            try {
+                listener();
+            }
+            catch {
+                // Observers cannot alter transport ownership or retry policy.
+            }
+        }
+    }
+    #clearRetry() {
+        this.#cancelRetry?.();
+        this.#cancelRetry = undefined;
+    }
+    #schedule(delayMs) {
+        if (!this.#canConnect() ||
+            this.#connected ||
+            this.#connecting ||
+            this.#cancelRetry) {
+            return;
+        }
+        this.#publish(delayMs > 0
+            ? { phase: 'retrying', attempt: this.#attempt, retryDelayMs: delayMs }
+            : { phase: 'connecting', attempt: this.#attempt });
+        this.#cancelRetry = this.#scheduleTimer(() => {
+            this.#cancelRetry = undefined;
+            void this.#connect();
+        }, delayMs);
+    }
+    #retryDelay() {
+        const exponential = Math.min(this.#maximumDelayMs, this.#initialDelayMs * 2 ** this.#attempt);
+        const random = this.#random();
+        const boundedRandom = Number.isFinite(random)
+            ? Math.max(0, Math.min(1, random))
+            : 0;
+        const jitter = Math.floor(exponential * 0.25 * boundedRandom);
+        return Math.min(this.#maximumDelayMs, exponential + jitter);
+    }
+    #scheduleRetry() {
+        if (!this.#canConnect()) {
+            this.#reconcileHostState();
+            return;
+        }
+        const delay = this.#retryDelay();
+        this.#attempt = Math.min(32, this.#attempt + 1);
+        this.#schedule(delay);
+    }
+    async #connect() {
+        if (!this.#canConnect() || this.#connected || this.#connecting)
+            return;
+        this.#connecting = true;
+        this.#publish({ phase: 'connecting', attempt: this.#attempt });
+        const generation = this.#generation;
+        let failed = false;
+        try {
+            await this.#client.connectRealtime();
+            this.#transportConnected = true;
+            if (generation !== this.#generation || !this.#canConnect()) {
+                this.#disconnect();
+                return;
+            }
+            await this.#catchUpConnectedTransport(generation);
+        }
+        catch {
+            failed = true;
+            this.#connected = false;
+            this.#transportConnected = false;
+            this.#disconnect();
+        }
+        finally {
+            this.#connecting = false;
+        }
+        if (failed && generation === this.#generation)
+            this.#scheduleRetry();
+    }
+    async #catchUpConnectedTransport(generation) {
+        await this.#client.syncUntilIdle();
+        if (generation !== this.#generation ||
+            !this.#canConnect() ||
+            !this.#transportConnected) {
+            this.#disconnect();
+            return;
+        }
+        this.#connected = true;
+        this.#attempt = 0;
+        this.#publish({ phase: 'connected', attempt: 0 });
+    }
+    async #adoptConnectedTransport() {
+        if (!this.#canConnect() || this.#connecting || !this.#transportConnected) {
+            return;
+        }
+        this.#connecting = true;
+        this.#clearRetry();
+        this.#publish({ phase: 'connecting', attempt: this.#attempt });
+        const generation = this.#generation;
+        let failed = false;
+        try {
+            await this.#catchUpConnectedTransport(generation);
+        }
+        catch {
+            failed = true;
+            this.#connected = false;
+            this.#transportConnected = false;
+            this.#disconnect();
+        }
+        finally {
+            this.#connecting = false;
+        }
+        if (failed && generation === this.#generation)
+            this.#scheduleRetry();
+    }
+    #observeDiagnostics(snapshot, initial = false) {
+        if (this.#stopped)
+            return;
+        this.#diagnosticConnectivity = snapshot.host.connectivity;
+        this.#diagnosticSecurity = snapshot.securityLifecycle;
+        if (snapshot.host.realtime === 'unsupported') {
+            const disconnect = this.#connected || this.#transportConnected || this.#connecting;
+            this.#realtimeSupported = false;
+            this.#generation += 1;
+            this.#connected = false;
+            this.#transportConnected = false;
+            this.#attempt = 0;
+            this.#clearRetry();
+            this.#publish({ phase: 'unsupported', attempt: 0 });
+            if (disconnect)
+                this.#disconnect();
+            return;
+        }
+        if (!this.#realtimeSupported)
+            return;
+        this.#realtimeSupported = true;
+        const block = this.#hostBlock();
+        if (block) {
+            this.#suspend(block);
+            return;
+        }
+        if (snapshot.host.realtime === 'connected') {
+            this.#transportConnected = true;
+            if (this.#connecting)
+                return;
+            this.#connected = false;
+            void this.#adoptConnectedTransport();
+            return;
+        }
+        if (snapshot.host.realtime === 'disconnected') {
+            this.#transportConnected = false;
+            this.#connected = false;
+            if (this.#connecting)
+                return;
+            if (this.#initialized && !initial)
+                this.#scheduleRetry();
+            return;
+        }
+        this.#reconcileHostState();
+    }
+    #reconcileHostState() {
+        if (this.#stopped)
+            return;
+        const block = this.#hostBlock();
+        if (block) {
+            this.#suspend(block);
+            return;
+        }
+        if (!this.#initialized) {
+            this.#publish({ phase: 'idle', attempt: 0 });
+            return;
+        }
+        if (!this.#realtimeSupported) {
+            this.#publish({ phase: 'unsupported', attempt: 0 });
+            return;
+        }
+        if (this.#connected) {
+            this.#publish({ phase: 'connected', attempt: 0 });
+            return;
+        }
+        this.#schedule(0);
+    }
+    #suspend(phase) {
+        const disconnect = this.#connected || this.#transportConnected || this.#connecting;
+        const hadScheduledWork = this.#cancelRetry !== undefined;
+        const phaseChanged = this.#snapshot.phase !== phase;
+        if (!disconnect && !hadScheduledWork && !phaseChanged)
+            return;
+        this.#generation += 1;
+        this.#connected = false;
+        this.#transportConnected = false;
+        this.#connecting = false;
+        this.#attempt = 0;
+        this.#clearRetry();
+        this.#publish({ phase, attempt: 0 });
+        if (disconnect)
+            this.#disconnect();
+    }
+    #disconnect() {
+        void Promise.resolve(this.#client.disconnectRealtime()).catch(() => undefined);
+    }
+}
+/** Install one supervisor and make client disposal cancel it before close. */
+export function installRealtimeSupervisor(client, options) {
+    if (attachment(client))
+        return client;
+    const supervisor = new RealtimeSupervisor(client, options);
+    Object.defineProperty(client, REALTIME_SUPERVISOR_KEY, {
+        configurable: false,
+        enumerable: false,
+        writable: false,
+        value: { version: 1, supervisor },
+    });
+    const close = client.close.bind(client);
+    Object.defineProperty(client, 'close', {
+        configurable: true,
+        writable: true,
+        value: async () => {
+            supervisor.stop();
+            await close();
+        },
+    });
+    supervisor.start();
+    return client;
+}
+export function realtimeSupervisorSnapshot(client) {
+    return attachment(client)?.supervisor.snapshot() ?? UNSUPPORTED_SNAPSHOT;
+}
+export function subscribeRealtimeSupervisor(client, listener) {
+    return (attachment(client)?.supervisor.subscribe(listener) ?? (() => undefined));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.35",
+  "version": "0.15.37",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.35"
+    "@syncular/core": "0.15.37"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11"
@@ -92,7 +92,7 @@
     }
   },
   "devDependencies": {
-    "@syncular/server": "0.15.35",
+    "@syncular/server": "0.15.37",
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.11.1"
   }

package/src/client.ts

@@ -109,6 +109,10 @@ import {
   type LocalDataRebootstrapResult,
   localDataRebootstrapMetaKey,
 } from './local-rebootstrap';
+import {
+  decodeLocalDataRebootstrapReceipt,
+  encodeLocalDataRebootstrapReceipt,
+} from './local-rebootstrap-receipt';
 import {
   appendOutboxCommit,
   deleteOutboxCommit,
@@ -541,6 +545,8 @@ export class SyncClient {
   #conflicts: ConflictRecord[] = [];
   #rejections: RejectionRecord[] = [];
   #socket: RealtimeSocket | undefined;
+  #realtimeConnectPromise: Promise<void> | undefined;
+  #realtimeGeneration = 0;
   #pendingRound: PendingRound | undefined;
   #needsPull = false;
   #syncing = false;
@@ -789,8 +795,7 @@ export class SyncClient {
   async close(): Promise<void> {
     this.#devtoolsUnregister?.();
     this.#devtoolsUnregister = undefined;
-    this.#socket?.close();
-    this.#socket = undefined;
+    this.disconnectRealtime();
     this.#abortPendingRound('client closed mid-round');
     await this.#lease?.release();
     this.#lease = undefined;
@@ -2244,11 +2249,13 @@ export class SyncClient {
     this.#requireActive();
     const rebootstrapId = compileLocalDataRebootstrap(input);
     const metaKey = localDataRebootstrapMetaKey(rebootstrapId);
-    if (getMeta(this.#db, metaKey) !== undefined) {
+    const persistedReceipt = getMeta(this.#db, metaKey);
+    if (persistedReceipt !== undefined) {
+      const receipt = decodeLocalDataRebootstrapReceipt(persistedReceipt);
       return {
         alreadyApplied: true,
-        retainedCommits: 0,
-        resetSubscriptions: 0,
+        retainedCommits: receipt.retainedCommits,
+        resetSubscriptions: receipt.resetSubscriptions,
       };
     }
     if (this.#schemaFloor !== undefined) {
@@ -2275,7 +2282,14 @@ export class SyncClient {
         for (const commit of pending) {
           this.#applyOperationsLocally(commit.operations, batch);
         }
-        setMeta(this.#db, metaKey, 'v1');
+        setMeta(
+          this.#db,
+          metaKey,
+          encodeLocalDataRebootstrapReceipt({
+            retainedCommits: pending.length,
+            resetSubscriptions,
+          }),
+        );
       });
     } catch (error) {
       this.#upgrading = priorUpgrading;
@@ -2745,10 +2759,32 @@ export class SyncClient {
   // -- realtime (§8 client side) ----------------------------------------------
 
   connectRealtime(): Promise<void> {
-    return this.#runProtectedAsync(() => this.#connectRealtime());
+    this.#requireActive();
+    if (this.#socket !== undefined) return Promise.resolve();
+    if (this.#realtimeConnectPromise !== undefined) {
+      return this.#realtimeConnectPromise;
+    }
+    const generation = this.#realtimeGeneration;
+    const task = this.#runProtectedAsync(() =>
+      this.#connectRealtime(generation),
+    );
+    this.#realtimeConnectPromise = task;
+    void task.then(
+      () => {
+        if (this.#realtimeConnectPromise === task) {
+          this.#realtimeConnectPromise = undefined;
+        }
+      },
+      () => {
+        if (this.#realtimeConnectPromise === task) {
+          this.#realtimeConnectPromise = undefined;
+        }
+      },
+    );
+    return task;
   }
 
-  async #connectRealtime(): Promise<void> {
+  async #connectRealtime(generation: number): Promise<void> {
     const connector = this.#config.realtime;
     if (connector === undefined) {
       throw new ClientSyncError(
@@ -2756,16 +2792,19 @@ export class SyncClient {
         'no realtime connector configured',
       );
     }
+    let openedSocket: RealtimeSocket | undefined;
     const socket = await connector({
       onText: (text) => this.#handleRealtimeText(text),
       onBinary: (bytes) => this.#routeRealtimeBinary(bytes),
       onClose: () => {
+        if (openedSocket === undefined || this.#socket !== openedSocket) return;
         this.#socket = undefined;
         this.#presence.clear(); // §8.6.1: presence is per-connection
         this.#abortPendingRound('realtime socket closed mid-round (§8.7)');
         this.#emitDiagnostics();
       },
     });
+    openedSocket = socket;
     if (this.#securityLifecycle === 'preflight') {
       socket.close();
       throw new ClientSyncError(
@@ -2773,11 +2812,20 @@ export class SyncClient {
         'realtime connected after the client entered security preflight',
       );
     }
+    if (generation !== this.#realtimeGeneration || !this.#started) {
+      socket.close();
+      throw new ClientSyncError(
+        'client.realtime_cancelled',
+        'realtime connection was cancelled before activation',
+      );
+    }
     this.#socket = socket;
     this.#emitDiagnostics();
   }
 
   disconnectRealtime(): void {
+    this.#realtimeGeneration += 1;
+    this.#realtimeConnectPromise = undefined;
     this.#socket?.close();
     this.#socket = undefined;
     this.#presence.clear(); // §8.6.1: presence is per-connection

package/src/index.ts

@@ -29,6 +29,7 @@ export * from './outbox';
 export * from './outcomes';
 export * from './query-guard';
 export * from './reactive-store';
+export * from './realtime-supervisor';
 export * from './schema';
 export * from './sql-tag';
 export * from './state';

package/src/local-rebootstrap-receipt.ts

@@ -0,0 +1,79 @@
+import { ClientSyncError } from './errors';
+
+const LEGACY_MARKER = 'v1';
+const RECEIPT_VERSION = 2;
+const RECEIPT_KEYS = [
+  'resetSubscriptions',
+  'retainedCommits',
+  'version',
+] as const;
+
+export interface LocalDataRebootstrapReceipt {
+  readonly retainedCommits: number;
+  readonly resetSubscriptions: number;
+}
+
+function invalidReceipt(): never {
+  throw new ClientSyncError(
+    'sync.local_corrupt',
+    'persisted local rebootstrap receipt is invalid',
+  );
+}
+
+function isCount(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+/** Encode only the bounded counts that are safe to replay outside the core. */
+export function encodeLocalDataRebootstrapReceipt(
+  receipt: LocalDataRebootstrapReceipt,
+): string {
+  if (
+    !isCount(receipt.retainedCommits) ||
+    !isCount(receipt.resetSubscriptions)
+  ) {
+    return invalidReceipt();
+  }
+  return JSON.stringify({
+    version: RECEIPT_VERSION,
+    retainedCommits: receipt.retainedCommits,
+    resetSubscriptions: receipt.resetSubscriptions,
+  });
+}
+
+/**
+ * Decode a committed receipt without leaking its application-owned key. The
+ * original counts were not retained by pre-0.15.36 `v1` markers, so those
+ * historical repairs keep their former zero-count replay behavior.
+ */
+export function decodeLocalDataRebootstrapReceipt(
+  value: string,
+): LocalDataRebootstrapReceipt {
+  if (value === LEGACY_MARKER) {
+    return { retainedCommits: 0, resetSubscriptions: 0 };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return invalidReceipt();
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return invalidReceipt();
+  }
+  const source = parsed as Record<string, unknown>;
+  const keys = Object.keys(source).sort();
+  if (
+    keys.length !== RECEIPT_KEYS.length ||
+    keys.some((key, index) => key !== RECEIPT_KEYS[index]) ||
+    source.version !== RECEIPT_VERSION ||
+    !isCount(source.retainedCommits) ||
+    !isCount(source.resetSubscriptions)
+  ) {
+    return invalidReceipt();
+  }
+  return {
+    retainedCommits: source.retainedCommits,
+    resetSubscriptions: source.resetSubscriptions,
+  };
+}