@evolu/common 7.4.1 → 8.0.0-next.1

package/src/local-first/Relay.ts

@@ -1,53 +1,61 @@
+/**
+ * Relay server for data synchronization.
+ *
+ * @module
+ */
+
 import {
+  dedupeArray,
   filterArray,
   firstInArray,
-  isNonEmptyReadonlyArray,
+  isNonEmptyArray,
   mapArray,
 } from "../Array.js";
-import { ConsoleConfig, ConsoleDep } from "../Console.js";
-import { TimingSafeEqualDep } from "../Crypto.js";
-import { LazyValue } from "../Function.js";
-import { createInstances } from "../Instances.js";
-import { err, ok, Result } from "../Result.js";
-import { sql, SqliteDep, SqliteError } from "../Sqlite.js";
-import { createMutex, isAsync, MaybeAsync, Mutex } from "../Task.js";
-import { PositiveInt, SimpleName } from "../Type.js";
+import { assert } from "../Assert.js";
+import type { TimingSafeEqualDep } from "../Crypto.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, uint8ArrayToBase64Url } from "../Type.js";
+import { isPromiseLike, type Awaitable } from "../Types.js";
 import {
   OwnerId,
   ownerIdBytesToOwnerId,
-  OwnerTransport,
+  // OwnerTransport,
   OwnerWriteKey,
 } from "./Owner.js";
