cojson 0.19.22 → 0.20.0

package/src/storage/sqlite/sqliteMigrations.ts

@@ -40,6 +40,13 @@ export const migrations: Record<number, string[]> = {
     );`,
     "CREATE INDEX IF NOT EXISTS idx_unsynced_covalues_co_value_id ON unsynced_covalues(co_value_id);",
   ],
+  5: [
+    `CREATE TABLE IF NOT EXISTS deletedCoValues (
+      coValueID TEXT PRIMARY KEY,
+      status INTEGER NOT NULL DEFAULT 0
+    ) WITHOUT ROWID;`,
+    "CREATE INDEX IF NOT EXISTS deletedCoValuesByStatus ON deletedCoValues (status);",
+  ],
 };
 
 type Migration = {

package/src/storage/sqliteAsync/client.ts

@@ -15,6 +15,7 @@ import type {
   StoredSessionRow,
   TransactionRow,
 } from "../types.js";
+import { DeletedCoValueDeletionStatus } from "../types.js";
 import type { SQLiteDatabaseDriverAsync } from "./types.js";
 import type { PeerID } from "../../sync.js";
 
@@ -29,6 +30,10 @@ export type RawTransactionRow = {
   tx: string;
 };
 
+type DeletedCoValueQueueRow = {
+  id: RawCoID;
+};
+
 export function getErrorMessage(error: unknown) {
   return error instanceof Error ? error.message : "Unknown error";
 }
@@ -146,6 +151,76 @@ export class SQLiteClientAsync
     return result.rowID;
   }
 
+  async markCoValueAsDeleted(id: RawCoID) {
+    // Work queue entry. Table only stores the coValueID.
+    // Idempotent by design.
+    await this.db.run(
+      `INSERT INTO deletedCoValues (coValueID) VALUES (?) ON CONFLICT(coValueID) DO NOTHING`,
+      [id],
+    );
+  }
+
+  async eraseCoValueButKeepTombstone(coValueId: RawCoID) {
+    const coValueRow = await this.db.get<RawCoValueRow & { rowID: number }>(
+      "SELECT * FROM coValues WHERE id = ?",
+      [coValueId],
+    );
+
+    if (!coValueRow) {
+      logger.warn(`CoValue ${coValueId} not found, skipping deletion`);
+      return;
+    }
+
+    await this.transaction(async () => {
+      await this.db.run(
+        `DELETE FROM transactions
+       WHERE ses IN (
+         SELECT rowID FROM sessions
+         WHERE coValue = ?
+           AND sessionID NOT LIKE '%$'
+       )`,
+        [coValueRow.rowID],
+      );
+
+      await this.db.run(
+        `DELETE FROM signatureAfter
+       WHERE ses IN (
+         SELECT rowID FROM sessions
+         WHERE coValue = ?
+           AND sessionID NOT LIKE '%$'
+       )`,
+        [coValueRow.rowID],
+      );
+
+      await this.db.run(
+        `DELETE FROM sessions
+       WHERE coValue = ?
+         AND sessionID NOT LIKE '%$'`,
+        [coValueRow.rowID],
+      );
+
+      await this.db.run(
+        `INSERT INTO deletedCoValues (coValueID, status) VALUES (?, ?)
+       ON CONFLICT(coValueID) DO UPDATE SET status=?`,
+        [
+          coValueId,
+          DeletedCoValueDeletionStatus.Done,
+          DeletedCoValueDeletionStatus.Done,
+        ],
+      );
+    });
+  }
+
+  async getAllCoValuesWaitingForDelete(): Promise<RawCoID[]> {
+    const rows = await this.db.query<DeletedCoValueQueueRow>(
+      `SELECT coValueID as id
+       FROM deletedCoValues
+       WHERE status = ?`,
+      [DeletedCoValueDeletionStatus.Pending],
+    );
+    return rows.map((r) => r.id);
+  }
+
   async addSessionUpdate({
     sessionUpdate,
   }: {

package/src/storage/storageAsync.ts

@@ -17,6 +17,7 @@ import {
   setSessionCounter,
 } from "../knownState.js";
 import { StorageKnownState } from "./knownState.js";
+import { DeletedCoValuesEraserScheduler } from "./DeletedCoValuesEraserScheduler.js";
 import {
   collectNewTxs,
   getDependedOnCoValues,
@@ -30,10 +31,15 @@ import type {
   StoredCoValueRow,
   StoredSessionRow,
 } from "./types.js";
+import { isDeleteSessionID } from "../ids.js";
 
 export class StorageApiAsync implements StorageAPI {
   private readonly dbClient: DBClientInterfaceAsync;
 
+  private deletedCoValuesEraserScheduler:
+    | DeletedCoValuesEraserScheduler
+    | undefined;
+  private eraserController: AbortController | undefined;
   /**
    * Keeps track of CoValues that are in memory, to avoid reloading them from storage
    * when it isn't necessary
@@ -114,6 +120,7 @@ export class StorageApiAsync implements StorageAPI {
     callback: (data: NewContentMessage) => void,
     done: (found: boolean) => void,
   ) {
+    this.interruptEraser("load");
     const coValueRow = await this.dbClient.getCoValue(id);
 
     if (!coValueRow) {
@@ -267,10 +274,35 @@ export class StorageApiAsync implements StorageAPI {
     this.storeQueue.push(msg, correctionCallback);
 
     this.storeQueue.processQueue(async (data, correctionCallback) => {
+      this.interruptEraser("store");
       return this.storeSingle(data, correctionCallback);
     });
   }
 
+  private interruptEraser(reason: string) {
+    // Cooperative cancellation: a DB transaction already in progress will complete,
+    // but the eraser loop will stop starting further work at its next abort check.
+    if (this.eraserController) {
+      this.eraserController.abort(reason);
+      this.eraserController = undefined;
+    }
+  }
+
+  async eraseAllDeletedCoValues() {
+    const ids = await this.dbClient.getAllCoValuesWaitingForDelete();
+
+    this.eraserController = new AbortController();
+    const signal = this.eraserController.signal;
+
+    for (const id of ids) {
+      if (signal.aborted) {
+        return;
+      }
+
+      await this.dbClient.eraseCoValueButKeepTombstone(id);
+    }
+  }
+
   /**
    * This function is called when the storage lacks the information required to store the incoming content.
    *
@@ -313,6 +345,7 @@ export class StorageApiAsync implements StorageAPI {
     msg: NewContentMessage,
     correctionCallback: CorrectionCallback,
   ): Promise<boolean> {
+    this.interruptEraser("store");
     if (this.storeQueue.closed) {
       return false;
     }
@@ -342,6 +375,10 @@ export class StorageApiAsync implements StorageAPI {
           sessionID,
         );
 
+        if (this.deletedValues.has(id) && isDeleteSessionID(sessionID)) {
+          await tx.markCoValueAsDeleted(id);
+        }
+
         if (sessionRow) {
           setSessionCounter(
             knownState.sessions,
@@ -445,6 +482,30 @@ export class StorageApiAsync implements StorageAPI {
     return newLastIdx;
   }
 
+  deletedValues = new Set<RawCoID>();
+
+  markDeleteAsValid(id: RawCoID) {
+    this.deletedValues.add(id);
+
+    if (this.deletedCoValuesEraserScheduler) {
+      this.deletedCoValuesEraserScheduler.onEnqueueDeletedCoValue();
+    }
+  }
+
+  enableDeletedCoValuesErasure() {
+    if (this.deletedCoValuesEraserScheduler) return;
+
+    this.deletedCoValuesEraserScheduler = new DeletedCoValuesEraserScheduler({
+      run: async () => {
+        // Async storage: no max-time budgeting; drain to completion when scheduled.
+        await this.eraseAllDeletedCoValues();
+        const remaining = await this.dbClient.getAllCoValuesWaitingForDelete();
+        return { hasMore: remaining.length > 0 };
+      },
+    });
+    this.deletedCoValuesEraserScheduler.scheduleStartupDrain();
+  }
+
   waitForSync(id: string, coValue: CoValueCore) {
     return this.knownStates.waitForSync(id, coValue);
   }
@@ -471,6 +532,7 @@ export class StorageApiAsync implements StorageAPI {
   }
 
   close() {
+    this.deletedCoValuesEraserScheduler?.dispose();
     this.inMemoryCoValues.clear();
     return this.storeQueue.close();
   }

package/src/storage/storageSync.ts

@@ -16,6 +16,7 @@ import {
   emptyKnownState,
   setSessionCounter,
 } from "../knownState.js";
+import { isDeleteSessionID } from "../ids.js";
 import {
   collectNewTxs,
   getDependedOnCoValues,
@@ -29,14 +30,21 @@ import type {
   StoredCoValueRow,
   StoredSessionRow,
 } from "./types.js";
+import { DeletedCoValuesEraserScheduler } from "./DeletedCoValuesEraserScheduler.js";
 import {
   ContentCallback,
   StorageStreamingQueue,
 } from "../queue/StorageStreamingQueue.js";
 import { getPriorityFromHeader } from "../priority.js";
 
+const MAX_DELETE_SCHEDULE_DURATION_MS = 100;
+
 export class StorageApiSync implements StorageAPI {
   private readonly dbClient: DBClientInterfaceSync;
+
+  private deletedCoValuesEraserScheduler:
+    | DeletedCoValuesEraserScheduler
+    | undefined;
   /**
    * Keeps track of CoValues that are in memory, to avoid reloading them from storage
    * when it isn't necessary
@@ -329,6 +337,10 @@ export class StorageApiSync implements StorageAPI {
 
     for (const sessionID of Object.keys(msg.new) as SessionID[]) {
       this.dbClient.transaction((tx) => {
+        if (this.deletedValues.has(id) && isDeleteSessionID(sessionID)) {
+          tx.markCoValueAsDeleted(id);
+        }
+
         const sessionRow = tx.getSingleCoValueSession(
           storedCoValueRowID,
           sessionID,
@@ -433,6 +445,51 @@ export class StorageApiSync implements StorageAPI {
     return newLastIdx;
   }
 
+  deletedValues = new Set<RawCoID>();
+
+  markDeleteAsValid(id: RawCoID) {
+    this.deletedValues.add(id);
+
+    if (this.deletedCoValuesEraserScheduler) {
+      this.deletedCoValuesEraserScheduler.onEnqueueDeletedCoValue();
+    }
+  }
+
+  async eraseAllDeletedCoValues(): Promise<void> {
+    const ids = this.dbClient.getAllCoValuesWaitingForDelete();
+
+    for (const id of ids) {
+      this.dbClient.eraseCoValueButKeepTombstone(id);
+    }
+  }
+
+  enableDeletedCoValuesErasure() {
+    if (this.deletedCoValuesEraserScheduler) return;
+    this.deletedCoValuesEraserScheduler = new DeletedCoValuesEraserScheduler({
+      run: async () =>
+        this.eraseDeletedCoValuesOnceBudgeted(MAX_DELETE_SCHEDULE_DURATION_MS),
+    });
+    this.deletedCoValuesEraserScheduler.scheduleStartupDrain();
+  }
+
+  private eraseDeletedCoValuesOnceBudgeted(budgetMs?: number) {
+    const startedAt = Date.now();
+    const ids = this.dbClient.getAllCoValuesWaitingForDelete();
+
+    for (const id of ids) {
+      // Strict time budget for sync storage to avoid blocking.
+      if (budgetMs && Date.now() - startedAt >= budgetMs) {
+        break;
+      }
+
+      this.dbClient.eraseCoValueButKeepTombstone(id);
+    }
+
+    return {
+      hasMore: this.dbClient.getAllCoValuesWaitingForDelete().length > 0,
+    };
+  }
+
   waitForSync(id: string, coValue: CoValueCore) {
     return this.knownStates.waitForSync(id, coValue);
   }
@@ -461,6 +518,7 @@ export class StorageApiSync implements StorageAPI {
   }
 
   close() {
+    this.deletedCoValuesEraserScheduler?.dispose();
     this.inMemoryCoValues.clear();
     return undefined;
   }

package/src/storage/types.ts

@@ -13,12 +13,43 @@ export type CorrectionCallback = (
   correction: CoValueKnownState,
 ) => NewContentMessage[] | undefined;
 
+/**
+ * Deletion work queue status for `deletedCoValues` (SQLite).
+ *
+ * Stored as an INTEGER in SQLite:
+ * - 0 = pending
+ * - 1 = done
+ */
+export enum DeletedCoValueDeletionStatus {
+  Pending = 0,
+  Done = 1,
+}
+
 /**
  * The StorageAPI is the interface that the StorageSync and StorageAsync classes implement.
  *
  * It uses callbacks instead of promises to have no overhead when using the StorageSync and less overhead when using the StorageAsync.
  */
 export interface StorageAPI {
+  /**
+   * Flags that the coValue delete is valid.
+   *
+   * When the delete tx is stored, the storage will mark the coValue as deleted.
+   */
+  markDeleteAsValid(id: RawCoID): void;
+
+  /**
+   * Enable the background erasure scheduler that drains the `deletedCoValues` work queue.
+   * This is intentionally opt-in and should be activated by `LocalNode`.
+   */
+  enableDeletedCoValuesErasure(): void;
+
+  /**
+   * Batch physical deletion for coValues queued in `deletedCoValues` with status `Pending`.
+   * Must preserve tombstones (header + delete session(s) + their tx/signatures).
+   */
+  eraseAllDeletedCoValues(): Promise<void>;
+
   load(
     id: string,
     // This callback is fired when data is found, might be called multiple times if the content requires streaming (e.g when loading files)
@@ -111,6 +142,13 @@ export interface DBTransactionInterfaceAsync {
     sessionID: SessionID,
   ): Promise<StoredSessionRow | undefined>;
 
+  /**
+   * Persist a "deleted coValue" marker in storage (work queue entry).
+   * This is an enqueue signal: implementations should set status to `Pending`.
+   * This is expected to be idempotent (safe to call repeatedly).
+   */
+  markCoValueAsDeleted(id: RawCoID): Promise<unknown>;
+
   addSessionUpdate({
     sessionUpdate,
     sessionRow,
@@ -146,6 +184,11 @@ export interface DBClientInterfaceAsync {
     header?: CoValueHeader,
   ): Promise<number | undefined>;
 
+  /**
+   * Enumerate all coValue IDs currently pending in the "deleted coValues" work queue.
+   */
+  getAllCoValuesWaitingForDelete(): Promise<RawCoID[]>;
+
   getCoValueSessions(coValueRowId: number): Promise<StoredSessionRow[]>;
 
   getNewTransactionInSession(
@@ -171,6 +214,13 @@ export interface DBClientInterfaceAsync {
 
   stopTrackingSyncState(id: RawCoID): Promise<void>;
 
+  /**
+   * Physical deletion primitive: erase all persisted history for a deleted coValue,
+   * while preserving the tombstone (header + delete session(s)).
+   * Must run inside a single storage transaction.
+   */
+  eraseCoValueButKeepTombstone(coValueID: RawCoID): Promise<unknown>;
+
   /**
    * Get the knownState for a CoValue without loading transactions.
    * Returns undefined if the CoValue doesn't exist.
@@ -186,6 +236,13 @@ export interface DBTransactionInterfaceSync {
     sessionID: SessionID,
   ): StoredSessionRow | undefined;
 
+  /**
+   * Persist a "deleted coValue" marker in storage (work queue entry).
+   * This is an enqueue signal: implementations should set status to `"pending"`.
+   * This is expected to be idempotent (safe to call repeatedly).
+   */
+  markCoValueAsDeleted(id: RawCoID): unknown;
+
   addSessionUpdate({
     sessionUpdate,
     sessionRow,
@@ -216,6 +273,11 @@ export interface DBClientInterfaceSync {
 
   upsertCoValue(id: string, header?: CoValueHeader): number | undefined;
 
+  /**
+   * Enumerate all coValue IDs currently pending in the "deleted coValues" work queue.
+   */
+  getAllCoValuesWaitingForDelete(): RawCoID[];
+
   getCoValueSessions(coValueRowId: number): StoredSessionRow[];
 
   getNewTransactionInSession(
@@ -239,6 +301,13 @@ export interface DBClientInterfaceSync {
 
   stopTrackingSyncState(id: RawCoID): void;
 
+  /**
+   * Physical deletion primitive: erase all persisted history for a deleted coValue,
+   * while preserving the tombstone (header + delete session(s)).
+   * Must run inside a single storage transaction.
+   */
+  eraseCoValueButKeepTombstone(coValueID: RawCoID): unknown;
+
   /**
    * Get the knownState for a CoValue without loading transactions.
    * Returns undefined if the CoValue doesn't exist.

package/src/sync.ts

@@ -14,7 +14,7 @@ import {
 import { CoValueCore } from "./coValueCore/coValueCore.js";
 import { CoValueHeader, Transaction } from "./coValueCore/verifiedState.js";
 import { Signature } from "./crypto/crypto.js";
-import { RawCoID, SessionID, isRawCoID } from "./ids.js";
+import { isDeleteSessionID, RawCoID, SessionID, isRawCoID } from "./ids.js";
 import { LocalNode } from "./localNode.js";
 import { logger } from "./logger.js";
 import { CoValuePriority } from "./priority.js";
@@ -213,7 +213,6 @@ export class SyncManager {
       return;
     }
 
-    // TODO: validate
     switch (msg.action) {
       case "load":
         return this.handleLoad(msg, peer);
@@ -265,10 +264,18 @@ export class SyncManager {
 
       peer.combineOptimisticWith(id, coValue.knownState());
     } else if (!peer.toldKnownState.has(id)) {
-      this.trySendToPeer(peer, {
-        action: "known",
-        ...coValue.knownStateWithStreaming(),
-      });
+      if (coValue.isDeleted) {
+        // This way we make the peer believe that we've always ingested all the content they sent, even though we skipped it because the coValue is deleted
+        this.trySendToPeer(
+          peer,
+          coValue.stopSyncingKnownStateMessage(peer.getKnownState(id)),
+        );
+      } else {
+        this.trySendToPeer(peer, {
+          action: "known",
+          ...coValue.knownStateWithStreaming(),
+        });
+      }
     }
 
     peer.trackToldKnownState(id);
@@ -875,6 +882,8 @@ export class SyncManager {
       new: {},
     };
 
+    let wasAlreadyDeleted = coValue.isDeleted;
+
     /**
      * The coValue is in memory, load the transactions from the content message
      */
@@ -882,6 +891,10 @@ export class SyncManager {
       sessionID,
       newContentForSession,
     ] of getSessionEntriesFromContentMessage(msg)) {
+      if (wasAlreadyDeleted && !isDeleteSessionID(sessionID)) {
+        continue;
+      }
+
       const newTransactions = getNewTransactionsFromContentMessage(
         newContentForSession,
         coValue.knownState(),
@@ -936,12 +949,25 @@ export class SyncManager {
         this.recordTransactionsSize(newTransactions, sourceRole);
       }
 
+      // We reset the new content for the deleted coValue
+      // because we want to store only the delete session/transaction
+      if (!wasAlreadyDeleted && coValue.isDeleted) {
+        wasAlreadyDeleted = true;
+        validNewContent.new = {};
+      }
+
       // The new content for this session has been verified, so we can store it
       validNewContent.new[sessionID] = newContentForSession;
     }
 
     if (peer) {
-      peer.combineWith(msg.id, knownStateFromContent(validNewContent));
+      if (coValue.isDeleted) {
+        // In case of deleted coValues, we combine the known state with the content message
+        // to avoid that clients that don't support deleted coValues try to sync their own content indefinitely
+        peer.combineWith(msg.id, knownStateFromContent(msg));
+      } else {
+        peer.combineWith(msg.id, knownStateFromContent(validNewContent));
+      }
     }
 
     /**
@@ -973,10 +999,18 @@ export class SyncManager {
        * This way the sender knows that the content has been received and applied
        * and can update their peer's knownState accordingly.
        */
-      this.trySendToPeer(peer, {
-        action: "known",
-        ...coValue.knownState(),
-      });
+      if (coValue.isDeleted) {
+        // This way we make the peer believe that we've ingested all the content, even though we skipped it because the coValue is deleted
+        this.trySendToPeer(
+          peer,
+          coValue.stopSyncingKnownStateMessage(peer.getKnownState(msg.id)),
+        );
+      } else {
+        this.trySendToPeer(peer, {
+          action: "known",
+          ...coValue.knownState(),
+        });
+      }
       peer.trackToldKnownState(msg.id);
     }
 
@@ -1124,6 +1158,12 @@ export class SyncManager {
 
     const value = this.local.getCoValue(content.id);
 
+    if (value.isDeleted) {
+      // This doesn't persist the delete flag, it only signals the storage
+      // API that the delete transaction is valid
+      storage.markDeleteAsValid(value.id);
+    }
+
     // 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) => {