@xnetjs/sqlite 0.0.3 → 0.1.1

package/dist/adapters/web-proxy.js

@@ -1,5 +1,209 @@
+import {
+  readBootLogArgs
+} from "../chunk-CGI2YBZY.js";
+
 // src/adapters/web-proxy.ts
 import * as Comlink from "comlink";
+
+// src/adapters/open-retry.ts
+async function openWithTimeoutRetry(makeAttempt, options = {}) {
+  const maxAttempts = options.maxAttempts ?? 3;
+  const timeoutMs = options.timeoutMs ?? 15e3;
+  const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const timeoutSeconds = Math.round(timeoutMs / 1e3);
+  let lastErr;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const controls = makeAttempt(attempt);
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(
+        () => reject(
+          new Error(
+            `Worker initialization timeout after ${timeoutSeconds}s (attempt ${attempt}/${maxAttempts})`
+          )
+        ),
+        timeoutMs
+      );
+    });
+    try {
+      await Promise.race([controls.open, timeout]);
+      return;
+    } catch (err) {
+      lastErr = err;
+      controls.abandon();
+      if (attempt >= maxAttempts) break;
+      options.onRetry?.(attempt, err);
+      await sleep(250 * attempt);
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
+  }
+  throw lastErr;
+}
+
+// src/adapters/web-leader.ts
+var DB_LEADER_LOCK_NAME = "xnet-sqlite-db-leader";
+var FOLLOWER_CONNECT_TIMEOUT_MS = 15e3;
+var FOLLOWER_RETRY_DELAY_MS = 250;
+var LeaderLostError = class extends Error {
+  constructor() {
+    super(
+      "SQLite leader tab closed while this call was in flight. Idempotent reads retry automatically; writes must be re-submitted."
+    );
+    this.name = "LeaderLostError";
+  }
+};
+function isMultiTabSupported() {
+  return typeof navigator !== "undefined" && typeof navigator.locks !== "undefined" && typeof globalThis.SharedWorker === "function";
+}
+function acquireTabRole(locks, onPromoted, lockName = DB_LEADER_LOCK_NAME) {
+  const held = { release: null };
+  const abort = new AbortController();
+  const hold = () => new Promise((resolve) => {
+    held.release = resolve;
+  });
+  const release = () => {
+    if (held.release) held.release();
+    else abort.abort();
+  };
+  return new Promise((resolve, reject) => {
+    locks.request(lockName, { mode: "exclusive", ifAvailable: true }, (lock) => {
+      if (lock === null) {
+        resolve({ role: "follower", release });
+        void locks.request(lockName, { mode: "exclusive", signal: abort.signal }, () => {
+          onPromoted();
+          return hold();
+        }).catch(() => {
+        });
+        return void 0;
+      }
+      resolve({ role: "leader", release });
+      return hold();
+    }).catch(reject);
+  });
+}
+function serveLeaderPorts(router, mintPort) {
+  const unsubscribe = router.onMessage((message) => {
+    const msg = message;
+    if (msg.t !== "mint-db-port" || typeof msg.requestId !== "string") return;
+    void mintPort().then((port) => {
+      router.post({ t: "db-port", requestId: msg.requestId }, [port]);
+    }).catch((err) => {
+      router.post({
+        t: "db-port-failed",
+        requestId: msg.requestId,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    });
+  });
+  router.post({ t: "leader-ready" });
+  return unsubscribe;
+}
+async function requestDbPort(router, options) {
+  const timeoutMs = options?.timeoutMs ?? FOLLOWER_CONNECT_TIMEOUT_MS;
+  const retryDelayMs = options?.retryDelayMs ?? FOLLOWER_RETRY_DELAY_MS;
+  const deadline = Date.now() + timeoutMs;
+  let attempt = 0;
+  for (; ; ) {
+    attempt += 1;
+    const requestId = `port-${attempt}-${Math.random().toString(36).slice(2)}`;
+    const result = await new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        resolve("retry");
+      }, retryDelayMs * 4);
+      const cleanup = router.onMessage((message, ports) => {
+        const msg = message;
+        if (msg.requestId !== requestId) return;
+        clearTimeout(timer);
+        cleanup();
+        if (msg.t === "db-port" && ports[0]) resolve(ports[0]);
+        else if (msg.t === "no-leader") resolve("retry");
+        else resolve("failed");
+      });
+      router.post({ t: "request-db-port", requestId });
+    });
+    if (result !== "retry" && result !== "failed") {
+      return result;
+    }
+    if (result === "failed" || Date.now() + retryDelayMs > deadline) {
+      throw new Error("Timed out waiting for the SQLite leader tab to share a database port");
+    }
+    await new Promise((r) => setTimeout(r, retryDelayMs));
+  }
+}
+var FollowerCallGuard = class {
+  pending = /* @__PURE__ */ new Set();
+  lost = false;
+  /**
+   * Run `op`, racing it against leader loss. `retry` (reads only — they're
+   * idempotent) re-runs the op once via `whenReconnected` after a loss.
+   */
+  async run(op, opts = {}) {
+    if (this.lost && !opts.retry) throw new LeaderLostError();
+    let rejectPending;
+    const lossSignal = new Promise((_, reject) => {
+      rejectPending = reject;
+      this.pending.add(reject);
+    });
+    try {
+      return await Promise.race([op(), lossSignal]);
+    } catch (err) {
+      if (err instanceof LeaderLostError && opts.retry) {
+        return opts.retry();
+      }
+      throw err;
+    } finally {
+      this.pending.delete(rejectPending);
+    }
+  }
+  /** Reject every in-flight call. Safe to call more than once. */
+  markLeaderLost() {
+    this.lost = true;
+    for (const reject of this.pending) {
+      reject(new LeaderLostError());
+    }
+    this.pending.clear();
+  }
+  /** The connection was re-established (this tab promoted or re-attached). */
+  markReconnected() {
+    this.lost = false;
+  }
+};
+function wrapRouterPort(port) {
+  const listeners = /* @__PURE__ */ new Set();
+  port.onmessage = (event) => {
+    for (const listener of [...listeners]) {
+      listener(event.data, event.ports);
+    }
+  };
+  port.start?.();
+  return {
+    post(message, transfer2) {
+      if (transfer2 && transfer2.length > 0) port.postMessage(message, transfer2);
+      else port.postMessage(message);
+    },
+    onMessage(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+function connectRouter() {
+  if (!isMultiTabSupported()) return null;
+  try {
+    const worker = new SharedWorker(new URL("./web-router-worker.js", import.meta.url), {
+      type: "module",
+      name: "xnet-sqlite-router"
+    });
+    return wrapRouterPort(worker.port);
+  } catch (err) {
+    console.warn("[WebSQLiteLeader] SharedWorker router unavailable:", err);
+    return null;
+  }
+}
+
+// src/adapters/web-proxy.ts
 function isDebugEnabled() {
   return typeof localStorage !== "undefined" && localStorage.getItem("xnet:sqlite:debug") === "true";
 }
@@ -33,6 +237,20 @@ var WebSQLiteProxy = class {
   _config = null;
   inTransaction = false;
   operationStats = createEmptyOperationStats();
+  // ─── Multi-tab leadership (exploration 0263) ────────────────────────────
+  /** 'single-tab' = the pre-0263 per-tab worker path (or multiTab: false). */
+  role = "single-tab";
+  roleHandle = null;
+  router = null;
+  unsubscribeLeaderServe = null;
+  unsubscribeRouterEvents = null;
+  /** The Comlink port into the LEADER's SQLite worker (follower role only). */
+  followerPort = null;
+  guard = new FollowerCallGuard();
+  /** Resolvers waiting for the connection to come back after leader loss. */
+  reconnectWaiters = [];
+  /** Serializes role transitions (promotion vs. reattach can race). */
+  transition = Promise.resolve();
   createWorkerProxy() {
     log("[WebSQLiteProxy] Creating worker...");
     this.worker = new Worker(new URL("./web-worker.js", import.meta.url), { type: "module" });
@@ -42,24 +260,193 @@ var WebSQLiteProxy = class {
     this.worker.onmessageerror = (event) => {
       console.error("[WebSQLiteProxy] Worker message error:", event);
     };
+    this.worker.addEventListener("message", (event) => {
+      const bootLogArgs = readBootLogArgs(event.data);
+      if (bootLogArgs) {
+        console.info(...bootLogArgs);
+      }
+    });
     log("[WebSQLiteProxy] Worker created, wrapping with Comlink...");
     this.proxy = Comlink.wrap(this.worker);
     return this.proxy;
   }
   async open(config) {
-    if (this.worker) {
+    if (this.worker || this.proxy) {
       throw new Error("Already open. Call close() first.");
     }
-    const proxy = this.createWorkerProxy();
-    log("[WebSQLiteProxy] Calling proxy.open()...");
-    const openPromise = proxy.open(config);
-    this.operationStats.workerRequestCount += 1;
-    const timeoutPromise = new Promise(
-      (_, reject) => setTimeout(() => reject(new Error("Worker initialization timeout after 15s")), 15e3)
+    if (config.multiTab !== false && isMultiTabSupported()) {
+      try {
+        await this.openMultiTab(config);
+        this._config = config;
+        return;
+      } catch (err) {
+        console.warn(
+          "[WebSQLiteProxy] Multi-tab routing failed \u2014 falling back to single-tab open:",
+          err
+        );
+        this.teardownMultiTab();
+      }
+    }
+    await this.openSingleTab(config);
+    this._config = config;
+  }
+  async openSingleTab(config) {
+    await openWithTimeoutRetry(
+      () => {
+        const proxy = this.createWorkerProxy();
+        log("[WebSQLiteProxy] Calling proxy.open()...");
+        this.operationStats.workerRequestCount += 1;
+        return {
+          open: proxy.open(config),
+          // (createWorkerProxy() set this.worker, but the top `if (this.worker)
+          // throw` guard narrowed it to null here — re-widen the read.)
+          abandon: () => {
+            const worker = this.worker;
+            worker?.terminate();
+            this.worker = null;
+            this.proxy = null;
+          }
+        };
+      },
+      {
+        timeoutMs: config.openTimeoutMs ?? 15e3,
+        onRetry: (attempt, err) => {
+          console.warn(
+            `[WebSQLiteProxy] SQLite worker open timed out (attempt ${attempt}); terminated the stuck worker to release its OPFS handle and retrying with a fresh worker (this usually clears handle contention left by a prior boot).`,
+            err
+          );
+        }
+      }
     );
-    await Promise.race([openPromise, timeoutPromise]);
     log("[WebSQLiteProxy] proxy.open() completed");
-    this._config = config;
+  }
+  // ─── Multi-tab open / transitions (exploration 0263) ────────────────────
+  async openMultiTab(config) {
+    const router = connectRouter();
+    if (!router) {
+      throw new Error("SharedWorker router unavailable");
+    }
+    this.router = router;
+    const locks = navigator.locks;
+    this.roleHandle = await acquireTabRole(locks, () => {
+      this.enqueueTransition(() => this.promoteToLeader());
+    });
+    this.role = this.roleHandle.role;
+    if (this.role === "leader") {
+      await this.openSingleTab(config);
+      this.becomeLeaderOnRouter();
+    } else {
+      this.unsubscribeRouterEvents = router.onMessage((message) => {
+        const msg = message;
+        if (msg.t === "leader-changed" && this.role === "follower") {
+          this.enqueueTransition(() => this.reattachFollower());
+        }
+      });
+      await this.attachToLeader();
+    }
+    console.info("[xNet] sqlite tab role", this.role);
+  }
+  becomeLeaderOnRouter() {
+    if (!this.router) return;
+    this.unsubscribeLeaderServe = serveLeaderPorts(this.router, () => this.createMessagePort());
+  }
+  async attachToLeader() {
+    if (!this.router) throw new Error("router not connected");
+    const port = await requestDbPort(this.router);
+    this.followerPort = port;
+    this.proxy = Comlink.wrap(port);
+    const isOpen = await this.guard.run(() => this.proxy.isOpen());
+    if (!isOpen) {
+      throw new Error("leader database is not open");
+    }
+    this.guard.markReconnected();
+    this.notifyReconnected();
+  }
+  /** This tab won the leadership lock after the previous leader went away. */
+  async promoteToLeader() {
+    if (this.role !== "follower" || !this._config) return;
+    log("[WebSQLiteProxy] Promoted to SQLite leader \u2014 opening own worker");
+    this.guard.markLeaderLost();
+    this.followerPort?.close();
+    this.followerPort = null;
+    this.proxy = null;
+    this.unsubscribeRouterEvents?.();
+    this.unsubscribeRouterEvents = null;
+    try {
+      await this.openSingleTab(this._config);
+      this.role = "leader";
+      this.becomeLeaderOnRouter();
+      this.guard.markReconnected();
+      this.notifyReconnected();
+      console.info("[xNet] sqlite tab role", this.role, "(promoted)");
+    } catch (err) {
+      console.error("[WebSQLiteProxy] Leader promotion failed:", err);
+    }
+  }
+  /** Another tab became leader; drop the dead port and fetch a fresh one. */
+  async reattachFollower() {
+    if (this.role !== "follower" || !this.router) return;
+    this.guard.markLeaderLost();
+    this.followerPort?.close();
+    this.followerPort = null;
+    this.proxy = null;
+    try {
+      await this.attachToLeader();
+      log("[WebSQLiteProxy] Reattached to new SQLite leader");
+    } catch (err) {
+      console.error("[WebSQLiteProxy] Reattach to new leader failed:", err);
+    }
+  }
+  enqueueTransition(fn) {
+    this.transition = this.transition.then(fn, fn);
+  }
+  notifyReconnected() {
+    const waiters = this.reconnectWaiters;
+    this.reconnectWaiters = [];
+    for (const resolve of waiters) resolve();
+  }
+  whenReconnected() {
+    if (this.proxy) return Promise.resolve();
+    return new Promise((resolve) => {
+      this.reconnectWaiters.push(resolve);
+    });
+  }
+  teardownMultiTab() {
+    this.unsubscribeLeaderServe?.();
+    this.unsubscribeLeaderServe = null;
+    this.unsubscribeRouterEvents?.();
+    this.unsubscribeRouterEvents = null;
+    this.roleHandle?.release();
+    this.roleHandle = null;
+    this.followerPort?.close();
+    this.followerPort = null;
+    if (this.role === "follower") this.proxy = null;
+    this.router = null;
+    this.role = "single-tab";
+  }
+  /**
+   * Run a worker RPC with follower protections: leader loss REJECTS in-flight
+   * calls immediately instead of hanging, and `retryable` (idempotent read)
+   * calls transparently re-issue once the connection is re-established —
+   * against this tab's own worker if it was promoted, or the new leader's.
+   */
+  rpc(retryable, op) {
+    const exec = async () => {
+      const proxy = this.proxy;
+      if (!proxy) throw new Error("Database not open");
+      this.operationStats.workerRequestCount += 1;
+      return op(proxy);
+    };
+    if (this.role !== "follower") return exec();
+    return this.guard.run(
+      exec,
+      retryable ? {
+        retry: async () => {
+          await this.whenReconnected();
+          return exec();
+        }
+      } : {}
+    );
   }
   async resetStorage(config) {
     if (this.worker) {
@@ -78,6 +465,14 @@ var WebSQLiteProxy = class {
     }
   }
   async close() {
+    if (this.role === "follower") {
+      this.teardownMultiTab();
+      this._config = null;
+      this.inTransaction = false;
+      return;
+    }
+    this.unsubscribeLeaderServe?.();
+    this.unsubscribeLeaderServe = null;
     if (this.proxy) {
       this.operationStats.workerRequestCount += 1;
       await this.proxy.close();
@@ -87,6 +482,7 @@ var WebSQLiteProxy = class {
       this.worker.terminate();
       this.worker = null;
     }
+    this.teardownMultiTab();
     this._config = null;
     this.inTransaction = false;
   }
@@ -94,30 +490,31 @@ var WebSQLiteProxy = class {
     return this.proxy !== null;
   }
   async query(sql, params) {
-    if (!this.proxy) throw new Error("Database not open");
     this.operationStats.queryCount += 1;
-    this.operationStats.workerRequestCount += 1;
-    const result = await this.proxy.query(sql, params);
+    const result = await this.rpc(true, (proxy) => proxy.query(sql, params));
     return result;
   }
   async queryOne(sql, params) {
-    if (!this.proxy) throw new Error("Database not open");
     this.operationStats.queryOneCount += 1;
-    this.operationStats.workerRequestCount += 1;
-    const result = await this.proxy.queryOne(sql, params);
+    const result = await this.rpc(true, (proxy) => proxy.queryOne(sql, params));
     return result;
   }
+  /**
+   * Execute several reads in ONE worker round-trip. N queries previously cost
+   * N postMessage round-trips; a batch costs one (exploration 0263).
+   */
+  async queryBatch(reads) {
+    if (reads.length === 0) return [];
+    this.operationStats.queryCount += reads.length;
+    return this.rpc(true, (proxy) => proxy.queryBatch(reads));
+  }
   async run(sql, params) {
-    if (!this.proxy) throw new Error("Database not open");
     this.operationStats.runCount += 1;
-    this.operationStats.workerRequestCount += 1;
-    return this.proxy.run(sql, params);
+    return this.rpc(false, (proxy) => proxy.run(sql, params));
   }
   async exec(sql) {
-    if (!this.proxy) throw new Error("Database not open");
     this.operationStats.execCount += 1;
-    this.operationStats.workerRequestCount += 1;
-    return this.proxy.exec(sql);
+    return this.rpc(false, (proxy) => proxy.exec(sql));
   }
   async transaction(_fn) {
     throw new Error("Complex transactions not supported in proxy. Use transactionBatch() instead.");
@@ -135,66 +532,55 @@ var WebSQLiteProxy = class {
    * ```
    */
   async transactionBatch(operations) {
-    if (!this.proxy) throw new Error("Database not open");
     this.operationStats.transactionBatchCount += 1;
     this.operationStats.transactionBatchOperationCount += operations.length;
-    this.operationStats.workerRequestCount += 1;
-    await this.proxy.transaction(operations);
+    await this.rpc(false, (proxy) => proxy.transaction(operations));
   }
   async applyNodeBatch(input) {
-    if (!this.proxy) throw new Error("Database not open");
     this.operationStats.transactionBatchCount += 1;
     this.operationStats.transactionBatchOperationCount += estimateNodeBatchSqlOperations(input);
-    this.operationStats.workerRequestCount += 1;
-    return this.proxy.applyNodeBatch(input);
+    return this.rpc(false, (proxy) => proxy.applyNodeBatch(input));
   }
   async beginTransaction() {
-    if (!this.proxy) throw new Error("Database not open");
     if (this.inTransaction) {
       throw new Error("Transaction already in progress");
     }
     this.operationStats.execCount += 1;
-    this.operationStats.workerRequestCount += 1;
-    await this.proxy.exec("BEGIN IMMEDIATE");
+    await this.rpc(false, (proxy) => proxy.exec("BEGIN IMMEDIATE"));
     this.inTransaction = true;
   }
   async commit() {
-    if (!this.proxy) throw new Error("Database not open");
     if (!this.inTransaction) {
       throw new Error("No transaction in progress");
     }
     this.operationStats.execCount += 1;
-    this.operationStats.workerRequestCount += 1;
-    await this.proxy.exec("COMMIT");
+    await this.rpc(false, (proxy) => proxy.exec("COMMIT"));
     this.inTransaction = false;
   }
   async rollback() {
-    if (!this.proxy) throw new Error("Database not open");
     if (!this.inTransaction) {
       return;
     }
     this.operationStats.execCount += 1;
-    this.operationStats.workerRequestCount += 1;
-    await this.proxy.exec("ROLLBACK");
+    await this.rpc(false, (proxy) => proxy.exec("ROLLBACK"));
     this.inTransaction = false;
   }
   async prepare(_sql) {
     throw new Error("Prepared statements not supported in proxy. Use query() or run() directly.");
   }
   async getSchemaVersion() {
-    if (!this.proxy) throw new Error("Database not open");
     this.operationStats.queryOneCount += 1;
-    this.operationStats.workerRequestCount += 1;
-    return this.proxy.getSchemaVersion();
+    return this.rpc(true, (proxy) => proxy.getSchemaVersion());
   }
   async setSchemaVersion(version) {
-    if (!this.proxy) throw new Error("Database not open");
     this.operationStats.runCount += 1;
-    this.operationStats.workerRequestCount += 1;
-    await this.proxy.run("INSERT INTO _schema_version (version, applied_at) VALUES (?, ?)", [
-      version,
-      Date.now()
-    ]);
+    await this.rpc(
+      false,
+      (proxy) => proxy.run("INSERT INTO _schema_version (version, applied_at) VALUES (?, ?)", [
+        version,
+        Date.now()
+      ])
+    );
   }
   async applySchema(version, sql) {
     const currentVersion = await this.getSchemaVersion();
@@ -204,24 +590,23 @@ var WebSQLiteProxy = class {
     return true;
   }
   async getDatabaseSize() {
-    if (!this.proxy) throw new Error("Database not open");
-    this.operationStats.workerRequestCount += 1;
-    return this.proxy.getDatabaseSize();
+    return this.rpc(true, (proxy) => proxy.getDatabaseSize());
   }
   async vacuum() {
+    return this.rpc(false, (proxy) => proxy.vacuum());
+  }
+  async incrementalVacuum(maxPages) {
     if (!this.proxy) throw new Error("Database not open");
     this.operationStats.workerRequestCount += 1;
-    return this.proxy.vacuum();
+    return this.proxy.incrementalVacuum(maxPages);
   }
   async checkpoint() {
     return 0;
   }
   async getStorageMode() {
-    if (!this.proxy) throw new Error("Database not open");
     try {
       log("[WebSQLiteProxy] Calling proxy.getStorageMode()...");
-      this.operationStats.workerRequestCount += 1;
-      const mode = await this.proxy.getStorageMode();
+      const mode = await this.rpc(true, (proxy) => proxy.getStorageMode());
       log("[WebSQLiteProxy] getStorageMode() returned:", mode);
       return mode;
     } catch (err) {
@@ -229,6 +614,10 @@ var WebSQLiteProxy = class {
       throw err;
     }
   }
+  /** This tab's multi-tab role: 'leader', 'follower', or 'single-tab'. */
+  getTabRole() {
+    return this.role;
+  }
   /**
    * Create a MessagePort connected directly to the SQLite worker.
    *
@@ -237,12 +626,26 @@ var WebSQLiteProxy = class {
    * (e.g. the data worker) so its storage calls skip the main thread.
    */
   async createMessagePort() {
-    if (!this.proxy) throw new Error("Database not open");
     const channel = new MessageChannel();
-    this.operationStats.workerRequestCount += 1;
-    await this.proxy.connectPort(Comlink.transfer(channel.port1, [channel.port1]));
+    await this.rpc(
+      false,
+      (proxy) => proxy.connectPort(Comlink.transfer(channel.port1, [channel.port1]))
+    );
     return channel.port2;
   }
+  /**
+   * Worker-side scheduler stats: per-lane p50/p95 queue+exec latency and
+   * coalesce hits (exploration 0263). Complements getOperationStats(), which
+   * counts main-thread RPCs — together they give "how many round-trips" and
+   * "how long each op spent in the worker".
+   */
+  async getSchedulerOpStats() {
+    return this.rpc(true, (proxy) => proxy.getSchedulerOpStats());
+  }
+  /** Zero the worker-side scheduler stats for a focused measurement. */
+  async resetSchedulerOpStats() {
+    return this.rpc(false, (proxy) => proxy.resetSchedulerOpStats());
+  }
   getOperationStats() {
     return cloneOperationStats(this.operationStats);
   }