@evolu/common 6.0.1-preview.2 → 6.0.1-preview.21

package/src/Evolu/Public.ts

@@ -5,23 +5,17 @@
  */
 
 export { createEvolu } from "./Evolu.js";
-export type {
-  Evolu,
-  EvoluConfigWithInitialData,
-  EvoluDeps,
-  EvoluError,
-} from "./Evolu.js";
+export type { Evolu, EvoluConfig, EvoluDeps, EvoluError } from "./Evolu.js";
 export * from "./Owner.js";
-export { binaryIdToId, idToBinaryId } from "./Protocol.js";
-export type { BinaryId } from "./Protocol.js";
+export * from "./LocalAuth.js";
 export * as kysely from "./PublicKysely.js";
 export type { InferRow, Query, QueryRows, Row } from "./Query.js";
-export { formatValidMutationSizeError } from "./Schema.js";
-export type { EvoluSchema, ValidMutationSizeError } from "./Schema.js";
+export type { EvoluSchema } from "./Schema.js";
 export type {
   NetworkError,
   PaymentRequiredError,
   ServerError,
+  SyncOwner,
   SyncState,
   SyncStateInitial,
   SyncStateIsNotSynced,
@@ -29,15 +23,14 @@ export type {
   SyncStateIsSyncing,
 } from "./Sync.js";
 export {
-  binaryTimestampToTimestamp,
   Timestamp,
-  timestampToBinaryTimestamp,
+  timestampBytesToTimestamp,
+  timestampToTimestampBytes,
 } from "./Timestamp.js";
 export type {
-  BinaryTimestamp,
+  TimestampBytes,
   TimestampCounterOverflowError,
   TimestampDriftError,
-  TimestampDuplicateNodeError,
   TimestampError,
   TimestampTimeOutOfRangeError,
 } from "./Timestamp.js";

package/src/Evolu/PublicKysely.ts

@@ -65,7 +65,7 @@ export type { NotNull } from "kysely";
  * from "person"
  * ```
  */
-// SQL formatting breaks generated SQL for some reason.
+// Kysely expects strict AST.
 // prettier-ignore
 export function jsonArrayFrom<O>(
     expr: SelectQueryBuilderExpression<O>,
@@ -122,7 +122,7 @@ export function jsonArrayFrom<O>(
  * from "person";
  * ```
  */
-// SQL formatting breaks generated SQL for some reason.
+// Kysely expects strict AST.
 // prettier-ignore
 export function jsonObjectFrom<O>(
     expr: SelectQueryBuilderExpression<O>,
@@ -172,7 +172,7 @@ export function jsonObjectFrom<O>(
  * from "person"
  * ```
  */
-// SQL formatting breaks generated SQL for some reason.
+// Kysely expects strict AST.
 // prettier-ignore
 export function jsonBuildObject<O extends Record<string, Expression<unknown>>>(
     obj: O,

package/src/Evolu/Query.ts

@@ -8,7 +8,8 @@ import {
   SqliteValue,
 } from "../Sqlite.js";
 import { Store, StoreSubscribe } from "../Store.js";
-import { Brand, Simplify } from "../Types.js";
+import { Simplify } from "../Types.js";
+import { Brand } from "../Brand.js";
 
 /**
  * A type-safe SQL query.

package/src/Evolu/Relay.ts

@@ -1,26 +1,73 @@
 import { isNonEmptyReadonlyArray } from "../Array.js";
-import { ConsoleConfig } from "../Console.js";
-import { eqArrayNumber } from "../Eq.js";
-import { ok, Result } from "../Result.js";
+import { ConsoleConfig, ConsoleDep } from "../Console.js";
+import { TimingSafeEqualDep } from "../Crypto.js";
+import { LazyValue } from "../Function.js";
+import { err, ok, Result } from "../Result.js";
 import { sql, SqliteError } from "../Sqlite.js";
 import { SimpleName } from "../Type.js";
-import { OwnerId, WriteKey } from "./Owner.js";
-import { EncryptedDbChange, Storage } from "./Protocol.js";
+import { OwnerId, OwnerWriteKey, TransportConfig } from "./Owner.js";
+import { ProtocolInvalidDataError } from "./Protocol.js";
 import {
   createSqliteStorageBase,
   CreateSqliteStorageBaseOptions,
+  EncryptedDbChange,
   SqliteStorageDeps,
+  Storage,
 } from "./Storage.js";
-import { timestampToBinaryTimestamp } from "./Timestamp.js";
+import { timestampToTimestampBytes } from "./Timestamp.js";
 
 export interface Relay extends Disposable {}
 
 export interface RelayConfig extends ConsoleConfig {
+  /**
+   * The relay name.
+   *
+   * Implementations can use this for identification purposes (e.g., database
+   * file name, logging).
+   */
   readonly name?: SimpleName;
+
+  /**
+   * Optional callback to authenticate an {@link OwnerId} with the relay.
+   *
+   * If this callback is not provided, all owners are allowed.
+   *
+   * If provided, the callback receives the OwnerId and should return a promise
+   * that resolves to `true` to allow access, or `false` to deny.
+   *
+   * The callback returns a boolean rather than an error type because error
+   * handling and logging are the responsibility of the callback implementation,
+   * not the relay. This prevents leaking authentication implementation details
+   * into the generic relay interface.
+   *
+   * OwnerId is used for authentication rather than short-lived tokens because
+   * this only controls 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 TransportConfig}. 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>`).
+   *
+   * ### Example
+   *
+   * ```ts
+   * const relay = await createNodeJsRelay(deps)({
+   *   authenticateOwner: async (ownerId) => {
+   *     const isRegistered = await db.checkOwner(ownerId);
+   *     if (!isRegistered) {
+   *       logger.warn("Unauthorized access attempt", { ownerId });
+   *     }
+   *     return isRegistered;
+   *   },
+   * });
+   * ```
+   */
+  readonly authenticateOwner?: (ownerId: OwnerId) => Promise<boolean>;
 }
 
-export const createRelayStorage =
-  (deps: SqliteStorageDeps) =>
+export const createRelaySqliteStorage =
+  (deps: SqliteStorageDeps & TimingSafeEqualDep) =>
   (options: CreateSqliteStorageBaseOptions): Result<Storage, SqliteError> => {
     const sqliteStorageBase = createSqliteStorageBase(deps)(options);
     if (!sqliteStorageBase.ok) return sqliteStorageBase;
@@ -53,7 +100,7 @@ export const createRelayStorage =
       ...sqliteStorageBase.value,
 
       /**
-       * Lazily authorizes the initiator's {@link WriteKey} for the given
+       * Lazily authorizes the initiator's {@link OwnerWriteKey} for the given
        * {@link OwnerId}.
        *
        * - If the {@link OwnerId} does not exist, it is created and associated with
@@ -62,11 +109,13 @@ export const createRelayStorage =
        *   stored key.
        */
       validateWriteKey: (ownerId, writeKey) => {
-        const selectWriteKey = deps.sqlite.exec<{ writeKey: WriteKey }>(sql`
-          select writeKey
-          from evolu_writeKey
-          where ownerId = ${ownerId};
-        `);
+        const selectWriteKey = deps.sqlite.exec<{ writeKey: OwnerWriteKey }>(
+          sql`
+            select writeKey
+            from evolu_writeKey
+            where ownerId = ${ownerId};
+          `,
+        );
         if (!selectWriteKey.ok) {
           options.onStorageError(selectWriteKey.error);
           return false;
@@ -87,16 +136,33 @@ export const createRelayStorage =
           return true;
         }
 
-        return eqArrayNumber(rows[0].writeKey, writeKey);
+        return deps.timingSafeEqual(rows[0].writeKey, writeKey);
+      },
+
+      setWriteKey: (ownerId, writeKey) => {
+        const upsertWriteKey = 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) {
+          options.onStorageError(upsertWriteKey.error);
+          return false;
+        }
+
+        return true;
       },
 
-      writeMessages: (ownerId, messages) => {
+      // https://eslint.org/docs/latest/rules/require-await#when-not-to-use-it
+      // eslint-disable-next-line @typescript-eslint/require-await
+      writeMessages: async (ownerId, messages) => {
         const result = deps.sqlite.transaction(() => {
           for (const message of messages) {
             const insertTimestampResult =
               sqliteStorageBase.value.insertTimestamp(
                 ownerId,
-                timestampToBinaryTimestamp(message.timestamp),
+                timestampToTimestampBytes(message.timestamp),
               );
             if (!insertTimestampResult.ok) return insertTimestampResult;
 
@@ -105,7 +171,7 @@ export const createRelayStorage =
               values
                 (
                   ${ownerId},
-                  ${timestampToBinaryTimestamp(message.timestamp)},
+                  ${timestampToTimestampBytes(message.timestamp)},
                   ${message.change}
                 )
               on conflict do nothing;
@@ -138,5 +204,159 @@ export const createRelayStorage =
 
         return result.value.rows[0]?.change;
       },
+
+      deleteOwner: (ownerId) => {
+        const result = deps.sqlite.transaction(() => {
+          const del1 = deps.sqlite.exec(sql`
+            delete from evolu_writeKey where ownerId = ${ownerId};
+          `);
+          if (!del1.ok) return del1;
+
+          const del2 = deps.sqlite.exec(sql`
+            delete from evolu_message where ownerId = ${ownerId};
+          `);
+          if (!del2.ok) return del2;
+
+          const del3 = sqliteStorageBase.value.deleteOwner(ownerId);
+          if (!del3) return err(null);
+
+          return ok();
+        });
+        if (!result.ok) {
+          if (result.error) options.onStorageError(result.error);
+          return false;
+        }
+        return true;
+      },
     });
   };
+
+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 authenticateOwnerError: (error: unknown) => 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 });
+  },
+
+  authenticateOwnerError: (error) => {
+    deps.console.error("[relay]", "authenticateOwner error", error);
+  },
+
+  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");
+  },
+});