@evolu/common 8.17.0 → 8.19.0

package/src/local-first/Evolu.test.ts

@@ -75,7 +75,7 @@ import { err, ok } from "../Result.ts";
 import { SqliteBoolean } from "../Sqlite.ts";
 import { explicitAbortReason, testCreateDeps, testCreateRun } from "../Task.ts";
 import { testCreateId } from "../Test.ts";
-import { Millis } from "../Time.ts";
+import { maxMillis, Millis } from "../Time.ts";
 import {
   assertType,
   createIdFromString,
@@ -90,8 +90,14 @@ import {
   Uint8Array as Uint8ArrayType,
 } from "../Type.ts";
 import type { ExtractTyped } from "../Type.ts";
-import { DbChange } from "./Storage.ts";
-import { createTimestamp, type NodeId } from "./Timestamp.ts";
+import { DbChange, RangeType } from "./Storage.ts";
+import {
+  createTimestamp,
+  maxCounter,
+  maxNodeId,
+  type NodeId,
+  timestampToTimestampBytes,
+} from "./Timestamp.ts";
 import {
   testCreateBroadcastChannel,
   testCreateMessageChannel,
@@ -3144,13 +3150,25 @@ describe("Evolu", () => {
         }),
       };
 
-      // A request and a broadcast assert that the change fits.
-      createProtocolMessageFromCrdtMessages(deps)(testAppOwner, [message]);
+      const change = encodeAndEncryptDbChange(deps)(
+        message,
+        testAppOwner.encryptionKey,
+      );
+
+      // A request leaves out a change that does not fit and asks for another
+      // round instead, so it must be longer than the change. A broadcast
+      // throws when the change does not fit.
+      assertTrue(
+        createProtocolMessageFromCrdtMessages(deps)(testAppOwner, [message])
+          .length > change.length,
+      );
       createProtocolBroadcastMessagesFromCrdtMessages(deps)(testAppOwner, [
         message,
       ]);
 
-      // A relay's response can pair it with the largest ranges section.
+      // A relay's response can pair it with the largest ranges section: a
+      // Skip range and a Timestamps range listing nearly 100,000 bytes, with
+      // room left to close the frame.
       const rangesMaxSize = ProtocolMessageRangesMaxSize.orThrow(100_000);
       const timestamps = createTimestampsBuffer();
       for (let index = 1; timestamps.getLength() < 99_900; index++) {
@@ -3167,12 +3185,25 @@ describe("Evolu", () => {
         rangesMaxSize,
       });
       assertTrue(
-        response.canAddTimestampsRangeAndMessage(timestamps, {
-          timestamp: message.timestamp,
-          change: encodeAndEncryptDbChange(deps)(
-            message,
-            testAppOwner.encryptionKey,
-          ),
+        response.tryWrite(() => {
+          response.addMessage({ timestamp: message.timestamp, change });
+          response.addRange({
+            type: RangeType.Skip,
+            upperBound: timestampToTimestampBytes(
+              createTimestamp({ millis: Millis.orThrow(2 ** 47) }),
+            ),
+          });
+          response.addRange({
+            type: RangeType.Timestamps,
+            upperBound: timestampToTimestampBytes(
+              createTimestamp({
+                millis: maxMillis,
+                counter: maxCounter,
+                nodeId: maxNodeId,
+              }),
+            ),
+            timestamps,
+          });
         }),
       );
     });

package/src/local-first/Evolu.ts

@@ -64,7 +64,11 @@ import type {
   CreateBroadcastChannelDep,
   CreateMessageChannelDep,
 } from "../Worker.ts";
-import type { CreateDbWorkerDep, UnsupportedDbVersionError } from "./Db.ts";
+import type {
+  CreateDbWorkerDep,
+  DatabaseHeldError,
+  UnsupportedDbVersionError,
+} from "./Db.ts";
 import type {
   AppOwner,
   Owner,
@@ -76,6 +80,7 @@ import type {
 import { createOwnerWebSocketTransport } from "./Owner.ts";
 import {
   encodeDbChange,
+  type ProtocolChangeTooLargeError,
   type ProtocolError,
   type ProtocolInvalidDataError,
   type ProtocolQuotaError,
@@ -946,6 +951,9 @@ export type DevicePersistence = "Persisted" | "NotPersisted" | "Unknown";
  *
  * - {@link UnsupportedDbVersionError} blocks the app: the local data needs a newer
  *   version of it. Ask the user to update the app or close all its tabs.
+ * - {@link DatabaseHeldError} blocks the app: another context keeps holding the
+ *   local data, as a browser can until it restarts. Ask the user to close the
+ *   app's other tabs or to restart the browser, then to reload the app.
  * - {@link OtherBuildRunningError} blocks the app while it lasts: another version
  *   of the app holds the local data. Ask the user to close the app's other
  *   tabs. It clears when the wait ends.
@@ -960,7 +968,8 @@ export type DevicePersistence = "Persisted" | "NotPersisted" | "Unknown";
  * request, or sent a frame that could not be decoded, the route shows a
  * {@link ProtocolError}. A {@link ProtocolQuotaError} needs more relay quota,
  * then {@link Evolu.requestSync}, and a {@link ProtocolVersionError} needs an app
- * or relay update.
+ * or relay update. A route shows an {@link UnknownError} failure when this
+ * device could not store received changes, for example on a full disk.
  *
  * A received change that was not created with the owner's encryption key, was
  * altered afterwards, or cannot be decoded by this app version is skipped,
@@ -985,10 +994,21 @@ export type DevicePersistence = "Persisted" | "NotPersisted" | "Unknown";
  * {@link DecryptWithXChaCha20Poly1305Error} and your code creates or shares the
  * owner, check the owner's keys.
  *
+ * A {@link ProtocolChangeTooLargeError} skip is a change no protocol message can
+ * hold: one this device saved before {@link maxMutationSize} existed, or a
+ * crafted one received from a relay. Every route through a relay that lacks it
+ * shows it after each sync, and everything else still syncs, but changes
+ * received from one relay reach the others only after a reconnect or
+ * {@link Evolu.requestSync}. The change is not recovered, and replacing relays
+ * does not help.
+ *
  * @group Core
  */
 export type EvoluError =
-  OtherBuildRunningError | UnknownError | UnsupportedDbVersionError;
+  | DatabaseHeldError
+  | OtherBuildRunningError
+  | UnknownError
+  | UnsupportedDbVersionError;
 
 /**
  * The largest {@link Mutation}, in bytes.
@@ -1061,9 +1081,10 @@ export interface EvoluErrorDep {
    * refusal to each tab once, including tabs that connect later, and starts no
    * replacement database workers. After all instances release that tenant and
    * it is disposed when idle, creating another instance retries startup and may
-   * send the refusal again. On the web, a refused tab first reloads once
-   * instead; see {@link UnsupportedDbVersionError}. Show that blocking message
-   * outside any query-loading boundary, so pending queries do not hide it.
+   * send the refusal again. On the web, a tab refused with
+   * {@link UnsupportedDbVersionError} first reloads once instead. Show that
+   * blocking message outside any query-loading boundary, so pending queries do
+   * not hide it.
    *
    * An {@link UnknownError} leaves Evolu in an unknown state, so the app can
    * only ask the user to close the tab. A failed shared worker closes itself,
@@ -1088,6 +1109,8 @@ export interface EvoluErrorDep {
    *   switch (error.type) {
    *     case "UnsupportedDbVersionError":
    *       return "Your data requires a newer version of this app. Please update it.";
+   *     case "DatabaseHeldError":
+   *       return "Your data is still in use elsewhere. Close this app's other tabs or restart the browser, then reload this page.";
    *     case "OtherBuildRunningError":
    *       return "This app is open in another tab with a different version. Close that tab to continue.";
    *     case "UnknownError":
@@ -1708,7 +1731,11 @@ export const createEvolu =
         // gets it already batched and cannot reach the call site; quarantine,
         // which holds changes stored for sync; and skipping it in sync, which
         // keeps range fingerprints disagreeing. Received changes are not
-        // checked, and oversized changes stored before this limit are not
+        // checked. Changes saved before this limit can be too large for any
+        // protocol message, as can crafted changes on a relay. Their
+        // fingerprints disagree either way, so sync skips them, which ends
+        // every round instead of retrying forever. A client reports such a
+        // change as its route's skippedError, and a relay logs it. They are not
         // recovered, which needs a history-aware design.
         //
         // Local-only tables never sync, so they have no limit.