Skip to content

Recover local database connections and propagate reflection failures - #225

Open
vrtmrz wants to merge 3 commits into
mainfrom
fix/local-database-connection-recovery
Open

vrtmrz wants to merge 3 commits into
mainfrom
fix/local-database-connection-recovery

Conversation

@vrtmrz

@vrtmrz vrtmrz commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

This fix restores an unavailable owned local database connection and propagates incomplete file-reflection failures to the host which can retain and recover the work.

Related to vrtmrz/obsidian-livesync#1360 and vrtmrz/obsidian-livesync#1224. The companion consumer is LiveSync #1364.

Behaviour

  • Probe only the existing initialised Pouch with canReadCurrentDatabaseInfo(). Serialise open, close, reset, and same-database recovery with the existing withLock; verify the current owner and physical selection before and after draining work.
  • Retire the old Pouch and managers before reopening the same physical database. Observe Pouch's closed event and await its close() promise. The key-value store owns its separate logical-database, reset, and shutdown lifecycle, so replacing the Pouch connection preserves pending records and retry allowances.
  • Give each reflection an explicit target and operation context. Strict reads propagate their original failure to the reflection owner; legacy Boolean/array entry points retain their compatibility conversion at the public boundary. Existing protection and fallback paths can still complete without creating failed work.
  • Record only resources established by the failed operation (local-database, remote, or no established recovery resource), with the original cause. Finite Chunk producers settle and perform the final local recheck before a read fails. Unknown failures remain reviewable without gaining automatic retry eligibility.
  • Keep asynchronous resource cleanup in the existing scope mechanism. Preserve rejection through reflection dispatch and scanner notification so a failed snapshot save cannot masquerade as successful retention.
  • Share immutable reflection outcomes and their predicates through the existing contract, and adapt them once at the scanner boundary. Use common rejection-preserving dispatchers for first-defined results and Boolean notifications. Separate Chunk request stages, database entry preparation, revision selection, and history comparison within their existing owners.

The host owns pause/drain, pending-target persistence, finite retry admission, and resumption policy. Recovery uses operation boundaries and the current Pouch probe; it does not replace public Pouch methods or infer connection loss from an error name, message, or nested cause.

Validation

  • Source type checks, package build, and packed-package consumer checks passed.
  • Commonlib unit suite: 210 files / 4,154 tests passed. After the final Chunk delivery cleanup, the affected 5 files / 94 tests passed again.
  • Focused coverage verifies unchanged callback rejection identity, handler priority and removal, per-invocation registration snapshots, scanner outcome conversion, and snapshot-save failures. A changed-test type comparison against the original baseline introduced no additional primary diagnostics; existing test type errors remain.
  • The PouchDB idb regression closes a retained native connection under fake IndexedDB and verifies same-database reopening with preserved content and revision.
  • The exact packed candidate passed downstream LiveSync source/application checks, the full host unit suite, CLI local-database E2E (11 tests), WebApp/WebPeer builds, and Linux Obsidian tests for receiver connection loss, offline start-up, an online transport interruption, and delayed Chunk arrival. The receiver test verifies retention before reopening, exact content/revision/provenance after recovery, and subsequent local writes.

Tested package: @vrtmrz/livesync-commonlib@0.5.0, built from this PR's 696e31bac449e5531242855bffa45080090df16e source; tarball SHA-256 4b2e0122514c925ba54bf2a85c3277e31b4d74fc30cc5f58029c3de31879e542. All 746 packed files were compared byte-for-byte with the installed consumer package, preserving locked transitive dependencies. The registry package with the same version does not contain these changes.

Boundaries and adoption

Controlled failures establish the tested recovery path. They do not establish the cause or frequency of natural iOS/WebKit connection termination, and automatic recovery on a physical iPhone remains unverified. A successful info() confirms only that operation; adapters can cache metadata or reopen internally. Linux WebKit diagnostics could not start because required shared libraries were unavailable.

This PR does not publish a package. LiveSync #1364 remains draft until an exact published package containing these changes is selected in its manifest and lockfile and verified as a consumer.

@vrtmrz vrtmrz changed the title Recover local database connections and report content-read failures Recover local database connections and propagate reflection failures Nov 16, 2026
Use immutable reflection results and shared rejection-preserving dispatchers. Adapt scanner outcomes at the scanner boundary, and separate chunk request stages and database entry preparation from their orchestration.

Preserve request ownership, retry admission, comparison locking, and revision selection.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant