fix: recover from force-closed IndexedDB connections

[sea-snake]

Closes #120.

Root cause

The error reported in #120 — InvalidStateError: Failed to execute 'transaction' on 'IDBDatabase': The database connection is closing — means the connection was already closed by the time a storage operation ran. Nothing in this library (or in idb) ever calls db.close(), so the closure comes from the browser: Chrome is known to force-close IndexedDB connections out from under pages (see e.g. Dexie #613, localForage #581), and constant full-page reload churn on Vite localhost dev servers makes this far more likely than on a deployed asset canister. IdbKeyVal cached one connection for its whole lifetime with no recovery path, so a single force-close turned every subsequent storage call into this error.

Changes

• IdbKeyVal now survives force-closed connections (src/client/db.ts): the connection promise is dropped via openDB's terminated hook when the browser reports an abnormal close, and — since Chrome does not always fire that event — an InvalidStateError thrown by an operation also drops the dead connection, reopens, and retries the operation once. A failed open is never cached.
• IdbStorage._db memoizes the in-flight creation (src/client/storage.ts): concurrent first accesses previously each started their own IdbKeyVal.create(), opening duplicate connections that leaked (the fix suggested in Race condition in IdbStorage causes 'IDBDatabase connection is closing' error on localhost dev servers #120). This became internally reachable with the 8.0.0 redirect flow, which touches storage concurrently with session hydration.
• signIn()/signOut() wait for session hydration (src/client/auth-client.ts): both now await the memoized #init() before touching storage, so their writes/deletes cannot interleave with the constructor's restore reads. In signIn() the await is placed after openChannel() — which must stay the first await so a popup opens in the same tick as the user's click — and after the eager session-key acquisition start, preserving the same-tick transport.memoize batching hold from fix(auth-client): keep the redirect flow batched and its derivation origin stable #124.

Tests

• tests/client/db-recovery.test.ts: closes the underlying connection out from under IdbKeyVal (via a pass-through openDB wrapper) and verifies reads/writes transparently reopen and succeed. This reproduces the retry path; the terminated event path is not reproducible under fake-indexeddb, which never force-closes.
• tests/client/storage.test.ts: verifies concurrent first accesses share a single IdbKeyVal.create() call, and that a failed open is not cached.

pnpm exec vitest run (92 tests), pnpm codestyle:check, and pnpm build all pass.

🤖 Generated with Claude Code

[marc0olo]

Independently verified and reviewed this — LGTM. ✅

Verification

Deterministic (unit): ran the PR's tests/client/db-recovery.test.ts against origin/main's src/ (no fix) → throws at db.put (the connection-closing path), 2 failed. Against this branch → 4 passed.

End-to-end (real browser): wired the fix into rust/vetkeys/basic_bls_signing in dfinity/examples, removed that example's localhost LocalStorage + Ed25519 workaround so it uses the default IdbStorage, then force-closed the live IDB connection the way Chrome does during Vite reload churn (db.close(), mirroring the test's opened.dbs[0].close()) and issued a write:

@icp-sdk/auth build	Result
8.0.3 (released latest, no fix)	❌ InvalidStateError: Failed to execute 'transaction' on 'IDBDatabase': The database connection is closing.
this branch (8.0.2 + fix)	✅ write + read-back succeed — connection transparently reopened

The two builds are source-identical apart from the 3 fix commits (the 8.0.2→8.0.3 delta touches only changelog/version/lockfile), so the behavior change is attributable to the fix alone. The real-Chrome error string matches #120 exactly.

Implementation review

Addresses both root causes, not just the promise-dedup suggested in #120:

• db.ts — terminated hook + retry-once on InvalidStateError recovers from force-closed connections (the actual cause of the reported error).
• storage.ts — _db now memoizes the in-flight promise, so concurrent first accesses share one IdbKeyVal.create() instead of leaking duplicate connections.
• auth-client.ts — signIn/signOut await #init() before touching storage, closing the hydration-vs-write race while keeping openChannel() the first await (popup-blocker constraint).

The if (this._dbPromise === promise) guard on every reset path makes concurrent recovery correct — traced it: two concurrent ops on a dead connection reopen exactly once and share the fresh one; a terminated event mid-op is handled. No public API breakage.

Minor, non-blocking: the terminated-event path isn't unit-tested (not reproducible under fake-indexeddb); recovery is a single retry, so a burst of force-closes during the retry could still surface. Both are reasonable tradeoffs.

Once released, this lets us drop the localhost LocalStorage/Ed25519 workaround from the 11 vetkeys examples currently carrying it — tracked in dfinity/examples#1467.

[Copilot]

Pull request overview

This PR hardens the client’s IndexedDB-backed storage against browser-forced connection closures and concurrent initialization races that can surface as InvalidStateError: ... database connection is closing, especially during rapid localhost reload + interaction cycles.

Changes:

• Add IndexedDB connection recovery in IdbKeyVal by dropping/reopening dead connections and retrying once on InvalidStateError.
• Memoize the in-flight IdbKeyVal.create() promise in IdbStorage to dedupe concurrent first access and avoid leaked duplicate connections.
• Ensure signIn()/signOut() await session hydration (#init()) before performing storage writes/deletes to prevent interleaving with restore reads.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/client/db.ts	Adds connection promise caching, terminated-hook handling, and an InvalidStateError retry path for IndexedDB operations.
src/client/storage.ts	Memoizes the in-flight DB creation promise to dedupe concurrent initialization and avoid caching failed opens.
src/client/auth-client.ts	Awaits session hydration in signIn()/signOut() to prevent storage read/write races.
tests/client/db-recovery.test.ts	Adds coverage for reopening/retrying operations after an underlying connection is closed.
tests/client/storage.test.ts	Adds coverage for concurrent first access deduplication and “failed open not cached” behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.