@evolu/common 8.12.0 → 8.13.0

package/src/Task.ts

@@ -485,7 +485,9 @@
  * ## Glossary
  *
  * - **Defect** — a thrown or rejected value other than {@link AbortError}, rather
- *   than a declared {@link Result} error.
+ *   than a declared {@link Result} error. A `SuppressedError` nesting only
+ *   AbortErrors, thrown when `await using` cleanup observes the abort a Task is
+ *   propagating, is an abort, like the same cleanup in `try`/`finally`.
  * - **Outcome** — a Fiber's settlement: resolution with the Task {@link Result},
  *   or rejection with {@link AbortError}. The original defect is reported
  *   through {@link ReportDefectDep} whether or not the Fiber is observed; the
@@ -1536,7 +1538,9 @@ export interface DisposableRun<D = unknown>
    * Sync disposal starts cleanup without waiting and does not throw finalizer
    * defects synchronously. Async disposal awaits cleanup. If a finalizer
    * defects, the defect is reported once, and every async disposal call rejects
-   * with the same already-reported {@link AbortError}.
+   * with the same already-reported {@link AbortError}. A finalizer that rejects
+   * with an AbortError, for example by awaiting another DisposableRun whose
+   * finalizer defected, is not reported; async disposal rejects with it.
    *
    * Calling `defer` after disposal starts is a programmer error.
    *
@@ -2012,10 +2016,10 @@ export const testAbortError = /*#__PURE__*/ createAbortError(testAbortReason);
 /**
  * Abort reason recorded when a defect panics the root {@link Run}.
  *
- * A defect is a thrown or rejected value other than {@link AbortError}.
- * Recoverable domain errors belong in {@link Result}. Bugs and unrecoverable
- * failures, such as storage engine errors the {@link Task} cannot usefully
- * handle, may throw or reject.
+ * A defect is a thrown or rejected value other than {@link AbortError} or a
+ * `SuppressedError` nesting only AbortErrors. Recoverable domain errors belong
+ * in {@link Result}. Bugs and unrecoverable failures, such as storage engine
+ * errors the {@link Task} cannot usefully handle, may throw or reject.
  *
  * {@link Run.onEvent} handler defects are different: event handlers are
  * monitoring code, so their defects are reported globally but do not panic the
@@ -2593,7 +2597,7 @@ const createRunInternal = <D extends object>(
         try {
           await finalizersToDispose.disposeAsync();
         } catch (error: unknown) {
-          finalizerAbortError = root.panic(error);
+          finalizerAbortError = thrownToAbortError(error) ?? root.panic(error);
           exit ??= err(finalizerAbortError);
         }
         return settle();
@@ -2738,7 +2742,7 @@ const createRunInternal = <D extends object>(
 
         exit = ok(result as UnknownResult);
       } catch (error: unknown) {
-        exit = err(AbortError.is(error) ? error : root.panic(error));
+        exit = err(thrownToAbortError(error) ?? root.panic(error));
       }
 
       // Internal Child Run disposal cannot reject; finalizer defects become Err
@@ -2893,7 +2897,7 @@ const createRunInternal = <D extends object>(
 
   run[Symbol.asyncDispose] = async (): Promise<void> => {
     await dispose();
-    // oxlint-disable-next-line typescript/only-throw-error -- AbortError is Task abort control flow; rethrowing it avoids reporting the finalizer defect twice in Task code.
+    // oxlint-disable-next-line typescript/only-throw-error -- AbortError is Task abort control flow; rethrowing the finalizer AbortError avoids reporting a defect twice in Task code.
     if (finalizerAbortError) throw finalizerAbortError;
   };
 
@@ -2906,6 +2910,40 @@ const createRunInternal = <D extends object>(
   return run;
 };
 
+// Cleanup that observes the abort a Task is propagating, for example a
+// DisposableRun whose finalizer defected rejecting with its already-reported
+// AbortError, makes `await using` throw a SuppressedError. When every nested
+// value is an AbortError, it is abort control flow like the same cleanup in
+// try/finally, so the latest error wins: `error`, the last cleanup failure.
+const thrownToAbortError = (thrown: unknown): AbortError | null => {
+  // Nothing here may throw out of runTask's catch. Inspecting the thrown value
+  // can throw, for example from a getter, so the value is then a defect.
+  try {
+    // A loop, not recursion: each failing cleanup nests one more
+    // SuppressedError, and a deep chain would overflow the stack.
+    const values: Array<unknown> = [thrown];
+    while (values.length > 0) {
+      const value = values.pop();
+      if (isSuppressedError(value)) values.push(value.error, value.suppressed);
+      else if (!AbortError.is(value)) return null;
+    }
+    let latest = thrown;
+    while (isSuppressedError(latest)) latest = latest.error;
+    return latest as AbortError;
+  } catch {
+    return null;
+  }
+};
+
+// The internal tag survives crossing realms, such as from an iframe, where
+// instanceof fails. The name also matches TypeScript's downleveled `using`,
+// which captures SuppressedError when a module evaluates, before
+// installPolyfills, and without a native one throws a plain Error named
+// SuppressedError.
+const isSuppressedError = (value: unknown): value is SuppressedError =>
+  Object.prototype.toString.call(value) === "[object Error]" &&
+  (value as Error).name === "SuppressedError";
+
 const withTaskMeta =
   (meta: TaskMeta) =>
   <T, E, D>(task: Task<T, E, D>): Task<T, E, D> => {
@@ -5713,9 +5751,6 @@ export interface SemaphoreSnapshot {
    * is `0` until enough permits are released.
    */
   readonly available: NonNegativeInt;
