@evolu/common 8.16.0 → 8.18.0

package/src/local-first/Relay.ts

@@ -13,7 +13,8 @@ import {
 } from "../Array.ts";
 import { assert } from "../Assert.ts";
 import type { TimingSafeEqualDep } from "../Crypto.ts";
-import { err, ok } from "../Result.ts";
+import { createUnknownError } from "../Error.ts";
+import { err, ok, trySync } from "../Result.ts";
 import type { SqliteDep } from "../Sqlite.ts";
 import { sql } from "../Sqlite.ts";
 import { createMutexByKey } from "../Task.ts";
@@ -25,12 +26,13 @@ import {
   // OwnerTransport,
   OwnerWriteKey,
 } from "./Owner.ts";
+import type { ProtocolWriteKeyError } from "./Protocol.ts";
 import type {
   EncryptedDbChange,
   SqliteStorageDeps,
   Storage,
   StorageConfig,
-  StorageQuotaError,
+  StorageWriteMessagesError,
 } from "./Storage.ts";
 import {
   createBaseSqliteStorage,
@@ -66,7 +68,15 @@ export interface RelayConfig extends StorageConfig {
    *
    * OwnerId is used rather than short-lived tokens because this only controls
    * relay access, not write permissions. Since all data is encrypted on the
-   * relay, OwnerId exposure is safe.
+   * relay, OwnerId exposure reveals no data.
+   *
+   * It does allow write-key squatting. The relay stores the first write key
+   * presented for an owner, so anyone who learns an OwnerId before the owner's
+   * own write key reaches the relay can claim it. The owner then gets
+   * {@link ProtocolWriteKeyError} on this relay until the operator deletes the
+   * owner's row in `evolu_writeKey`. This callback does not prevent that: it
+   * receives only the OwnerId of a connection, which a squatter can name as
+   * well, and every message on the connection can name another owner.
    *
    * Owners specify which relays to connect to via `OwnerTransport`. In
    * WebSocket-based implementations, this check occurs before accepting the
@@ -186,6 +196,9 @@ export const createRelaySqliteStorage =
           return deps.timingSafeEqual(rows[0].writeKey, writeKey);
         }
 
+        // When SQLite fails this insert, for example on a full disk, the throw
+        // reaches the protocol, which logs it and answers with WriteError,
+        // because a boolean has no room for the error.
         deps.sqlite.exec(sql`
           insert into evolu_writeKey (ownerId, writeKey)
           values (${ownerId}, ${writeKey});
@@ -194,15 +207,6 @@ export const createRelaySqliteStorage =
         return true;
       },
 
-      setWriteKey: (ownerId, writeKey) => {
-        deps.sqlite.exec(sql`
-          insert into evolu_writeKey (ownerId, writeKey)
-          values (${ownerId}, ${writeKey})
-          on conflict (ownerId) do update
-            set writeKey = excluded.writeKey;
-        `);
-      },
-
       writeMessages: (ownerIdBytes, messages) => async (run) => {
         const ownerId = ownerIdBytesToOwnerId(ownerIdBytes);
         const uniqueMessagesWithTimestampBytes = dedupeArray(
@@ -215,32 +219,42 @@ export const createRelaySqliteStorage =
 
         return run(
           mutexByOwnerId.withLock(ownerId, async () => {
-            const existingTimestampsResult =
-              sqliteStorageBase.getExistingTimestamps(
-                ownerIdBytes,
-                mapArray(uniqueMessagesWithTimestampBytes, (m) => m.timestamp),
+            // SQLite can fail these reads, for example on a corrupt page, and
+            // a throw would panic the relay's shared Run.
+            const readResult = trySync(() => {
+              const existingTimestampsResult =
+                sqliteStorageBase.getExistingTimestamps(
+                  ownerIdBytes,
+                  mapArray(
+                    uniqueMessagesWithTimestampBytes,
+                    (m) => m.timestamp,
+                  ),
+                );
+
+              const existingTimestampKeys = new Set(
+                mapArray(existingTimestampsResult, uint8ArrayToBase64Url),
+              );
+              const newMessages = filterArray(
+                uniqueMessagesWithTimestampBytes,
+                (message) =>
+                  !existingTimestampKeys.has(
+                    uint8ArrayToBase64Url(message.timestamp),
+                  ),
               );
 
-            const existingTimestampKeys = new Set(
-              mapArray(existingTimestampsResult, uint8ArrayToBase64Url),
-            );
-            const newMessages = filterArray(
-              uniqueMessagesWithTimestampBytes,
-              (message) =>
-                !existingTimestampKeys.has(
-                  uint8ArrayToBase64Url(message.timestamp),
-                ),
-            );
+              // Nothing to write
+              if (!isNonEmptyArray(newMessages)) return null;
 
-            // Nothing to write
-            if (!isNonEmptyArray(newMessages)) {
-              return ok();
-            }
+              const usage = readOwnerUsageOrDefault(deps)(
+                ownerIdBytes,
+                firstInArray(newMessages).timestamp,
+              );
 
-            const usage = readOwnerUsageOrDefault(deps)(
-              ownerIdBytes,
-              firstInArray(newMessages).timestamp,
-            );
+              return { newMessages, usage };
+            }, createUnknownError);
+            if (!readResult.ok) return readResult;
+            if (readResult.value === null) return ok();
+            const { newMessages, usage } = readResult.value;
 
             const incomingBytes = newMessages.reduce(
               (sum, m) => sum + m.change.length,
@@ -260,7 +274,7 @@ export const createRelaySqliteStorage =
               ? await quotaResult
               : quotaResult;
             if (!isWithinQuota) {
-              return err<StorageQuotaError>({
+              return err<StorageWriteMessagesError>({
                 type: "StorageQuotaError",
                 ownerId,
               });
@@ -268,39 +282,42 @@ export const createRelaySqliteStorage =
 
             let { firstTimestamp, lastTimestamp } = usage;
 
-            return deps.sqlite.transaction(() => {
-              for (const { timestamp, change } of newMessages) {
-                let strategy;
-                [strategy, firstTimestamp, lastTimestamp] =
-                  getTimestampInsertStrategy(
+            // SQLite can fail the write, for example on a full disk. The
+            // transaction has rolled back, and a throw would panic the relay's
+            // shared Run.
+            return trySync(() => {
+              deps.sqlite.transaction(() => {
+                for (const { timestamp, change } of newMessages) {
+                  let strategy;
+                  [strategy, firstTimestamp, lastTimestamp] =
+                    getTimestampInsertStrategy(
+                      timestamp,
+                      firstTimestamp,
+                      lastTimestamp,
+                    );
+
+                  sqliteStorageBase.insertTimestamp(
+                    ownerIdBytes,
                     timestamp,
-                    firstTimestamp,
-                    lastTimestamp,
+                    strategy,
                   );
 
-                sqliteStorageBase.insertTimestamp(
+                  deps.sqlite.exec(sql`
+                    insert into evolu_message
+                      ("ownerId", "timestamp", "change")
+                    values (${ownerIdBytes}, ${timestamp}, ${change})
+                    on conflict do nothing;
+                  `);
+                }
+
+                updateOwnerUsage(deps)(
                   ownerIdBytes,
-                  timestamp,
-                  strategy,
+                  newStoredBytes,
+                  firstTimestamp,
+                  lastTimestamp,
                 );
-
-                deps.sqlite.exec(sql`
-                  insert into evolu_message
-                    ("ownerId", "timestamp", "change")
-                  values (${ownerIdBytes}, ${timestamp}, ${change})
-                  on conflict do nothing;
-                `);
-              }
-
-              updateOwnerUsage(deps)(
-                ownerIdBytes,
-                newStoredBytes,
-                firstTimestamp,
-                lastTimestamp,
-              );
-
-              return ok();
-            });
+              });
+            }, createUnknownError);
           }),
         );
       },
@@ -329,13 +346,7 @@ export const createRelaySqliteStorage =
             delete from evolu_message where ownerId = ${ownerId};
           `);
 
-          deps.sqlite.exec(sql`
-            delete from evolu_usage where ownerId = ${ownerId};
-          `);
-
           sqliteStorageBase.deleteOwner(ownerId);
-
-          return ok();
         });
       },
     };

package/src/local-first/Shared.ts

@@ -111,10 +111,10 @@
  * whichever instance made it, even one disposed before the database worker
  * answered. When a relay frame stores new messages, the tenant requests a round
  * through each other transport claimed for the owner, so data learned from one
- * relay reaches the others, except through a route that skipped a message, as
- * described below. A closed transport reconciles when it opens, and a
- * replacement leader reconciles every transport again, because a response
- * reporting stored messages may have been lost.
+ * relay reaches the others, except through a route that skipped a message it
+ * received or could not send, as described below. A closed transport reconciles
+ * when it opens, and a replacement leader reconciles every transport again,
+ * because a response reporting stored messages may have been lost.
  *
  * Relays omit the sending socket when broadcasting an upload, so the uploader
  * also delivers it as local Broadcast frames to every other tenant with
@@ -178,17 +178,17 @@
  *   request, a replacement leader, or storing messages from another transport,
  *   unless the route skipped a message. No failed or aborted result has arrived
  *   on the route since.
- * - No result that skipped a received message has arrived on the route since a
- *   round was last requested through it, and since that request, no messages
- *   have been stored from another transport, directly or through a sibling copy
- *   uploaded outside this transport, and no sibling copy has failed to apply or
- *   skipped a message.
+ * - No result that skipped a received message or a stored change too large to
+ *   send has arrived on the route since a round was last requested through it,
+ *   and since that request, no messages have been stored from another
+ *   transport, directly or through a sibling copy uploaded outside this
+ *   transport, and no sibling copy has failed to apply or skipped a message.
  *
  * A route is settled when every condition except the last holds, so a complete
  * route is settled too. A settled route that is incomplete has ended its
