@evolu/common 8.17.0 → 8.19.0

package/src/local-first/Storage.ts

@@ -10,6 +10,7 @@ import { firstInArray, isNonEmptyArray } from "../Array.ts";
 import { assert, assertNonNullable } from "../Assert.ts";
 import type { Brand } from "../Brand.ts";
 import { concatByteArrays } from "../Bytes.ts";
+import type { UnknownError } from "../Error.ts";
 import { decrement } from "../Number.ts";
 import type { RandomDep } from "../Random.ts";
 import { err, ok } from "../Result.ts";
@@ -36,9 +37,10 @@ import {
   type UnionType,
 } from "../Type.ts";
 import type { Awaitable } from "../Types.ts";
-import type { Owner, OwnerError, OwnerIdBytes } from "./Owner.ts";
+import type { Evolu } from "./Evolu.ts";
+import type { Owner, OwnerError, OwnerIdBytes, SharedOwner } from "./Owner.ts";
 import { OwnerId, OwnerWriteKey } from "./Owner.ts";
-import type { ProtocolQuotaError } from "./Protocol.ts";
+import type { ProtocolQuotaError, ProtocolWriteError } from "./Protocol.ts";
 import { systemColumnsWithId } from "./Schema.ts";
 import type { syncStateToOwnerSyncStatus } from "./Shared.ts";
 import {
@@ -67,7 +69,10 @@ export interface StorageConfig {
    * asynchronous (for calling remote APIs).
    *
    * The callback returns a boolean rather than an error because error handling
-   * and logging are the responsibility of the callback implementation.
+   * and logging are the responsibility of the callback implementation. It must
+   * not throw or reject, because a throw is a defect that shuts the relay down
+   * for a supervisor to restart it; a callback calling a remote service catches
+   * its failure and returns whether to allow the write.
    *
    * Relay deployments configure this callback. Client applications observe a
    * denied relay write as a {@link ProtocolQuotaError} in the `failure` of that
@@ -120,10 +125,9 @@ export interface StorageConfig {
  * that satisfies this contract.
  *
  * {@link Storage.writeMessages} returns the {@link StorageWriteMessagesError}
- * that made it store none of a batch. Implementations return expected write
- * rejections without reporting them; the caller owns reporting. The client
- * protocol forwards these errors unchanged, while the relay protocol maps them
- * to wire error codes.
+ * that made it store none of a batch. Implementations return it without
+ * reporting it; the caller owns reporting. The client protocol forwards these
+ * errors unchanged, while the relay protocol maps them to wire error codes.
  *
  * The Storage API is synchronous because SQLite's synchronous API is the
  * fastest way to use SQLite. Synchronous bindings (like better-sqlite3) call
@@ -134,11 +138,20 @@ export interface StorageConfig {
  * for async validation logic before writing to storage. The write operation
  * itself remains synchronous.
  *
+ * Indexes count an owner's timestamps in order from 0, and none may exceed the
+ * owner's size from {@link Storage.getSize}. Sync reads the size once per
+ * message and derives every index from it.
+ *
  * @group Core
  */
 export interface Storage {
+  /** Returns the number of the owner's timestamps. */
   readonly getSize: (ownerId: OwnerIdBytes) => NonNegativeInt;
 
+  /**
+   * Returns the {@link Fingerprint} of the owner's timestamps from index `begin`
+   * up to, but not including, `end`, where `begin` is at most `end`.
+   */
   readonly fingerprint: (
     ownerId: OwnerIdBytes,
     begin: NonNegativeInt,
@@ -148,6 +161,9 @@ export interface Storage {
   /**
    * Computes fingerprints with their upper bounds in one call.
    *
+   * Each bucket is the end index of a range that starts at the previous bucket,
+   * or at 0 for the first, so the buckets must be ascending.
+   *
    * This function can be replaced with many fingerprint/findLowerBound calls,
    * but implementations can leverage it for batching and more efficient
    * fingerprint computation.
@@ -158,6 +174,16 @@ export interface Storage {
     upperBound?: RangeUpperBound,
   ) => ReadonlyArray<FingerprintRange>;
 
+  /**
+   * Returns the index of the owner's first timestamp not below `upperBound`,
+   * counted from the owner's first timestamp, or `end` when there is none or
+   * `upperBound` is {@link InfiniteUpperBound}.
+   *
+   * `begin` must be 0 or the result for an earlier bound not above
+   * `upperBound`, and `end` the owner's size, so the result lies in [`begin`,
+   * `end`]. When `end` is 0 or equals `begin`, the result is `end`. Sync meets
+   * this because the protocol rejects range upper bounds that decrease.
+   */
   readonly findLowerBound: (
     ownerId: OwnerIdBytes,
     begin: NonNegativeInt,
@@ -165,6 +191,11 @@ export interface Storage {
     upperBound: RangeUpperBound,
   ) => NonNegativeInt;
 
+  /**
+   * Calls `callback` with the owner's timestamps and their indexes from `begin`
+   * up to, but not including, `end`, where `begin` is at most `end`, until the
+   * callback returns `false`.
+   */
   readonly iterate: (
     ownerId: OwnerIdBytes,
     begin: NonNegativeInt,
@@ -175,19 +206,14 @@ export interface Storage {
   /**
    * Validates the {@link OwnerWriteKey} for the given {@link Owner}.
    *
-   * Returns `true` if the write key is valid, `false` otherwise.
+   * Returns `true` if the write key is valid, `false` otherwise. A relay logs a
+   * throw and answers the request with {@link ProtocolWriteError}.
    */
   readonly validateWriteKey: (
     ownerId: OwnerIdBytes,
     writeKey: OwnerWriteKey,
   ) => boolean;
 
-  /** Sets the {@link OwnerWriteKey} for the given {@link Owner}. */
-  readonly setWriteKey: (
-    ownerId: OwnerIdBytes,
-    writeKey: OwnerWriteKey,
-  ) => void;
-
   /**
    * Write encrypted {@link CrdtMessage}s to storage.
    *
@@ -205,7 +231,12 @@ export interface Storage {
     messages: NonEmptyReadonlyArray<EncryptedCrdtMessage>,
   ) => Task<void, StorageWriteMessagesError>;
 
-  /** Read encrypted {@link DbChange}s from storage. */
+  /**
+   * Read encrypted {@link DbChange}s from storage.
+   *
+   * The returned array must not be modified or reused later, because sync
+   * references it until it finishes its answer.
+   */
   readonly readDbChange: (
     ownerId: OwnerIdBytes,
     timestamp: TimestampBytes,
@@ -233,7 +264,7 @@ export interface StorageQuotaError
   extends OwnerError, Typed<"StorageQuotaError"> {}
 
 /**
- * Expected reasons why {@link Storage.writeMessages} stored none of a batch.
+ * Reasons why {@link Storage.writeMessages} stored none of a batch.
  *
  * The built-in relay storage stores opaque encrypted messages and rejects
  * batches over quota. The built-in client storage decrypts and validates
@@ -243,16 +274,39 @@ export interface StorageQuotaError
  * never a reason to reject a batch. The contract permits quota checks on either
  * side.
  *
+ * Both built-in storages return {@link UnknownError} when SQLite fails the
+ * write, for example on a full disk, after rolling it back.
+ *
  * @group Core
  */
-export type StorageWriteMessagesError = StorageQuotaError;
+export type StorageWriteMessagesError = StorageQuotaError | UnknownError;
 
 /**
- * A cryptographic hash used for efficiently comparing collections of
- * {@link TimestampBytes}es.
- *
- * It consists of the first {@link fingerprintSize} bytes of the SHA-256 hash of
- * one or more timestamps.
+ * A summary of a range of {@link TimestampBytes} for comparing ranges cheaply.
+ *
+ * It is the XOR of the first {@link fingerprintSize} bytes of the SHA-256 hash
+ * of each timestamp in the range, or {@link zeroFingerprint} for an empty
+ * range.
+ *
+ * XOR is linear, so fingerprints are not collision resistant: any 97 timestamps
+ * contain a nonempty subset whose fingerprints XOR to zero. Anyone who can
+ * write to a relay for an owner, which includes every collaborator of a
+ * {@link SharedOwner}, can store timestamps whose fingerprints XOR to the
+ * fingerprint of a chosen change. Two ranges that differ only by that change
+ * and those timestamps then compare equal, so sync skips them, and the change
+ * does not move between that relay and a peer. This was demonstrated end to
+ * end, and nothing reports it. {@link Evolu.requestSync} does not heal it,
+ * because the next round compares the same fingerprints. In protocol version 1,
+ * the only recovery is syncing through a relay that does not hold those
+ * timestamps. Binding the count or hashing the result changes every
+ * fingerprint, so it needs a new protocol version.
+ *
+ * A write-key holder can also store a change under a timestamp another device
+ * has not used yet, such as a later one with that device's NodeId, because
+ * relays accept timestamps from any time. A relay keeps the first change stored
+ * for a timestamp, so it does not store the device's change when it arrives,
+ * and peers that sync through that relay later get the stored one instead. A
+ * new fingerprint does not close this.
  *
  * @group Ranges
  */
@@ -374,6 +428,9 @@ export interface EncryptedCrdtMessage {
 /**
  * Encrypted DbChange
  *
+ * A 24-byte XChaCha20-Poly1305 nonce, the ciphertext length, and the ciphertext
+ * ending with its 16-byte Poly1305 tag, so at least 41 bytes.
+ *
  * @group Messages
  */
 export type EncryptedDbChange = Uint8Array & Brand<"EncryptedDbChange">;
@@ -512,7 +569,7 @@ export interface DbChange extends InferType<typeof DbChange> {}
  */
 export interface BaseSqliteStorage extends Omit<
   Storage,
-  "validateWriteKey" | "setWriteKey" | "writeMessages" | "readDbChange"
+  "validateWriteKey" | "writeMessages" | "readDbChange"
 > {
   /**
    * Inserts a timestamp for an owner into the skiplist-based storage.
@@ -584,6 +641,10 @@ export const createBaseSqliteStorage = (
     // into concatBytes.
     const concatenatedTimestamps = concatByteArrays(timestampsBytes);
 
+    // A batch has no known size, so unlike the CTEs bounded by
+    // skiplistMaxLevel, the planner would make the owner's timestamps the outer
+    // loop. A cross join keeps the order as written, so each timestamp is
+    // looked up by primary key.
     const result = deps.sqlite.exec<{
       timestampBytes: TimestampBytes;
     }>(sql`
@@ -602,7 +663,7 @@ export const createBaseSqliteStorage = (
       select s.timestampBytes
       from
         split_timestamps s
-        join evolu_timestamp t
+        cross join evolu_timestamp t
           on t.ownerId = ${ownerIdBytes} and s.timestampBytes = t.t;
     `);
 
@@ -659,6 +720,9 @@ export const createBaseSqliteStorage = (
     deps.sqlite.exec(sql`
       delete from evolu_timestamp where ownerId = ${ownerId};
     `);
+    deps.sqlite.exec(sql`
+      delete from evolu_usage where ownerId = ${ownerId};
+    `);
   },
 });
 
@@ -1549,6 +1613,8 @@ const fingerprintRanges =
   ): ReadonlyArray<FingerprintRange> => {
     const bucketsJson = JSON.stringify(buckets);
 
+    // A bucket past the owner's timestamps would descend below level 1
+    // forever, so the walk stops there and the bucket has no row.
     const result = deps.sqlite.exec<{
       b: TimestampBytes | null;
       h1: Int64String;
@@ -1618,7 +1684,7 @@ const fingerprintRanges =
             c1
             left join evolu_timestamp as node
               on not c1.b and node.ownerId = ${ownerId} and node.t = c1.nt
-          where iif(c1.b, 1, c1.ic != c1.c)
+          where iif(c1.b, 1, c1.ic != c1.c) and c1.dl >= 1
         ),
         c2(h1, h2, t, rn) as (
           select
@@ -1650,6 +1716,7 @@ const fingerprintRanges =
       select b, cast(h1 as text) as h1, cast(h2 as text) as h2
       from c3;
     `);
+    assert(result.rows.length === buckets.length, "bucket out of range");
 
     const fingerprintRanges = result.rows.map(
       (row, i, arr): FingerprintRange => ({
@@ -1671,11 +1738,15 @@ const x = (a: string, b: string) => sql.raw(`(${a} | ${b}) - (${a} & ${b})`);
 /**
  * Reads the timestamp at a position within an owner's ordered timestamps.
  *
+ * Throws when `index` is not below the owner's size.
+ *
  * @group SQLite
  */
 export const getTimestampByIndex =
   (deps: SqliteDep) =>
   (ownerId: OwnerIdBytes, index: NonNegativeInt): TimestampBytes => {
+    // An index past the owner's timestamps would descend below level 1
+    // forever, so the walk stops there and finds no row.
     const result = deps.sqlite.exec<{
       readonly pt: TimestampBytes;
     }>(sql.prepared`
@@ -1743,14 +1814,16 @@ export const getTimestampByIndex =
               )
             )
           from fi
-          where ic != ${index + 1}
+          where ic != ${index + 1} and cl >= 1
         )
       select pt
       from fi
       where ic == ${index + 1};
     `);
 
-    return result.rows[0].pt;
+    const row = result.rows.at(0);
+    assert(row, "index out of range");
+    return row.pt;
   };
 
 /**