-import { ProtocolInvalidDataError } from "./Protocol.js";
-import {
-  createBaseSqliteStorage,
-  CreateBaseSqliteStorageConfig,
+import type {
   EncryptedDbChange,
-  getOwnerUsage,
-  getTimestampInsertStrategy,
   SqliteStorageDeps,
   Storage,
   StorageConfig,
   StorageQuotaError,
+} from "./Storage.js";
+import {
+  createBaseSqliteStorage,
+  getTimestampInsertStrategy,
+  readOwnerUsageOrDefault,
   updateOwnerUsage,
 } from "./Storage.js";
 import { timestampToTimestampBytes } from "./Timestamp.js";
 
-export interface RelayConfig extends ConsoleConfig, StorageConfig {
+export interface RelayConfig extends StorageConfig {
   /**
    * The relay name.
    *
    * Implementations can use this for identification purposes (e.g., database
    * file name, logging).
    */
-  readonly name?: SimpleName;
+  readonly name?: Name;
 
   /**
    * 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 MaybeAsync}
-   * 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).
@@ -60,11 +68,11 @@ export interface RelayConfig extends ConsoleConfig, StorageConfig {
    * relay access, not write permissions. Since all data is encrypted on the
    * relay, OwnerId exposure is safe.
    *
-   * Owners specify which relays to connect to via {@link OwnerTransport}. In
+   * 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
    *
@@ -81,37 +89,39 @@ export interface RelayConfig extends ConsoleConfig, StorageConfig {
    *
    *
    * // Relay
-   * isOwnerAllowed: (ownerId) =>
+   * isOwnerAllowed: (ownerId, { signal: _signal }) =>
    *   Promise.resolve(ownerId === "6jy_2F4RT5qqeLgJ14_dnQ"),
    * ```
    */
-  readonly isOwnerAllowed?: (ownerId: OwnerId) => MaybeAsync<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 Disposable {}
+export interface Relay extends AsyncDisposable {
+  /** The TCP port actually bound by the relay. */
+  readonly port: number;
+}
 
 export const createRelaySqliteStorage =
   (deps: SqliteStorageDeps & TimingSafeEqualDep) =>
-  (config: CreateBaseSqliteStorageConfig): Storage => {
-    const sqliteStorageBase = createBaseSqliteStorage(deps)(config);
-
-    /**
-     * Mutex instances are cached per OwnerId to prevent concurrent writes for
-     * the same owner. Instances are never evicted, causing a memory leak
-     * proportional to unique owner count. However, per-instance overhead should
-     * be small. Monitor production memory usage to determine if
-     * eviction/cleanup is needed.
-     */
-    const ownerMutexes = createInstances<OwnerId, Mutex>();
+  (config: StorageConfig): Storage => {
+    const sqliteStorageBase = createBaseSqliteStorage(deps);
+
+    /** Mutex keyed by OwnerId to prevent concurrent writes. */
+    const mutexByOwnerId = createMutexByKey<OwnerId>();
 
     return {
       ...sqliteStorageBase,
@@ -133,97 +143,91 @@ export const createRelaySqliteStorage =
             where ownerId = ${ownerId};
           `,
         );
-        if (!selectWriteKey.ok) {
-          config.onStorageError(selectWriteKey.error);
-          return false;
-        }
-
-        const { rows } = selectWriteKey.value;
+        const { rows } = selectWriteKey;
 
-        if (isNonEmptyReadonlyArray(rows)) {
+        if (isNonEmptyArray(rows)) {
           return deps.timingSafeEqual(rows[0].writeKey, writeKey);
         }
 
-        const insertWriteKey = deps.sqlite.exec(sql`
+        deps.sqlite.exec(sql`
           insert into evolu_writeKey (ownerId, writeKey)
           values (${ownerId}, ${writeKey});
         `);
-        if (!insertWriteKey.ok) {
-          config.onStorageError(insertWriteKey.error);
-          return false;
-        }
 
         return true;
       },
 
       setWriteKey: (ownerId, writeKey) => {
-        const upsertWriteKey = deps.sqlite.exec(sql`
+        deps.sqlite.exec(sql`
           insert into evolu_writeKey (ownerId, writeKey)
           values (${ownerId}, ${writeKey})
           on conflict (ownerId) do update
             set writeKey = excluded.writeKey;
         `);
-        if (!upsertWriteKey.ok) {
-          config.onStorageError(upsertWriteKey.error);
-          return false;
-        }
-
-        return true;
       },
 
-      writeMessages: async (ownerIdBytes, messages) => {
+      writeMessages: (ownerIdBytes, messages) => async (run) => {
         const ownerId = ownerIdBytesToOwnerId(ownerIdBytes);
-        const messagesWithTimestampBytes = mapArray(messages, (m) => ({
-          timestamp: timestampToTimestampBytes(m.timestamp),
-          change: m.change,
-        }));
-
-        const result = await ownerMutexes
-          .ensure(ownerId, createMutex)
-          .withLock<void, SqliteError | StorageQuotaError>(async () => {
+        const uniqueMessagesWithTimestampBytes = dedupeArray(
+          mapArray(messages, (m) => ({
+            timestamp: timestampToTimestampBytes(m.timestamp),
+            change: m.change,
+          })),
+          (message) => uint8ArrayToBase64Url(message.timestamp),
+        );
+
+        return run(
+          mutexByOwnerId.withLock(ownerId, async () => {
             const existingTimestampsResult =
               sqliteStorageBase.getExistingTimestamps(
                 ownerIdBytes,
-                mapArray(messagesWithTimestampBytes, (m) => m.timestamp),
+                mapArray(uniqueMessagesWithTimestampBytes, (m) => m.timestamp),
               );
-            if (!existingTimestampsResult.ok) return existingTimestampsResult;
 
-            const existingTimestampsSet = new Set(
-              existingTimestampsResult.value.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
-            if (!isNonEmptyReadonlyArray(newMessages)) {
+            if (!isNonEmptyArray(newMessages)) {
               return ok();
             }
 
-            const usage = getOwnerUsage(deps)(
+            const usage = readOwnerUsageOrDefault(deps)(
               ownerIdBytes,
               firstInArray(newMessages).timestamp,
             );
-            if (!usage.ok) return usage;
-
-            const { storedBytes } = usage.value;
 
             const incomingBytes = newMessages.reduce(
               (sum, m) => sum + m.change.length,
               0,
             );
             const newStoredBytes = PositiveInt.orThrow(
-              (storedBytes ?? 0) + incomingBytes,
+              (usage.storedBytes ?? 0) + incomingBytes,
             );
 
-            const result = config.isOwnerWithinQuota(ownerId, newStoredBytes);
-            const isWithinQuota = isAsync(result) ? await result : result;
+            const quotaResult = config.isOwnerWithinQuota(
+              ownerId,
+              newStoredBytes,
+            );
+            const isWithinQuota = isPromiseLike(quotaResult)
+              ? await quotaResult
+              : quotaResult;
             if (!isWithinQuota) {
-              return err({ type: "StorageQuotaError", ownerId });
+              return err<StorageQuotaError>({
+                type: "StorageQuotaError",
+                ownerId,
+              });
             }
 
-            let { firstTimestamp, lastTimestamp } = usage.value;
+            let { firstTimestamp, lastTimestamp } = usage;
 
             return deps.sqlite.transaction(() => {
               for (const { timestamp, change } of newMessages) {
@@ -235,45 +239,31 @@ export const createRelaySqliteStorage =
                     lastTimestamp,
                   );
 
-                {
-                  const result = sqliteStorageBase.insertTimestamp(
-                    ownerIdBytes,
-                    timestamp,
-                    strategy,
-                  );
-                  if (!result.ok) return result;
-                }
-
-                {
-                  const result = deps.sqlite.exec(sql`
-                    insert into evolu_message ("ownerId", "timestamp", "change")
-                    values (${ownerIdBytes}, ${timestamp}, ${change})
-                    on conflict do nothing;
-                  `);
-                  if (!result.ok) return result;
-                }
+                sqliteStorageBase.insertTimestamp(
+                  ownerIdBytes,
+                  timestamp,
+                  strategy,
+                );
+
+                deps.sqlite.exec(sql`
+                  insert into evolu_message
+                    ("ownerId", "timestamp", "change")
+                  values (${ownerIdBytes}, ${timestamp}, ${change})
+                  on conflict do nothing;
+                `);
               }
 
-              return updateOwnerUsage(deps)(
+              updateOwnerUsage(deps)(
                 ownerIdBytes,
                 newStoredBytes,
                 firstTimestamp,
                 lastTimestamp,
               );
-            });
-          })();
-
-        if (!result.ok && result.error.type !== "AbortError") {
-          switch (result.error.type) {
-            case "SqliteError":
-              config.onStorageError(result.error);
-              return err({ type: "StorageWriteError", ownerId });
-            case "StorageQuotaError":
-              return err({ type: "StorageQuotaError", ownerId });
-          }
-        }
 
-        return ok();
+              return ok();
+            });
+          }),
+        );
       },
 
       readDbChange: (ownerId, timestamp) => {
@@ -284,51 +274,35 @@ export const createRelaySqliteStorage =
           from evolu_message
           where "ownerId" = ${ownerId} and "timestamp" = ${timestamp};
         `);
-        if (!result.ok) {
-          config.onStorageError(result.error);
-          return null;
-        }
 
-        return result.value.rows[0]?.change;
+        const row = result.rows[0];
+        assert(row, "Every timestamp must have a change");
+        return row.change;
       },
 
       deleteOwner: (ownerId) => {
-        const transactionResult = deps.sqlite.transaction(() => {
-          const deleteWriteKey = deps.sqlite.exec(sql`
+        deps.sqlite.transaction(() => {
+          deps.sqlite.exec(sql`
             delete from evolu_writeKey where ownerId = ${ownerId};
           `);
-          if (!deleteWriteKey.ok) return deleteWriteKey;
 
-          const deleteMessages = deps.sqlite.exec(sql`
+          deps.sqlite.exec(sql`
             delete from evolu_message where ownerId = ${ownerId};
           `);
-          if (!deleteMessages.ok) return deleteMessages;
 
-          const deleteUsage = deps.sqlite.exec(sql`
+          deps.sqlite.exec(sql`
             delete from evolu_usage where ownerId = ${ownerId};
           `);
-          if (!deleteUsage.ok) return deleteUsage;
 
-          const deleteBaseOwner = sqliteStorageBase.deleteOwner(ownerId);
-          if (!deleteBaseOwner) return err(null);
+          sqliteStorageBase.deleteOwner(ownerId);
 
           return ok();
         });
-
-        if (!transactionResult.ok) {
-          if (transactionResult.error)
-            config.onStorageError(transactionResult.error);
-          return false;
-        }
-
-        return true;
       },
     };
   };
 
-export const createRelayStorageTables = (
-  deps: SqliteDep,
-): Result<void, SqliteError> => {
+export const createRelayStorageTables = (deps: SqliteDep): void => {
   for (const query of [
     sql`
       create table evolu_writeKey (
@@ -349,134 +323,6 @@ export const createRelayStorageTables = (
       strict;
     `,
   ]) {
-    const result = deps.sqlite.exec(query);
-    if (!result.ok) return result;
+    deps.sqlite.exec(query);
   }
-
-  return ok();
 };
-
-export interface RelayLogger {
-  readonly started: (enableLogging: boolean, port: number) => void;
-  readonly storageError: (error: unknown) => void;
-  readonly upgradeSocketError: (error: Error) => void;
-  readonly invalidOrMissingOwnerIdInUrl: (url: string | undefined) => void;
-  readonly unauthorizedOwner: (ownerId: OwnerId) => void;
-  readonly connectionEstablished: (totalConnectionCount: number) => void;
-  readonly connectionWebSocketError: (error: Error) => void;
-  readonly relayOptionSubscribe: (
-    ownerId: OwnerId,
-    getSubscriberCount: LazyValue<number>,
-  ) => void;
-  readonly relayOptionUnsubscribe: (
-    ownerId: OwnerId,
-    getSubscriberCount: LazyValue<number>,
-  ) => void;
-  readonly relayOptionBroadcast: (
-    ownerId: OwnerId,
-    broadcastCount: number,
-    subscriberCount: number,
-  ) => void;
-  readonly messageLength: (messageLength: number) => void;
-  readonly applyProtocolMessageAsRelayError: (
-    error: ProtocolInvalidDataError,
-  ) => void;
-  readonly responseLength: (responseLength: number) => void;
-  readonly applyProtocolMessageAsRelayUnknownError: (error: unknown) => void;
-  readonly connectionClosed: (totalConnectionCount: number) => void;
-  readonly shuttingDown: () => void;
-  readonly webSocketServerDisposed: () => void;
-  readonly httpServerDisposed: () => void;
-}
-
-export const createRelayLogger = (deps: ConsoleDep): RelayLogger => ({
-  started: (enableLogging, port) => {
-    deps.console.enabled = true;
-    deps.console.log(`Evolu Relay started on port ${port}`);
-    deps.console.enabled = enableLogging;
-  },
-
-  storageError: (error) => {
-    deps.console.error("[relay]", "storage", error);
-  },
-
-  upgradeSocketError: (error) => {
-    deps.console.warn("[relay]", "socket error", { error });
-  },
-
-  invalidOrMissingOwnerIdInUrl: (url) => {
-    deps.console.warn("[relay]", "invalid or missing ownerId in URL", { url });
-  },
-
-  unauthorizedOwner: (ownerId) => {
-    deps.console.warn("[relay]", "unauthorized owner", { ownerId });
-  },
-
-  connectionEstablished: (totalConnectionCount) => {
-    deps.console.log("[relay]", "connection", { totalConnectionCount });
-  },
-
-  connectionWebSocketError: (error) => {
-    deps.console.error("[relay]", "error", { error });
-  },
-
-  relayOptionSubscribe: (ownerId, getSubscriberCount) => {
-    if (deps.console.enabled)
-      deps.console.log("[relay]", "subscribe", {
-        ownerId,
-        subscriberCount: getSubscriberCount(),
-      });
-  },
-
-  relayOptionUnsubscribe: (ownerId, getSubscriberCount) => {
-    if (deps.console.enabled)
-      deps.console.log("[relay]", "unsubscribe", {
-        ownerId,
-        subscriberCount: getSubscriberCount(),
-      });
-  },
-
-  relayOptionBroadcast: (ownerId, broadcastCount, totalSubscribers) => {
-    deps.console.log("[relay]", "broadcast", {
-      ownerId,
-      broadcastCount,
-      totalSubscribers,
-    });
-  },
-
-  messageLength: (messageLength) => {
-    deps.console.log("[relay]", "on message", { messageLength });
-  },
-
-  applyProtocolMessageAsRelayError: (error) => {
-    deps.console.error("[relay]", "applyProtocolMessageAsRelay", error);
-  },
-
-  responseLength: (responseLength) => {
-    deps.console.log("[relay]", "responseLength", { responseLength });
-  },
-
-  applyProtocolMessageAsRelayUnknownError: (error) => {
-    deps.console.error(
-      "[relay]",
-      "applyProtocolMessageAsRelayUnknownError",
-      error,
-    );
-  },
-
-  connectionClosed: (totalConnectionCount) => {
-    deps.console.log("[relay]", "close", { totalConnectionCount });
-  },
-
-  shuttingDown: () => {
-    deps.console.log("Shutting down Evolu Relay...");
-  },
-
-  webSocketServerDisposed: () => {
-    deps.console.log("Evolu Relay WebSocketServer disposed");
-  },
-
-  httpServerDisposed: () => {
-    deps.console.log("Evolu Relay HTTP server disposed");
-  },
-});