-
-  /** Whether no permits are held and no requests are queued. */
-  readonly isIdle: boolean;
 }
 
 /**
@@ -5898,7 +5933,6 @@ export const createSemaphore = (
       available: NonNegativeInt.orThrow(
         !isGreedy && waiters.size > 0 ? 0 : Math.max(0, permits - taken),
       ),
-      isIdle: isIdle(),
     }),
     isIdle,
   };

package/src/Worker.ts

@@ -39,9 +39,9 @@ export interface SharedWorker<Input, Output = never> extends Disposable {
  *
  * Note: There is no reliable way to detect when a port is closed or
  * disconnected. Calling `postMessage` on a disposed port does not throw — it
- * silently fails. To detect dead ports, use a heartbeat pattern where the other
- * end periodically sends "alive" messages and stale ports are pruned after a
- * timeout.
+ * silently fails. To detect that the other end is gone, let it hold a Web Lock
+ * for its lifetime and request the same lock: the browser grants it once the
+ * holder releases it or its context closes, with no timeout to tune.
  *
  * @group Core
  * @see https://developer.mozilla.org/en-US/docs/Web/API/MessagePort

package/src/local-first/Db.ts

@@ -40,6 +40,7 @@
 import {
   appendToArray,
   firstInArray,
+  isNonEmptyArray,
   type NonEmptyArray,
   type NonEmptyReadonlyArray,
 } from "../Array.ts";
@@ -50,12 +51,20 @@ import {
   assertNotUndefined,
 } from "../Assert.ts";
 import type { ConsoleLevel } from "../Console.ts";
-import { EncryptionKey, type RandomBytesDep } from "../Crypto.ts";
+import {
+  EncryptionKey,
+  type DecryptWithXChaCha20Poly1305Error,
+  type RandomBytesDep,
+} from "../Crypto.ts";
+import { createUnknownError } from "../Error.ts";
 import { constFalse, constVoid } from "../Function.ts";
 import type { LockManagerDep } from "../LockManager.ts";
-import { acquireLeaderLock } from "../LockManager.ts";
+import {
+  acquireLeaderLock,
+  acquireLeaderLockCallback,
+} from "../LockManager.ts";
 import { createMutableRecord, getOwnProp, objectToEntries } from "../Object.ts";
-import { err, getOk, ok, type Result } from "../Result.ts";
+import { err, getOk, ok, trySync, type Result } from "../Result.ts";
 import type {
   CreateSqliteDriverDep,
   SqliteDep,
@@ -107,7 +116,9 @@ import {
   decryptAndDecodeDbChange,
   encodeAndEncryptDbChange,
   SubscriptionFlags,
+  type ProtocolInvalidDataError,
   type ProtocolMessage,
+  type ProtocolTimestampMismatchError,
 } from "./Protocol.ts";
 import type { Query, RowsByQueryMap } from "./Query.ts";
 import type { MutationChange, SqliteSchemaDep } from "./Schema.ts";
@@ -124,6 +135,7 @@ import type {
   DbWorkerOutput,
   DbWorkerQueuedResponse,
   EvoluInput,
+  SharedWorkerId,
 } from "./Shared.ts";
 import { consoleEntryOrErrorBroadcastChannelName } from "./Shared.ts";
 import {
@@ -162,6 +174,11 @@ export interface DbWorkerInit {
   readonly sqliteSchema: SqliteSchema;
   readonly encryptionKey: EncryptionKey;
   readonly memoryOnly: boolean;
+  /**
+   * The SharedWorker that requested this DbWorker. It leads for this ID while
+   * it runs, so the DbWorker stops serving once it can lead for it.
+   */
+  readonly sharedWorkerId: SharedWorkerId;
   readonly port: NativeMessagePort<DbWorkerOutput, DbWorkerInput>;
 }
 
