cojson 0.20.17 → 0.20.19

package/src/storage/storageAsync.ts

@@ -267,16 +267,26 @@ export class StorageApiAsync implements StorageAPI {
 
   storeQueue = new StoreQueue();
 
-  async store(msg: NewContentMessage, correctionCallback: CorrectionCallback) {
+  async store(
+    msg: NewContentMessage,
+    correctionCallback: CorrectionCallback,
+    done?: () => void,
+  ) {
     /**
      * 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(msg, correctionCallback);
+    this.storeQueue.push(msg, correctionCallback, done);
 
-    this.storeQueue.processQueue(async (data, correctionCallback) => {
+    this.storeQueue.processQueue(async (data, correctionCallback, done) => {
       this.interruptEraser("store");
-      return this.storeSingle(data, correctionCallback);
+      const success = await this.storeSingle(data, correctionCallback);
+
+      if (success) {
+        done?.();
+      }
+
+      return success;
     });
   }
 

package/src/storage/storageSync.ts

@@ -300,8 +300,18 @@ export class StorageApiSync implements StorageAPI {
     pushCallback(contentMessage);
   }
 
-  store(msg: NewContentMessage, correctionCallback: CorrectionCallback) {
-    return this.storeSingle(msg, correctionCallback);
+  store(
+    msg: NewContentMessage,
+    correctionCallback: CorrectionCallback,
+    done?: () => void,
+  ) {
+    const success = this.storeSingle(msg, correctionCallback);
+
+    if (success) {
+      done?.();
+    }
+
+    return success;
   }
 
   /**

package/src/storage/types.ts

@@ -60,7 +60,19 @@ export interface StorageAPI {
     callback: (data: NewContentMessage) => void,
     done?: (found: boolean) => void,
   ): void;
-  store(data: NewContentMessage, handleCorrection: CorrectionCallback): void;
+  /**
+   * Stores the content. `done` is invoked only after the content is durably
+   * stored (including any correction round-trip). It is NOT invoked when the
+   * write fails or is dropped — callers rely on that to detect content that
+   * was sent to peers but never persisted. Depending on the implementation,
+   * done may fire synchronously before store() returns (sync storage) or
+   * later (async queue).
+   */
+  store(
+    data: NewContentMessage,
+    handleCorrection: CorrectionCallback,
+    done?: () => void,
+  ): void;
 
   streamingQueue?: StorageStreamingQueue;
 

package/src/sync.ts

@@ -53,6 +53,11 @@ export type KnownStateMessage = {
   asDependencyOf?: RawCoID;
 } & CoValueKnownState;
 
+export type LocalStoreDurabilityListener = (
+  hasPending: boolean,
+  sessionID: SessionID,
+) => void;
+
 export type NewContentMessage = {
   action: "content";
   id: RawCoID;
@@ -805,6 +810,15 @@ export class SyncManager {
   }
 
   trySendToPeer(peer: PeerState, msg: SyncMessage) {
+    if (msg.action === "content") {
+      // Content leaves the node from several paths (local-transaction sync,
+      // reconnection reconciliation, corrections). This is the single choke
+      // point for all of them, so the durability window is opened here: if any
+      // local store is still pending when content goes out, the session must
+      // be marked unsafe to reuse until storage drains.
+      this.openLocalStoreDurabilityWindow();
+    }
+
     return peer.pushOutgoingMessage(msg);
   }
 
@@ -1424,10 +1438,62 @@ export class SyncManager {
   syncLocalTransaction = this.syncQueue.syncTransaction;
   trackDirtyCoValues = this.syncQueue.trackDirtyCoValues;
 
+  /**
+   * Tracks locally-created content that has been handed to async storage but
+   * is not yet durably stored. If such content is also sent to a peer and the
+   * process crashes before the write completes, local storage ends up behind
+   * what the server received for this session — reusing the session after
+   * restart would then fork its hash chain. The listener lets the platform
+   * layer mark the session as unsafe to reuse while that window is open.
+   *
+   * With synchronous storage the store completes inline, the counter is back
+   * to 0 before any send, and the listener never fires.
+   *
+   * Exceptions thrown by the listener are caught and logged so they can't
+   * disrupt the sync/store flow.
+   */
+  onLocalStoreDurabilityChange?: LocalStoreDurabilityListener;
+  private pendingLocalStores = 0;
+  private localStoreDurabilityWindowOpen = false;
+
+  private emitLocalStoreDurabilityChange(hasPending: boolean) {
+    try {
+      this.onLocalStoreDurabilityChange?.(
+        hasPending,
+        this.local.currentSessionID,
+      );
+    } catch (err) {
+      logger.error("Error in onLocalStoreDurabilityChange listener", { err });
+    }
+  }
+
+  private handleLocalStoreDone = () => {
+    this.pendingLocalStores--;
+
+    if (this.pendingLocalStores === 0 && this.localStoreDurabilityWindowOpen) {
+      this.localStoreDurabilityWindowOpen = false;
+      this.emitLocalStoreDurabilityChange(false);
+    }
+  };
+
+  private openLocalStoreDurabilityWindow() {
+    if (this.pendingLocalStores > 0 && !this.localStoreDurabilityWindowOpen) {
+      this.localStoreDurabilityWindowOpen = true;
+      this.emitLocalStoreDurabilityChange(true);
+    }
+  }
+
   syncContent(content: NewContentMessage) {
     const coValue = this.local.getCoValue(content.id);
 
-    this.storeContent(content);
+    if (this.local.storage) {
+      // A per-message done callback is used instead of storage.waitForSync
+      // because waitForSync resolves on known-state coverage (which can also
+      // happen on deletion/erasure) and allocates a promise + subscription per
+      // wait — done fires only on a durable write of exactly this content.
+      this.pendingLocalStores++;
+      this.storeContent(content, this.handleLocalStoreDone);
+    }
 
     this.trackSyncState(coValue.id);
 
@@ -1498,7 +1564,7 @@ export class SyncManager {
     }
   }
 
-  private storeContent(content: NewContentMessage) {
+  private storeContent(content: NewContentMessage, onStored?: () => void) {
     const storage = this.local.storage;
 
     if (!storage) return;
@@ -1513,22 +1579,26 @@ export class SyncManager {
 
     // Try to store the content as-is for performance
     // In case that some transactions are missing, a correction will be requested, but it's an edge case
-    storage.store(content, (correction) => {
-      if (!value.verified) {
-        logger.error(
-          "Correction requested for a CoValue with no verified content",
-          {
-            id: content.id,
-            content: getContenDebugInfo(content),
-            correction,
-            state: value.loadingState,
-          },
-        );
-        return undefined;
-      }
+    storage.store(
+      content,
+      (correction) => {
+        if (!value.verified) {
+          logger.error(
+            "Correction requested for a CoValue with no verified content",
+            {
+              id: content.id,
+              content: getContenDebugInfo(content),
+              correction,
+              state: value.loadingState,
+            },
+          );
+          return undefined;
+        }
 
-      return value.newContentSince(correction);
-    });
+        return value.newContentSince(correction);
+      },
+      onStored,
+    );
   }
 
   /**

package/src/tests/ClockOffset.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, test } from "vitest";
+import { ClockOffset } from "../ClockOffset.js";
+
+function makeRng(seed: number) {
+  let state = seed >>> 0;
+  return () => {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    return ((state >>> 0) / 0xffffffff) * 2 - 1;
+  };
+}
+
+describe("ClockOffset", () => {
+  test("currentOffset() returns 0 before any samples are ingested", () => {
+    const clockOffset = new ClockOffset();
+
+    expect(clockOffset.currentOffset()).toBe(0);
+  });
+
+  test("sampleCount() reports sliding window size capped at windowSize", () => {
+    const windowSize = 4;
+    const clockOffset = new ClockOffset({
+      windowSize,
+      // Keep the outlier gate wide enough to accept the spread of samples
+      // we feed below; the point of this test is the window count, not
+      // outlier rejection.
+      outlierThresholdMs: 10_000,
+    });
+
+    expect(clockOffset.sampleCount()).toBe(0);
+
+    for (let i = 0; i < 3; i++) {
+      clockOffset.addSample({
+        serverTime: 1_000 + i,
+        localReceiveTime: 1_000,
+      });
+    }
+    expect(clockOffset.sampleCount()).toBe(3);
+
+    for (let i = 0; i < windowSize + 2; i++) {
+      clockOffset.addSample({
+        serverTime: 2_000 + i,
+        localReceiveTime: 2_000,
+      });
+    }
+    expect(clockOffset.sampleCount()).toBe(windowSize);
+  });
+
+  test("after a single sample, currentOffset() reflects serverTime - localReceiveTime", () => {
+    const clockOffset = new ClockOffset();
+
+    clockOffset.addSample({ serverTime: 10_500, localReceiveTime: 10_000 });
+
+    expect(clockOffset.currentOffset()).toBe(500);
+  });
+
+  test("converges to within a small tolerance of the true offset under bounded jitter", () => {
+    // True offset is 1000 ms; each sample has jitter of +/- 50 ms. The tolerance
+    // of 60 ms is chosen to be slightly larger than the jitter amplitude so the
+    // test does not assume a specific estimator (mean / median / trimmed mean
+    // would all satisfy it), but is tight enough to prove convergence is real.
+    const clockOffset = new ClockOffset();
+    const rng = makeRng(42);
+    const trueOffset = 1000;
+
+    for (let i = 0; i < 64; i++) {
+      const jitter = rng() * 50;
+      const localReceiveTime = 1_000_000 + i * 100;
+      const serverTime = localReceiveTime + trueOffset + jitter;
+      clockOffset.addSample({ serverTime, localReceiveTime });
+    }
+
+    expect(clockOffset.currentOffset()).toBeGreaterThan(trueOffset - 60);
+    expect(clockOffset.currentOffset()).toBeLessThan(trueOffset + 60);
+  });
+
+  test("a single huge outlier does not meaningfully move the estimate", () => {
+    const clockOffset = new ClockOffset();
+    const trueOffset = 1000;
+
+    // Fill the window with clean samples near offset=1000.
+    for (let i = 0; i < 32; i++) {
+      const localReceiveTime = 2_000_000 + i * 100;
+      clockOffset.addSample({
+        serverTime: localReceiveTime + trueOffset,
+        localReceiveTime,
+      });
+    }
+
+    const before = clockOffset.currentOffset();
+
+    // One extreme sample — offset would be ~100_000 if taken at face value.
+    clockOffset.addSample({
+      serverTime: 2_000_000 + 32 * 100 + 100_000,
+      localReceiveTime: 2_000_000 + 32 * 100,
+    });
+
+    const after = clockOffset.currentOffset();
+
+    expect(Math.abs(after - trueOffset)).toBeLessThan(50);
+    expect(Math.abs(after - before)).toBeLessThan(50);
+  });
+
+  test("samples beyond maxAbsOffsetMs are ignored entirely", () => {
+    const clockOffset = new ClockOffset({ maxAbsOffsetMs: 5000 });
+
+    clockOffset.addSample({ serverTime: 10_200, localReceiveTime: 10_000 });
+    const before = clockOffset.currentOffset();
+
+    // Implied offset is 10_000_000 ms — well beyond the 5000 ms cap.
+    clockOffset.addSample({
+      serverTime: 20_000_000,
+      localReceiveTime: 10_000_000,
+    });
+
+    expect(clockOffset.currentOffset()).toBe(before);
+  });
+
+  test("sliding window drops old samples once newer ones fill it", () => {
+    const clockOffset = new ClockOffset({ windowSize: 10 });
+
+    // Ten samples establishing offset ~500.
+    for (let i = 0; i < 10; i++) {
+      const localReceiveTime = 3_000_000 + i * 100;
+      clockOffset.addSample({
+        serverTime: localReceiveTime + 500,
+        localReceiveTime,
+      });
+    }
+
+    // Twenty samples at offset ~2000 — more than the window, so the old
+    // offset=500 samples should be fully evicted.
+    for (let i = 0; i < 20; i++) {
+      const localReceiveTime = 3_100_000 + i * 100;
+      clockOffset.addSample({
+        serverTime: localReceiveTime + 2000,
+        localReceiveTime,
+      });
+    }
+
+    expect(clockOffset.currentOffset()).toBeGreaterThan(1950);
+    expect(clockOffset.currentOffset()).toBeLessThan(2050);
+  });
+
+  test("a hostile peer's single bad sample does not poison later estimates", () => {
+    const clockOffset = new ClockOffset();
+    const trueOffset = 1000;
+
+    // Warm-up with good samples.
+    for (let i = 0; i < 16; i++) {
+      const localReceiveTime = 4_000_000 + i * 100;
+      clockOffset.addSample({
+        serverTime: localReceiveTime + trueOffset,
+        localReceiveTime,
+      });
+    }
+
+    // Hostile sample — way off.
+    clockOffset.addSample({
+      serverTime: 4_000_000 + 16 * 100 + 500_000,
+      localReceiveTime: 4_000_000 + 16 * 100,
+    });
+
+    // More good samples after the attack.
+    for (let i = 17; i < 48; i++) {
+      const localReceiveTime = 4_000_000 + i * 100;
+      clockOffset.addSample({
+        serverTime: localReceiveTime + trueOffset,
+        localReceiveTime,
+      });
+    }
+
+    expect(clockOffset.currentOffset()).toBeGreaterThan(trueOffset - 25);
+    expect(clockOffset.currentOffset()).toBeLessThan(trueOffset + 25);
+  });
+});

package/src/tests/SQLiteClientAsync.test.ts

@@ -2,6 +2,15 @@ import { beforeEach, describe, expect, test } from "vitest";
 import { getDbPath } from "./testStorage.js";
 import { setupTestNode } from "./testUtils.js";
 import { DBClientInterfaceAsync } from "../exports.js";
+import type { Transaction } from "../coValueCore/verifiedState.js";
+
+function makeTrustingTransaction(changes: string) {
+  return {
+    privacy: "trusting",
+    madeAt: 0,
+    changes,
+  } as unknown as Transaction;
+}
 
 describe("SQLiteClientAsync", () => {
   describe("transaction", () => {
@@ -50,18 +59,12 @@ describe("SQLiteClientAsync", () => {
           signature: `signature_z0`,
         });
       });
-      // Second transaction fails (duplicate primary key)
+      // Second transaction fails
       await expect(
-        dbClient.transaction(async (tx) => {
-          return tx.addSignatureAfter({
-            sessionRowID: 0,
-            idx: 0,
-            signature: `signature_z0`,
-          });
+        dbClient.transaction(async () => {
+          throw new Error("transaction failed");
         }),
-      ).rejects.toThrow(
-        /UNIQUE constraint failed: signatureAfter\.ses, signatureAfter\.idx/,
-      );
+      ).rejects.toThrow("transaction failed");
       // Third transaction succeeds
       await dbClient.transaction(async (tx) => {
         return tx.addSignatureAfter({
@@ -71,5 +74,47 @@ describe("SQLiteClientAsync", () => {
         });
       });
     });
+
+    test("addTransaction overwrites an orphan row at the same (ses, idx)", async () => {
+      // Simulates a row left behind by an interrupted write transaction:
+      // the session row was rolled back but the transaction row persisted.
+      await dbClient.transaction(async (tx) => {
+        return tx.addTransaction(1, 0, makeTrustingTransaction("orphan"));
+      });
+
+      await expect(
+        dbClient.transaction(async (tx) => {
+          return tx.addTransaction(1, 0, makeTrustingTransaction("recovered"));
+        }),
+      ).resolves.not.toThrow();
+
+      const txs = await dbClient.getNewTransactionInSession(1, 0, 0);
+      expect(txs).toHaveLength(1);
+      expect(txs[0]?.tx).toEqual(makeTrustingTransaction("recovered"));
+    });
+
+    test("addSignatureAfter overwrites an orphan row at the same (ses, idx)", async () => {
+      await dbClient.transaction(async (tx) => {
+        return tx.addSignatureAfter({
+          sessionRowID: 1,
+          idx: 0,
+          signature: "signature_zorphan",
+        });
+      });
+
+      await expect(
+        dbClient.transaction(async (tx) => {
+          return tx.addSignatureAfter({
+            sessionRowID: 1,
+            idx: 0,
+            signature: "signature_zrecovered",
+          });
+        }),
+      ).resolves.not.toThrow();
+
+      const signatures = await dbClient.getSignatures(1, 0);
+      expect(signatures).toHaveLength(1);
+      expect(signatures[0]?.signature).toBe("signature_zrecovered");
+    });
   });
 });

package/src/tests/StoreQueue.test.ts

@@ -82,11 +82,13 @@ describe("StoreQueue", () => {
         1,
         data1,
         mockCorrectionCallback,
+        undefined,
       );
       expect(mockCallback).toHaveBeenNthCalledWith(
         2,
         data2,
         mockCorrectionCallback,
+        undefined,
       );
     });
 
@@ -192,6 +194,7 @@ describe("StoreQueue", () => {
       expect(mockCallback).toHaveBeenLastCalledWith(
         data3,
         mockCorrectionCallback,
+        undefined,
       );
     });
 
@@ -267,4 +270,21 @@ describe("StoreQueue", () => {
       expect(count).toBe(entries);
     });
   });
+
+  describe("done callbacks", () => {
+    test("passes each entry's done callback to the processing callback", async () => {
+      const queue = new StoreQueue();
+      const done1 = vi.fn();
+
+      queue.push(createMockNewContentMessage("co_z1"), () => undefined, done1);
+      queue.push(createMockNewContentMessage("co_z2"), () => undefined);
+
+      const seen: Array<(() => void) | undefined> = [];
+      await queue.processQueue(async (_data, _correction, done) => {
+        seen.push(done);
+      });
+
+      expect(seen).toEqual([done1, undefined]);
+    });
+  });
 });