- * reconciliation, but its relay may offer a message the database skipped, or
- * messages stored elsewhere may not have reached it; it is published as
- * {@link SettledSyncRoute}.
+ * reconciliation, but its relay may offer a message the database skipped, the
+ * database may store a change too large to send, or messages stored elsewhere
+ * may not have reached it; it is published as {@link SettledSyncRoute}.
  *
  * A reconciliation chain ends only with a converged result, a failure, an
  * abort, a dropped frame, or a continuation that finds the socket closed, and
@@ -207,20 +207,34 @@
  * while the database worker creates a round is logged there and fails the
  * round's routes with `SyncFailed` without a retry. A mutation that throws is
  * rolled back and reported as an {@link UnknownError} to the tab that made it,
- * or to every tab when its Evolu instance was disposed first. Other unexpected
- * SQLite exceptions remain unsupported and can panic the database worker. A
- * frame the relay silently drops, such as invalid data, leaves the count above
- * zero until the liveness rule below replaces the socket.
- *
- * A result that skipped a received message the database could not decrypt,
- * verify, or decode records the error on the route as its `skippedError`,
- * without ending its chain, so it requests no round, and the relay offers the
- * message again in every round through the route until the database stores a
- * message with that timestamp. The messages received elsewhere that the last
- * condition names request no round through such a route, even while a requested
- * round checks it again, because each round would download every skipped
- * message again. The next round that an explicit request, a reopen, a
- * replacement leader, or a failure sends through the route reconciles them.
+ * or to every tab when its Evolu instance was disposed first. A received batch
+ * SQLite fails to store, for example on a full disk, is rolled back and fails
+ * its route with an `UnknownError`. Other unexpected SQLite exceptions remain
+ * unsupported and can panic the database worker. A frame the relay silently
+ * drops, such as invalid data, leaves the count above zero until the liveness
+ * rule below replaces the socket.
+ *
+ * A result that skipped a message records the error on the route as its
+ * `skippedError`, without ending its chain, so it requests no round. A message
+ * is skipped in two cases:
+ *
+ * - The relay offers a message the database could not decrypt, verify, or decode.
+ *   The relay offers it again in every round through the route until the
+ *   database stores a message with that timestamp.
+ * - The database stores a change it cannot send, a
+ *   {@link ProtocolChangeTooLargeError}: one saved before `maxMutationSize`
+ *   existed, or a crafted one received from a relay. Every route through a
+ *   relay that lacks it skips it on every sync, so each such route stays
+ *   settled.
+ *
+ * The messages received elsewhere that the last condition names request no
+ * round through such a route, even while a requested round checks it again,
+ * because each round would download every skipped message again, or skip again
+ * a change too large to send. The next round that an explicit request, a
+ * reopen, a replacement leader, or a failure sends through the route reconciles
+ * them. So while the database stores a change too large to send, messages from
+ * other relays reach a route only through such a round, for example after a
+ * reconnect or {@link Evolu.requestSync}.
  *
  * ### Liveness
  *
