@evolu/common 6.0.1-preview.9 → 7.0.0

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,
@@ -209,8 +209,7 @@ export function getJsonObjectArgs(
   table: string,
 ): Array<Expression<unknown> | string> {
   const args: Array<Expression<unknown> | string> = [];
-  args.push(kyselyJsonIdentifier, kyselyJsonIdentifier);
-
+  
   for (const { selection: s } of node.selections ?? []) {
     if (ReferenceNode.is(s) && ColumnNode.is(s.column)) {
       args.push(

package/src/Evolu/Query.ts

@@ -1,3 +1,4 @@
+import { Brand } from "../Brand.js";
 import { bytesToHex, hexToBytes } from "../Buffer.js";
 import { objectToEntries } from "../Object.js";
 import {
@@ -8,7 +9,7 @@ import {
   SqliteValue,
 } from "../Sqlite.js";
 import { Store, StoreSubscribe } from "../Store.js";
-import { Brand, Simplify } from "../Types.js";
+import { Simplify } from "../Types.js";
 
 /**
  * A type-safe SQL query.
@@ -51,7 +52,7 @@ export const serializeQuery = <R extends Row>(query: SqliteQuery): Query<R> => {
   );
 
   const options = query.options
-    ? objectToEntries(query.options).sort(([a], [b]) => a.localeCompare(b))
+    ? objectToEntries(query.options).toSorted(([a], [b]) => a.localeCompare(b))
     : [];
 
   return JSON.stringify([query.sql, params, options]) as Query<R>;

package/src/Evolu/Relay.ts

@@ -1,61 +1,123 @@
-import { isNonEmptyReadonlyArray } from "../Array.js";
-import { ConsoleConfig } from "../Console.js";
+import {
+  filterArray,
+  firstInArray,
+  isNonEmptyReadonlyArray,
+  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, SqliteError } from "../Sqlite.js";
-import { SimpleName } from "../Type.js";
-import { OwnerId, WriteKey } from "./Owner.js";
-import { EncryptedDbChange, Storage } from "./Protocol.js";
+import { sql, SqliteDep, SqliteError } from "../Sqlite.js";
+import { createMutex, isAsync, MaybeAsync, Mutex } from "../Task.js";
+import { PositiveInt, SimpleName } from "../Type.js";
+import {
+  OwnerId,
+  ownerIdBytesToOwnerId,
+  OwnerTransport,
+  OwnerWriteKey,
+} from "./Owner.js";
+import { ProtocolInvalidDataError } from "./Protocol.js";
 import {
-  createSqliteStorageBase,
-  CreateSqliteStorageBaseOptions,
+  createBaseSqliteStorage,
+  CreateBaseSqliteStorageConfig,
+  EncryptedDbChange,
+  getOwnerUsage,
+  getTimestampInsertStrategy,
   SqliteStorageDeps,
+  Storage,
+  StorageConfig,
+  StorageQuotaError,
+  updateOwnerUsage,
 } from "./Storage.js";
-import { timestampToBinaryTimestamp } from "./Timestamp.js";
+import { timestampToTimestampBytes } from "./Timestamp.js";
 
-export interface Relay extends Disposable {}
-
-export interface RelayConfig extends ConsoleConfig {
+export interface RelayConfig extends ConsoleConfig, StorageConfig {
+  /**
+   * The relay name.
+   *
+   * Implementations can use this for identification purposes (e.g., database
+   * file name, logging).
+   */
   readonly name?: SimpleName;
+
+  /**
+   * 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 can be synchronous (for SQLite or in-memory checks) or
+   * asynchronous (for calling remote APIs).
+   *
+   * The callback returns a boolean rather than an error type because error
+   * handling and logging are the responsibility of the callback
+   * implementation.
+   *
+   * OwnerId is used 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 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.
+   *
+   * ### Example
+   *
+   * ```ts
+   * // Client
+   * const transport = createOwnerWebSocketTransport({
+   *   url: "wss://relay.evolu.dev",
+   *   ownerId: owner.id,
+   * });
+   *
+   * const evolu = createEvolu(deps)(Schema, {
+   *   transports: [transport],
+   * });
+   *
+   *
+   * // Relay
+   * isOwnerAllowed: (ownerId) =>
+   *   Promise.resolve(ownerId === "6jy_2F4RT5qqeLgJ14_dnQ"),
+   * ```
+   */
+  readonly isOwnerAllowed?: (ownerId: OwnerId) => MaybeAsync<boolean>;
 }
 
-export type RelaySqliteStorageDeps = SqliteStorageDeps & TimingSafeEqualDep;
-
-export const createRelayStorage =
-  (deps: RelaySqliteStorageDeps) =>
-  (options: CreateSqliteStorageBaseOptions): Result<Storage, SqliteError> => {
-    const sqliteStorageBase = createSqliteStorageBase(deps)(options);
-    if (!sqliteStorageBase.ok) return sqliteStorageBase;
-
-    for (const query of [
-      sql`
-        create table if not exists evolu_writeKey (
-          "ownerId" blob not null,
-          "writeKey" blob not null,
-          primary key ("ownerId")
-        )
-        strict;
-      `,
-
-      sql`
-        create table if not exists evolu_message (
-          "ownerId" blob not null,
-          "timestamp" blob not null,
-          "change" blob not null,
-          primary key ("ownerId", "timestamp")
-        )
-        strict;
-      `,
-    ]) {
-      const result = deps.sqlite.exec(query);
-      if (!result.ok) return result;
-    }
-
-    return ok({
-      ...sqliteStorageBase.value,
+/**
+ * A completely interchangeable server for syncing and backing up encrypted data
+ * between 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.
+ */
+export interface Relay extends Disposable {}
+
+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>();
+
+    return {
+      ...sqliteStorageBase,
 
       /**
-       * 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
@@ -64,32 +126,34 @@ 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);
+          config.onStorageError(selectWriteKey.error);
           return false;
         }
 
         const { rows } = selectWriteKey.value;
 
-        if (!isNonEmptyReadonlyArray(rows)) {
-          const insertWriteKey = deps.sqlite.exec(sql`
-            insert into evolu_writeKey (ownerId, writeKey)
-            values (${ownerId}, ${writeKey});
-          `);
-          if (!insertWriteKey.ok) {
-            options.onStorageError(insertWriteKey.error);
-            return false;
-          }
+        if (isNonEmptyReadonlyArray(rows)) {
+          return deps.timingSafeEqual(rows[0].writeKey, writeKey);
+        }
 
-          return true;
+        const insertWriteKey = deps.sqlite.exec(sql`
+          insert into evolu_writeKey (ownerId, writeKey)
+          values (${ownerId}, ${writeKey});
+        `);
+        if (!insertWriteKey.ok) {
+          config.onStorageError(insertWriteKey.error);
+          return false;
         }
 
-        return deps.timingSafeEqual(rows[0].writeKey, writeKey);
+        return true;
       },
 
       setWriteKey: (ownerId, writeKey) => {
@@ -100,44 +164,120 @@ export const createRelayStorage =
             set writeKey = excluded.writeKey;
         `);
         if (!upsertWriteKey.ok) {
-          options.onStorageError(upsertWriteKey.error);
+          config.onStorageError(upsertWriteKey.error);
           return false;
         }
 
         return true;
       },
 
-      writeMessages: (ownerId, messages) => {
-        const result = deps.sqlite.transaction(() => {
-          for (const message of messages) {
-            const insertTimestampResult =
-              sqliteStorageBase.value.insertTimestamp(
-                ownerId,
-                timestampToBinaryTimestamp(message.timestamp),
+      writeMessages: async (ownerIdBytes, messages) => {
+        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 existingTimestampsResult =
+              sqliteStorageBase.getExistingTimestamps(
+                ownerIdBytes,
+                mapArray(messagesWithTimestampBytes, (m) => m.timestamp),
               );
-            if (!insertTimestampResult.ok) return insertTimestampResult;
-
-            const insertMessage = deps.sqlite.exec(sql`
-              insert into evolu_message ("ownerId", "timestamp", "change")
-              values
-                (
-                  ${ownerId},
-                  ${timestampToBinaryTimestamp(message.timestamp)},
-                  ${message.change}
-                )
-              on conflict do nothing;
-            `);
-            if (!insertMessage.ok) return insertMessage;
-          }
-          return ok();
-        });
+            if (!existingTimestampsResult.ok) return existingTimestampsResult;
 
-        if (!result.ok) {
-          options.onStorageError(result.error);
-          return false;
+            const existingTimestampsSet = new Set(
+              existingTimestampsResult.value.map((t) => t.toString()),
+            );
+            const newMessages = filterArray(
+              messagesWithTimestampBytes,
+              (m) => !existingTimestampsSet.has(m.timestamp.toString()),
+            );
+
+            // Nothing to write
+            if (!isNonEmptyReadonlyArray(newMessages)) {
+              return ok();
+            }
+
+            const usage = 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,
+            );
+
+            const withinQuotaResult = config.isOwnerWithinQuota(
+              ownerId,
+              newStoredBytes,
+            );
+            const isWithinQuota = isAsync(withinQuotaResult)
+              ? await withinQuotaResult
+              : withinQuotaResult;
+            if (!isWithinQuota) {
+              return err({ type: "StorageQuotaError", ownerId });
+            }
+
+            let { firstTimestamp, lastTimestamp } = usage.value;
+
+            return deps.sqlite.transaction(() => {
+              for (const { timestamp, change } of newMessages) {
+                let strategy;
+                [strategy, firstTimestamp, lastTimestamp] =
+                  getTimestampInsertStrategy(
+                    timestamp,
+                    firstTimestamp,
+                    lastTimestamp,
+                  );
+
+                const insertTimestampResult = sqliteStorageBase.insertTimestamp(
+                  ownerIdBytes,
+                  timestamp,
+                  strategy,
+                );
+                if (!insertTimestampResult.ok) return insertTimestampResult;
+
+                const insertMessage = deps.sqlite.exec(sql`
+                  insert into evolu_message ("ownerId", "timestamp", "change")
+                  values (${ownerIdBytes}, ${timestamp}, ${change})
+                  on conflict do nothing;
+                `);
+                if (!insertMessage.ok) return insertMessage;
+              }
+
+              const updateUsage = updateOwnerUsage(deps)(
+                ownerIdBytes,
+                newStoredBytes,
+                firstTimestamp,
+                lastTimestamp,
+              );
+              if (!updateUsage.ok) return updateUsage;
+
+              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 });
+          }
         }
 
-        return true;
+        return ok();
       },
 
       readDbChange: (ownerId, timestamp) => {
@@ -149,7 +289,7 @@ export const createRelayStorage =
           where "ownerId" = ${ownerId} and "timestamp" = ${timestamp};
         `);
         if (!result.ok) {
-          options.onStorageError(result.error);
+          config.onStorageError(result.error);
           return null;
         }
 
@@ -157,27 +297,190 @@ export const createRelayStorage =
       },
 
       deleteOwner: (ownerId) => {
-        const result = deps.sqlite.transaction(() => {
-          const del1 = deps.sqlite.exec(sql`
+        const transactionResult = deps.sqlite.transaction(() => {
+          const deleteWriteKey = deps.sqlite.exec(sql`
             delete from evolu_writeKey where ownerId = ${ownerId};
           `);
-          if (!del1.ok) return del1;
+          if (!deleteWriteKey.ok) return deleteWriteKey;
 
-          const del2 = deps.sqlite.exec(sql`
+          const deleteMessages = deps.sqlite.exec(sql`
             delete from evolu_message where ownerId = ${ownerId};
           `);
-          if (!del2.ok) return del2;
+          if (!deleteMessages.ok) return deleteMessages;
 
-          const del3 = sqliteStorageBase.value.deleteOwner(ownerId);
-          if (!del3) return err(null);
+          const deleteUsage = 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);
 
           return ok();
         });
-        if (!result.ok) {
-          if (result.error) options.onStorageError(result.error);
+
+        if (!transactionResult.ok) {
+          if (transactionResult.error)
+            config.onStorageError(transactionResult.error);
           return false;
         }
+
         return true;
       },
-    });
+    };
   };
+
+export const createRelayStorageTables = (
+  deps: SqliteDep,
+): Result<void, SqliteError> => {
+  for (const query of [
+    sql`
+      create table evolu_writeKey (
+        "ownerId" blob not null,
+        "writeKey" blob not null,
+        primary key ("ownerId")
+      )
+      strict;
+    `,
+
+    sql`
+      create table evolu_message (
+        "ownerId" blob not null,
+        "timestamp" blob not null,
+        "change" blob not null,
+        primary key ("ownerId", "timestamp")
+      )
+      strict;
+    `,
+  ]) {
+    const result = deps.sqlite.exec(query);
+    if (!result.ok) return result;
+  }
+
+  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");
+  },
+});