cojson 0.16.3 → 0.16.5

package/src/queue/LocalTransactionsSyncQueue.ts

@@ -0,0 +1,96 @@
+import {
+  addTransactionToContentMessage,
+  createContentMessage,
+} from "../coValueContentMessage.js";
+import { Transaction, VerifiedState } from "../coValueCore/verifiedState.js";
+import { Signature } from "../crypto/crypto.js";
+import { SessionID } from "../ids.js";
+import { NewContentMessage } from "../sync.js";
+import { LinkedList } from "./LinkedList.js";
+
+/**
+ * This queue is used to batch the sync of local transactions while preserving the order of updates between CoValues.
+ *
+ * We need to preserve the order of updates between CoValues to keep the state always consistent in case of shutdown in the middle of a sync.
+ *
+ * Examples:
+ * 1. When we extend a Group we need to always ensure that the parent group is persisted before persisting the extension transaction.
+ * 2. If we do multiple updates on the same CoMap, the updates will be batched because it's safe to do so.
+ */
+export class LocalTransactionsSyncQueue {
+  private readonly queue = new LinkedList<NewContentMessage>();
+
+  constructor(private readonly sync: (content: NewContentMessage) => void) {}
+
+  syncHeader = (coValue: VerifiedState) => {
+    const lastPendingSync = this.queue.tail?.value;
+
+    if (lastPendingSync?.id === coValue.id) {
+      return;
+    }
+
+    this.enqueue(createContentMessage(coValue.id, coValue.header));
+  };
+
+  syncTransaction = (
+    coValue: VerifiedState,
+    transaction: Transaction,
+    sessionID: SessionID,
+    signature: Signature,
+    txIdx: number,
+  ) => {
+    const lastPendingSync = this.queue.tail?.value;
+    const lastSignatureIdx = coValue.getLastSignatureCheckpoint(sessionID);
+    const isSignatureCheckpoint =
+      lastSignatureIdx > -1 && lastSignatureIdx === txIdx - 1;
+
+    if (lastPendingSync?.id === coValue.id && !isSignatureCheckpoint) {
+      addTransactionToContentMessage(
+        lastPendingSync,
+        transaction,
+        sessionID,
+        signature,
+        txIdx,
+      );
+
+      return;
+    }
+
+    const content = createContentMessage(coValue.id, coValue.header, false);
+
+    addTransactionToContentMessage(
+      content,
+      transaction,
+      sessionID,
+      signature,
+      txIdx,
+    );
+
+    this.enqueue(content);
+  };
+
+  enqueue(content: NewContentMessage) {
+    this.queue.push(content);
+
+    this.processPendingSyncs();
+  }
+
+  private processingSyncs = false;
+  processPendingSyncs() {
+    if (this.processingSyncs) return;
+
+    this.processingSyncs = true;
+
+    queueMicrotask(() => {
+      while (this.queue.head) {
+        const content = this.queue.head.value;
+
+        this.sync(content);
+
+        this.queue.shift();
+      }
+
+      this.processingSyncs = false;
+    });
+  }
+}

package/src/queue/StoreQueue.ts

@@ -1,19 +1,22 @@
+import { CorrectionCallback } from "../exports.js";
 import { logger } from "../logger.js";