@@ -197,8 +214,8 @@ export interface UnsupportedDbVersionError extends Typed<"UnsupportedDbVersionEr
 
 /**
  * Starts the platform-agnostic Evolu DbWorker and owns its resources until
- * startup is refused, the worker receives a dispose message, or its {@link Run}
- * is aborted.
+ * startup is refused, the worker receives a dispose message, the SharedWorker
+ * that requested it ends, or its {@link Run} is aborted.
  */
 export const startDbWorker =
   (self: WorkerSelf<DbWorkerInit>): Task<void, never, DbWorkerDeps> =>
@@ -289,7 +306,7 @@ export const startDbWorker =
     );
     if (!startup.ok) {
       // Nothing was written. Returning lets the disposer close SQLite and
-      // release the database lock, which the SharedWorker's tenant disposal
+      // release the database lock, which the next DbWorker for this database
       // waits on. The tab leader lock is unaffected.
       port.postMessage({
         type: "LeaderRefused",
@@ -362,19 +379,30 @@ export const startDbWorker =
                     clock: context.clock.get(),
                     ownerId: owner.id,
                     didWriteMessages: storage.didWriteMessages(),
+                    skippedError: storage.skippedError(),
                     result,
                   },
                 });
                 return ok();
               });
             } else {
+              // SQLite can fail a write the app cannot prevent, such as on a
+              // full disk. The transaction has rolled back, so the mutation is
+              // answered, or every later request of this database would wait.
+              const mutation = trySync(
+                () =>
+                  handleMutation({
+                    ...dbDeps,
+                    clock: context.clock,
+                  })(request.message, now),
+                createUnknownError,
+              );
               postQueuedResponse({
                 type: "ForEvolu",
                 id: request.id,
-                message: handleMutation({
-                  ...dbDeps,
-                  clock: context.clock,
-                })(request.message, now),
+                message: mutation.ok
+                  ? mutation.value
+                  : { type: "MutateFailed", error: mutation.error },
               });
             }
             return;
@@ -441,8 +469,17 @@ export const startDbWorker =
           }
         };
 
+        // Stops once the SharedWorker no longer leads for its ID, which the
+        // platform releases when it closes, because Firefox can lose a Dispose
+        // posted right before that.
+        const sharedWorkerEnded = acquireLeaderLockCallback(deps)(
+          initMessage.sharedWorkerId,
+          () => resolve(ok()),
+        );
+
         return () => {
           port.onMessage = null;
+          sharedWorkerEnded[Symbol.dispose]();
         };
       }),
     );
