Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
fix(standalone): end the boot when the OPFS pool stays locked
Elian Doran916ab908a65a
diff --git a/.claude/skills/developing-standalone/SKILL.md b/.claude/skills/developing-standalone/SKILL.mdindex 03a90b0136..8890db7641 100644--- a/.claude/skills/developing-standalone/SKILL.md+++ b/.claude/skills/developing-standalone/SKILL.md@@ -33,7 +33,7 @@ apps/standalone/1. **`main.ts`** requires a service worker (secure context: HTTPS or localhost — otherwise it throws a message explaining that), registers `./sw.js` with scope `/`, reloads once if the SW installed but doesn't control the page yet, and exposes `window.standaloneApi` (`restore.importBackup`, `backup.downloadDatabase`) — the client's escape hatch for things carrying a whole file, the twin of desktop's `window.electronApi`.2. **Leader election** (`leader_election.ts`): the OPFS SAHPool VFS takes *exclusive* sync-access handles, and `createSyncAccessHandle` exists only in a dedicated worker, so exactly one tab per origin can own the database. A **Web Lock** (`trilium-standalone-db`, held for the tab's lifetime) picks it; only the winner calls `startLocalServerWorker()`; when it closes the browser releases the lock and a waiting tab is promoted. Where Web Locks are missing (some WebViews) the tab assumes it is alone.3. **Service worker** (`sw.ts`): cache-first for hashed assets, network-first otherwise; requests under `LOCAL_API_PREFIXES` (`/bootstrap`, `/api/`, `/sync/`, `/search/`, from `local-bridge.ts`) are forwarded with `LOCAL_FETCH` to the **leader** client, found via a cached id, `WHO_IS_LEADER` / `LEADER_REPLY` probing, and one retry on `NOT_LEADER` (leadership can flip while a request is in flight). Backup downloads stream over a `MessageChannel` from the leader. It must **let `/_trilium_native_http/` fall through** (Android native proxy) and has a defensive guard for `capacitor://`.-4. **The worker** (`local-server-worker.ts`): waits for the previous worker's OPFS access handles to be released (`waitForSahPoolRelease` — a reload races the browser's asynchronous release, and `installOpfsSAHPoolVfs()` reacts to an acquisition failure by *deleting the pool directory*, so the pool must be acquirable before it runs), then installs the SAHPool VFS **once** — failure is a fatal startup error painted by `error-overlay.ts`, never an in-memory fallback (`TRILIUM_INTEGRATION_TEST=memory` builds seed a fixture into the pool, so writes survive reloads within a test). It then calls `initializeCore({...})` with the `lightweight/*` providers, registers `createConfiguredRouter()` (`BrowserRouter` mimicking Express, path params + query strings), then answers `LOCAL_REQUEST` messages. `DbLock` (`lightweight/db_lock.ts`) serialises `createAsyncRoute` handlers (imports) that hold a transaction across `await`s against the single connection — synchronous routes keep a zero-overhead path. `WS_MESSAGE` replaces the WebSocket in both directions. Anything that escapes after startup is reported as `WORKER_ERROR` for one background task; before startup it means the app never came up and `error-overlay.ts` paints it (the async worker init is invisible to `main.ts`'s try/catch).+4. **The worker** (`local-server-worker.ts`): waits for the previous worker's OPFS access handles to be released (`waitForSahPoolRelease` — a reload races the browser's asynchronous release, and `installOpfsSAHPoolVfs()` reacts to an acquisition failure by *deleting the pool directory*, so the pool must be acquirable before it runs — a wait that reaches its deadline ends the boot instead of installing anyway), then installs the SAHPool VFS **once** — failure is a fatal startup error painted by `error-overlay.ts`, never an in-memory fallback (`TRILIUM_INTEGRATION_TEST=memory` builds seed a fixture into the pool, so writes survive reloads within a test). It then calls `initializeCore({...})` with the `lightweight/*` providers, registers `createConfiguredRouter()` (`BrowserRouter` mimicking Express, path params + query strings), then answers `LOCAL_REQUEST` messages. `DbLock` (`lightweight/db_lock.ts`) serialises `createAsyncRoute` handlers (imports) that hold a transaction across `await`s against the single connection — synchronous routes keep a zero-overhead path. `WS_MESSAGE` replaces the WebSocket in both directions. Anything that escapes after startup is reported as `WORKER_ERROR` for one background task; before startup it means the app never came up and `error-overlay.ts` paints it (the async worker init is invisible to `main.ts`'s try/catch).## The provider set (`src/lightweight/`)diff --git a/apps/standalone/src/lightweight/sql_provider.spec.ts b/apps/standalone/src/lightweight/sql_provider.spec.tsindex ceeaf778ee..1efaab0858 100644--- a/apps/standalone/src/lightweight/sql_provider.spec.ts+++ b/apps/standalone/src/lightweight/sql_provider.spec.ts@@ -541,8 +541,10 @@ describe("BrowserSqlProvider error and defensive paths", () => {});describe("waitForSahPoolRelease", () => {+ type FakeEntry = { kind: string; createSyncAccessHandle?: () => Promise<{ close(): void }> };+/** A fake OPFS root holding `.opfs-sahpool/.opaque` with the given entries. */- function fakeRootWith(entries: [string, { kind: string; createSyncAccessHandle?: () => Promise<{ close(): void }> }][]) {+ function fakeRootWith(entries: [string, FakeEntry][]) {const opaque = {async *entries() {yield* entries;@@ -589,7 +591,7 @@ describe("waitForSahPoolRelease", () => {expect(closed).toEqual(["pool-1", "pool-2"]);});- it("waits for a held file's release, and reports one still held at the deadline", async () => {+ it("waits for a held file, and reports one still held at the deadline", async () => {let denials = 3;const eventuallyReleased = {kind: "file",@@ -619,4 +621,19 @@ describe("waitForSahPoolRelease", () => {deadlineMs: 25})).resolves.toBe(false);});++ it("treats a probe failure other than a held lock as nothing to wait for", async () => {+ const broken = {+ kind: "file",+ createSyncAccessHandle: async () => {+ throw new DOMException("gone", "NotFoundError");+ }+ };++ await expect(waitForSahPoolRelease({+ getRoot: fakeRootWith([["pool-1", broken]]),+ pollMs: 1,+ deadlineMs: 25+ })).resolves.toBe(true);+ });});diff --git a/apps/standalone/src/lightweight/sql_provider.ts b/apps/standalone/src/lightweight/sql_provider.tsindex a7cf6948f9..6994356501 100644--- a/apps/standalone/src/lightweight/sql_provider.ts+++ b/apps/standalone/src/lightweight/sql_provider.ts@@ -703,9 +703,11 @@ export interface SahPoolReleaseWait {* Resolves `true` once every pool file accepts a (immediately closed) probe access handle, and* without waiting when the pool does not exist yet or the OPFS API is missing — in both cases* `installSahPool()` is the one with the authoritative answer. Resolves `false` when a file is- * still held after `deadlineMs`.+ * still locked after `deadlineMs`.*/-export async function waitForSahPoolRelease({ deadlineMs = 15_000, pollMs = 150, getRoot }: SahPoolReleaseWait = {}): Promise<boolean> {+export async function waitForSahPoolRelease(+ { deadlineMs = 15_000, pollMs = 150, getRoot }: SahPoolReleaseWait = {}+): Promise<boolean> {if (!getRoot) {if (!navigator?.storage?.getDirectory) {return true;@@ -734,7 +736,10 @@ export async function waitForSahPoolRelease({ deadlineMs = 15_000, pollMs = 150,return true;}if (!announced) {- console.log(`[BrowserSqlProvider] Pool file "${heldFile}" is still held, usually by the worker of the page this one replaced — waiting for its release...`);+ console.log(+ `[BrowserSqlProvider] Pool file "${heldFile}" is still held, usually by the `+ + "worker of the page this one replaced — waiting for its release..."+ );announced = true;}if (Date.now() >= deadline) {@@ -753,8 +758,14 @@ async function findHeldPoolFile(dir: FileSystemDirectoryHandle): Promise<stringtry {const probe = await (handle as FileSystemFileHandle).createSyncAccessHandle();probe.close();- } catch {- return name;+ } catch (e) {+ // `createSyncAccessHandle()` throws NoModificationAllowedError for exactly the case+ // worth waiting out: a lock another context holds. Every other failure is a broken+ // environment that waiting cannot fix, and reporting it as held would keep the boot+ // from starting at all.+ if ((e as DOMException)?.name === "NoModificationAllowedError") {+ return name;+ }}}return null;diff --git a/apps/standalone/src/local-server-worker.ts b/apps/standalone/src/local-server-worker.tsindex 10bd15e8c1..3d3de6a57b 100644--- a/apps/standalone/src/local-server-worker.ts+++ b/apps/standalone/src/local-server-worker.ts@@ -232,9 +232,11 @@ async function initialize(): Promise<void> {// A reload starts this worker while the browser is still releasing the previous// worker's exclusive OPFS access handles, so the boot waits for the database pool// to be free — before the log service, whose own OPFS file is held the same way.- const poolReleased = await waitForSahPoolRelease();- if (!poolReleased) {- console.warn("[Worker] The SAHPool files are still held by another context; opening the database is expected to fail.");+ // Running installSahPool() against files another context still holds is worse than+ // not booting: installOpfsSAHPoolVfs() answers the acquisition failure by deleting+ // the pool directory, and a lock covering only part of it takes the rest with it.+ if (!await waitForSahPoolRelease()) {+ throw opfsAccessError("another context still holds the database files");}// Initialize log service as early as possible so subsequent@@ -247,20 +249,12 @@ async function initialize(): Promise<void> {logService.info("[Worker] Initializing SQLite WASM...");await sqlProvider!.initWasm();- // A failure here ends the boot: throwing from initialize() reaches the page as- // WORKER_ERROR and error-overlay.ts paints it. Opening an in-memory database- // instead would boot an empty instance whose notes vanish on the next reload.+ // A failure past the wait is a broken environment rather than a transient, so it+ // ends the boot: throwing from initialize() reaches the page as WORKER_ERROR.try {await sqlProvider!.installSahPool();} catch (e) {- const reason = e instanceof Error ? e.message : String(e);- throw new Error(- "The notes database could not be opened, because the browser did not grant "- + `exclusive access to its persistent storage (OPFS): ${reason}\n\n`- + "Close any other window running Trilium and reload this page. Your notes are "- + "not affected. If the browser does not support OPFS sync access handles at "- + "all, Trilium cannot run in it."- );+ throw opfsAccessError(e instanceof Error ? e.message : String(e));}// Integration test mode is baked in at build time via the@@ -282,7 +276,7 @@ async function initialize(): Promise<void> {// the fixture, and subsequent inits in the same test reuse it.await loadTestDatabase(dbName);} else {- logService.info("[Worker] Loading persistent database from SAHPool (WAL mode)...");+ logService.info("[Worker] Loading persistent database from SAHPool (WAL)...");sqlProvider!.loadFromSahPool(dbName);}@@ -411,6 +405,21 @@ async function initialize(): Promise<void> {return initPromise;}+/**+ * The startup error for a database the browser will not grant exclusive OPFS access to, painted+ * by `error-overlay.ts`. Opening an in-memory database instead would boot an empty instance+ * whose notes vanish on the next reload.+ */+function opfsAccessError(reason: string): Error {+ return new Error(+ "The notes database could not be opened, because the browser did not grant exclusive "+ + `access to its persistent storage (OPFS): ${reason}\n\n`+ + "Close any other window running Trilium and reload this page. Your notes are not "+ + "affected. If the browser does not support OPFS sync access handles at all, Trilium "+ + "cannot run in it."+ );+}+/*** Ensure the worker is initialized before processing requests.* Returns the router if initialization was successful.