@evolu/common 6.0.1-preview.3 → 6.0.1-preview.30

package/src/Evolu/Sync.ts

@@ -1,58 +1,741 @@
-import { ConsoleConfig, ConsoleDep } from "../Console.js";
-import { createWebSocket } from "../WebSocket.js";
-import { ProtocolMessage } from "./Protocol.js";
-import { Millis } from "./Timestamp.js";
+import { NonEmptyArray, NonEmptyReadonlyArray } from "../Array.js";
+import { assert } from "../Assert.js";
+import { Brand } from "../Brand.js";
+import { ConsoleDep } from "../Console.js";
+import {
+  RandomBytesDep,
+  SymmetricCryptoDecryptError,
+  SymmetricCryptoDep,
+} from "../Crypto.js";
+import { eqArrayNumber } from "../Eq.js";
+import { createTransferableError, TransferableError } from "../Error.js";
+import { constFalse, constTrue } from "../Function.js";
+import { objectToEntries } from "../Object.js";
+import { RandomDep } from "../Random.js";
+import { createResources } from "../Resources.js";
+import { err, ok, Result } from "../Result.js";
+import { sql, SqliteDep, SqliteError, SqliteValue } from "../Sqlite.js";
+import { AbortError, createMutex } from "../Task.js";
+import { TimeDep } from "../Time.js";
+import { IdBytes, idBytesToId, idToIdBytes } from "../Type.js";
+import { CreateWebSocketDep, WebSocket } from "../WebSocket.js";
+import type { PostMessageDep } from "./Db.js";
+import {
+  AppOwner,
+  OwnerEncryptionKey,
+  OwnerId,
+  OwnerIdBytes,
+  ownerIdBytesToOwnerId,
+  ownerIdToOwnerIdBytes,
+  OwnerTransport,
+  OwnerWriteKey,
+  ShardOwner,
+  SharedOwner,
+  SharedReadonlyOwner,
+} from "./Owner.js";
+import {
+  applyProtocolMessageAsClient,
+  createProtocolMessageForSync,
+  createProtocolMessageForUnsubscribe,
+  createProtocolMessageFromCrdtMessages,
+  decryptAndDecodeDbChange,
+  encodeAndEncryptDbChange,
+  ProtocolError,
+  ProtocolInvalidDataError,
+  ProtocolTimestampMismatchError,
+  SubscriptionFlags,
+} from "./Protocol.js";
+import { MutationChange } from "./Schema.js";
+import {
+  BaseSqliteStorage,
+  CrdtMessage,
+  createBaseSqliteStorage,
+  DbChange,
+  Storage,
+  StorageWriteError,
+} from "./Storage.js";
+import {
+  createInitialTimestamp,
+  Millis,
+  receiveTimestamp,
+  sendTimestamp,
+  Timestamp,
+  timestampBytesToTimestamp,
+  TimestampConfigDep,
+  TimestampCounterOverflowError,
+  TimestampDriftError,
+  TimestampTimeOutOfRangeError,
+  timestampToTimestampBytes,
+  timestampToTimestampString,
+} from "./Timestamp.js";
 
