@evolu/web 3.1.2 → 3.2.0

package/src/local-first/Evolu.ts

@@ -1,13 +1,26 @@
-import { exhaustiveCheck, type ConsoleDep } from "@evolu/common";
+import {
+  exhaustiveCheck,
+  trySync,
+  type ConsoleDep,
+  type ReloadApp,
+  type ReloadAppDep,
+  type UnsupportedDbVersionError,
+} from "@evolu/common";
 import type {
   SharedWorker as CommonSharedWorker,
   CreateDbWorker,
   DbWorkerInit,
   EvoluDeps,
+  SharedWorkerId,
   SharedWorkerInput,
   SharedWorkerOutput,
 } from "@evolu/common/local-first";
-import { createEvoluDeps as createCommonEvoluDeps } from "@evolu/common/local-first";
+import {
+  BuildWaiting,
+  BuildWaitingRequest,
+  buildsBroadcastChannelName,
+  createEvoluDeps as createCommonEvoluDeps,
+} from "@evolu/common/local-first";
 import { reloadApp } from "../Platform.ts";
 import {
   createBroadcastChannel,
@@ -17,12 +30,6 @@ import {
   installOneTabSharedWorkerPolyfill,
 } from "../Worker.ts";
 
-// // TODO: Redesign.
-// export const localAuth = createLocalAuth({
-//   randomBytes: createRandomBytes(),
-//   secureStorage: createWebAuthnStore({ randomBytes: createRandomBytes() }),
-// });
-
 export interface SharedWorkerUnsupported {
   readonly type: "SharedWorkerUnsupported";
 }
@@ -31,18 +38,231 @@ export interface SharedWorkerUnsupportedDep {
   readonly onSharedWorkerUnsupported: () => void;
 }
 
-/** Creates Evolu dependencies for the web platform. */
+export interface StorageUnavailableDep {
+  /**
+   * Called when the browser offers no persistent storage, as in Safari's
+   * Private Browsing, so every database is kept in memory. See Storage in the
+   * Shared module of `@evolu/common`.
+   *
+   * The app keeps working. Data synced with a relay comes back, as on a new
+   * device, and nothing stays on the device once the tabs close. That suits
+   * someone checking their app on a borrowed phone, so a message such as
+   * "Nothing from this session is kept on this device." tells the user what to
+   * expect. Data that exists only locally, or has not synced yet, is lost when
+   * the tab hosting the database closes or navigates away, even while other
+   * tabs stay open.
+   */
+  readonly onStorageUnavailable: () => void;
+}
+
+/**
+ * Creates Evolu dependencies for the web platform.
+ *
+ * When another build of the app waits for this one, this tab reloads to load
+ * the build the server now serves: at once if the user is not in the tab,
+ * otherwise once they leave it. See Builds in the Shared module of
+ * `@evolu/common`. A tab whose database refuses to start with
+ * {@link UnsupportedDbVersionError} reloads once for each stored version, even
+ * while the user is in it, because the server may now serve a build that
+ * supports the database. The error is reported when the reloaded build refuses
+ * it too, or when the tab has no session storage. A tab whose worker was
+ * relaunched without its state, as WebKit does when the process hosting it
+ * ends, also reloads at once.
+ *
+ * When the page enters the browser's back-forward cache, as Safari does on
+ * every navigation away, this tab ends its part as if it closed: it stops the
+ * database workers it hosts, so another tab takes them over, and it reloads if
+ * the user comes back to it.
+ *
+ * Where the browser offers no persistent storage, as in Safari's Private
+ * Browsing, the database is kept in memory, and
+ * {@link StorageUnavailableDep.onStorageUnavailable} lets the app tell the
+ * user.
+ *
+ * A custom {@link ReloadApp} replaces the default page reload, for example to
+ * save state first. It should end by reloading the page, because the other
+ * build waits until this tab reloads or closes, and a page restored from the
+ * back-forward cache cannot work until it reloads.
+ */
 export const createEvoluDeps = (
-  deps: Partial<ConsoleDep> & Partial<SharedWorkerUnsupportedDep> = {},
+  deps: Partial<ConsoleDep> &
+    Partial<ReloadAppDep> &
+    Partial<SharedWorkerUnsupportedDep> &
+    Partial<StorageUnavailableDep> = {},
 ): EvoluDeps => {
   installOneTabSharedWorkerPolyfill();
+  const reloadThisApp = deps.reloadApp ?? reloadApp;
+  // A page an automatic reload loaded never announces its build, so two builds
+  // cannot keep reloading each other.
+  const isAutomaticReload = takeAutomaticReload();
+  // Waiting workers this tab already reloaded for. A reload that loaded the
+  // running build again did not help, so the tab does not repeat it.
+  const reloadedForWorkerIds = getReloadedForWorkerIds();
+  // Versions a refusal already reloaded this tab for, read once, so every
+  // refusal before this page unloads reloads it.
+  const refusalReloadVersions = getRefusalReloadVersions();
+
+  let connectedWorkerId: SharedWorkerId | null = null;
+  let waitingWorkerId: SharedWorkerId | null = null;
+  // Workers announced before this tab connected. The lock can pass to this
+  // tab's worker first, and their tabs may not answer a request, for example
+  // when frozen, so the tab handles them once it connects.
+  const earlyAnnouncedWorkerIds = new Set<SharedWorkerId>();
+  // Checks whether the user left this tab while another build waits.
+  let focusCheckId: ReturnType<typeof setInterval> | null = null;
 
-  const createDbWorker: CreateDbWorker = () =>
-    createWorker<DbWorkerInit, never>(
+  using disposer = new DisposableStack();
+  const buildsBroadcastChannel = disposer.use(
+    createBroadcastChannel<unknown>(buildsBroadcastChannelName),
+  );
+
+  const stopFocusCheck = (): void => {
+    if (focusCheckId === null) return;
+    clearInterval(focusCheckId);
+    focusCheckId = null;
+  };
+  disposer.defer(stopFocusCheck);
+
+  const announceWaitingBuild = (): void => {
+    if (waitingWorkerId === null || isAutomaticReload) return;
+    buildsBroadcastChannel.postMessage({
+      type: "BuildWaiting",
+      workerId: waitingWorkerId,
+    } satisfies BuildWaiting);
+  };
+
+  const reloadForWaitingBuild = (workerId: SharedWorkerId): void => {
+    stopFocusCheck();
+    // Without session storage, the reloaded page could announce in turn.
+    if (!markAutomaticReload(workerId)) return;
+    reloadThisApp();
+  };
+
+  const handleWaitingBuild = (workerId: SharedWorkerId): void => {
+    if (workerId === connectedWorkerId || reloadedForWorkerIds.has(workerId)) {
+      return;
+    }
+    if (!document.hasFocus()) {
+      reloadForWaitingBuild(workerId);
+      return;
+    }
+    // Focus can leave the page from a frame without a window event.
+    focusCheckId ??= setInterval(() => {
+      if (!document.hasFocus()) reloadForWaitingBuild(workerId);
+    }, 1000);
+  };
+
+  // Builds of different releases share the channel, so messages are validated.
+  buildsBroadcastChannel.onMessage = (message) => {
+    if (BuildWaitingRequest.is(message)) {
+      announceWaitingBuild();
+    } else if (BuildWaiting.is(message)) {
+      if (connectedWorkerId === null) {
+        earlyAnnouncedWorkerIds.add(message.workerId);
+      } else handleWaitingBuild(message.workerId);
+    }
+  };
+
+  const handleSharedWorkerMessage = (
+    message: SharedWorkerOutput | SharedWorkerUnsupported,
+    forward: (message: SharedWorkerOutput) => void,
+  ): void => {
+    // WebKit can relaunch a SharedWorker without its state when the process
+    // hosting it ends, and connect the tabs' existing ports to the new worker
+    // (https://bugs.webkit.org/show_bug.cgi?id=318873). A worker tells a tab
+    // at most once that it waits and once that it connected, both with its own
+    // id, so only then does a tab hear from a worker with another id. The
+    // tab's state, including the databases it asked for while it waited, ended
+    // with the old worker, so it reloads at once.
+    const knownWorkerId = connectedWorkerId ?? waitingWorkerId;
+    if (
+      (message.type === "Waiting" || message.type === "Connected") &&
+      knownWorkerId !== null &&
+      message.workerId !== knownWorkerId
+    ) {
+      reloadThisApp();
+      return;
+    }
+
+    switch (message.type) {
+      case "DbWorkerInit": {
+        forward(message);
+        break;
+      }
+
+      case "Error": {
+        // The page is about to reload, so the error is not reported.
+        if (
+          message.error.type === "UnsupportedDbVersionError" &&
+          !refusalReloadVersions.has(String(message.error.storedVersion)) &&
+          markRefusalReload(message.error)
+        ) {
+          reloadThisApp();
+          break;
+        }
+        forward(message);
+        break;
+      }
+
+      case "Waiting": {
+        waitingWorkerId = message.workerId;
+        announceWaitingBuild();
+        forward(message);
+        break;
+      }
+
+      case "Connected": {
+        waitingWorkerId = null;
+        connectedWorkerId = message.workerId;
+        forward(message);
+        for (const workerId of earlyAnnouncedWorkerIds) {
+          handleWaitingBuild(workerId);
+        }
+        // An announcement may have come before this tab started.
+        buildsBroadcastChannel.postMessage({
+          type: "BuildWaitingRequest",
+        } satisfies BuildWaitingRequest);
+        break;
+      }
+
+      case "StorageUnavailable": {
+        deps.onStorageUnavailable?.();
+        forward(message);
+        break;
+      }
+
+      case "SharedWorkerUnsupported": {
+        if (deps.onSharedWorkerUnsupported) {
+          deps.onSharedWorkerUnsupported();
+        } else {
+          alert(
+            "This browser supports Evolu in one tab only. Close this tab and use the already open tab.",
+          );
+        }
+        break;
+      }
+
+      default:
+        exhaustiveCheck(message);
+    }
+  };
+
+  // Disposing the deps ends the DbWorkers this tab hosts, which releases their
+  // database locks for the tab that takes over.
+  const dbWorkers = new Set<Disposable>();
+  disposer.defer(() => {
+    for (const dbWorker of dbWorkers) dbWorker[Symbol.dispose]();
+  });
+
+  const createDbWorker: CreateDbWorker = () => {
+    const dbWorker = createWorker<DbWorkerInit, never>(
       new Worker(new URL("Db.worker.js", import.meta.url), {
         type: "module",
       }),
     );
+    dbWorkers.add(dbWorker);
+    return dbWorker;
+  };
 
   const webSharedWorker = createSharedWorker<
     SharedWorkerInput,
@@ -65,39 +285,100 @@ export const createEvoluDeps = (
         onSharedWorkerMessage = fn;
         webSharedWorker.port.onMessage = fn
           ? (message: SharedWorkerOutput | SharedWorkerUnsupported) => {
-              switch (message.type) {
-                case "DbWorkerInit": {
-                  fn(message);
-                  break;
-                }
-
-                case "SharedWorkerUnsupported": {
-                  if (deps.onSharedWorkerUnsupported) {
-                    deps.onSharedWorkerUnsupported();
-                  } else {
-                    alert(
-                      "This browser supports Evolu in one tab only. Close this tab and use the already open tab.",
-                    );
-                  }
-                  break;
-                }
-
-                default:
-                  exhaustiveCheck(message);
-              }
+              handleSharedWorkerMessage(message, fn);
             }
           : null;
       },
     },
   };
 
-  return createCommonEvoluDeps({
-    ...deps,
-    createDbWorker,
-    createBroadcastChannel,
-    createMessageChannel,
-    lockManager: navigator.locks,
-    reloadApp,
-    sharedWorker,
+  const evoluDeps = disposer.use(
+    createCommonEvoluDeps({
+      ...deps,
+      createDbWorker,
+      createBroadcastChannel,
+      createMessageChannel,
+      lockManager: navigator.locks,
+      reloadApp: reloadThisApp,
+      sharedWorker,
+    }),
+  );
+
+  // A page entering the back-forward cache is frozen with its DbWorkers, which
+  // keep their database locks, so the other tabs would stall. WebKit also
+  // releases the page's own locks, so a restored page would work with state
+  // the other tabs gave up on. The page therefore ends its part as if it
+  // closed, and reloads when it is shown again.
+  const reloadRestoredPage = (event: PageTransitionEvent): void => {
+    if (event.persisted) reloadThisApp();
+  };
+  const handlePageHide = (event: PageTransitionEvent): void => {
+    if (!event.persisted) return;
+    addEventListener("pageshow", reloadRestoredPage, { once: true });
+    disposables.dispose();
+  };
+  addEventListener("pagehide", handlePageHide);
+  disposer.defer(() => {
+    removeEventListener("pagehide", handlePageHide);
+  });
+
+  const disposables = disposer.move();
+
+  return {
+    ...evoluDeps,
+    [Symbol.dispose]: () => {
+      disposables.dispose();
+    },
+  };
+};
+
+// Marks, for the tab's session, that Evolu reloaded the page for another build.
+const automaticReloadKey = "evolu:automatic-reload";
+// Holds, for the tab's session, every waiting worker Evolu reloaded it for.
+const reloadedForKey = "evolu:reloaded-for";
+
+// Removes the mark, so only the page the reload loaded sees it.
+const takeAutomaticReload = (): boolean => {
+  const item = trySync(() => {
+    const value = sessionStorage.getItem(automaticReloadKey);
+    sessionStorage.removeItem(automaticReloadKey);
+    return value;
   });
+  return item.ok && item.value !== null;
 };
+
+const getReloadedForWorkerIds = (): ReadonlySet<string> => {
+  const item = trySync(() => sessionStorage.getItem(reloadedForKey));
+  return new Set(item.ok && item.value !== null ? item.value.split(",") : []);
+};
+
+const markAutomaticReload = (workerId: SharedWorkerId): boolean =>
+  trySync(() => {
+    const workerIds = new Set(
+      sessionStorage.getItem(reloadedForKey)?.split(","),
+    );
+    workerIds.add(workerId);
+    sessionStorage.setItem(reloadedForKey, [...workerIds].join(","));
+    sessionStorage.setItem(automaticReloadKey, "1");
+  }).ok;
+
+// Holds, for the tab's session, every stored database version a refusal
+// reloaded the page for. Each version reloads it once, so refusals of several
+// databases cannot keep reloading it, and a build that refuses them again
+// reports the error instead.
+const refusalReloadKey = "evolu:refusal-reloads";
+
+const getRefusalReloadVersions = (): ReadonlySet<string> => {
+  const item = trySync(() => sessionStorage.getItem(refusalReloadKey));
+  return new Set(item.ok && item.value !== null ? item.value.split(",") : []);
+};
+
+// Adds to the stored versions, which include those marked earlier in this page.
+const markRefusalReload = (error: UnsupportedDbVersionError): boolean =>
+  trySync(() => {
+    const versions = new Set(
+      sessionStorage.getItem(refusalReloadKey)?.split(","),
+    );
+    versions.add(String(error.storedVersion));
+    sessionStorage.setItem(refusalReloadKey, [...versions].join(","));
+  }).ok;

package/src/local-first/Shared.worker.ts

@@ -4,7 +4,7 @@ declare const self: DedicatedWorkerGlobalScope | SharedWorkerGlobalScope;
 import { installPolyfills } from "@evolu/common/polyfills";
 installPolyfills();
 
-import { createWebSocket, ok, waitForAbort } from "@evolu/common";
+import { createWebSocket, ok, tryAsync, waitForAbort } from "@evolu/common";
 import type {
   SharedWorkerInput,
   SharedWorkerOutput,
@@ -21,6 +21,9 @@ import {
 const run = createRun({
   ...createWorkerDeps(),
   createWebSocket,
+  // Safari's Private Browsing offers no OPFS; see Storage in the Shared module.
+  isPersistentStorageAvailable: async () =>
+    (await tryAsync(() => navigator.storage.getDirectory())).ok,
   lockManager: navigator.locks,
 });
 

package/dist/src/local-first/LocalAuth.d.ts

@@ -1,3 +0,0 @@
-import type { RandomBytesDep, SecureStorage } from "@evolu/common";
-export declare const createWebAuthnStore: (deps: RandomBytesDep) => SecureStorage;
-//# sourceMappingURL=LocalAuth.d.ts.map

package/dist/src/local-first/LocalAuth.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"LocalAuth.d.ts","sourceRoot":"","sources":["../../../src/local-first/LocalAuth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,cAAc,EACd,aAAa,EAEd,MAAM,eAAe,CAAC;AAiBvB,eAAO,MAAM,mBAAmB,SAAU,cAAc,KAAG,aA4GzD,CAAC"}

package/dist/src/local-first/LocalAuth.js

@@ -1,185 +0,0 @@
-import { Base64Url, base64UrlToUint8Array, bytesToUtf8, createSlip21, decryptWithXChaCha20Poly1305, EncryptionKey, encryptWithXChaCha20Poly1305, Entropy24, uint8ArrayToBase64Url, utf8ToBytes, XChaCha20Poly1305Ciphertext, } from "@evolu/common";
-import { clear, createStore, del, get, keys, set } from "idb-keyval";
-export const createWebAuthnStore = (deps) => ({
-    setItem: async (key, value, options) => {
-        if (options?.accessControl === "none") {
-            const metadata = createMetadata(false);
-            await set(key, { value, metadata }, getStore(options.service));
-            return { metadata };
-        }
-        const seed = generateSeed(deps)();
-        const authResult = JSON.parse(value);
-        const credential = await createCredential(deps)(options?.webAuthnUsername ?? "Evolu User", seed, options?.relyingPartyID, options?.relyingPartyName, options?.webAuthnUserVerification, options?.webAuthnAuthenticatorAttachment);
-        const encryptionKey = deriveEncryptionKey(seed);
-        const encryptedData = encryptAuthResult(deps)(authResult, encryptionKey);
-        const credentialId = uint8ArrayToBase64Url(new Uint8Array(credential.rawId));
-        const metadata = createMetadata();
-        await set(key, { credentialId, ...encryptedData, metadata }, getStore(options?.service));
-        return { metadata };
-    },
-    getItem: async (key, options) => {
-        if (options?.accessControl === "none") {
-            const data = await get(key, getStore(options.service));
-            return data
-                ? {
-                    key,
-                    value: data.value,
-                    service: options.service ?? "default",
-                    metadata: data.metadata,
-                }
-                : null;
-        }
-        const data = await get(key, getStore(options?.service));
-        if (!data) {
-            return null;
-        }
-        try {
-            const credential = await getCredential(deps)(data.credentialId, options?.relyingPartyID, options?.webAuthnUserVerification);
-            const credentialSeed = extractSeedFromCredential(credential);
-            const encryptionKey = deriveEncryptionKey(credentialSeed);
-            const authResultVal = decryptAuthResult(data, encryptionKey);
-            if (!authResultVal) {
-                return null;
-            }
-            return {
-                key,
-                service: options?.service ?? "default",
-                value: authResultVal,
-                metadata: data.metadata,
-            };
-        }
-        catch (_error) {
-            return null;
-        }
-    },
-    deleteItem: async (key, options) => {
-        await del(key, getStore(options?.service));
-        return true;
-    },
-    getAllItems: async (options) => {
-        const service = options?.service ?? "default";
-        const itemKeys = await keys(getStore(service));
-        const items = await Promise.all(itemKeys.map(async (key) => {
-            const data = await get(key, getStore(service));
-            return {
-                key,
-                service,
-                metadata: data?.metadata ?? createMetadata(),
-                ...(options?.includeValues && data?.value
-                    ? { value: data.value }
-                    : {}),
-            };
-        }));
-        return items;
-    },
-    clearService: async (options) => {
-        await clear(getStore(options?.service));
-    },
-});
-/**
- * Create default metadata for backwards compatibility with items that don't
- * have stored metadata.
- */
-const createMetadata = (isSecure = true) => ({
-    backend: "keychain",
-    accessControl: isSecure ? "biometryCurrentSet" : "none",
-    securityLevel: isSecure ? "biometry" : "software",
-    timestamp: Date.now(),
-});
-/** Get storage key for owner ID. (supports namespaces via prefix) */
-const getStore = (prefix = "default") => createStore(prefix, "evolu-auth");
-const createCredential = (deps) => async (username, seed, relyingPartyID, relyingPartyName, userVerification, authenticatorAttachment) => {
-    const options = createCredentialCreationOptions(deps)(username, seed, relyingPartyID, relyingPartyName, userVerification, authenticatorAttachment);
-    const credential = (await navigator.credentials.create(options));
-    if (!credential) {
-        throw new Error("Failed to create WebAuthn credential");
-    }
-    return credential;
-};
-const getCredential = (deps) => async (credentialId, relyingPartyID, userVerification) => {
-    const options = createCredentialRequestOptions(deps)(credentialId, relyingPartyID, userVerification);
-    const credential = (await navigator.credentials.get(options));
-    if (!credential?.response) {
-        throw new Error("Failed to get WebAuthn credential");
-    }
-    return credential;
-};
-const extractSeedFromCredential = (credential) => {
-    const response = credential.response;
-    if (!response.userHandle) {
-        throw new Error("No userHandle in credential response");
-    }
-    return new Uint8Array(response.userHandle);
-};
-const createCredentialCreationOptions = (deps) => (username, seed, relyingPartyID, relyingPartyName, userVerification, authenticatorAttachment) => ({
-    publicKey: {
-        challenge: generateSeed(deps)(),
-        rp: {
-            id: relyingPartyID ?? document.location.hostname,
-            name: relyingPartyName ?? "Evolu",
-        },
-        user: {
-            id: seed,
-            name: username,
-            displayName: username,
-        },
-        pubKeyCredParams: [
-            // Ed25519
-            { type: "public-key", alg: -8 },
-            // ES256
-            { type: "public-key", alg: -7 },
-            // RS256
-            { type: "public-key", alg: -257 },
-        ],
-        attestation: "none",
-        authenticatorSelection: {
-            // - "platform": Uses the platform's built-in authenticator.
-            // - "cross-platform": Uses a device specific authenticator (yubikey, fido2, etc.)
-            authenticatorAttachment: authenticatorAttachment ?? "platform",
-            // - "discouraged": Only User Presence is needed.
-            // - "preferred": User Verification is preferred but not required. Falls back to User Presence.
-            // - "required": User Verification MUST occur (biometrics/PIN). Clients may silently downgrade to User Presence only.
-            userVerification: userVerification ?? "required",
-            // - "discouraged": Server-side credential is preferable, but will accept client-side discoverable credential.
-            // - "preferred": Relying Party strongly prefers client-side discoverable credential but will accept server-side credential.
-            // - "required": Client-side discoverable credential MUST be created, error if it can't be created.
-            residentKey: "required",
-            // Included for backwards compatibility. Deprecated in favor of residentKey (true = "required")
-            requireResidentKey: true,
-        },
-    },
-});
-const createCredentialRequestOptions = (deps) => (credentialId, relyingPartyID, userVerification) => ({
-    publicKey: {
-        challenge: generateSeed(deps)(),
-        rpId: relyingPartyID ?? document.location.hostname,
-        userVerification: userVerification ?? "preferred",
-        allowCredentials: [
-            {
-                type: "public-key",
-                id: base64UrlToUint8Array(Base64Url.orThrow(credentialId)),
-            },
-        ],
-    },
-});
-const deriveEncryptionKey = (seed) => {
-    const seed32 = seed.length === 32 ? seed : seed.slice(0, 32);
-    return EncryptionKey.orThrow(createSlip21(seed32, ["evolu", "auth"]));
-};
-const encryptAuthResult = (deps) => (authResult, encryptionKey) => {
-    const plaintext = utf8ToBytes(JSON.stringify(authResult));
-    const [ciphertext, nonce] = encryptWithXChaCha20Poly1305(deps)(plaintext, encryptionKey);
-    return {
-        nonce: uint8ArrayToBase64Url(nonce),
-        ciphertext: uint8ArrayToBase64Url(ciphertext),
-    };
-};
-const decryptAuthResult = (encryptedData, encryptionKey) => {
-    const nonce = base64UrlToUint8Array(encryptedData.nonce);
-    const ciphertext = base64UrlToUint8Array(encryptedData.ciphertext);
-    const result = decryptWithXChaCha20Poly1305(XChaCha20Poly1305Ciphertext.orThrow(ciphertext), Entropy24.orThrow(nonce), encryptionKey);
-    if (!result.ok)
-        return null;
-    return bytesToUtf8(result.value);
-};
-const generateSeed = (deps) => () => deps.randomBytes.create(32);