@evolu/common 8.17.0 → 8.18.0

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

@@ -5,6 +5,7 @@
  */
 import type { NonEmptyReadonlyArray } from "../Array.ts";
 import type { Brand } from "../Brand.ts";
+import type { UnknownError } from "../Error.ts";
 import type { RandomDep } from "../Random.ts";
 import type { SqliteDep } from "../Sqlite.ts";
 import type { Task } from "../Task.ts";
@@ -32,7 +33,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
@@ -81,10 +85,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
@@ -95,29 +98,55 @@ 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, end: NonNegativeInt) => Fingerprint;
     /**
      * 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.
      */
     readonly fingerprintRanges: (ownerId: OwnerIdBytes, buckets: ReadonlyArray<NonNegativeInt>, 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, end: NonNegativeInt, 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, end: NonNegativeInt, callback: (timestamp: TimestampBytes, index: NonNegativeInt) => boolean) => void;
     /**
      * 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.
      *
@@ -131,7 +160,12 @@ export interface Storage {
      * protocol logic handling during sync operations.
      */
     readonly writeMessages: (ownerIdBytes: OwnerIdBytes, 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) => EncryptedDbChange;
     /** Delete all data for the given {@link Owner}. */
     readonly deleteOwner: (ownerId: OwnerIdBytes) => void;
