Skip to content

Build your personal knowledge base with Trilium Notes

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.md
index 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.ts
index 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.ts
index 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<string
try {
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.ts
index 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.