@fairfox/polly 0.60.0 → 0.62.0

package/dist/src/shared/lib/idb-helpers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tiny internal helpers around the raw IndexedDB API.
+ *
+ * Wraps the patterns that `storage-adapter.ts` and `blob-cache.ts` both
+ * re-implement: timed open with retry-on-failure caching, request→promise
+ * wrapping, transaction-to-completion, and cursor iteration. Not exported
+ * from the public package — internal to `src/shared/lib`.
+ */
+/** Polly#107 post-v0.60: hard timeout on `indexedDB.open()`. Healthy
+ *  opens land in microseconds; the v0.60.0 fingerprint surfaced a zombie
+ *  cross-tab connection that left an open request firing no events at all.
+ *  5s is two orders of magnitude beyond the normal upper bound and short
+ *  enough that the operator gets a named failure instead of a hung page
+ *  when the storage layer wedges. */
+export declare const IDB_OPEN_TIMEOUT_MS = 5000;
+export interface OpenIDBOptions {
+    name: string;
+    version: number;
+    /** Invoked inside `onupgradeneeded`. Create object stores here. */
+    upgrade: (db: IDBDatabase, event: IDBVersionChangeEvent) => void;
+}
+/** Open an IndexedDB database with the Polly#107 timeout guard. */
+export declare function openIDB(options: OpenIDBOptions): Promise<IDBDatabase>;
+/** One-shot open caching with retry-on-failure. Caller owns a `{ promise }`
+ *  cell; first call opens, subsequent calls return the cached promise, and
+ *  a rejected open clears the cache so the next call can retry instead of
+ *  being poisoned by one transient failure. */
+export declare function cachedOpen(ref: {
+    promise: Promise<IDBDatabase> | null;
+}, options: OpenIDBOptions): Promise<IDBDatabase>;
+/** Promise-wrap a single `IDBRequest` (`get`, `put`, `count`, `delete`…). */
+export declare function runRequest<T>(request: IDBRequest<T>): Promise<T>;
+/** Run a transaction to completion. Resolves on `tx.oncomplete` (write
+ *  durability), not on individual request success. Throws inside `fn`
+ *  abort the transaction and reject. */
+export declare function runTx(db: IDBDatabase, storeName: string, mode: IDBTransactionMode, fn: (store: IDBObjectStore) => void): Promise<void>;
+/** Walk every record in a store. */
+export declare function iterateCursor<V>(db: IDBDatabase, storeName: string, visit: (key: IDBValidKey, value: V) => void): Promise<void>;

package/dist/src/shared/lib/mesh-client.d.ts

@@ -23,7 +23,7 @@ import { Repo, type StorageAdapterInterface } from "@automerge/automerge-repo/sl
 import type { KeyringStorage } from "./keyring-storage";
 import { type MeshKeyring, MeshNetworkAdapter } from "./mesh-network-adapter";
 import { MeshSignalingClient, type MeshSignalingClientOptions } from "./mesh-signaling-client";
