@evolu/common 8.0.0-next.0 → 8.0.0-next.2

package/src/WebSocket.ts

@@ -4,6 +4,7 @@
  * @module
  */
 
+import { assert } from "./Assert.js";
 import { lazyTrue } from "./Function.js";
 import type { Result } from "./Result.js";
 import { err, ok } from "./Result.js";
@@ -12,8 +13,7 @@ import { exponential, jitter, maxDelay } from "./Schedule.js";
 import type { RetryError, Task } from "./Task.js";
 import { callback, retry } from "./Task.js";
 import type { Millis } from "./Time.js";
-import { String, type Typed } from "./Type.js";
-import { assert } from "./Assert.js";
+import { ArrayBuffer, String, Uint8Array, type Typed } from "./Type.js";
 
 /**
  * WebSocket with auto-reconnect.
@@ -27,7 +27,9 @@ import { assert } from "./Assert.js";
  *
  * Created via {@link createWebSocket} which returns a {@link Task}.
  *
- * Disposing the WebSocket closes the connection.
+ * Disposing starts closing the connection without waiting for the close event
+ * so disposal stays immediate. This wrapper treats disposal as local teardown,
+ * not as waiting for the full WebSocket close handshake to finish.
  *
  * ## How Binary Messages Work
  *
@@ -69,7 +71,7 @@ export interface WebSocket extends AsyncDisposable {
    * error if the data couldn't be sent.
    */
   send: (
-    data: string | ArrayBufferLike | Blob | ArrayBufferView,
+    data: BufferSource | Blob | string | globalThis.Uint8Array,
   ) => Result<void, WebSocketSendError>;
 
   readonly getReadyState: () => WebSocketReadyState;
@@ -201,7 +203,6 @@ export const createWebSocket: CreateWebSocket =
     await using stack = new AsyncDisposableStack();
 
     let socket: globalThis.WebSocket | null = null;
-    let disposed = false;
 
     const closeSocket = () => {
       if (!socket) return;
@@ -284,36 +285,54 @@ export const createWebSocket: CreateWebSocket =
         if (!socket || socket.readyState === socket.CONNECTING) {
           return err({ type: "WebSocketSendError" });
         }
-        socket.send(data);
+        socket.send(ensureSendableData(data));
         return ok();
       },
 
       getReadyState: () => {
-        if (disposed) return "closed";
+        if (moved.disposed) return "closed";
         return socket ? nativeToStringState[socket.readyState] : "connecting";
       },
 
       isOpen: () =>
-        !disposed && socket?.readyState === globalThis.WebSocket.OPEN,
+        !moved.disposed && socket?.readyState === globalThis.WebSocket.OPEN,
 
-      [Symbol.asyncDispose]: async () => {
-        disposed = true;
-        await moved.disposeAsync();
-      },
+      [Symbol.asyncDispose]: () => moved.disposeAsync(),
     });
   };
 
-/** Creates a deterministic in-memory {@link CreateWebSocket} for testing. */
+/** Clones SharedArrayBuffer-backed Uint8Array values before WebSocket.send. */
+const ensureSendableData = (
+  data: BufferSource | Blob | string | globalThis.Uint8Array,
+): BufferSource | Blob | string => {
+  if (!Uint8Array.is(data)) return data;
+  return ArrayBuffer.is(data.buffer)
+    ? (data as globalThis.Uint8Array<ArrayBuffer>)
+    : new globalThis.Uint8Array(data);
+};
+
+const nativeToStringState: Record<number, WebSocketReadyState> = {
+  [globalThis.WebSocket.CONNECTING]: "connecting",
+  [globalThis.WebSocket.OPEN]: "open",
+  [globalThis.WebSocket.CLOSING]: "closing",
+  [globalThis.WebSocket.CLOSED]: "closed",
+};
+
+/**
+ * An inspectable in-memory {@link CreateWebSocket} for testing by
+ * {@link testCreateWebSocket}.
+ */
 export interface TestCreateWebSocket extends CreateWebSocket {
   readonly createdUrls: Array<string>;
   readonly sentMessages: Array<{
     readonly url: string;
-    readonly data: string | ArrayBufferLike | Blob | ArrayBufferView;
+    readonly data: BufferSource | Blob | string | globalThis.Uint8Array;
   }>;
   readonly message: (url: string, data: string | ArrayBuffer | Blob) => void;
   readonly open: (url: string) => void;
 }
 