-export interface Sync {
-  readonly send: (message: ProtocolMessage) => void;
+export interface Sync extends Disposable {
+  /**
+   * Assigns or removes an owner to/from transports with reference counting.
+   *
+   * Owners are only "active" if assigned to at least one transport. Uses
+   * `owner.transports` or falls back to config transports. Multiple calls
+   * increment/decrement reference counts (useful for React Hooks).
+   */
+  readonly useOwner: (use: boolean, owner: SyncOwner) => void;
+
+  readonly applyChanges: (
+    changes: NonEmptyReadonlyArray<MutationChange>,
+  ) => Result<
+    void,
+    | SqliteError
+    | TimestampCounterOverflowError
+    | TimestampDriftError
+    | TimestampTimeOutOfRangeError
+  >;
 }
 
 export interface SyncDep {
   readonly sync: Sync;
 }
 
-export type CreateSync = (deps: ConsoleDep) => (config: SyncConfig) => Sync;
+/**
+ * Represents an owner for sync operations. This is a unified interface that
+ * abstracts over the specific owner types ({@link ShardOwner},
+ * {@link SharedOwner}, {@link SharedReadonlyOwner}) for the sync layer.
+ *
+ * The sync layer only needs the essential data for synchronization and doesn't
+ * need to distinguish between different owner types.
+ */
+export interface SyncOwner {
+  readonly id: OwnerId;
+  readonly encryptionKey: OwnerEncryptionKey;
+  /** Optional for read-only owners like {@link SharedReadonlyOwner}. */
+  readonly writeKey?: OwnerWriteKey;
+  readonly transports?: ReadonlyArray<OwnerTransport>;
+}
+
+export interface SyncConfig {
+  readonly appOwner: AppOwner;
+
+  readonly transports: ReadonlyArray<OwnerTransport>;
+
+  /**
+   * Delay in milliseconds before disposing unused WebSocket connections.
+   * Defaults to 100ms.
+   */
+  readonly disposalDelayMs?: number;
+
+  readonly onError: (
+    error:
+      | ProtocolError
+      | ProtocolInvalidDataError
+      | ProtocolTimestampMismatchError
+      | SqliteError
+      | SymmetricCryptoDecryptError
+      | TimestampCounterOverflowError
+      | TimestampDriftError
+      | TimestampTimeOutOfRangeError
+      | TransferableError,
+  ) => void;
+
+  readonly onReceive: () => void;
+}
+
+export const createSync =
+  (
+    deps: ClockDep &
+      ConsoleDep &
+      CreateWebSocketDep &
+      PostMessageDep &
+      RandomBytesDep &
+      RandomDep &
+      SqliteDep &
+      SymmetricCryptoDep &
+      TimeDep &
+      TimestampConfigDep,
+  ) =>
+  (config: SyncConfig): Result<Sync, SqliteError> => {
+    let isDisposed = false;
+
+    /** Returns owner data only if actively assigned to at least one transport. */
+    const getSyncOwner = (ownerId: OwnerId): SyncOwner | null => {
+      if (isDisposed) return null;
+      return transports.getConsumer(ownerId);
+    };
+
+    const storageResult = createClientStorage({
+      ...deps,
+      getSyncOwner,
+    })(config);
+
+    if (!storageResult.ok) return storageResult;
+    const storage = storageResult.value;
+
+    const createResource = (transportConfig: OwnerTransport): WebSocket => {
+      const transportKey = createTransportKey(transportConfig);
+
+      deps.console.log("[sync]", "createWebSocket", {
+        transportKey,
+        url: transportConfig.url,
+      });
+
+      return deps.createWebSocket(transportConfig.url, {
+        binaryType: "arraybuffer",
+
+        onOpen: () => {
+          if (isDisposed) return;
+
+          const webSocket = transports.getResource(transportKey);
+          if (!webSocket) return;
+
+          const ownerIds = transports.getConsumersForResource(transportKey);
+          deps.console.log("[sync]", "onOpen", { transportKey, ownerIds });
+
+          for (const ownerId of ownerIds) {
+            const message = createProtocolMessageForSync({ storage })(
+              ownerId,
+              SubscriptionFlags.Subscribe,
+            );
+            if (!message) continue;
+            deps.console.log("[sync]", "send", { message });
+            webSocket.send(message);
+          }
+        },
+
+        onClose: (event) => {
+          deps.console.log("[sync]", "onClose", {
+            transportKey,
+            code: event.code,
+            reason: event.reason,
+            wasClean: event.wasClean,
+          });
+        },
+
+        onError: (error) => {
+          deps.console.warn("[sync]", "onError", { transportKey, error });
+        },
+
+        onMessage: (data: string | ArrayBuffer | Blob) => {
+          // Only handle ArrayBuffer data for sync messages
+          if (isDisposed || !(data instanceof ArrayBuffer)) return;
+
+          const webSocket = transports.getResource(transportKey);
+          if (!webSocket) return;
+
+          const input = new Uint8Array(data);
+          deps.console.log("[sync]", "onMessage", {
+            transportKey,
+            message: input,
+          });
+
+          applyProtocolMessageAsClient({ storage })(input, {
+            // No write key, no sync (for a case when an owner was unused).
+            getWriteKey: (ownerId) => getSyncOwner(ownerId)?.writeKey ?? null,
+          })
+            .then((message) => {
+              if (!message.ok) {
+                config.onError(message.error);
+                return;
+              }
+
+              switch (message.value.type) {
+                case "response":
+                  webSocket.send(message.value.message);
+                  break;
+                case "no-response":
+                  // Sync complete, no response needed
+                  break;
+                case "broadcast":
+                  // This was a broadcast message, don't affect sync counter
+                  break;
+              }
+            })
+            .catch((error: unknown) => {
+              config.onError(createTransferableError(error));
+            });
+        },
+      });
+    };
 
-export interface CreateSyncDep {
-  readonly createSync: CreateSync;
+    const transports = createResources<
+      WebSocket,
+      TransportKey,
+      OwnerTransport,
+      SyncOwner,
+      OwnerId
+    >({
+      createResource,
+      getResourceKey: createTransportKey,
+      getConsumerId: (owner) => owner.id,
+      disposalDelay: config.disposalDelayMs ?? 100,
+
+      onConsumerAdded: (owner, webSocket) => {
+        deps.console.log("[sync]", "onConsumerAdded", {
+          ownerId: owner.id,
+          isOpen: webSocket.isOpen(),
+        });
+
+        // The onOpen handler will sync it.
+        if (!webSocket.isOpen()) return;
+        const message = createProtocolMessageForSync({ storage })(
+          owner.id,
+          SubscriptionFlags.Subscribe,
+        );
+        if (message) webSocket.send(message);
+      },
+
+      onConsumerRemoved: (owner, webSocket) => {
+        deps.console.log("[sync]", "onConsumerRemoved", {
+          ownerId: owner.id,
+          isOpen: webSocket.isOpen(),
+        });
+
+        const message = createProtocolMessageForUnsubscribe(owner.id);
+        webSocket.send(message);
+      },
+    });
+
+    const sync: Sync = {
+      useOwner: (use, owner) => {
+        if (isDisposed) {
+          deps.console.warn(
+            "[sync]",
+            "useOwner called on disposed Sync instance",
+            { owner },
+          );
+          return;
+        }
+
+        deps.console.log("[sync]", "useOwner", { use, owner });
+        const transportsToUse = owner.transports ?? config.transports;
+
+        if (use) {
+          transports.addConsumer(owner, transportsToUse);
+        } else {
+          const result = transports.removeConsumer(owner, transportsToUse);
+
+          if (!result.ok) {
+            deps.console.warn("[sync]", "Failed to remove consumer", {
+              transportsToUse,
+              ownerId: owner.id,
+              error: result.error,
+            });
+          }
+        }
+      },
+
+      applyChanges: (changes) => {
+        deps.console.log("[sync]", "applyChanges", { changes });
+
+        let clockTimestamp = deps.clock.get();
+        const ownerMessages = new Map<OwnerId, NonEmptyArray<CrdtMessage>>();
+
+        for (const change of changes) {
+          const nextTimestamp = sendTimestamp(deps)(clockTimestamp);
+          if (!nextTimestamp.ok) return nextTimestamp;
+          clockTimestamp = nextTimestamp.value;
+
+          const { ownerId = config.appOwner.id, ...dbChange } = change;
+          const message = { timestamp: clockTimestamp, change: dbChange };
+
+          const messages = ownerMessages.get(ownerId);
+          if (messages) messages.push(message);
+          else ownerMessages.set(ownerId, [message]);
+        }
+
+        for (const [ownerId, messages] of ownerMessages) {
+          const result = applyMessages({ ...deps, storage })(ownerId, messages);
+          if (!result.ok) return result;
+
+          const owner = getSyncOwner(ownerId);
+          if (!owner?.writeKey) continue;
+
+          const message = createProtocolMessageFromCrdtMessages(deps)(
+            {
+              id: owner.id,
+              encryptionKey: owner.encryptionKey,
+              writeKey: owner.writeKey,
+            },
+            messages,
+          );
+
+          const transportsToUse = owner.transports ?? config.transports;
+
+          // Send message to all transports for this owner
+          for (const transportConfig of transportsToUse) {
+            const transportKey = createTransportKey(transportConfig);
+
+            const webSocket = transports.getResource(transportKey);
+            if (!webSocket) continue;
+
+            if (webSocket.isOpen()) {
+              deps.console.log("[sync]", "send", { transportKey, message });
+              webSocket.send(message);
+            }
+          }
+        }
+
+        return deps.clock.save(clockTimestamp);
+      },
+
+      [Symbol.dispose]: () => {
+        if (isDisposed) return;
+        isDisposed = true;
+        transports[Symbol.dispose]();
+      },
+    };
+
+    return ok(sync);
+  };
+
+export interface ClockDep {
+  readonly clock: Clock;
 }
 
-export interface SyncConfig extends ConsoleConfig {
-  readonly syncUrl: string;
-  readonly onOpen: (send: Sync["send"]) => void;
-  readonly onMessage: (message: Uint8Array, send: Sync["send"]) => void;
+// HLC
+export interface Clock {
+  readonly get: () => Timestamp;
+  readonly save: (timestamp: Timestamp) => Result<void, SqliteError>;
 }
 
-export const createWebSocketSync: CreateSync = (_deps) => (config) => {
-  const sync: Sync = {
-    send: (message) => {
-      /**
-       * We don't need an in-memory queue; apps can be offline for a long time,
-       * and mutations are stored in SQLite. Dropped CRDT messages are synced
-       * when the web socket connection is open.
-       */
-      if (socket.getReadyState() !== "open") return;
-      socket.send(message);
-    },
+export const createClock =
+  (deps: RandomBytesDep & SqliteDep) =>
+  (initialTimestamp = createInitialTimestamp(deps)): Clock => {
+    let currentTimestamp = initialTimestamp;
+
+    return {
+      get: () => currentTimestamp,
+      save: (timestamp) => {
+        currentTimestamp = timestamp;
+
+        const timestampString = timestampToTimestampString(timestamp);
+        const result = deps.sqlite.exec(sql.prepared`
+          update evolu_config set "clock" = ${timestampString};
+        `);
+        if (!result.ok) return result;
+
+        return ok();
+      },
+    };
   };
 
-  const socket = createWebSocket(config.syncUrl, {
-    binaryType: "arraybuffer",
-    onOpen: () => {
-      config.onOpen(sync.send);
-    },
-    onMessage: (data) => {
-      if (data instanceof ArrayBuffer) {
-        const messages = new Uint8Array(data);
-        config.onMessage(messages, sync.send);
-      }
-    },
-  });
+interface GetSyncOwnerDep {
+  readonly getSyncOwner: (ownerId: OwnerId) => SyncOwner | null;
+}
+
+export interface ClientStorage extends Storage, BaseSqliteStorage {}
+
+export interface ClientStorageDep {
+  readonly storage: ClientStorage;
+}
+
+const createClientStorage =
+  (
+    deps: ClockDep &
+      GetSyncOwnerDep &
+      RandomDep &
+      SqliteDep &
+      SymmetricCryptoDep &
+      TimeDep &
+      TimestampConfigDep &
+      PostMessageDep,
+  ) =>
+  (config: {
+    onError: (
+      error:
+        | ProtocolInvalidDataError
+        | ProtocolTimestampMismatchError
+        | SqliteError
+        | SymmetricCryptoDecryptError
+        | TimestampCounterOverflowError
+        | TimestampDriftError
+        | TimestampTimeOutOfRangeError,
+    ) => void;
+    onReceive: () => void;
+  }): Result<ClientStorage, SqliteError> => {
+    const sqliteStorageBase = createBaseSqliteStorage(deps)({
+      onStorageError: config.onError,
+      isOwnerWithinQuota: constTrue, // Clients don't have quota limits
+    });
+
+    // TODO: Mutex per OwnerId
+    const mutex = createMutex();
+
+    const storage: ClientStorage = {
+      ...sqliteStorageBase,
+
+      // Not implemented yet.
+      validateWriteKey: constFalse,
+      setWriteKey: constFalse,
+
+      writeMessages: async (ownerIdBytes, encryptedMessages) => {
+        const ownerId = ownerIdBytesToOwnerId(ownerIdBytes);
+
+        // Everything is sync now, but we will need async crypto in the future.
+        const writeResult = await mutex.withLock<
+          boolean,
+          | AbortError
+          | ProtocolInvalidDataError
+          | ProtocolTimestampMismatchError
+          | SqliteError
+          | SymmetricCryptoDecryptError
+          | TimestampCounterOverflowError
+          | TimestampDriftError
+          | TimestampTimeOutOfRangeError
+          // eslint-disable-next-line @typescript-eslint/require-await
+        >(async () => {
+          const owner = deps.getSyncOwner(ownerId);
+          // Owner can be removed during syncing.
+          // `ok(true)` means success, we just skipped the write.
+          if (!owner) return ok(true);
+
+          // TODO: Add quota checking for collaborative scenarios.
+          // When receiving messages from other owners via relay broadcast,
+          // check if this owner is within quota before accepting the data.
+          // This prevents an owner from exceeding storage limits when receiving
+          // data shared by other collaborators.
+
+          const messages: Array<CrdtMessage> = [];
+
+          for (const message of encryptedMessages) {
+            const change = decryptAndDecodeDbChange(deps)(
+              message,
+              owner.encryptionKey,
+            );
+            if (!change.ok) return change;
+
+            messages.push({
+              timestamp: message.timestamp,
+              change: change.value,
+            });
+          }
+
+          const transaction = deps.sqlite.transaction(() => {
+            let clockTimestamp = deps.clock.get();
+
+            for (const message of messages) {
+              const nextTimestamp = receiveTimestamp(deps)(
+                clockTimestamp,
+                message.timestamp,
+              );
+              if (!nextTimestamp.ok) return nextTimestamp;
+
+              clockTimestamp = nextTimestamp.value;
+            }
+
+            const applyMessagesResult = applyMessages({ ...deps, storage })(
+              owner.id,
+              messages,
+            );
+            if (!applyMessagesResult.ok) return applyMessagesResult;
+
+            // // Apply local mutations atomically with approved messages
+            // for (const change of localMutations) {
+            //   const result = applyLocalOnlyChange(deps)(change);
+            //   if (!result.ok) return result;
+            // }
+
+            return deps.clock.save(clockTimestamp);
+          });
+
+          if (!transaction.ok) return transaction;
+
+          return ok(true);
+        })();
+
+        if (!writeResult.ok) {
+          if (writeResult.error.type !== "AbortError") {
+            config.onError(writeResult.error);
+          }
+          return err<StorageWriteError>({ type: "StorageWriteError", ownerId });
+        }
+
+        config.onReceive();
+
+        return ok();
+      },
+
+      readDbChange: (ownerId, timestamp) => {
+        const owner = deps.getSyncOwner(ownerIdBytesToOwnerId(ownerId));
+        // Owner can be removed to stop syncing.
+        if (!owner) return null;
+
+        const result = deps.sqlite.exec<{
+          table: string;
+          id: IdBytes;
+          column: string;
+          value: SqliteValue;
+        }>(sql`
+          select "table", "id", "column", "value"
+          from evolu_history
+          where "ownerId" = ${ownerId} and "timestamp" = ${timestamp};
+        `);
+        if (!result.ok) {
+          config.onError(result.error);
+          return null;
+        }
+
+        const { rows } = result.value;
+        assert(rows.length > 0, "Rows must not be empty");
+
+        const { table, id } = rows[0];
+        const values: Record<string, SqliteValue> = {};
 
-  return sync;
+        for (const r of rows) {
+          assert(r.table === table, "All rows must have the same table");
+          assert(eqArrayNumber(r.id, id), "All rows must have the same Id");
+          values[r.column] = r.value;
+        }
+
+        const message: CrdtMessage = {
+          timestamp: timestampBytesToTimestamp(timestamp),
+          change: {
+            table: rows[0].table,
+            id: idBytesToId(rows[0].id),
+            values,
+          },
+        };
+
+        return encodeAndEncryptDbChange(deps)(message, owner.encryptionKey);
+      },
+    };
+
+    return ok(storage);
+  };
+
+type TransportKey = string & Brand<"TransportKey">;
+
+/** Creates a unique identifier for a transport configuration. */
+const createTransportKey = (transportConfig: OwnerTransport): TransportKey => {
+  return `${transportConfig.type}:${transportConfig.url}` as TransportKey;
 };
 
+export const applyLocalOnlyChange =
+  (deps: SqliteDep & TimeDep) =>
+  (change: MutationChange): Result<void, SqliteError> => {
+    const dbChange: DbChange = {
+      table: change.table,
+      id: change.id,
+      values: change.values,
+    };
+
+    const isDeletion =
+      "isDeleted" in dbChange.values && dbChange.values.isDeleted === 1;
+
+    if (isDeletion) {
+      const result = deps.sqlite.exec(sql`
+        delete from ${sql.identifier(dbChange.table)}
+        where id = ${dbChange.id};
+      `);
+      if (!result.ok) return result;
+    } else {
+      const date = new Date(deps.time.now()).toISOString();
+
+      for (const [column, value] of objectToEntries(dbChange.values)) {
+        const result = deps.sqlite.exec(sql.prepared`
+          insert into ${sql.identifier(dbChange.table)}
+            ("id", ${sql.identifier(column)}, createdAt, updatedAt)
+          values (${dbChange.id}, ${value}, ${date}, ${date})
+          on conflict ("id") do update
+            set
+              ${sql.identifier(column)} = ${value},
+              updatedAt = ${date};
+        `);
+        if (!result.ok) return result;
+      }
+    }
+
+    return ok();
+  };
+
+export const applyMessages =
+  (deps: ClientStorageDep & ClockDep & RandomDep & SqliteDep) =>
+  (
+    ownerId: OwnerId,
+    messages: ReadonlyArray<CrdtMessage>,
+  ): Result<void, SqliteError> => {
+    const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
+
+    for (const message of messages) {
+      const result1 = applyMessageToAppTable(deps)(ownerIdBytes, message);
+      if (!result1.ok) return result1;
+
+      const result2 = applyMessageToTimestampAndHistoryTables(deps)(
+        ownerIdBytes,
+        message,
+      );
+      if (!result2.ok) return result2;
+    }
+
+    return ok();
+  };
+
+const applyMessageToAppTable =
+  (deps: SqliteDep) =>
+  (ownerId: OwnerIdBytes, message: CrdtMessage): Result<void, SqliteError> => {
+    const timestamp = timestampToTimestampBytes(message.timestamp);
+    const updatedAt = new Date(message.timestamp.millis).toISOString();
+
+    for (const [column, value] of objectToEntries(message.change.values)) {
+      const result = deps.sqlite.exec(sql.prepared`
+        with
+          existingTimestamp as (
+            select 1
+            from evolu_history
+            where
+              "ownerId" = ${ownerId}
+              and "table" = ${message.change.table}
+              and "id" = ${idToIdBytes(message.change.id)}
+              and "column" = ${column}
+              and "timestamp" >= ${timestamp}
+            limit 1
+          )
+        insert into ${sql.identifier(message.change.table)}
+          ("id", ${sql.identifier(column)}, updatedAt)
+        select ${message.change.id}, ${value}, ${updatedAt}
+        where not exists (select 1 from existingTimestamp)
+        on conflict ("id") do update
+          set
+            ${sql.identifier(column)} = ${value},
+            updatedAt = ${updatedAt}
+          where not exists (select 1 from existingTimestamp);
+      `);
+
+      if (!result.ok) return result;
+    }
+
+    return ok();
+  };
+
+export const applyMessageToTimestampAndHistoryTables =
+  (deps: ClientStorageDep & SqliteDep) =>
+  (ownerId: OwnerIdBytes, message: CrdtMessage): Result<void, SqliteError> => {
+    const timestamp = timestampToTimestampBytes(message.timestamp);
+    const id = idToIdBytes(message.change.id);
+
+    const result = deps.storage.insertTimestamp(ownerId, timestamp);
+    if (!result.ok) return result;
+
+    for (const [column, value] of Object.entries(message.change.values)) {
+      const result = deps.sqlite.exec(sql.prepared`
+        insert into evolu_history
+          ("ownerId", "table", "id", "column", "value", "timestamp")
+        values
+          (
+            ${ownerId},
+            ${message.change.table},
+            ${id},
+            ${column},
+            ${value},
+            ${timestamp}
+          )
+        on conflict do nothing;
+      `);
+      if (!result.ok) return result;
+    }
+
+    return ok();
+  };
+
 /**
+ * TODO: Rework for the new owners API.
+ *
  * The possible states of a synchronization process. The `SyncState` can be one
  * of the following:
  *