-import { type MeshStateLazyWrapperRecord, type MeshStateLoadedRejectionBreadcrumb } from "./mesh-state";
+import { type MeshStateLazyWrapperRecord, type MeshStateLoadedRejectionBreadcrumb, type MeshStateStorageOpenError } from "./mesh-state";
 import { MeshWebRTCAdapter, type MeshWebRTCAdapterOptions } from "./mesh-webrtc-adapter";
 /** Options for {@link createMeshClient}. */
 export interface CreateMeshClientOptions {
@@ -164,6 +164,30 @@ export interface CreateMeshClientOptions {
  * production call site is inside {@link createMeshClient}.
  */
 export declare function resolveIceServers(rtc: CreateMeshClientOptions["rtc"]): Promise<RTCIceServer[] | undefined>;
+/** Polly#107 post-v0.60 instrumentation. Walks the lazy-wrapper log
+ * and groups records by `docId`; emits one entry per `docId` that
+ * appears in more than one record. Surfaces the "17 wrappers / 16
+ * `repo.handles`" off-by-one shape that the v0.60.0 single-tab
+ * fingerprint flagged — typically two distinct `$mesh*` consumer
+ * call sites whose logical keys hash to the same Automerge
+ * `DocumentId`, or the same logical key invoked from two consumers
+ * during pre-warm before either factory's `repo.import` committed
+ * the handle. The snapshot can paste this verbatim; an empty array
+ * means the wrapper-to-handle accounting is one-to-one. */
+export interface MeshStateLazyWrapperDocIdDuplicate {
+    /** The `DocumentId` that more than one factory invocation
+     * resolved to. */
+    docId: string;
+    /** Distinct logical keys that derived to this same `DocumentId`.
+     * Length 1 means the same key was registered twice; length > 1
+     * means two different keys hashed to the same id (a SHA-512-prefix
+     * collision in {@link deriveDocumentId}, vanishingly unlikely but
+     * detected for completeness). */
+    keys: string[];
+    /** Total number of records in the lazy-wrapper log that resolved
+     * to this `DocumentId`. Typically 2 for a same-key double-call. */
+    recordCount: number;
+}
 /** Per-peer per-handle enrichment polly#107 adds on top of the
  * {@link MeshWebRTCAdapter} snapshot. `state` and `announcedToPeer`
  * come from the Repo side (which the adapter cannot see); the wire
@@ -255,6 +279,17 @@ export interface MeshStateModuleDiagnostics {
      * silently. `undefined` means no rejection has escaped any
      * wrapper on THIS module instance since module load. */
     lastLoadedRejection: MeshStateLoadedRejectionBreadcrumb | undefined;
+    /** Polly#107 post-v0.60 instrumentation. Populated when a storage
+     * read inside `buildHandleFactory` exceeds the internal 5s
+     * timeout — i.e. `cached.whenReady(...)` or
+     * `repo.storageSubsystem.loadDoc(...)` hung. Names the operation,
+     * the document id under attempt, the elapsed time, and a
+     * pre-formatted message ready to paste into a ticket. The v0.60.0
+     * fingerprint diagnosed "factories hung mid-await, not throwing"
+     * indirectly; this field surfaces the same shape within seconds
+     * and in one read. `undefined` means no storage timeout has
+     * occurred since module load. */
+    storageOpenError: MeshStateStorageOpenError | undefined;
     /** Polly#107 post-v0.59 instrumentation. Per-factory-invocation
      * structured log — one record per `$mesh*` wrapper's lazy handle
      * factory call, ring-buffered at 64 entries. Each row names the
@@ -269,6 +304,15 @@ export interface MeshStateModuleDiagnostics {
      * `exitReason: "seeded-and-imported"` and
      * `handleRegistered: false`. */
     lazyWrappers: MeshStateLazyWrapperRecord[];
+    /** Polly#107 post-v0.60 instrumentation. One entry per
+     * `DocumentId` that appears in more than one
+     * {@link lazyWrappers} record — the shape behind the v0.60.0
+     * single-tab fingerprint's "17 wrappers / 16 `repo.handles`"
+     * off-by-one. Empty when wrapper-to-handle accounting is
+     * one-to-one, populated when two factory invocations resolved to
+     * the same `DocumentId` (most commonly the same logical key
+     * registered from two consumer call sites during pre-warm). */
+    lazyWrapperDuplicateDocIds: MeshStateLazyWrapperDocIdDuplicate[];
 }
 /** The mesh client's enriched per-peer state snapshot. Mirrors the
  * underlying {@link MeshWebRTCAdapter.getPeerStateSnapshot} shape but

package/dist/src/shared/lib/mesh-state.d.ts

@@ -140,6 +140,43 @@ export interface MeshStateLoadedRejectionBreadcrumb {
 /** Returns the most recent rejection escaping a `$meshState` factory
  * invocation since module load. See {@link lastLoadedRejection}. */
 export declare function getLastLoadedRejection(): MeshStateLoadedRejectionBreadcrumb | undefined;
+/** Polly#107 post-v0.60 instrumentation. Captured when a storage
+ * read from inside a `$meshState`-family factory exceeds
+ * {@link STORAGE_OP_TIMEOUT_MS}. Names which op timed out
+ * (`whenReady`, `loadDoc`), the document id under attempt, the
+ * elapsed time, and a single human-readable message that the
+ * snapshot can paste verbatim into a ticket. The breadcrumb also
+ * flows into {@link lastLoadedRejection} so the existing
+ * "did anything reject" channel surfaces it alongside.
+ *
+ * The v0.60.0 fingerprint diagnosed "factories hung mid-await,
+ * not throwing" indirectly — empty {@link lazyWrappers} beside
+ * non-zero {@link lazyInvocations} / {@link lazyReachedRepo}. With
+ * this field a future polly#107-shaped session reads
+ * `storageOpenError.message: "Polly $meshState: storage operation
+ * 'loadDoc' on document '<id>' timed out after 5000ms"` and jumps
+ * directly to "the storage layer is hung; clear site data,"
+ * skipping every other rung in the ladder. */
+export interface MeshStateStorageOpenError {
+    /** Which await in `buildHandleFactory` exceeded the timeout. */
+    operation: "whenReady" | "loadDoc";
+    /** Stringified Automerge `DocumentId` that was under attempt. */
+    documentId: string;
+    /** Time the operation was given before the timeout fired (ms). */
+    timeoutMs: number;
+    /** Wall-clock elapsed when the timeout fired (ms). Always
+     * `>= timeoutMs`; a small overshoot is normal. */
+    elapsedMs: number;
+    /** Pre-formatted human-readable message. Identical to what
+     * flows into {@link lastLoadedRejection}.message. */
+    message: string;
+    /** `Date.now()` at the moment the timeout fired. */
+    at: number;
+}
+/** Returns the most recent storage-operation timeout escaping a
+ * `$meshState` factory invocation since module load. See
+ * {@link lastStorageOpenError}. */
+export declare function getStorageOpenError(): MeshStateStorageOpenError | undefined;
 /** Polly#107 post-v0.59 instrumentation. Categorises the exit path
  * a `$mesh*` lazy factory invocation took. The v0.59.0 fingerprint
  * showed `lazyInvocations === lazyReachedRepo === 17` and no

package/dist/src/shared/lib/message-bus.js

@@ -69,6 +69,90 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
+// src/shared/lib/idb-helpers.ts
+function openIDB(options) {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const request = indexedDB.open(options.name, options.version);
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled)
+        return;
+      settled = true;
+      const elapsedMs = Date.now() - start;
+      reject(new Error(`Polly IndexedDB open of '${options.name}' timed out after ${elapsedMs}ms (cross-tab lock or zombie connection?)`));
+    }, IDB_OPEN_TIMEOUT_MS);
+    request.onerror = () => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      reject(request.error);
+    };
+    request.onsuccess = () => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(request.result);
+    };
+    request.onupgradeneeded = (event) => {
+      const db = event.target.result;
+      options.upgrade(db, event);
+    };
+  });
+}
+function cachedOpen(ref, options) {
+  if (ref.promise)
+    return ref.promise;
+  const pending = openIDB(options);
+  pending.catch(() => {
+    if (ref.promise === pending)
+      ref.promise = null;
+  });
+  ref.promise = pending;
+  return pending;
+}
+function runRequest(request) {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+function runTx(db, storeName, mode, fn) {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(storeName, mode);
+    const store = tx.objectStore(storeName);
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+    tx.onabort = () => reject(tx.error);
+    try {
+      fn(store);
+    } catch (err) {
+      try {
+        tx.abort();
+      } catch {}
+      reject(err);
+    }
+  });
+}
+function iterateCursor(db, storeName, visit) {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(storeName, "readonly");
+    const store = tx.objectStore(storeName);
+    const request = store.openCursor();
+    request.onsuccess = () => {
+      const cursor = request.result;
+      if (!cursor)
+        return resolve();
+      visit(cursor.key, cursor.value);
+      cursor.continue();
+    };
+    request.onerror = () => reject(request.error);
+  });
+}
+var IDB_OPEN_TIMEOUT_MS = 5000;
+
 // src/shared/lib/storage-adapter.ts
 var exports_storage_adapter = {};
 __export(exports_storage_adapter, {
@@ -81,42 +165,32 @@ __export(exports_storage_adapter, {
 class IndexedDBAdapter {
   dbName;
   storeName = "state";
-  dbPromise = null;
+  dbRef = { promise: null };
   constructor(dbName = "polly-state") {
     this.dbName = dbName;
   }
   getDB() {
-    if (this.dbPromise)
-      return this.dbPromise;
-    this.dbPromise = new Promise((resolve, reject) => {
-      const request = indexedDB.open(this.dbName, 1);
-      request.onerror = () => reject(request.error);
-      request.onsuccess = () => resolve(request.result);
-      request.onupgradeneeded = (event) => {
-        const db = event.target.result;
+    return cachedOpen(this.dbRef, {
+      name: this.dbName,
+      version: 1,
+      upgrade: (db) => {
         if (!db.objectStoreNames.contains(this.storeName)) {
           db.createObjectStore(this.storeName);
         }
-      };
+      }
     });
-    return this.dbPromise;
   }
   async get(keys) {
     try {
       const db = await this.getDB();
+      const tx = db.transaction(this.storeName, "readonly");
+      const store = tx.objectStore(this.storeName);
+      const pairs = await Promise.all(keys.map(async (key) => [key, await runRequest(store.get(key))]));
       const result = {};
-      await Promise.all(keys.map((key) => new Promise((resolve, reject) => {
-        const transaction = db.transaction([this.storeName], "readonly");
-        const store = transaction.objectStore(this.storeName);
-        const request = store.get(key);
-        request.onerror = () => reject(request.error);
-        request.onsuccess = () => {
-          if (request.result !== undefined) {
-            result[key] = request.result;
-          }
-          resolve();
-        };
-      })));
+      for (const [key, value] of pairs) {
+        if (value !== undefined)
+          result[key] = value;
+      }
       return result;
     } catch (error) {
       console.warn("[Polly] IndexedDB get failed:", error);
@@ -126,13 +200,11 @@ class IndexedDBAdapter {
   async set(items) {
     try {
       const db = await this.getDB();
-      await Promise.all(Object.entries(items).map(([key, value]) => new Promise((resolve, reject) => {
-        const transaction = db.transaction([this.storeName], "readwrite");
-        const store = transaction.objectStore(this.storeName);
-        const request = store.put(value, key);
-        request.onerror = () => reject(request.error);
-        request.onsuccess = () => resolve();
-      })));
+      await runTx(db, this.storeName, "readwrite", (store) => {
+        for (const [key, value] of Object.entries(items)) {
+          store.put(value, key);
+        }
+      });
     } catch (error) {
       console.warn("[Polly] IndexedDB set failed:", error);
     }
@@ -140,13 +212,10 @@ class IndexedDBAdapter {
   async remove(keys) {
     try {
       const db = await this.getDB();
-      await Promise.all(keys.map((key) => new Promise((resolve, reject) => {
-        const transaction = db.transaction([this.storeName], "readwrite");
-        const store = transaction.objectStore(this.storeName);
-        const request = store.delete(key);
-        request.onerror = () => reject(request.error);
-        request.onsuccess = () => resolve();
-      })));
+      await runTx(db, this.storeName, "readwrite", (store) => {
+        for (const key of keys)
+          store.delete(key);
+      });
     } catch (error) {
       console.warn("[Polly] IndexedDB remove failed:", error);
     }
@@ -219,6 +288,7 @@ function createStorageAdapter() {
   }
   return new MemoryStorageAdapter;
 }
+var init_storage_adapter = () => {};
 
 // src/shared/lib/sync-adapter.ts
 var exports_sync_adapter = {};
@@ -722,6 +792,7 @@ class MessageLoggerAdapter {
 }
 
 // src/shared/lib/adapter-factory.ts
+init_storage_adapter();
 function createStateAdapters(options = {}) {
   if (options.storage && options.sync) {
     return {
@@ -742,7 +813,7 @@ function createStateAdapters(options = {}) {
   return { storage, sync };
 }
 function createChromeAdapters() {
-  const { ChromeStorageAdapter: ChromeStorageAdapter3 } = __toCommonJS(exports_storage_adapter);
+  const { ChromeStorageAdapter: ChromeStorageAdapter3 } = (init_storage_adapter(), __toCommonJS(exports_storage_adapter));
   const { ChromeRuntimeSyncAdapter: ChromeRuntimeSyncAdapter2 } = __toCommonJS(exports_sync_adapter);
   return {
     storage: new ChromeStorageAdapter3,
@@ -750,14 +821,14 @@ function createChromeAdapters() {
   };
 }
 function createWebAdapters(options = {}) {
-  const { IndexedDBAdapter: IndexedDBAdapter2 } = __toCommonJS(exports_storage_adapter);
+  const { IndexedDBAdapter: IndexedDBAdapter2 } = (init_storage_adapter(), __toCommonJS(exports_storage_adapter));
   const { BroadcastChannelSyncAdapter: BroadcastChannelSyncAdapter2, NoOpSyncAdapter: NoOpSyncAdapter2 } = __toCommonJS(exports_sync_adapter);
   const storage = new IndexedDBAdapter2(options.dbName);
   const sync = options.singleTab ? new NoOpSyncAdapter2 : new BroadcastChannelSyncAdapter2(options.channelName);
   return { storage, sync };
 }
 function createNodeAdapters() {
-  const { MemoryStorageAdapter: MemoryStorageAdapter2 } = __toCommonJS(exports_storage_adapter);
+  const { MemoryStorageAdapter: MemoryStorageAdapter2 } = (init_storage_adapter(), __toCommonJS(exports_storage_adapter));
   const { NoOpSyncAdapter: NoOpSyncAdapter2 } = __toCommonJS(exports_sync_adapter);
   return {
     storage: new MemoryStorageAdapter2,
@@ -765,7 +836,7 @@ function createNodeAdapters() {
   };
 }
 function createMockAdapters() {
-  const { MemoryStorageAdapter: MemoryStorageAdapter2 } = __toCommonJS(exports_storage_adapter);
+  const { MemoryStorageAdapter: MemoryStorageAdapter2 } = (init_storage_adapter(), __toCommonJS(exports_storage_adapter));
   const { NoOpSyncAdapter: NoOpSyncAdapter2 } = __toCommonJS(exports_sync_adapter);
   return {
     storage: new MemoryStorageAdapter2,
@@ -774,6 +845,7 @@ function createMockAdapters() {
 }
 
 // src/shared/adapters/index.ts
+init_storage_adapter();
 function createChromeAdapters2(context, options) {
   const runtime2 = new ChromeRuntimeAdapter;
   return {
@@ -1563,4 +1635,4 @@ export {
   MessageBus
 };
 
-//# debugId=93688ED3AE3A9AC864756E2164756E21
+//# debugId=3223EA30A6C6201E64756E2164756E21