-import { CoValueKnownState, NewContentMessage } from "../sync.js";
+import { NewContentMessage } from "../sync.js";
 import { LinkedList } from "./LinkedList.js";
 
 type StoreQueueEntry = {
-  data: NewContentMessage[];
-  correctionCallback: (data: CoValueKnownState) => void;
+  data: NewContentMessage;
+  correctionCallback: CorrectionCallback;
 };
 
 export class StoreQueue {
   private queue = new LinkedList<StoreQueueEntry>();
+  closed = false;
+
+  public push(data: NewContentMessage, correctionCallback: CorrectionCallback) {
+    if (this.closed) {
+      return;
+    }
 
-  public push(
-    data: NewContentMessage[],
-    correctionCallback: (data: CoValueKnownState) => void,
-  ) {
     this.queue.push({ data, correctionCallback });
   }
 
@@ -22,12 +25,13 @@ export class StoreQueue {
   }
 
   processing = false;
+  lastCallback: Promise<unknown> | undefined;
 
   async processQueue(
     callback: (
-      data: NewContentMessage[],
-      correctionCallback: (data: CoValueKnownState) => void,
-    ) => Promise<void>,
+      data: NewContentMessage,
+      correctionCallback: CorrectionCallback,
+    ) => Promise<unknown>,
   ) {
     if (this.processing) {
       return;
@@ -41,16 +45,22 @@ export class StoreQueue {
       const { data, correctionCallback } = entry;
 
       try {
-        await callback(data, correctionCallback);
+        this.lastCallback = callback(data, correctionCallback);
+        await this.lastCallback;
       } catch (err) {
         logger.error("Error processing message in store queue", { err });
       }
     }
 
+    this.lastCallback = undefined;
     this.processing = false;
   }
 
-  drain() {
+  close() {
+    this.closed = true;
+
     while (this.pull()) {}
+
+    return this.lastCallback;
   }
 }

package/src/storage/storageAsync.ts

@@ -1,11 +1,15 @@
+import {
+  createContentMessage,
+  exceedsRecommendedSize,
+  getTransactionSize,
+} from "../coValueContentMessage.js";
 import {
   type CoValueCore,
-  MAX_RECOMMENDED_TX_SIZE,
   type RawCoID,
   type SessionID,
   type StorageAPI,
+  logger,
 } from "../exports.js";
-import { getPriorityFromHeader } from "../priority.js";
 import { StoreQueue } from "../queue/StoreQueue.js";
 import {
   CoValueKnownState,
@@ -13,8 +17,13 @@ import {
   emptyKnownState,
 } from "../sync.js";
 import { StorageKnownState } from "./knownState.js";
-import { collectNewTxs, getDependedOnCoValues } from "./syncUtils.js";
+import {
+  collectNewTxs,
+  getDependedOnCoValues,
+  getNewTransactionsSize,
+} from "./syncUtils.js";
 import type {
+  CorrectionCallback,
   DBClientInterfaceAsync,
   SignatureAfterRow,
   StoredCoValueRow,
@@ -82,6 +91,7 @@ export class StorageApiAsync implements StorageAPI {
     );
 
     const knownState = this.knwonStates.getKnownState(coValueRow.id);
+    knownState.header = true;
 
     for (const sessionRow of allCoValueSessions) {
       knownState.sessions[sessionRow.sessionID] = sessionRow.lastIdx;
@@ -89,13 +99,7 @@ export class StorageApiAsync implements StorageAPI {
 
     this.loadedCoValues.add(coValueRow.id);
 
-    let contentMessage = {
-      action: "content",
-      id: coValueRow.id,
-      header: coValueRow.header,
-      new: {},
-      priority: getPriorityFromHeader(coValueRow.header),
-    } as NewContentMessage;
+    let contentMessage = createContentMessage(coValueRow.id, coValueRow.header);
 
     if (contentStreaming) {
       contentMessage.expectContentUntil = knownState["sessions"];
@@ -136,13 +140,10 @@ export class StorageApiAsync implements StorageAPI {
             contentMessage,
             callback,
           );
-          contentMessage = {
-            action: "content",
-            id: coValueRow.id,
-            header: coValueRow.header,
-            new: {},
-            priority: getPriorityFromHeader(coValueRow.header),
-          } satisfies NewContentMessage;
+          contentMessage = createContentMessage(
+            coValueRow.id,
+            coValueRow.header,
+          );
         }
       }
     }
@@ -194,33 +195,64 @@ export class StorageApiAsync implements StorageAPI {
 
   storeQueue = new StoreQueue();
 
-  async store(
-    msgs: NewContentMessage[],
-    correctionCallback: (data: CoValueKnownState) => void,
-  ) {
+  async store(msg: NewContentMessage, correctionCallback: CorrectionCallback) {
     /**
      * The store operations must be done one by one, because we can't start a new transaction when there
      * is already a transaction open.
      */
-    this.storeQueue.push(msgs, correctionCallback);
+    this.storeQueue.push(msg, correctionCallback);
 
     this.storeQueue.processQueue(async (data, correctionCallback) => {
-      for (const msg of data) {
-        const success = await this.storeSingle(msg, correctionCallback);
+      return this.storeSingle(data, correctionCallback);
+    });
+  }
 
-        if (!success) {
-          // Stop processing the messages for this entry, because the data is out of sync with storage
-          // and the other transactions will be rejected anyway.
-          break;
-        }
+  /**
+   * This function is called when the storage lacks the information required to store the incoming content.
+   *
+   * It triggers a `correctionCallback` to ask the syncManager to provide the missing information.
+   *
+   * The correction is applied immediately, to ensure that, when applicable, the dependent content in the queue won't require additional corrections.
+   */
+  private async handleCorrection(
+    knownState: CoValueKnownState,
+    correctionCallback: CorrectionCallback,
+  ) {
+    const correction = correctionCallback(knownState);
+
+    if (!correction) {
+      logger.error("Correction callback returned undefined", {
+        knownState,
+        correction: correction ?? null,
+      });
+      return false;
+    }
+
+    for (const msg of correction) {
+      const success = await this.storeSingle(msg, (knownState) => {
+        logger.error("Double correction requested", {
+          msg,
+          knownState,
+        });
+        return undefined;
+      });
+
+      if (!success) {
+        return false;
       }
-    });
+    }
+
+    return true;
   }
 
   private async storeSingle(
     msg: NewContentMessage,
-    correctionCallback: (data: CoValueKnownState) => void,
+    correctionCallback: CorrectionCallback,
   ): Promise<boolean> {
+    if (this.storeQueue.closed) {
+      return false;
+    }
+
     const id = msg.id;
     const coValueRow = await this.dbClient.getCoValue(id);
 
@@ -231,8 +263,7 @@ export class StorageApiAsync implements StorageAPI {
       const knownState = emptyKnownState(id as RawCoID);
       this.knwonStates.setKnownState(id, knownState);
 
-      correctionCallback(knownState);
-      return false;
+      return this.handleCorrection(knownState, correctionCallback);
     }
 
     const storedCoValueRowID: number = coValueRow
@@ -276,8 +307,7 @@ export class StorageApiAsync implements StorageAPI {
     this.knwonStates.handleUpdate(id, knownState);
 
     if (invalidAssumptions) {
-      correctionCallback(knownState);
-      return false;
+      return this.handleCorrection(knownState, correctionCallback);
     }
 
     return true;
@@ -290,38 +320,31 @@ export class StorageApiAsync implements StorageAPI {
     storedCoValueRowID: number,
   ) {
     const newTransactions = msg.new[sessionID]?.newTransactions || [];
+    const lastIdx = sessionRow?.lastIdx || 0;
 
-    const actuallyNewOffset =
-      (sessionRow?.lastIdx || 0) - (msg.new[sessionID]?.after || 0);
+    const actuallyNewOffset = lastIdx - (msg.new[sessionID]?.after || 0);
 
     const actuallyNewTransactions = newTransactions.slice(actuallyNewOffset);
 
     if (actuallyNewTransactions.length === 0) {
-      return sessionRow?.lastIdx || 0;
+      return lastIdx;
     }
 
-    let newBytesSinceLastSignature =
-      (sessionRow?.bytesSinceLastSignature || 0) +
-      actuallyNewTransactions.reduce(
-        (sum, tx) =>
-          sum +
-          (tx.privacy === "private"
-            ? tx.encryptedChanges.length
-            : tx.changes.length),
-        0,
-      );
+    let bytesSinceLastSignature = sessionRow?.bytesSinceLastSignature || 0;
+    const newTransactionsSize = getNewTransactionsSize(actuallyNewTransactions);
 
-    const newLastIdx =
-      (sessionRow?.lastIdx || 0) + actuallyNewTransactions.length;
+    const newLastIdx = lastIdx + actuallyNewTransactions.length;
 
     let shouldWriteSignature = false;
 
-    if (newBytesSinceLastSignature > MAX_RECOMMENDED_TX_SIZE) {
+    if (exceedsRecommendedSize(bytesSinceLastSignature, newTransactionsSize)) {
       shouldWriteSignature = true;
-      newBytesSinceLastSignature = 0;
+      bytesSinceLastSignature = 0;
+    } else {
+      bytesSinceLastSignature += newTransactionsSize;
     }
 
-    const nextIdx = sessionRow?.lastIdx || 0;
+    const nextIdx = lastIdx;
 
     if (!msg.new[sessionID]) throw new Error("Session ID not found");
 
@@ -330,7 +353,7 @@ export class StorageApiAsync implements StorageAPI {
       sessionID,
       lastIdx: newLastIdx,
       lastSignature: msg.new[sessionID].lastSignature,
-      bytesSinceLastSignature: newBytesSinceLastSignature,
+      bytesSinceLastSignature,
     };
 
     const sessionRowID: number = await this.dbClient.addSessionUpdate({
@@ -360,7 +383,6 @@ export class StorageApiAsync implements StorageAPI {
   }
 
   close() {
-    // Drain the store queue
-    this.storeQueue.drain();
+    return this.storeQueue.close();
   }
 }

package/src/storage/storageSync.ts

@@ -1,20 +1,29 @@
 import { UpDownCounter, metrics } from "@opentelemetry/api";
+import {
+  createContentMessage,
+  exceedsRecommendedSize,
+  getTransactionSize,
+} from "../coValueContentMessage.js";
 import {
   CoValueCore,
-  MAX_RECOMMENDED_TX_SIZE,
   RawCoID,
   type SessionID,
   type StorageAPI,
+  logger,
 } from "../exports.js";
-import { getPriorityFromHeader } from "../priority.js";
 import {
   CoValueKnownState,
   NewContentMessage,
   emptyKnownState,
 } from "../sync.js";
 import { StorageKnownState } from "./knownState.js";
-import { collectNewTxs, getDependedOnCoValues } from "./syncUtils.js";
+import {
+  collectNewTxs,
+  getDependedOnCoValues,
+  getNewTransactionsSize,
+} from "./syncUtils.js";
 import type {
+  CorrectionCallback,
   DBClientInterfaceSync,
   SignatureAfterRow,
   StoredCoValueRow,
@@ -84,6 +93,7 @@ export class StorageApiSync implements StorageAPI {
     }
 
     const knownState = this.knwonStates.getKnownState(coValueRow.id);
+    knownState.header = true;
 
     for (const sessionRow of allCoValueSessions) {
       knownState.sessions[sessionRow.sessionID] = sessionRow.lastIdx;
@@ -91,13 +101,7 @@ export class StorageApiSync implements StorageAPI {
 
     this.loadedCoValues.add(coValueRow.id);
 
-    let contentMessage = {
-      action: "content",
-      id: coValueRow.id,
-      header: coValueRow.header,
-      new: {},
-      priority: getPriorityFromHeader(coValueRow.header),
-    } as NewContentMessage;
+    let contentMessage = createContentMessage(coValueRow.id, coValueRow.header);
 
     if (contentStreaming) {
       this.streamingCounter.add(1);
@@ -137,13 +141,10 @@ export class StorageApiSync implements StorageAPI {
             contentMessage,
             callback,
           );
-          contentMessage = {
-            action: "content",
-            id: coValueRow.id,
-            header: coValueRow.header,
-            new: {},
-            priority: getPriorityFromHeader(coValueRow.header),
-          } satisfies NewContentMessage;
+          contentMessage = createContentMessage(
+            coValueRow.id,
+            coValueRow.header,
+          );
 
           // Introduce a delay to not block the main thread
           // for the entire content processing
@@ -189,22 +190,49 @@ export class StorageApiSync implements StorageAPI {
     pushCallback(contentMessage);
   }
 
-  store(
-    msgs: NewContentMessage[],
-    correctionCallback: (data: CoValueKnownState) => void,
+  store(msg: NewContentMessage, correctionCallback: CorrectionCallback) {
+    return this.storeSingle(msg, correctionCallback);
+  }
+
+  /**
+   * This function is called when the storage lacks the information required to store the incoming content.
+   *
+   * It triggers a `correctionCallback` to ask the syncManager to provide the missing information.
+   */
+  private handleCorrection(
+    knownState: CoValueKnownState,
+    correctionCallback: CorrectionCallback,
   ) {
-    for (const msg of msgs) {
-      const success = this.storeSingle(msg, correctionCallback);
+    const correction = correctionCallback(knownState);
+
+    if (!correction) {
+      logger.error("Correction callback returned undefined", {
+        knownState,
+        correction: correction ?? null,
+      });
+      return false;
+    }
+
+    for (const msg of correction) {
+      const success = this.storeSingle(msg, (knownState) => {
+        logger.error("Double correction requested", {
+          msg,
+          knownState,
+        });
+        return undefined;
+      });
 
       if (!success) {
         return false;
       }
     }
+
+    return true;
   }
 
   private storeSingle(
     msg: NewContentMessage,
-    correctionCallback: (data: CoValueKnownState) => void,
+    correctionCallback: CorrectionCallback,
   ): boolean {
     const id = msg.id;
     const coValueRow = this.dbClient.getCoValue(id);
@@ -214,11 +242,9 @@ export class StorageApiSync implements StorageAPI {
 
     if (invalidAssumptionOnHeaderPresence) {
       const knownState = emptyKnownState(id as RawCoID);
-      correctionCallback(knownState);
-
       this.knwonStates.setKnownState(id, knownState);
 
-      return false;
+      return this.handleCorrection(knownState, correctionCallback);
     }
 
     const storedCoValueRowID: number = coValueRow
@@ -258,8 +284,7 @@ export class StorageApiSync implements StorageAPI {
     this.knwonStates.handleUpdate(id, knownState);
 
     if (invalidAssumptions) {
-      correctionCallback(knownState);
-      return false;
+      return this.handleCorrection(knownState, correctionCallback);
     }
 
     return true;
@@ -272,35 +297,29 @@ export class StorageApiSync implements StorageAPI {
     storedCoValueRowID: number,
   ) {
     const newTransactions = msg.new[sessionID]?.newTransactions || [];
+    const lastIdx = sessionRow?.lastIdx || 0;
 
-    const actuallyNewOffset =
-      (sessionRow?.lastIdx || 0) - (msg.new[sessionID]?.after || 0);
+    const actuallyNewOffset = lastIdx - (msg.new[sessionID]?.after || 0);
 
     const actuallyNewTransactions = newTransactions.slice(actuallyNewOffset);
 
     if (actuallyNewTransactions.length === 0) {
-      return sessionRow?.lastIdx || 0;
+      return lastIdx;
     }
 
-    let newBytesSinceLastSignature =
-      (sessionRow?.bytesSinceLastSignature || 0) +
-      actuallyNewTransactions.reduce(
-        (sum, tx) =>
-          sum +
-          (tx.privacy === "private"
-            ? tx.encryptedChanges.length
-            : tx.changes.length),
-        0,
-      );
+    let bytesSinceLastSignature = sessionRow?.bytesSinceLastSignature || 0;
+    const newTransactionsSize = getNewTransactionsSize(actuallyNewTransactions);
 
     const newLastIdx =
       (sessionRow?.lastIdx || 0) + actuallyNewTransactions.length;
 
     let shouldWriteSignature = false;
 
-    if (newBytesSinceLastSignature > MAX_RECOMMENDED_TX_SIZE) {
+    if (exceedsRecommendedSize(bytesSinceLastSignature, newTransactionsSize)) {
       shouldWriteSignature = true;
-      newBytesSinceLastSignature = 0;
+      bytesSinceLastSignature = 0;
+    } else {
+      bytesSinceLastSignature += newTransactionsSize;
     }
 
     const nextIdx = sessionRow?.lastIdx || 0;
@@ -312,7 +331,7 @@ export class StorageApiSync implements StorageAPI {
       sessionID,
       lastIdx: newLastIdx,
       lastSignature: msg.new[sessionID].lastSignature,
-      bytesSinceLastSignature: newBytesSinceLastSignature,
+      bytesSinceLastSignature,
     };
 
     const sessionRowID: number = this.dbClient.addSessionUpdate({
@@ -339,5 +358,7 @@ export class StorageApiSync implements StorageAPI {
     return this.knwonStates.waitForSync(id, coValue);
   }
 
-  close() {}
+  close() {
+    return undefined;
+  }
 }

package/src/storage/syncUtils.ts

@@ -1,5 +1,9 @@
+import { getTransactionSize } from "../coValueContentMessage.js";
 import { getDependedOnCoValuesFromRawData } from "../coValueCore/utils.js";
-import type { CoValueHeader } from "../coValueCore/verifiedState.js";
+import type {
+  CoValueHeader,
+  Transaction,
+} from "../coValueCore/verifiedState.js";
 import type { Signature } from "../crypto/crypto.js";
 import type { SessionID } from "../exports.js";
 import type { NewContentMessage } from "../sync.js";
@@ -48,3 +52,7 @@ export function getDependedOnCoValues(
 
   return getDependedOnCoValuesFromRawData(id, header, sessionIDs, transactions);
 }
+
+export function getNewTransactionsSize(newTxs: Transaction[]) {
+  return newTxs.reduce((sum, tx) => sum + getTransactionSize(tx), 0);
+}

package/src/storage/types.ts

@@ -6,6 +6,10 @@ import { Signature } from "../crypto/crypto.js";
 import type { CoValueCore, RawCoID, SessionID } from "../exports.js";
 import { CoValueKnownState, NewContentMessage } from "../sync.js";
 
+export type CorrectionCallback = (
+  correction: CoValueKnownState,
+) => NewContentMessage[] | undefined;
+
 /**
  * The StorageAPI is the interface that the StorageSync and StorageAsync classes implement.
  *
@@ -18,16 +22,13 @@ export interface StorageAPI {
     callback: (data: NewContentMessage) => void,
     done?: (found: boolean) => void,
   ): void;
-  store(
-    data: NewContentMessage[] | undefined,
-    handleCorrection: (correction: CoValueKnownState) => void,
-  ): void;
+  store(data: NewContentMessage, handleCorrection: CorrectionCallback): void;
 
   getKnownState(id: string): CoValueKnownState;
 
   waitForSync(id: string, coValue: CoValueCore): Promise<void>;
 
-  close(): void;
+  close(): Promise<unknown> | undefined;
 }
 
 export type CoValueRow = {