@@ -353,6 +367,7 @@ import {
   MessageType,
   parseProtocolHeader,
   type ApplyProtocolMessageAsClientResult,
+  type ProtocolChangeTooLargeError,
   type ProtocolError,
   type ProtocolInvalidDataError,
   type ProtocolMessage,
@@ -659,8 +674,9 @@ export interface ReadonlySyncTenantOwner extends Typed<"Readonly"> {
 
 /**
  * One database's use of one owner through one transport: `Pending` until its
- * reconciliation ends, then `Complete`, or `Settled` while its relay offers a
- * change the database skipped. See Synchronization completion in this module's
+ * reconciliation ends, then `Complete`, or `Settled` while it skips a change:
+ * one its relay offers that the database could not store, or one the database
+ * stores but cannot send. See Synchronization completion in this module's
  * documentation.
  */
 export type SyncRoute = PendingSyncRoute | SettledSyncRoute | CompleteSyncRoute;
@@ -680,9 +696,12 @@ export interface PendingSyncRoute extends Typed<"Pending"> {
    */
   readonly failure: SyncRouteError | null;
   /**
-   * The first change skipped in the latest reply that skipped one, or null. The
-   * relay offers it again in every round through the route until this database
-   * stores a change with that timestamp.
+   * The first change skipped in the latest reply that skipped one, or null. A
+   * change the relay offers is offered again in every round through the route
+   * until this database stores a change with that timestamp. A
+   * {@link ProtocolChangeTooLargeError} is a change this database stores but
+   * cannot send, which every route through a relay that lacks it skips on every
+   * sync.
    */
   readonly skippedError: SyncRouteError | null;
   /** When the route last became complete, or null. */
@@ -697,10 +716,15 @@ export interface PendingSyncRoute extends Typed<"Pending"> {
 }
 
 /**
- * A route whose reconciliation ended while its relay offers a change the
- * database skipped, so it is incomplete. Changes stored from other relays
- * request no round through it; the next round requested through it, such as by
- * {@link Evolu.requestSync} or a reopen, checks it again.
+ * A route whose reconciliation ended with a skipped change, so it is
+ * incomplete: its relay offers a change the database could not store, or the
+ * database stores a change it cannot send, a
+ * {@link ProtocolChangeTooLargeError}. Changes stored from other relays request
+ * no round through it; the next round requested through it, such as by
+ * {@link Evolu.requestSync} or a reopen, checks it again. Every route through a
+ * relay that lacks a change too large to send skips it on every sync, so those
+ * routes stay settled, and messages from other relays reach them only through
+ * such rounds.
  */
 export interface SettledSyncRoute extends Typed<"Settled"> {
   readonly transportId: SyncTransportId;
@@ -734,11 +758,13 @@ export interface CompleteSyncRoute extends Typed<"Complete"> {
  *
  * It is the error itself, so it carries its details, such as the expected and
  * actual timestamps of a {@link ProtocolTimestampMismatchError}. A skipped
- * message adds {@link DecryptWithXChaCha20Poly1305Error}. A
- * {@link ProtocolInvalidDataError} leaves out its data, which can be a whole
- * frame. `WriteFailed` means a `writeMessages` call that threw, logged by the
- * protocol, and `SyncFailed` means a logged failure while creating a round or
- * reconciling ranges.
+ * message adds {@link DecryptWithXChaCha20Poly1305Error} and
+ * {@link ProtocolChangeTooLargeError}. A {@link ProtocolInvalidDataError} leaves
+ * out its data, which can be a whole frame. An {@link UnknownError} means SQLite
+ * failed to store received messages, for example on a full disk. `WriteFailed`
+ * means a `writeMessages` call that threw, logged by the protocol, and
+ * `SyncFailed` means a logged failure while creating a round or reconciling
+ * ranges.
  */
 export type SyncRouteError = (
   | Exclude<ProtocolError, ProtocolInvalidDataError>
@@ -749,6 +775,7 @@ export type SyncRouteError = (
   | (Omit<DecryptWithXChaCha20Poly1305Error, "error"> & {
       readonly error: UnknownError;
     })
+  | ProtocolChangeTooLargeError
   | Typed<"WriteFailed">
   | Typed<"SyncFailed">
 ) & { readonly at: Millis };
@@ -779,10 +806,10 @@ export interface RelaySyncState {
  * - `Synced`: a relay is up to date, and none syncs.
  * - `Offline`: every relay is disconnected. Evolu keeps reconnecting, up to 30
  *   seconds apart, so `Offline` can briefly outlast the outage.
- * - `Error`: a relay failed or offers a change this database skipped. `error` is
- *   the newest failure, or without one, the newest skipped change: a failure
- *   stops syncing through its relay, while a skipped change leaves out only
- *   that change.
+ * - `Error`: a relay failed, a relay offers a change this database skipped, or
+ *   this database stores a change too large to send. `error` is the newest
+ *   failure, or without one, the newest skipped change: a failure stops syncing
+ *   through its relay, while a skipped change leaves out only that change.
  *
  * Evolu stores changes in the local database before they sync, so sync needs no
  * UI while it works: show nothing for `NoRelays`, `Syncing`, and `Synced`. An
@@ -1365,13 +1392,15 @@ export type DbWorkerQueuedResponse =
             readonly ownerId: OwnerId;
             readonly didWriteMessages: boolean;
             /**
-             * The first error of a received message the DbWorker skipped while
-             * storing the rest, or null. It does not end the round.
+             * The first error of a message the DbWorker skipped, or null: a
+             * received one it did not store while storing the rest, or a stored
+             * change too large to send. It does not end the round.
              */
             readonly skippedError:
               | DecryptWithXChaCha20Poly1305Error
               | ProtocolInvalidDataError
               | ProtocolTimestampMismatchError
+              | ProtocolChangeTooLargeError
               | null;
             readonly result: Result<
               ApplyProtocolMessageAsClientResult,
@@ -1529,8 +1558,10 @@ interface PendingRoute extends Typed<"Pending"> {
 }
 
 /**
- * A message a route skipped. Its relay offers the message again in every round,
- * so messages received elsewhere request no round through the route.
+ * A message a route skipped: one its relay offers that the database could not
+ * store, which the relay offers again in every round, or one the database
+ * stores but cannot send, which every round skips again. So messages received
+ * elsewhere request no round through the route.
  */
 interface RouteSkip {
   readonly error: SyncRouteError;
@@ -1543,8 +1574,9 @@ interface RouteSkip {
 }
 
 /**
- * A route whose reconciliation has ended, but whose relay may offer a skipped
- * message or lack messages stored elsewhere, so it is incomplete.
+ * A route whose reconciliation has ended, but which is incomplete: its relay
+ * may offer a skipped message, the database may store a change too large to
+ * send, or the relay may lack messages stored elsewhere.
  */
 interface SettledRoute extends Typed<"Settled"> {
   readonly skippedError: SyncRouteError;
@@ -1584,6 +1616,7 @@ const errorToSyncRouteError = (
     | ProtocolError
     | StorageWriteMessagesError
     | DecryptWithXChaCha20Poly1305Error
+    | ProtocolChangeTooLargeError
     | Typed<"WriteFailed">
     | Typed<"SyncFailed">,
   at: Millis,
@@ -1773,8 +1806,9 @@ export const initSharedWorker =
 
     // Held while this worker runs. Its DbWorkers stop once they can take it,
     // because a Dispose posted right before this worker closes can be lost, as
-    // in Firefox. Taken before the build lock, so nothing delays the end of
-    // starting once that lock is held.
+    // in Firefox (https://bugzilla.mozilla.org/show_bug.cgi?id=2077609). Taken
+    // before the build lock, so nothing delays the end of starting once that
+    // lock is held.
     disposer.use(await run.ok(acquireLeaderLock(workerId)));
 
     // Released after every tenant is disposed and has told its DbWorker to
@@ -2780,7 +2814,8 @@ const createEvoluTenant =
             !hasQueuedWrite;
           // Settling drops the failure, so the next one requests a round
           // again. A route with a skip it is not rechecking settles without
-          // completing, because its relay may offer the skipped message or
+          // completing, because its relay may offer the skipped message, the
+          // database may store a change too large to send, or the relay may
           // lack messages stored elsewhere.
           const pending = routeToPending(route.progress);
           route.progress =
@@ -2887,11 +2922,12 @@ const createEvoluTenant =
               if (!isAborted) route.lastReceivedAt = now;
               // A skipped message is recorded as the route's skip, not a
               // failure, and does not end the round, whose response below is
-              // still sent, so it requests no round. The relay offers the
-              // message again in every later round, so the route stays
-              // incomplete until a round requested through it settles without
-              // skipping a message and without messages stored elsewhere since
-              // that request.
+              // still sent, so it requests no round. The relay offers a message
+              // the database could not store again in every later round, and
+              // every round skips a stored change too large to send again, so
+              // the route stays incomplete until a round requested through it
+              // settles without skipping a message and without messages stored
+              // elsewhere since that request.
               if (skippedError !== null)
                 route.progress = {
                   ...routeToPending(route.progress),
@@ -2918,12 +2954,14 @@ const createEvoluTenant =
             }
           } else if (failure !== null || skippedError !== null) {
             // A sibling's copy comes from this worker, not from a relay, so no
-            // route shows its failure. It is a Broadcast, which carries no
-            // relay error, so an error or a skip means a bug, such as
-            // databases holding different keys for the owner, and is reported
-            // as an unexpected failure. A Failed result was logged, which
-            // reports it already. An error is the failure, which is never an
-            // abort, and like a route, the report leaves out its frame.
+            // route shows its failure. SQLite can fail to store it, for example
+            // on a full disk, which returns an UnknownError. It is a Broadcast,
+            // which carries no relay error, so any other error or a skip means
+            // a bug, such as databases holding different keys for the owner.
+            // Each is reported as an unexpected failure. A Failed result was
+            // logged, which reports it already. An error is the failure, which
+            // is never an abort, and like a route, the report leaves out its
+            // frame.
             const unexpected = error !== null ? failure : skippedError;
             if (unexpected !== null)
               deps.postConsoleEntryOrError({
@@ -3043,9 +3081,10 @@ const createEvoluTenant =
      * `except`, after messages from elsewhere were stored or a sibling copy was
      * not fully stored. Rounds toward the same transport coalesce whatever
      * their source. A route that skipped a message gets none, because its relay
-     * would offer that message again, and a route rechecking one stops
-     * rechecking, because its round may have read the database before this
-     * event. A later requested round through such a route reconciles it.
+     * would offer that message again or the round would skip a stored change
+     * too large to send again. A route rechecking one stops rechecking, because
+     * its round may have read the database before this event. A later requested
+     * round through such a route reconciles it.
      */
     const requestRoundsForReceivedMessages = (
       ownerId: OwnerId,