@syncular/client 0.19.0 → 0.20.0

package/src/wasm-database.ts

@@ -53,6 +53,13 @@ interface SahPoolUtil {
   OpfsSAHPoolDb: new (filename: string) => Oo1Database;
 }
 
+interface SqliteIoMethods {
+  installMethod(
+    name: 'xCheckReservedLock',
+    callback: (file: number, output: number) => number,
+  ): unknown;
+}
+
 interface Sqlite3Static {
   oo1: {
     DB: new (filename: string, flags?: string) => Oo1Database;
@@ -60,6 +67,18 @@ interface Sqlite3Static {
   capi: {
     SQLITE_DESERIALIZE_FREEONCLOSE: number;
     SQLITE_DESERIALIZE_READONLY: number;
+    SQLITE_FCNTL_FILE_POINTER: number;
+    sqlite3_file_control(
+      db: number,
+      schema: string,
+      operation: number,
+      output: number,
+    ): number;
+    sqlite3_file: new (pointer: number) => {
+      readonly $pMethods: number;
+      dispose(): void;
+    };
+    sqlite3_io_methods: new (pointer: number) => SqliteIoMethods;
     sqlite3_deserialize(
       db: number,
       schema: string,
@@ -71,6 +90,13 @@ interface Sqlite3Static {
   };
   wasm: {
     allocFromTypedArray(bytes: Uint8Array): number;
+    peekPtr(pointer: number): number;
+    poke32(pointer: number, value: number): unknown;
+    pstack: {
+      readonly pointer: number;
+      allocPtr(): number;
+      restore(pointer: number): void;
+    };
   };
   installOpfsSAHPoolVfs(options: {
     name?: string;
@@ -217,6 +243,10 @@ function inWorkerContext(): boolean {
 /** One registered VFS per pool directory, reused across opens. */
 const sahPools = new Map<string, Promise<SahPoolUtil>>();
 
+// SAH pools share an I/O method table within the WASM runtime. Keep the
+// installed callback alive for that runtime, including across database closes.
+const sahIoMethods = new Map<number, SqliteIoMethods>();
+
 function opfsSahPoolError(error: unknown, directory: string): ClientSyncError {
   const detail = error instanceof Error ? error.message : String(error);
   const normalized = detail.toLowerCase();
@@ -306,5 +336,53 @@ export async function openPersistentWasmDatabase(
     sahPools.set(directory, pool);
   }
   const util = await pool;
-  return new WasmClientDatabase(new util.OpfsSAHPoolDb(`/${name}.db`), sqlite3);
+  const db = new util.OpfsSAHPoolDb(`/${name}.db`);
+  const { capi, wasm } = sqlite3;
+  const stack = wasm.pstack.pointer;
+  try {
+    // Do this before the first SQL statement, when SQLite checks for a hot
+    // journal. The SAH-pool callback in sqlite-wasm 3.53 reports a reserved
+    // lock unconditionally, which suppresses crash rollback. The pool already
+    // excludes other owners; report no competing writer, as the other OPFS
+    // VFS does. Keep DELETE/FULL and the existing database/journal files.
+    const output = wasm.pstack.allocPtr();
+    if (
+      db.pointer === undefined ||
+      capi.sqlite3_file_control(
+        db.pointer,
+        'main',
+        capi.SQLITE_FCNTL_FILE_POINTER,
+        output,
+      ) !== 0 ||
+      !wasm.peekPtr(output)
+    ) {
+      throw new ClientSyncError(
+        STORAGE_UNAVAILABLE_CODE,
+        'Could not configure OPFS crash recovery',
+      );
+    }
+    const file = new capi.sqlite3_file(wasm.peekPtr(output));
+    const methodsPointer = file.$pMethods;
+    file.dispose(); // Borrowed struct view; SQLite still owns the file.
+    if (!methodsPointer) {
+      throw new ClientSyncError(
+        STORAGE_UNAVAILABLE_CODE,
+        'Could not configure OPFS crash recovery',
+      );
+    }
+    if (!sahIoMethods.has(methodsPointer)) {
+      const methods = new capi.sqlite3_io_methods(methodsPointer);
+      methods.installMethod('xCheckReservedLock', (_file, reserved) => {
+        wasm.poke32(reserved, 0);
+        return 0;
+      });
+      sahIoMethods.set(methodsPointer, methods);
+    }
+    return new WasmClientDatabase(db, sqlite3);
+  } catch (error) {
+    db.close();
+    throw error;
+  } finally {
+    wasm.pstack.restore(stack);
+  }
 }

package/src/worker-entry.ts

@@ -20,7 +20,7 @@ import {
   withClientDiagnosticsHost,
 } from './diagnostics';
 import { encryptionConfigFromKeyring } from './encryption';
-import { ClientSyncError } from './errors';
+import { ClientSyncError, STORAGE_BUSY_CODE } from './errors';
 import {
   httpBlobTransport,
   httpSegmentDownloader,
@@ -51,6 +51,8 @@ export interface SyncWorkerOverrides {
   readonly openDatabase?: (
     config: WorkerInitConfig,
   ) => Promise<ClientDatabase> | ClientDatabase;
+  /** Retry deadline indirection for deterministic worker-host tests. */
+  readonly waitForStorageRetry?: (delayMs: number) => Promise<void>;
   readonly createTransport?: (config: WorkerInitConfig) => SyncTransport;
   readonly createSegments?: (
     config: WorkerInitConfig,
@@ -244,9 +246,12 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     return Object.assign(gateOffline(inner), {
       ...(fetchUrl !== undefined
         ? {
-            fetchUrl: (url: string) => {
+            fetchUrl: (
+              url: string,
+              onProgress?: (bytesReceived: number) => void,
+            ) => {
               assertOnline();
-              return fetchUrl(url);
+              return fetchUrl(url, onProgress);
             },
           }
         : {}),
@@ -262,10 +267,33 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
     }
     autoSync = config.autoSync ?? true;
 
-    database =
-      overrides.openDatabase !== undefined
-        ? await overrides.openDatabase(config)
-        : await defaultOpenDatabase(config);
+    for (let attempt = 0; ; attempt++) {
+      try {
+        database =
+          overrides.openDatabase !== undefined
+            ? await overrides.openDatabase(config)
+            : await defaultOpenDatabase(config);
+        break;
+      } catch (error) {
+        if (
+          config.database.mode !== 'persistent' ||
+          !(error instanceof ClientSyncError) ||
+          error.code !== STORAGE_BUSY_CODE ||
+          !error.retryable ||
+          attempt === 6
+        ) {
+          throw error;
+        }
+        // Retain the leader lease while the previous worker's OPFS handles
+        // drain. Only opening is retried; core initialization has not started.
+        const delayMs = Math.min(50 * 2 ** attempt, 1000);
+        if (overrides.waitForStorageRetry !== undefined) {
+          await overrides.waitForStorageRetry(delayMs);
+        } else {
+          await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
+        }
+      }
+    }
     const transport = gateOffline(
       overrides.createTransport !== undefined
         ? overrides.createTransport(config)
@@ -336,6 +364,9 @@ export function startSyncWorker(overrides: SyncWorkerOverrides = {}): void {
         post({ t: 'event', event: { kind: 'presence', scopeKey } });
       },
     });
+    started.onProgress((progress) => {
+      if (!closed) post({ t: 'event', event: { kind: 'progress', progress } });
+    });
     started.onChange((batch) => {
       if (!closed) post({ t: 'event', event: { kind: 'change', batch } });
     });

package/src/worker-host.ts

@@ -1,3 +1,8 @@
+import {
+  ProgressEmitter,
+  type SyncProgress,
+  type SyncProgressListener,
+} from './progress';
 import type { PromiseMethods } from './client';
 /**
  * Main-thread side of the worker mode and the
@@ -273,6 +278,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
   #core: LeaderCore | undefined;
   #follower: FollowerLink | undefined;
   readonly #invalidation: InvalidationEmitter;
+  readonly #progress = new ProgressEmitter();
   readonly #changes: ChangeEmitter;
   readonly #presence: Set<(scopeKey: string) => void>;
   readonly #diagnostics: ClientDiagnosticsEmitter;
@@ -376,7 +382,9 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
 
   /** @internal — dispatch a worker/relayed event to handle-local listeners. */
   __dispatchEvent(event: SyncWorkerEvent): void {
-    if (event.kind === 'presence') {
+    if (event.kind === 'progress') {
+      this.#progress.emit(event.progress);
+    } else if (event.kind === 'presence') {
       for (const listener of this.#presence) {
         try {
           listener(event.scopeKey);
@@ -409,6 +417,13 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
     return this.#invalidation.on(listener);
   }
 
+  onProgress(listener: SyncProgressListener): () => void {
+    return this.#progress.on(listener);
+  }
+  progressSnapshot(): SyncProgress | undefined {
+    return this.#progress.snapshot();
+  }
+
   onChange(listener: ClientChangeListener): () => void {
     return this.#changes.on(listener);
   }
@@ -646,6 +661,7 @@ export class SyncClientHandle implements PromiseMethods<WorkerApi> {
   async close(): Promise<void> {
     if (this.#closed) return;
     this.#closed = true;
+    this.#progress.clear();
     this.#devtoolsUnregister();
     if (this.#follower !== undefined) {
       this.#follower.close();

package/src/worker-protocol.ts

@@ -1,3 +1,4 @@
+import type { SyncProgress } from './progress';
 /**
  * The worker RPC protocol: the whole
  * client core runs in a Web Worker; the UI thread talks to it through
@@ -206,6 +207,7 @@ export interface WorkerErrorShape {
 }
 
 export type SyncWorkerEvent =
+  | { readonly kind: 'progress'; readonly progress: SyncProgress }
   | {
       readonly kind: 'sync-needed';
       readonly reason: 'startup' | 'hello' | WakeReason;