+/** Creates {@link TestCreateWebSocket}. */
 export const testCreateWebSocket = (
   options: {
     /** Throw immediately when a socket is created. */
@@ -326,7 +345,7 @@ export const testCreateWebSocket = (
   const createdUrls: Array<string> = [];
   const sentMessages: Array<{
     readonly url: string;
-    readonly data: string | ArrayBufferLike | Blob | ArrayBufferView;
+    readonly data: BufferSource | Blob | string | globalThis.Uint8Array;
   }> = [];
   const stateByUrl = new Map<
     string,
@@ -361,7 +380,10 @@ export const testCreateWebSocket = (
         if (state.isDisposed || !state.isOpen) {
           return err({ type: "WebSocketSendError" });
         }
-        sentMessages.push({ url, data });
+        sentMessages.push({
+          url,
+          data: ensureSendableData(data),
+        });
         return ok();
       },
 
@@ -399,9 +421,91 @@ export const testCreateWebSocket = (
   });
 };
 
-const nativeToStringState: Record<number, WebSocketReadyState> = {
-  [globalThis.WebSocket.CONNECTING]: "connecting",
-  [globalThis.WebSocket.OPEN]: "open",
-  [globalThis.WebSocket.CLOSING]: "closing",
-  [globalThis.WebSocket.CLOSED]: "closed",
+/**
+ * A native {@link WebSocket} prepared for integration tests by
+ * {@link testSetupWebSocket}.
+ */
+export interface TestSetupWebSocket extends AsyncDisposable {
+  readonly socket: globalThis.WebSocket;
+  readonly send: (
+    data: BufferSource | Blob | string | globalThis.Uint8Array,
+  ) => void;
+  readonly waitForMessage: () => Promise<string | globalThis.Uint8Array>;
+}
+
+/** Opens a native {@link WebSocket} and returns {@link TestSetupWebSocket}. */
+export const testSetupWebSocket = async (
+  url: string,
+): Promise<TestSetupWebSocket> => {
+  const socket = new globalThis.WebSocket(url);
+  socket.binaryType = "arraybuffer";
+
+  await new Promise<void>((resolve, reject) => {
+    const onOpen = () => {
+      cleanup();
+      resolve();
+    };
+
+    const onError = () => {
+      cleanup();
+      socket.close();
+      reject(new Error("WebSocket connection failed"));
+    };
+
+    const cleanup = () => {
+      socket.removeEventListener("open", onOpen);
+      socket.removeEventListener("error", onError);
+    };
+
+    socket.addEventListener("open", onOpen, { once: true });
+    socket.addEventListener("error", onError, { once: true });
+  });
+
+  return {
+    socket,
+    send: (data) => {
+      socket.send(ensureSendableData(data));
+    },
+    waitForMessage: () =>
+      new Promise((resolve, reject) => {
+        if (socket.readyState === globalThis.WebSocket.CLOSED) {
+          reject(new Error("WebSocket closed before message"));
+          return;
+        }
+
+        const onMessage = (event: MessageEvent) => {
+          cleanup();
+
+          if (typeof event.data === "string") {
+            resolve(event.data);
+            return;
+          }
+
+          resolve(new globalThis.Uint8Array(event.data as ArrayBuffer));
+        };
+
+        const onClose = () => {
+          cleanup();
+          reject(new Error("WebSocket closed before message"));
+        };
+
+        const cleanup = () => {
+          socket.removeEventListener("message", onMessage);
+          socket.removeEventListener("close", onClose);
+        };
+
+        socket.addEventListener("message", onMessage, { once: true });
+        socket.addEventListener("close", onClose, { once: true });
+      }),
+    [Symbol.asyncDispose]: async () => {
+      if (socket.readyState === globalThis.WebSocket.CLOSED) return;
+
+      const closed = new Promise<void>((resolve) => {
+        socket.addEventListener("close", () => resolve(), { once: true });
+      });
+
+      socket.close();
+      await closed;
+    },
+  };
 };

package/src/local-first/Db.ts

@@ -10,7 +10,7 @@ import {
   type NonEmptyArray,
   type NonEmptyReadonlyArray,
 } from "../Array.js";
-import { assert, assertNonEmptyReadonlyArray } from "../Assert.js";
+import { assert, assertNonEmptyReadonlyArray, assertType } from "../Assert.js";
 import type { ConsoleLevel } from "../Console.js";
 import {
   EncryptionKey,
@@ -77,8 +77,8 @@ import {
   createBaseSqliteStorage,
   createBaseSqliteStorageTables,
   DbChange,
-  getOwnerUsage,
   getTimestampInsertStrategy,
+  readOwnerUsageOrDefault,
   updateOwnerUsage,
   type BaseSqliteStorage,
   type BaseSqliteStorageDep,
@@ -120,10 +120,7 @@ export interface CreateDbWorkerDep {
   readonly createDbWorker: CreateDbWorker;
 }
 
-export type DbWorkerDeps = WorkerDeps &
-  LeaderLockDep &
-  CreateSqliteDriverDep &
-  RandomBytesDep;
+export type DbWorkerDeps = WorkerDeps & LeaderLockDep & CreateSqliteDriverDep;
 
 export const startDbWorker =
   (self: WorkerSelf<DbWorkerInit>): Task<void, never, DbWorkerDeps> =>
@@ -207,10 +204,14 @@ export const startDbWorker =
     const runWithStorage = run.addDeps({ storage });
 
     /**
-     * SharedWorker repeats sends until it gets a response, so handling here
-     * must be idempotent and ignore already processed IDs.
+     * SharedWorker retries until some leader replies, so this worker must
+     * ignore callback IDs it already completed.
      *
-     * TODO: Bound memory growth by evicting old IDs.
+     * The Set intentionally lives for one leader's lifetime. If that leader tab
+     * closes, retries go to a new leader with a fresh Set. Revisit this only if
+     * memory pressure shows up; even millions of short callback IDs are
+     * acceptable here, and naive eviction could let a still-retried request run
+     * again.
      */
     const processedRequestIds = new Set<Id>();
 
@@ -285,15 +286,12 @@ export const startDbWorker =
               >();
 
               for (const owner of request.message.owners) {
-                storage.setOwnerState(owner.encryptionKey);
+                storage.setRequestContext(owner.encryptionKey);
                 const protocolMessage = createProtocolMessageForSync({
                   storage,
                   console,
                 })(owner.id, SubscriptionFlags.Subscribe);
-
-                if (protocolMessage) {
-                  protocolMessagesByOwnerId.set(owner.id, protocolMessage);
-                }
+                protocolMessagesByOwnerId.set(owner.id, protocolMessage);
               }
 
               postQueuedResponse({
@@ -310,7 +308,7 @@ export const startDbWorker =
               const { owner, inputMessage } = request.message;
 
               runWithStorage<void, never>(async (run) => {
-                storage.setOwnerState(owner.encryptionKey);
+                storage.setRequestContext(owner.encryptionKey);
 
                 const result = await run(
                   applyProtocolMessageAsClient(inputMessage, {
@@ -611,7 +609,7 @@ const applyColumnChange =
  * implementation, and switch owner encryption keys between requests.
  */
 interface ClientStorage extends Storage, BaseSqliteStorage {
-  readonly setOwnerState: (encryptionKey: EncryptionKey) => void;
+  readonly setRequestContext: (encryptionKey: EncryptionKey) => void;
   readonly didWriteMessages: () => boolean;
 }
 
@@ -653,7 +651,7 @@ const createClientStorage =
       // same file.
       // This is safe because the worker handles one message at a time. We will
       // refactor it later, we will probably have to change Protocol API.
-      setOwnerState: (nextEncryptionKey) => {
+      setRequestContext: (nextEncryptionKey) => {
         encryptionKey = nextEncryptionKey;
         didWriteMessages = false;
       },
@@ -743,9 +741,8 @@ const createClientStorage =
               isInsert = false;
               break;
             case "isDeleted":
-              if (SqliteBoolean.is(r.value)) {
-                isDelete = sqliteBooleanToBoolean(r.value);
-              }
+              assertType(SqliteBoolean, r.value);
+              isDelete = sqliteBooleanToBoolean(r.value);
               break;
             default:
               values[r.column] = r.value;
@@ -843,7 +840,7 @@ const applyLocalOnlyChange =
     if (change.isDelete) {
       deps.sqlite.exec(sql`
         delete from ${sql.identifier(change.table)}
-        where id = ${change.id};
+        where "ownerId" = ${change.ownerId} and "id" = ${change.id};
       `);
     } else {
       const ownerId = change.ownerId;
@@ -866,13 +863,12 @@ const applyMessages =
   (ownerId: OwnerId, messages: NonEmptyReadonlyArray<CrdtMessage>): void => {
     const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
 
-    const usage = getOwnerUsage(deps)(
+    const usage = readOwnerUsageOrDefault(deps)(
       ownerIdBytes,
       timestampToTimestampBytes(firstInArray(messages).timestamp),
     );
-    if (!usage.ok) return;
 
-    let { firstTimestamp, lastTimestamp } = usage.value;
+    let { firstTimestamp, lastTimestamp } = usage;
 
     for (const { timestamp, change } of messages) {
       const columns = dbChangeToColumns(change, timestamp.millis);

package/src/local-first/Protocol.ts

@@ -181,7 +181,6 @@ import { Packr } from "msgpackr";
 import { isNonEmptyArray, type NonEmptyReadonlyArray } from "../Array.js";
 import { assert } from "../Assert.js";
 import type { Brand } from "../Brand.js";
-import type { ConsoleDep } from "../Console.js";
 import {
   type Buffer,
   bytesToHex,
@@ -190,6 +189,7 @@ import {
   hexToBytes,
   utf8ToBytes,
 } from "../Buffer.js";
+import type { ConsoleDep } from "../Console.js";
 import {
   createPadmePadding,
   decryptWithXChaCha20Poly1305,
@@ -548,10 +548,7 @@ export const createProtocolMessageFromCrdtMessages =
 /** Creates a {@link ProtocolMessage} for sync. */
 export const createProtocolMessageForSync =
   (deps: StorageDep & ConsoleDep) =>
-  (
-    ownerId: OwnerId,
-    subscriptionFlag?: SubscriptionFlag,
-  ): ProtocolMessage | null => {
+  (ownerId: OwnerId, subscriptionFlag?: SubscriptionFlag): ProtocolMessage => {
     const buffer = createProtocolMessageBuffer(ownerId, {
       messageType: MessageType.Request,
       subscriptionFlag: subscriptionFlag ?? SubscriptionFlags.None,

package/src/local-first/Relay.ts

@@ -5,6 +5,7 @@
  */
 
 import {
+  dedupeArray,
   filterArray,
   firstInArray,
   isNonEmptyArray,
@@ -12,11 +13,11 @@ import {
 } from "../Array.js";
 import { assert } from "../Assert.js";
 import type { TimingSafeEqualDep } from "../Crypto.js";
-import { err, getOk, ok } from "../Result.js";
+import { err, ok } from "../Result.js";
 import type { SqliteDep } from "../Sqlite.js";
 import { sql } from "../Sqlite.js";
 import { createMutexByKey } from "../Task.js";
-import { Name, PositiveInt } from "../Type.js";
+import { Name, PositiveInt, uint8ArrayToBase64Url } from "../Type.js";
 import { isPromiseLike, type Awaitable } from "../Types.js";
 import {
   OwnerId,
@@ -33,8 +34,8 @@ import type {
 } from "./Storage.js";
 import {
   createBaseSqliteStorage,
-  getOwnerUsage,
   getTimestampInsertStrategy,
+  readOwnerUsageOrDefault,
   updateOwnerUsage,
 } from "./Storage.js";
 import { timestampToTimestampBytes } from "./Timestamp.js";
@@ -52,8 +53,9 @@ export interface RelayConfig extends StorageConfig {
    * Optional callback to check if an {@link OwnerId} is allowed to access the
    * relay. If this callback is not provided, all owners are allowed.
    *
-   * The callback receives the {@link OwnerId} and returns a {@link Awaitable}
-   * boolean: `true` to allow access, or `false` to deny.
+   * The callback receives the {@link OwnerId} and an options object with an
+   * abort `AbortSignal`, and returns a {@link Awaitable} boolean: `true` to
+   * allow access, or `false` to deny.
    *
    * The callback can be synchronous (for SQLite or in-memory checks) or
    * asynchronous (for calling remote APIs).
@@ -68,9 +70,9 @@ export interface RelayConfig extends StorageConfig {
    *
    * Owners specify which relays to connect to via `OwnerTransport`. In
    * WebSocket-based implementations, this check occurs before accepting the
-   * connection, with the OwnerId typically extracted from the URL Path (e.g.,
-   * `ws://localhost:4000/<ownerId>`). The relay requires the URL to be in the
-   * correct format for OwnerId extraction.
+   * connection, with the OwnerId typically extracted from the URL query string
+   * (e.g., `ws://localhost:4000?ownerId=...`). The relay requires the URL to be
+   * in the correct format for OwnerId extraction.
    *
    * ### Example
    *
@@ -87,23 +89,31 @@ export interface RelayConfig extends StorageConfig {
    *
    *
    * // Relay
-   * isOwnerAllowed: (ownerId) =>
+   * isOwnerAllowed: (ownerId, { signal: _signal }) =>
    *   Promise.resolve(ownerId === "6jy_2F4RT5qqeLgJ14_dnQ"),
    * ```
    */
-  readonly isOwnerAllowed?: (ownerId: OwnerId) => Awaitable<boolean>;
+  readonly isOwnerAllowed?: (
+    ownerId: OwnerId,
+    options: {
+      /** Aborted when the relay stops waiting for the access check. */
+      readonly signal: AbortSignal;
+    },
+  ) => Awaitable<boolean>;
 }
 
 /**
- * A completely interchangeable server for syncing and backing up encrypted data
- * between Evolu clients.
+ * Sync and backup relay for Evolu clients.
  *
- * Unlike traditional servers, relays are blind by design—they transmit
- * encrypted data without understanding its shape or meaning. This enables true
- * decentralization and infinite horizontal scalability with minimal
- * infrastructure.
+ * A relay syncs and backs up encrypted data for Evolu apps. Evolu apps can use
+ * multiple relays at the same time, combining self-hosted and cloud relays for
+ * resilience. Relays are blind by design: they transmit and store encrypted
+ * data without understanding its shape or meaning.
  */
-export interface Relay extends AsyncDisposable {}
+export interface Relay extends AsyncDisposable {
+  /** The TCP port actually bound by the relay. */
+  readonly port: number;
+}
 
 export const createRelaySqliteStorage =
   (deps: SqliteStorageDeps & TimingSafeEqualDep) =>
@@ -158,25 +168,31 @@ export const createRelaySqliteStorage =
 
       writeMessages: (ownerIdBytes, messages) => async (run) => {
         const ownerId = ownerIdBytesToOwnerId(ownerIdBytes);
-        const messagesWithTimestampBytes = mapArray(messages, (m) => ({
-          timestamp: timestampToTimestampBytes(m.timestamp),
-          change: m.change,
-        }));
+        const uniqueMessagesWithTimestampBytes = dedupeArray(
+          mapArray(messages, (m) => ({
+            timestamp: timestampToTimestampBytes(m.timestamp),
+            change: m.change,
+          })),
+          (message) => uint8ArrayToBase64Url(message.timestamp),
+        );
 
-        const result = await run(
+        return run(
           mutexByOwnerId.withLock(ownerId, async () => {
             const existingTimestampsResult =
               sqliteStorageBase.getExistingTimestamps(
                 ownerIdBytes,
-                mapArray(messagesWithTimestampBytes, (m) => m.timestamp),
+                mapArray(uniqueMessagesWithTimestampBytes, (m) => m.timestamp),
               );
 
-            const existingTimestampsSet = new Set(
-              existingTimestampsResult.map((t) => t.toString()),
+            const existingTimestampKeys = new Set(
+              mapArray(existingTimestampsResult, uint8ArrayToBase64Url),
             );
             const newMessages = filterArray(
-              messagesWithTimestampBytes,
-              (m) => !existingTimestampsSet.has(m.timestamp.toString()),
+              uniqueMessagesWithTimestampBytes,
+              (message) =>
+                !existingTimestampKeys.has(
+                  uint8ArrayToBase64Url(message.timestamp),
+                ),
             );
 
             // Nothing to write
@@ -184,11 +200,9 @@ export const createRelaySqliteStorage =
               return ok();
             }
 
-            const usage = getOk(
-              getOwnerUsage(deps)(
-                ownerIdBytes,
-                firstInArray(newMessages).timestamp,
-              ),
+            const usage = readOwnerUsageOrDefault(deps)(
+              ownerIdBytes,
+              firstInArray(newMessages).timestamp,
             );
 
             const incomingBytes = newMessages.reduce(
@@ -250,13 +264,6 @@ export const createRelaySqliteStorage =
             });
           }),
         );
-
-        if (!result.ok) {
-          if (result.error.type === "AbortError") return ok();
-          return result;
-        }
-
-        return ok();
       },
 
       readDbChange: (ownerId, timestamp) => {

package/src/local-first/Shared.ts

@@ -324,7 +324,7 @@ interface SharedEvolu extends AsyncDisposable {
 
   readonly requestApplySyncMessage: (
     ownerId: OwnerId,
-    inputMessage: Uint8Array<ArrayBuffer>,
+    inputMessage: Uint8Array,
   ) => void;
 }
 
@@ -364,7 +364,7 @@ export interface DbWorkerInput {
           | {
               readonly type: "ApplySyncMessage";
               readonly owner: Owner;
-              readonly inputMessage: Uint8Array<ArrayBuffer>;
+              readonly inputMessage: Uint8Array;
             };
       };
 }

package/src/local-first/Storage.ts

@@ -12,7 +12,6 @@ import type { Brand } from "../Brand.js";
 import { concatBytes } from "../Buffer.js";
 import { decrement } from "../Number.js";
 import type { RandomDep } from "../Random.js";
-import type { Result } from "../Result.js";
 import { err, ok } from "../Result.js";
 import type { SqliteDep } from "../Sqlite.js";
 import { sql, SqliteValue } from "../Sqlite.js";
@@ -1569,17 +1568,17 @@ export const getTimestampByIndex =
     return result.rows[0].pt;
   };
 
-/** Retrieves usage information for an owner from the evolu_usage table. */
-export const getOwnerUsage =
+/** Reads owner usage from SQLite and returns default bounds when absent. */
+export const readOwnerUsageOrDefault =
   (deps: SqliteDep) =>
   (
     ownerIdBytes: OwnerIdBytes,
     initialTimestamp: TimestampBytes,
-  ): Result<{
-    storedBytes: NonNegativeInt | null;
-    firstTimestamp: TimestampBytes;
-    lastTimestamp: TimestampBytes;
-  }> => {
+  ): {
+    readonly storedBytes: NonNegativeInt | null;
+    readonly firstTimestamp: TimestampBytes;
+    readonly lastTimestamp: TimestampBytes;
+  } => {
     const result = deps.sqlite.exec<{
       storedBytes: NonNegativeInt;
       firstTimestamp: TimestampBytes | null;
@@ -1591,22 +1590,22 @@ export const getOwnerUsage =
     `);
 
     if (!isNonEmptyArray(result.rows)) {
-      return ok({
+      return {
         storedBytes: null,
         firstTimestamp: initialTimestamp,
         lastTimestamp: initialTimestamp,
-      });
+      };
     }
 
     const row = firstInArray(result.rows);
     assert(row.firstTimestamp, "not null");
     assert(row.lastTimestamp, "not null");
 
-    return ok({
+    return {
       storedBytes: row.storedBytes,
       firstTimestamp: row.firstTimestamp,
       lastTimestamp: row.lastTimestamp,
-    });
+    };
   };
 
 /**