@@ -152,7 +186,7 @@ export interface StorageDep {
 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
@@ -162,15 +196,38 @@ export interface StorageQuotaError extends OwnerError, Typed<"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;
-/**
- * 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.
+export type StorageWriteMessagesError = StorageQuotaError | UnknownError;
+/**
+ * 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
  */
@@ -275,6 +332,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">;
@@ -367,7 +427,7 @@ export interface DbChange extends InferType<typeof DbChange> {
  *
  * @group SQLite
  */
-export interface BaseSqliteStorage extends Omit<Storage, "validateWriteKey" | "setWriteKey" | "writeMessages" | "readDbChange"> {
+export interface BaseSqliteStorage extends Omit<Storage, "validateWriteKey" | "writeMessages" | "readDbChange"> {
     /**
      * Inserts a timestamp for an owner into the skiplist-based storage.
      *
@@ -448,6 +508,8 @@ export declare const testFingerprintTimestamps: (timestamps: ReadonlyArray<Times
 /**
  * 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 declare const getTimestampByIndex: (deps: SqliteDep) => (ownerId: OwnerIdBytes, index: NonNegativeInt) => TimestampBytes;

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

@@ -1 +1 @@
-{"version":3,"file":"Storage.d.ts","sourceRoot":"","sources":["../../../src/local-first/Storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Storage.d.ts","sourceRoot":"","sources":["../../../src/local-first/Storage.ts"],"names":[],"mappings":"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"}

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

@@ -119,6 +119,10 @@ export const createBaseSqliteStorage = (deps) => ({
         // A batch can hold hundreds of thousands of timestamps, too many to spread
         // 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(sql `
       with recursive
         split_timestamps(timestampBytes, pos) as (
@@ -135,7 +139,7 @@ export const createBaseSqliteStorage = (deps) => ({
       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;
     `);
         return result.rows.map((row) => row.timestampBytes);
@@ -183,6 +187,9 @@ export const createBaseSqliteStorage = (deps) => ({
     deleteOwner: (ownerId) => {
         deps.sqlite.exec(sql `
       delete from evolu_timestamp where ownerId = ${ownerId};
+    `);
+        deps.sqlite.exec(sql `
+      delete from evolu_usage where ownerId = ${ownerId};
     `);
     },
 });
@@ -956,6 +963,8 @@ const fingerprint = (deps) => (ownerId, begin, end) => {
  */
 const fingerprintRanges = (deps) => (ownerId, buckets, upperBound = InfiniteUpperBound) => {
     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(sql.prepared `
       with
         ml(ml) as (
@@ -1021,7 +1030,7 @@ const fingerprintRanges = (deps) => (ownerId, buckets, upperBound = InfiniteUppe
             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
@@ -1053,6 +1062,7 @@ const fingerprintRanges = (deps) => (ownerId, buckets, upperBound = InfiniteUppe
       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) => ({
         type: RangeType.Fingerprint,
         upperBound: i === arr.length - 1 ? upperBound : row.b,
@@ -1068,9 +1078,13 @@ const x = (a, b) => 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) => (ownerId, index) => {
+    // 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(sql.prepared `
       with
         fi(b, cl, ic, pt, mt, nt, nc) as (
@@ -1136,13 +1150,15 @@ export const getTimestampByIndex = (deps) => (ownerId, index) => {
               )
             )
           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;
 };
 /**
  * Reads owner usage from SQLite and returns default bounds when absent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/common",
-  "version": "8.17.0",
+  "version": "8.18.0",
   "description": "TypeScript library and local-first platform",
   "keywords": [
     "evolu",

package/src/Bytes.test.ts

@@ -1,10 +1,15 @@
+import * as fc from "fast-check";
 import { describe, it, mock } from "node:test";
+import { setFlagsFromString } from "node:v8";
+import { runInNewContext } from "node:vm";
 import {
+  assert,
   assertEqual,
   assertEqualBytes,
   assertErr,
   assertFalse,
   assertInstanceOf,
+  assertNonNullable,
   assertOk,
   assertSame,
   assertThrowsInstanceOf,
@@ -95,6 +100,23 @@ describe("BufferError", () => {
     assertEqual(error.name, "BufferError");
     assertEqual(error.message, "test error");
   });
+
+  it("constructs without Error.captureStackTrace", () => {
+    const descriptor = globalThis.Object.getOwnPropertyDescriptor(
+      Error,
+      "captureStackTrace",
+    );
+    assertNonNullable(descriptor);
+    Reflect.deleteProperty(Error, "captureStackTrace");
+    try {
+      const error = new BufferError("x");
+      assertInstanceOf(error, BufferError);
+      assertEqual(error.message, "x");
+      assertThrowsInstanceOf(() => decodeJson([0xc1]), BufferError);
+    } finally {
+      globalThis.Object.defineProperty(Error, "captureStackTrace", descriptor);
+    }
+  });
 });
 
 describe("concatByteArrays", () => {
@@ -279,6 +301,16 @@ describe("Buffer", () => {
     assertEqual(buffer.getLength(), 2);
     assertEqualBytes(buffer.unwrap(), [6, 7]);
   });
+
+  it("has readonly members", () => {
+    const buffer = createBuffer();
+    const { shift } = buffer;
+
+    // @ts-expect-error Cannot assign to 'shift' because it is a read-only property.
+    buffer.shift = shift;
+
+    assertSame(buffer.shift, shift);
+  });
 });
 
 describe("number encoding", () => {
@@ -482,6 +514,31 @@ describe("string encoding", () => {
     );
     assertEqual(decodeString(buffer), value);
   });
+
+  // Unlike the JSON codec, the string codec keeps the wire valid UTF-8, because
+  // deployed decoders read WTF-8 as three U+FFFD per lone surrogate.
+  it("replaces a lone surrogate with U+FFFD", () => {
+    const buffer = createBuffer();
+    encodeString(buffer, "a\uD800b");
+
+    assertEqualBytes(buffer.unwrap(), [5, 97, 0xef, 0xbf, 0xbd, 98]);
+    assertSame(decodeString(buffer), "a�b");
+  });
+
+  it("decodes invalid UTF-8 as U+FFFD", () => {
+    assertSame(
+      decodeString(createBuffer([5, 97, 0xed, 0xa0, 0x80, 98])),
+      "a���b",
+    );
+  });
+
+  it("keeps a byte order mark", () => {
+    for (const value of ["\uFEFFabc", "\uFEFF", "a\uFEFFb"]) {
+      const buffer = createBuffer();
+      encodeString(buffer, value);
+      assertSame(decodeString(buffer), value);
+    }
+  });
 });
 
 describe("run-length encoding", () => {
@@ -574,6 +631,140 @@ describe("run-length encoding", () => {
   });
 });
 
+describe("run-length encoder checkpoint", () => {
+  const setupEncoder = (values: ReadonlyArray<number> = []) => {
+    const encoder =
+      createRunLengthEncoder<NonNegativeInt>(encodeNonNegativeInt);
+    for (const value of values) encoder.add(NonNegativeInt.orThrow(value));
+    return encoder;
+  };
+
+  const decodeEncoder = (
+    encoder: ReturnType<typeof setupEncoder>,
+    length: number,
+  ) => {
+    const buffer = createBuffer(encoder.unwrap());
+    const values = decodeRle(buffer, NonNegativeInt.orThrow(length), () =>
+      decodeNonNegativeInt(buffer),
+    );
+    assertSame(buffer.getLength(), 0);
+    return values;
+  };
+
+  it("restores a run rewritten in place", () => {
+    const encoder = setupEncoder([7, 5]);
+    const restore = encoder.checkpoint();
+    encoder.add(NonNegativeInt.orThrow(5));
+    encoder.add(NonNegativeInt.orThrow(5));
+    assertEqualBytes(encoder.unwrap(), [7, 1, 5, 3]);
+
+    restore();
+    assertEqualBytes(encoder.unwrap(), [7, 1, 5, 1]);
+
+    encoder.add(NonNegativeInt.orThrow(5));
+    assertEqualBytes(encoder.unwrap(), setupEncoder([7, 5, 5]).unwrap());
+    assertEqual(decodeEncoder(encoder, 3), [7, 5, 5]);
+  });
+
+  it("restores a run length across the 127/128 varint boundary", () => {
+    const run127 = Array.from({ length: 127 }, () => 5);
+    const encoder = setupEncoder(run127);
+    const restoreAt127 = encoder.checkpoint();
+    encoder.add(NonNegativeInt.orThrow(5));
+    assertEqualBytes(encoder.unwrap(), [5, 128, 1]);
+    const restoreAt128 = encoder.checkpoint();
+    encoder.add(NonNegativeInt.orThrow(5));
+    assertEqualBytes(encoder.unwrap(), [5, 129, 1]);
+
+    restoreAt128();
+    assertEqualBytes(encoder.unwrap(), [5, 128, 1]);
+
+    restoreAt127();
+    assertEqualBytes(encoder.unwrap(), [5, 127]);
+    assertEqual(encoder.getLength(), 2);
+
+    encoder.add(NonNegativeInt.orThrow(6));
+    assertEqualBytes(encoder.unwrap(), [5, 127, 6, 1]);
+    assertEqual(decodeEncoder(encoder, 128), [...run127, 6]);
+  });
+
+  it("restores the previous value after a different value", () => {
+    const encoder = setupEncoder([5]);
+    const restore = encoder.checkpoint();
+    encoder.add(NonNegativeInt.orThrow(7));
+    encoder.add(NonNegativeInt.orThrow(7));
+    assertEqualBytes(encoder.unwrap(), [5, 1, 7, 2]);
+
+    restore();
+    assertEqualBytes(encoder.unwrap(), [5, 1]);
+
+    // Without the previous value, the next 5 would start a new run.
+    encoder.add(NonNegativeInt.orThrow(5));
+    assertEqualBytes(encoder.unwrap(), [5, 2]);
+  });
+
+  it("restores an empty encoder", () => {
+    const encoder = setupEncoder();
+    const restore = encoder.checkpoint();
+    encoder.add(NonNegativeInt.orThrow(5));
+
+    restore();
+    assertEqual(encoder.getLength(), 0);
+    assertEqualBytes(encoder.unwrap(), []);
+
+    encoder.add(NonNegativeInt.orThrow(5));
+    assertEqualBytes(encoder.unwrap(), [5, 1]);
+  });
+
+  it("encodes only the committed values after restores", () => {
+    fc.assert(
+      fc.property(
+        fc.array(
+          fc.oneof(
+            fc.record({
+              value: fc.constantFrom(0, 5, 300),
+              count: fc.integer({ min: 1, max: 200 }),
+            }),
+            fc.constant("checkpoint" as const),
+            fc.constant("restore" as const),
+          ),
+          { maxLength: 30 },
+        ),
+        (operations) => {
+          const encoder = setupEncoder();
+          const committed: Array<number> = [];
+          const checkpoints: Array<{
+            readonly restore: () => void;
+            readonly length: number;
+          }> = [];
+
+          for (const operation of operations) {
+            if (operation === "checkpoint") {
+              checkpoints.push({
+                restore: encoder.checkpoint(),
+                length: committed.length,
+              });
+            } else if (operation === "restore") {
+              const checkpoint = checkpoints.pop();
+              if (!checkpoint) continue;
+              checkpoint.restore();
+              committed.length = checkpoint.length;
+            } else {
+              for (let i = 0; i < operation.count; i++) {
+                encoder.add(NonNegativeInt.orThrow(operation.value));
+                committed.push(operation.value);
+              }
+            }
+          }
+
+          assertEqualBytes(encoder.unwrap(), setupEncoder(committed).unwrap());
+          assertEqual(decodeEncoder(encoder, committed.length), committed);
+        },
+      ),
+    );
+  });
+});
+
 describe("JSON binary codec", () => {
   it("matches fixed msgpackr 2.0.5 fixtures", () => {
     const fixtures: ReadonlyArray<readonly [unknown, ReadonlyArray<number>]> = [
@@ -1164,6 +1355,27 @@ describe("JSON binary codec", () => {
     }
   });
 
+  it("releases an oversized encoder arena", () => {
+    setFlagsFromString("--expose-gc");
+    const gc = runInNewContext("gc") as () => void;
+    gc();
+    gc();
+    const before = process.memoryUsage().arrayBuffers;
+    const buffer = createBuffer();
+
+    // A string reserves 3 bytes per UTF-16 code unit, so this one grows the
+    // module-scope arena to 6 MB.
+    encodeJsonValue(buffer, JsonValue.orThrow("x".repeat(2_000_000)));
+    gc();
+    gc();
+
+    const retained =
+      process.memoryUsage().arrayBuffers - before - buffer.getCapacity();
+    assert(retained < 1_000_000, "Expected the arena to be released.", {
+      actual: retained,
+    });
+  });
+
   it("converts unexpected decoder errors to BufferError", () => {
     const errorBuffer = {
       ...createBuffer([0xc0]),