@evolu/web 3.1.1 → 3.2.0

package/src/Platform.test.ts

@@ -6,8 +6,9 @@ import {
   PositiveInt,
   testStubGlobal,
 } from "@evolu/common";
-import { test } from "node:test";
+import { mock, test } from "node:test";
 import { availableParallelism, isApplePlatform } from "./index.ts";
+import { reloadApp } from "./Platform.ts";
 
 for (const platform of ["macOS", "MacIntel", "iPhone", "iPad", "iPod"]) {
   test(`isApplePlatform recognizes ${platform}`, () => {
@@ -43,3 +44,30 @@ test("availableParallelism returns the validated browser value", () => {
   assertType<typeof parallelism, PositiveInt>();
   assertEqual(parallelism, 128);
 });
+
+test("reloadApp reloads the current page", () => {
+  const reload = mock.fn<() => void>();
+  const replace = mock.fn<(url: string) => void>();
+  using _document = testStubGlobal("document", {});
+  using _location = testStubGlobal("location", { reload, replace });
+
+  reloadApp();
+
+  assertEqual(reload.mock.callCount(), 1);
+  assertEqual(replace.mock.callCount(), 0);
+});
+
+test("reloadApp loads a given URL instead", () => {
+  const reload = mock.fn<() => void>();
+  const replace = mock.fn<(url: string) => void>();
+  using _document = testStubGlobal("document", {});
+  using _location = testStubGlobal("location", { reload, replace });
+
+  reloadApp("/signed-out");
+
+  assertEqual(
+    replace.mock.calls.map((call) => call.arguments),
+    [["/signed-out"]],
+  );
+  assertEqual(reload.mock.callCount(), 0);
+});

package/src/Platform.ts

@@ -16,5 +16,6 @@ export const reloadApp: ReloadApp = (url) => {
     return;
   }
 
-  location.replace(url ?? "/");
+  if (url === undefined) location.reload();
+  else location.replace(url);
 };

package/src/Sqlite.test.ts

@@ -1,7 +1,11 @@
 import {
+  AbortError,
+  assert,
   assertEqual,
   assertEqualBytes,
+  assertSame,
   assertTrue,
+  assertType,
   EncryptionKey,
   Name,
   sql,
@@ -9,6 +13,90 @@ import {
 } from "@evolu/common";
 import { describe, it, mock } from "node:test";
 
+// OPFS with an optional pool directory. Each pool file lists the error names
+// its next openings reject with, in order.
+const opfsMock = (() => {
+  const state = {
+    closedAccessHandleCount: 0,
+    directoryNames: [] as Array<string>,
+    getDirectoryCount: 0,
+    hasOpaqueDirectory: true,
+    openedAccessHandleCount: 0,
+    poolFiles: null as Array<Array<string>> | null,
+  };
+
+  const opaqueDirectory = {
+    // for await also iterates a sync iterable.
+    values: function* () {
+      yield { kind: "directory" };
+      for (const errorNames of state.poolFiles ?? [])
+        yield {
+          kind: "file",
+          createSyncAccessHandle: () => {
+            const errorName = errorNames.shift();
+            if (errorName !== undefined)
+              return Promise.reject(new DOMException("Held", errorName));
+            state.openedAccessHandleCount += 1;
+            return Promise.resolve({
+              close: () => {
+                state.closedAccessHandleCount += 1;
+              },
+            });
+          },
+        };
+    },
+  };
+
+  const poolDirectory = {
+    getDirectoryHandle: (name: string) => {
+      state.directoryNames.push(name);
+      return state.hasOpaqueDirectory
+        ? Promise.resolve(opaqueDirectory)
+        : Promise.reject(new DOMException("Missing", "NotFoundError"));
+    },
+  };
+
+  const root = {
+    getDirectoryHandle: (name: string) => {
+      state.directoryNames.push(name);
+      return state.poolFiles
+        ? Promise.resolve(poolDirectory)
+        : Promise.reject(new DOMException("Missing", "NotFoundError"));
+    },
+  };
+
+  Object.defineProperty(navigator, "storage", {
+    configurable: true,
+    value: {
+      getDirectory: () => {
+        state.getDirectoryCount += 1;
+        return Promise.resolve(root);
+      },
+    },
+  });
+
+  return {
+    reset: (
+      poolFiles: Array<Array<string>> | null = null,
+      { hasOpaqueDirectory = true } = {},
+    ) => {
+      state.closedAccessHandleCount = 0;
+      state.directoryNames.length = 0;
+      state.getDirectoryCount = 0;
+      state.hasOpaqueDirectory = hasOpaqueDirectory;
+      state.openedAccessHandleCount = 0;
+      state.poolFiles = poolFiles;
+    },
+    state,
+  };
+})();
+
+// Lets resolved mocks settle before test time advances.
+const flushMicrotasks = (): Promise<void> =>
+  new Promise((resolve) => {
+    setImmediate(resolve);
+  });
+
 const sqliteMock = (() => {
   class PreparedStatement {
     finalized = false;
@@ -115,6 +203,7 @@ const sqliteMock = (() => {
     consoleWarn: mock.fn<typeof console.warn>(),
     pool,
     reset: () => {
+      opfsMock.reset();
       state.closedDatabases.length = 0;
       state.createdDatabases.length = 0;
       state.deletedFilenames.length = 0;
@@ -193,6 +282,7 @@ describe("createWasmSqliteDriver coverage helpers", () => {
 
     assertEqual(sqliteMock.sqlite3.installOpfsSAHPoolVfs.mock.callCount(), 0);
     assertEqual(sqliteMock.state.createdDatabases[0]?.filename, ":memory:");
+    assertEqual(opfsMock.state.getDirectoryCount, 0);
   });
 
   it("executes non-prepared query and exports database", async () => {
@@ -354,3 +444,89 @@ describe("createWasmSqliteDriver coverage helpers", () => {
     );
   });
 });
+
+describe("createWasmSqliteDriver held pool files", () => {
+  for (const errorName of ["InvalidStateError", "NoModificationAllowedError"])
+    it(`sets up the pool once a file held with ${errorName} is released`, async () => {
+      sqliteMock.reset();
+      opfsMock.reset([[], [errorName, errorName]]);
+
+      await using run = testCreateRun();
+      const driver = run.ok(createWasmSqliteDriver(Name.orThrow("MockPlain")));
+      await flushMicrotasks();
+
+      assertEqual(opfsMock.state.directoryNames, [".MockPlain", ".opaque"]);
+      run.deps.time.advance("49ms");
+      await flushMicrotasks();
+      assertEqual(sqliteMock.sqlite3.installOpfsSAHPoolVfs.mock.callCount(), 0);
+
+      // The retry delay doubles after each held pass.
+      run.deps.time.advance("1ms");
+      await flushMicrotasks();
+      run.deps.time.advance("99ms");
+      await flushMicrotasks();
+      assertEqual(sqliteMock.sqlite3.installOpfsSAHPoolVfs.mock.callCount(), 0);
+
+      run.deps.time.advance("1ms");
+      using _driver = await driver;
+
+      // The free file opens on each of the three passes, the held one once.
+      assertEqual(sqliteMock.sqlite3.installOpfsSAHPoolVfs.mock.callCount(), 1);
+      assertEqual(opfsMock.state.openedAccessHandleCount, 4);
+      assertEqual(opfsMock.state.closedAccessHandleCount, 4);
+    });
+
+  it("sets up the pool at once when its directory has no files yet", async () => {
+    sqliteMock.reset();
+    opfsMock.reset([], { hasOpaqueDirectory: false });
+
+    await using run = testCreateRun();
+    using _driver = await run.ok(
+      createWasmSqliteDriver(Name.orThrow("MockPlain")),
+    );
+
+    assertEqual(opfsMock.state.directoryNames, [".MockPlain", ".opaque"]);
+    assertEqual(opfsMock.state.openedAccessHandleCount, 0);
+    assertEqual(sqliteMock.sqlite3.installOpfsSAHPoolVfs.mock.callCount(), 1);
+  });
+
+  it("warns once when pool files stay held for five seconds", async () => {
+    sqliteMock.reset();
+    opfsMock.reset([Array.from({ length: 12 }, () => "InvalidStateError")]);
+
+    await using run = testCreateRun();
+    const driver = run.ok(createWasmSqliteDriver(Name.orThrow("MockPlain")));
+    for (let second = 0; second < 12; second += 1) {
+      await flushMicrotasks();
+      run.deps.time.advance("1s");
+    }
+    using _driver = await driver;
+
+    const warnings = run.deps.console
+      .getEntriesSnapshot()
+      .filter((entry) => entry.method === "warn");
+    assertEqual(
+      warnings.map((entry) => entry.args),
+      [
+        [
+          "Waiting for an ended DbWorker to release the files of database MockPlain.",
+        ],
+      ],
+    );
+  });
+
+  it("fails before setting up the pool when a file cannot be opened", async () => {
+    sqliteMock.reset();
+    opfsMock.reset([["UnknownError"]]);
+
+    await using run = testCreateRun();
+    const result = await run.abortable(
+      createWasmSqliteDriver(Name.orThrow("MockPlain")),
+    );
+
+    assert(!result.ok, "Expected the driver to fail.");
+    assertType(AbortError, result.error);
+    assertSame(result.error.reason.type, "PanicAbortReason");
+    assertEqual(sqliteMock.sqlite3.installOpfsSAHPoolVfs.mock.callCount(), 0);
+  });
+});

package/src/Sqlite.ts

@@ -4,6 +4,10 @@ import {
   createPreparedStatementsCache,
   exhaustiveCheck,
   ok,
+  performanceDurationBetween,
+  PositiveMillis,
+  sleep,
+  tryAsync,
 } from "@evolu/common";
 import sqlite3InitModule, {
   type Database,
@@ -32,7 +36,7 @@ const sqlite3Promise = sqlite3InitModule();
 const fileName = "evolu1.db";
 
 export const createWasmSqliteDriver: CreateSqliteDriver =
-  (name, options) => async () => {
+  (name, options) => async (run) => {
     const sqlite3 = await sqlite3Promise;
 
     using disposer = new DisposableStack();
@@ -45,6 +49,69 @@ export const createWasmSqliteDriver: CreateSqliteDriver =
     const createOpfsSAHPoolVfs = async (
       options: Parameters<typeof sqlite3.installOpfsSAHPoolVfs>[0],
     ): Promise<SAHPoolUtil> => {
+      // Evolu opens a database only while it holds the database lock, but a
+      // DbWorker that ended without closing it, because its tab closed,
+      // crashed or navigated away, can hold pool files after the lock has
+      // passed on: WebKit releases a terminated worker's locks and its files
+      // separately, in no set order. sqlite-wasm cannot set up a pool with a
+      // held file, and it then deletes the pool directory, which the held file
+      // usually but not always prevents. Only a worker that has ended can hold
+      // the files, and it can only release them, so the pool is set up once
+      // every file opens.
+      const canOpenPoolFiles = async (): Promise<boolean> => {
+        const root = await navigator.storage.getDirectory();
+        // sqlite-wasm keeps the pool in `.${name}/.opaque` in both OPFS modes.
+        const poolDirectory = await tryAsync(() =>
+          root.getDirectoryHandle(`.${name}`),
+        );
+        if (!poolDirectory.ok) return true;
+        const opaqueDirectory = await tryAsync(() =>
+          poolDirectory.value.getDirectoryHandle(".opaque"),
+        );
+        if (!opaqueDirectory.ok) return true;
+        for await (const handle of opaqueDirectory.value.values()) {
+          if (handle.kind !== "file") continue;
+          const accessHandle = await tryAsync(() =>
+            handle.createSyncAccessHandle(),
+          );
+          if (!accessHandle.ok) {
+            // WebKit rejects a held file with InvalidStateError, other
+            // engines with NoModificationAllowedError, as the spec says.
+            // WebKit also uses InvalidStateError for a closed or invalid
+            // handle and a stopped context. A retry opens fresh handles from
+            // a new listing, and a stopped context ends the loop with its
+            // worker, so retrying those is harmless.
+            if (
+              accessHandle.error instanceof DOMException &&
+              (accessHandle.error.name === "InvalidStateError" ||
+                accessHandle.error.name === "NoModificationAllowedError")
+            )
+              return false;
+            throw accessHandle.error;
+          }
+          accessHandle.value.close();
+        }
+        return true;
+      };
+
+      const waitStart = run.deps.time.performance.now();
+      let retryDelay = 50;
+      let isWaitReported = false;
+      while (!(await canOpenPoolFiles())) {
+        const waited = performanceDurationBetween(
+          waitStart,
+          run.deps.time.performance.now(),
+        );
+        if (!isWaitReported && waited >= 5000) {
+          isWaitReported = true;
+          run.deps.console.warn(
+            `Waiting for an ended DbWorker to release the files of database ${name}.`,
+          );
+        }
+        await run.ok(sleep(PositiveMillis.orThrow(retryDelay)));
+        retryDelay = Math.min(retryDelay * 2, 1000);
+      }
+
       const pool = await sqlite3.installOpfsSAHPoolVfs(options);
       if (pool.isPaused()) await pool.unpauseVfs();
       disposer.defer(() => {

package/src/Task.test.ts

@@ -1,14 +1,9 @@
-import {
-  assertEqual,
-  assertNonNullable,
-  assertTrue,
-  testStubGlobal,
-} from "@evolu/common";
+import { assertEqual, assertSame, testStubGlobal } from "@evolu/common";
 import { describe, it, mock } from "node:test";
 import { createRun } from "./Task.ts";
 
 describe("createRun", () => {
-  it("createRun reports defects with global reportError", async () => {
+  it("createRun reports a panic's defect with global reportError", async () => {
     const reportError = mock.fn<(error: unknown) => void>();
     using _reportError = testStubGlobal("reportError", reportError);
     await using run = createRun();
@@ -17,13 +12,7 @@ describe("createRun", () => {
     run.panic(defect);
 
     assertEqual(reportError.mock.callCount(), 1);
-    const reported = reportError.mock.calls[0]?.arguments[0];
-    assertNonNullable(reported);
-    assertTrue(typeof reported === "object");
-    assertEqual(Reflect.get(reported, "reason"), {
-      type: "PanicAbortReason",
-      defect,
-    });
+    assertSame(reportError.mock.calls[0]?.arguments[0], defect);
   });
 
   it("createRun preserves a custom reportDefect", async () => {

package/src/Task.ts

@@ -6,6 +6,7 @@
 
 import {
   createRun as createCommonRun,
+  defectToError,
   type DisposableRun,
   type Run,
   type RunCustomDeps,
@@ -14,13 +15,16 @@ import {
 /**
  * Creates a root {@link Run} for the browser.
  *
- * Defects are reported with the browser's global `reportError`. A custom
- * `reportDefect` dependency overrides the browser default.
+ * Defects are reported with the browser's global `reportError` as an `Error`
+ * from {@link defectToError}, because browsers show any other value only as
+ * unhelpful text. A custom `reportDefect` dependency overrides the browser
+ * default.
  *
  * ### Example
  *
  * ```ts
  * import {
+ *   assertEqual,
  *   createConsole,
  *   createConsoleFormatter,
  *   ok,
@@ -36,7 +40,7 @@ import {
  * await using run = createRun({ console });
  * const appPromise = run.ok(() => ok("started"));
  *
- * expect(await appPromise).toBe("started");
+ * assertEqual(await appPromise, "started");
  * ```
  */
 export function createRun(): DisposableRun;
@@ -49,7 +53,7 @@ export function createRun<D extends object>(
   deps?: RunCustomDeps<D>,
 ): DisposableRun | DisposableRun<D> {
   const reportDefect = (reported: unknown): void => {
-    reportError(reported);
+    reportError(defectToError(reported));
   };
 
   return deps === undefined