@evolu/common 7.4.0 → 8.0.0-next.0

package/src/local-first/Relay.ts

@@ -1,52 +1,58 @@
+/**
+ * Relay server for data synchronization.
+ *
+ * @module
+ */
+
 import {
   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, getOk, 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 { 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,
+  getOwnerUsage,
+  getTimestampInsertStrategy,
   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}
+   * The callback receives the {@link OwnerId} 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
@@ -60,7 +66,7 @@ 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
@@ -85,7 +91,7 @@ export interface RelayConfig extends ConsoleConfig, StorageConfig {
    *   Promise.resolve(ownerId === "6jy_2F4RT5qqeLgJ14_dnQ"),
    * ```
    */
-  readonly isOwnerAllowed?: (ownerId: OwnerId) => MaybeAsync<boolean>;
+  readonly isOwnerAllowed?: (ownerId: OwnerId) => Awaitable<boolean>;
 }
 
 /**
@@ -97,21 +103,15 @@ export interface RelayConfig extends ConsoleConfig, StorageConfig {
  * decentralization and infinite horizontal scalability with minimal
  * infrastructure.
  */
-export interface Relay extends Disposable {}
+export interface Relay extends AsyncDisposable {}
 
 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,63 +133,46 @@ export const createRelaySqliteStorage =
             where ownerId = ${ownerId};
           `,
         );
-        if (!selectWriteKey.ok) {
-          config.onStorageError(selectWriteKey.error);
-          return false;
-        }
+        const { rows } = selectWriteKey;
 
-        const { rows } = selectWriteKey.value;
-
-        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 result = await run(
+          mutexByOwnerId.withLock(ownerId, async () => {
             const existingTimestampsResult =
               sqliteStorageBase.getExistingTimestamps(
                 ownerIdBytes,
                 mapArray(messagesWithTimestampBytes, (m) => m.timestamp),
               );
-            if (!existingTimestampsResult.ok) return existingTimestampsResult;
 
             const existingTimestampsSet = new Set(
-              existingTimestampsResult.value.map((t) => t.toString()),
+              existingTimestampsResult.map((t) => t.toString()),
             );
             const newMessages = filterArray(
               messagesWithTimestampBytes,
@@ -197,33 +180,40 @@ export const createRelaySqliteStorage =
             );
 
             // Nothing to write
-            if (!isNonEmptyReadonlyArray(newMessages)) {
+            if (!isNonEmptyArray(newMessages)) {
               return ok();
             }
 
-            const usage = getOwnerUsage(deps)(
-              ownerIdBytes,
-              firstInArray(newMessages).timestamp,
+            const usage = getOk(
+              getOwnerUsage(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,42 +225,35 @@ 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,
               );
+
+              return ok();
             });
-          })();
-
-        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 });
-          }
+          }),
+        );
+
+        if (!result.ok) {
+          if (result.error.type === "AbortError") return ok();
+          return result;
         }
 
         return ok();
@@ -284,51 +267,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 +316,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");
-  },
-});