@@ -478,8 +515,10 @@ interface WriteContext extends ClockDep {
  *
  * Local-only mutations and sync requests that do not invoke `writeMessages`
  * skip this. Successfully processed batches in `writeMessages` call this even
- * when every message is duplicated or quarantined. Duplicate receipts within
- * the drift limit can advance the clock without storing new messages.
+ * when every message is duplicated or quarantined, but not when every message
+ * was skipped, because a skipped message does not affect the clock. Duplicate
+ * receipts within the drift limit can advance the clock without storing new
+ * messages.
  */
 const saveClock =
   (deps: SqliteDep) =>
@@ -873,6 +912,15 @@ interface ClientStorage extends Storage, BaseSqliteStorage {
     writeContext?: WriteContext,
   ) => void;
   readonly didWriteMessages: () => boolean;
+  /**
+   * The first error of a message that {@link Storage.writeMessages} skipped in
+   * this request, or null.
+   */
+  readonly skippedError: () =>
+    | DecryptWithXChaCha20Poly1305Error
+    | ProtocolInvalidDataError
+    | ProtocolTimestampMismatchError
+    | null;
 }
 
 const createClientStorage = (
@@ -884,6 +932,7 @@ const createClientStorage = (
 ): ClientStorage => {
   let encryptionKey: EncryptionKey | null = null;
   let didWriteMessages = false;
+  let skippedError: ReturnType<ClientStorage["skippedError"]> = null;
   let writeContext: WriteContext | undefined;
 
   const getEncryptionKey = (): EncryptionKey => {
@@ -903,9 +952,11 @@ const createClientStorage = (
       encryptionKey = nextEncryptionKey;
       writeContext = nextWriteContext;
       didWriteMessages = false;
+      skippedError = null;
     },
 
     didWriteMessages: () => didWriteMessages,
+    skippedError: () => skippedError,
 
     // Not implemented yet.
     validateWriteKey: constFalse,
@@ -921,20 +972,41 @@ const createClientStorage = (
       const messages: Array<CrdtMessage> = [];
       const currentEncryptionKey = getEncryptionKey();
 
+      // Each message is authenticated on its own, so one this client cannot
+      // decrypt, verify, or decode is skipped while the rest are stored. A
+      // relay can serve anything, and anyone with the owner's write key can
+      // store anything on a relay, so Evolu cannot tell who is at fault; the
+      // SharedWorker shows the skip on the route.
+      //
+      // A skipped message leaves nothing, not even its timestamp. A stored
+      // timestamp would stop this client from fetching the real change with
+      // that timestamp from another relay, and quarantine rows are synced to
+      // other relays. The relay offers the message again on each sync, so once
+      // this client is fixed, the next sync stores it.
+      //
+      // The error is not returned, because that would end the round: the
+      // relay's ranges would go unanswered, so changes it lacks might never be
+      // uploaded to it, and every round would end the same way.
       for (const message of encryptedMessages) {
         const change = decryptAndDecodeDbChange(message, currentEncryptionKey);
-        if (!change.ok) return err(change.error);
+        if (!change.ok) {
+          skippedError ??= change.error;
+          continue;
+        }
         messages.push({ timestamp: message.timestamp, change: change.value });
       }
 
+      if (!isNonEmptyArray(messages)) return ok();
+
       assertNonNullable(writeContext);
       const { clock, now } = writeContext;
       let clockTimestamp = clock.get();
       const receive = receiveTimestamp(deps);
 
-      // The clock is computed over every message, duplicates included, so a
-      // retry with the same inputs reports the same clock. Writes for
-      // timestamps already in the owner's set are skipped by applyMessages.
+      // The clock is computed over every message that was not skipped,
+      // duplicates included, so a retry with the same inputs reports the same
+      // clock. Writes for timestamps already in the owner's set are skipped by
+      // applyMessages.
       for (const message of messages) {
         const nextTimestamp = receive(clockTimestamp, message.timestamp, now);
         if (!nextTimestamp.ok) {
@@ -943,8 +1015,6 @@ const createClientStorage = (
         } else clockTimestamp = nextTimestamp.value;
       }
 
-      assertNonEmptyReadonlyArray(messages);
-
       let wroteNewMessages = false;
       deps.sqlite.transaction(() => {
         wroteNewMessages = applyMessages(deps)(