cojson 0.19.22 → 0.20.1

package/src/queue/LinkedList.ts

@@ -10,8 +10,9 @@ type Tuple<T, N extends number, A extends unknown[] = []> = A extends {
   ? A
   : Tuple<T, N, [...A, T]>;
 export type QueueTuple = Tuple<LinkedList<SyncMessage>, 3>;
-type LinkedListNode<T> = {
+export type LinkedListNode<T> = {
   value: T;
+  prev: LinkedListNode<T> | undefined;
   next: LinkedListNode<T> | undefined;
 };
 /**
@@ -26,13 +27,14 @@ export class LinkedList<T> {
   tail: LinkedListNode<T> | undefined = undefined;
   length = 0;
 
-  push(value: T) {
-    const node = { value, next: undefined };
+  push(value: T): LinkedListNode<T> {
+    const node: LinkedListNode<T> = { value, prev: undefined, next: undefined };
 
     if (this.head === undefined) {
       this.head = node;
       this.tail = node;
     } else if (this.tail) {
+      node.prev = this.tail;
       this.tail.next = node;
       this.tail = node;
     } else {
@@ -41,6 +43,7 @@ export class LinkedList<T> {
 
     this.length++;
     this.meter?.push();
+    return node;
   }
 
   shift() {
@@ -55,6 +58,8 @@ export class LinkedList<T> {
 
     if (this.head === undefined) {
       this.tail = undefined;
+    } else {
+      this.head.prev = undefined;
     }
 
     this.length--;
@@ -63,6 +68,31 @@ export class LinkedList<T> {
     return value;
   }
 
+  /**
+   * Remove a specific node from the list in O(1) time.
+   * The node must be a valid node that was returned by push().
+   */
+  remove(node: LinkedListNode<T>): void {
+    if (node.prev) {
+      node.prev.next = node.next;
+    } else {
+      // Node is the head
+      this.head = node.next;
+    }
+
+    if (node.next) {
+      node.next.prev = node.prev;
+    } else {
+      // Node is the tail
+      this.tail = node.prev;
+    }
+
+    node.prev = undefined;
+    node.next = undefined;
+    this.length--;
+    this.meter?.pull();
+  }
+
   isEmpty() {
     return this.head === undefined;
   }
@@ -108,7 +138,7 @@ class QueueMeter {
   }
 }
 export function meteredList<T>(
-  type: "incoming" | "outgoing" | "storage-streaming",
+  type: "incoming" | "outgoing" | "storage-streaming" | "load-requests-queue",
   attrs?: Record<string, string | number>,
 ) {
   return new LinkedList<T>(new QueueMeter("jazz.messagequeue." + type, attrs));

package/src/queue/OutgoingLoadQueue.ts

@@ -0,0 +1,307 @@
+import { CO_VALUE_LOADING_CONFIG } from "../config.js";
+import { CoValueCore } from "../exports.js";
+import type { RawCoID } from "../ids.js";
+import { logger } from "../logger.js";
+import type { PeerID } from "../sync.js";
+import { LinkedList, type LinkedListNode, meteredList } from "./LinkedList.js";
+
+interface PendingLoad {
+  value: CoValueCore;
+  sendCallback: () => void;
+}
+
+/**
+ * Mode for enqueuing load requests:
+ * - "high-priority" (default): high priority, processed in order
+ * - "low-priority": processed after all high priority requests
+ * - "immediate": bypasses the queue entirely, executes immediately
+ */
+export type LoadMode = "low-priority" | "immediate" | "high-priority";
+
+/**
+ * A queue that manages outgoing load requests with throttling.
+ *
+ * Features:
+ * - Limits concurrent in-flight load requests per peer
+ * - FIFO order for pending requests
+ * - O(1) enqueue and dequeue operations using LinkedList
+ * - Manages timeouts for in-flight loads with a single timer
+ */
+export class OutgoingLoadQueue {
+  private inFlightLoads: Map<CoValueCore, number> = new Map();
+  private highPriorityPending: LinkedList<PendingLoad> = meteredList(
+    "load-requests-queue",
+    { priority: "high" },
+  );
+  private lowPriorityPending: LinkedList<PendingLoad> = meteredList(
+    "load-requests-queue",
+    { priority: "low" },
+  );
+  /**
+   * Tracks nodes in the low-priority queue by CoValue ID for O(1) upgrade lookup.
+   */
+  private lowPriorityNodes: Map<RawCoID, LinkedListNode<PendingLoad>> =
+    new Map();
+  /**
+   * Tracks nodes in the high-priority queue by CoValue ID for O(1) immediate mode lookup.
+   */
+  private highPriorityNodes: Map<RawCoID, LinkedListNode<PendingLoad>> =
+    new Map();
+  private timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private peerId: PeerID) {}
+
+  /**
+   * Check if we can send another load request.
+   */
+  private canSend(): boolean {
+    return (
+      this.inFlightLoads.size <
+      CO_VALUE_LOADING_CONFIG.MAX_IN_FLIGHT_LOADS_PER_PEER
+    );
+  }
+
+  /**
+   * Track that a load request has been sent.
+   */
+  private trackSent(coValue: CoValueCore): void {
+    const now = performance.now();
+    this.inFlightLoads.set(coValue, now);
+    this.scheduleTimeoutCheck(CO_VALUE_LOADING_CONFIG.TIMEOUT);
+  }
+
+  /**
+   * Schedule a timeout check if not already scheduled.
+   * Uses a single timer to check all in-flight loads.
+   */
+  private scheduleTimeoutCheck(nextTimeout: number): void {
+    if (this.timeoutHandle !== null) {
+      return;
+    }
+
+    this.timeoutHandle = setTimeout(() => {
+      this.timeoutHandle = null;
+      this.checkTimeouts();
+    }, nextTimeout);
+  }
+
+  /**
+   * Check all in-flight loads for timeouts and handle them.
+   */
+  private checkTimeouts(): void {
+    const now = performance.now();
+
+    let nextTimeout: number | undefined;
+    for (const [coValue, sentAt] of this.inFlightLoads.entries()) {
+      const timeout = sentAt + CO_VALUE_LOADING_CONFIG.TIMEOUT;
+
+      if (now >= timeout) {
+        if (!coValue.isAvailable()) {
+          logger.warn("Load request timed out", {
+            id: coValue.id,
+            peerId: this.peerId,
+          });
+          coValue.markNotFoundInPeer(this.peerId);
+        } else if (coValue.isStreaming()) {
+          logger.warn(
+            "Content streaming is taking more than " +
+              CO_VALUE_LOADING_CONFIG.TIMEOUT / 1000 +
+              "s",
+            {
+              id: coValue.id,
+              peerId: this.peerId,
+              knownState: coValue.knownState().sessions,
+              streamingTarget: coValue.knownStateWithStreaming().sessions,
+            },
+          );
+        }
+
+        this.inFlightLoads.delete(coValue);
+        this.processQueue();
+      } else {
+        nextTimeout = Math.min(nextTimeout ?? Infinity, timeout - now);
+      }
+    }
+
+    // Reschedule if there are still in-flight loads
+    if (nextTimeout) {
+      this.scheduleTimeoutCheck(nextTimeout);
+    }
+  }
+
+  trackUpdate(coValue: CoValueCore): void {
+    if (!this.inFlightLoads.has(coValue)) {
+      return;
+    }
+
+    // Refresh the timeout for the in-flight load
+    this.inFlightLoads.set(coValue, performance.now());
+  }
+
+  /**
+   * Track that a load request has completed.
+   * Triggers processing of pending requests.
+   */
+  trackComplete(coValue: CoValueCore): void {
+    if (!this.inFlightLoads.has(coValue)) {
+      return;
+    }
+
+    if (coValue.isStreaming()) {
+      // wait for the next chunk
+      return;
+    }
+
+    this.inFlightLoads.delete(coValue);
+    this.processQueue();
+  }
+
+  /**
+   * Enqueue a load request.
+   * Immediately processes the queue to send requests if capacity is available.
+   * Skips CoValues that are already in-flight or pending.
+   *
+   * @param coValue - The CoValue to load
+   * @param sendCallback - Callback to send the request when ready
+   * @param mode - Optional mode: "low-priority" for background loads, "immediate" to bypass queue
+   */
+  enqueue(
+    value: CoValueCore,
+    sendCallback: () => void,
+    mode: LoadMode = "high-priority",
+  ): void {
+    if (this.inFlightLoads.has(value)) {
+      return;
+    }
+
+    const lowPriorityNode = this.lowPriorityNodes.get(value.id);
+    const highPriorityNode = this.highPriorityNodes.get(value.id);
+
+    switch (mode) {
+      case "immediate":
+        // Upgrade any low-priority or high-priority requests to immediate priority
+        if (lowPriorityNode) {
+          this.lowPriorityPending.remove(lowPriorityNode);
+          this.lowPriorityNodes.delete(value.id);
+        }
+        if (highPriorityNode) {
+          this.highPriorityPending.remove(highPriorityNode);
+          this.highPriorityNodes.delete(value.id);
+        }
+
+        this.trackSent(value);
+        sendCallback();
+        break;
+      case "high-priority":
+        if (highPriorityNode) {
+          return;
+        }
+
+        // Upgrade any low-priority requests to high-priority
+        if (lowPriorityNode) {
+          this.lowPriorityPending.remove(lowPriorityNode);
+          this.lowPriorityNodes.delete(value.id);
+        }
+
+        this.highPriorityNodes.set(
+          value.id,
+          this.highPriorityPending.push({ value, sendCallback }),
+        );
+        this.processQueue();
+        break;
+      case "low-priority":
+        if (lowPriorityNode || highPriorityNode) {
+          return;
+        }
+
+        this.lowPriorityNodes.set(
+          value.id,
+          this.lowPriorityPending.push({ value, sendCallback }),
+        );
+        this.processQueue();
+        break;
+    }
+  }
+
+  private processing = false;
+  /**
+   * Process all pending load requests while capacity is available.
+   * High-priority requests are processed first, then low-priority.
+   */
+  private processQueue(): void {
+    if (this.processing || !this.canSend()) {
+      return;
+    }
+    this.processing = true;
+
+    while (this.canSend()) {
+      // Try high-priority first
+      let next = this.highPriorityPending.shift();
+
+      if (next) {
+        // Remove from the tracking map since we're processing it
+        this.highPriorityNodes.delete(next.value.id);
+      } else {
+        // Fall back to low-priority if high-priority is empty
+        next = this.lowPriorityPending.shift();
+        if (next) {
+          // Remove from the tracking map since we're processing it
+          this.lowPriorityNodes.delete(next.value.id);
+        }
+      }
+
+      if (!next) {
+        break;
+      }
+
+      this.trackSent(next.value);
+      next.sendCallback();
+    }
+
+    this.processing = false;
+  }
+
+  /**
+   * Clear all state. Called on disconnect.
+   * Clears the timeout and all pending/in-flight loads.
+   */
+  clear(): void {
+    if (this.timeoutHandle !== null) {
+      clearTimeout(this.timeoutHandle);
+      this.timeoutHandle = null;
+    }
+    this.inFlightLoads.clear();
+    this.highPriorityPending = new LinkedList();
+    this.lowPriorityPending = new LinkedList();
+    this.highPriorityNodes.clear();
+    this.lowPriorityNodes.clear();
+  }
+
+  /**
+   * Get the number of in-flight loads (for testing/debugging).
+   */
+  get inFlightCount(): number {
+    return this.inFlightLoads.size;
+  }
+
+  /**
+   * Get the number of pending loads (for testing/debugging).
+   */
+  get pendingCount(): number {
+    return this.highPriorityPending.length + this.lowPriorityPending.length;
+  }
+
+  /**
+   * Get the number of high-priority pending loads (for testing/debugging).
+   */
+  get highPriorityPendingCount(): number {
+    return this.highPriorityPending.length;
+  }
+
+  /**
+   * Get the number of low-priority pending loads (for testing/debugging).
+   */
+  get lowPriorityPendingCount(): number {
+    return this.lowPriorityPending.length;
+  }
+}

package/src/storage/DeletedCoValuesEraserScheduler.ts

@@ -0,0 +1,124 @@
+import { logger } from "../logger.js";
+
+export type DeletedCoValuesEraserSchedulerRunResult = {
+  hasMore: boolean;
+};
+
+export type DeletedCoValuesEraserSchedulerOpts = {
+  throttleMs: number;
+  startupDelayMs: number;
+  followUpDelayMs: number;
+};
+
+type SchedulerState =
+  | "idle"
+  | "startup_scheduled"
+  | "throttle_scheduled"
+  | "followup_scheduled"
+  | "running"
+  | "disposed";
+
+export const DEFAULT_DELETE_SCHEDULE_OPTS = {
+  throttleMs: 60_000,
+  startupDelayMs: 1_000,
+  followUpDelayMs: 1_000,
+} satisfies DeletedCoValuesEraserSchedulerOpts;
+
+export class DeletedCoValuesEraserScheduler {
+  private readonly runCallback: () => Promise<DeletedCoValuesEraserSchedulerRunResult>;
+  private readonly opts: DeletedCoValuesEraserSchedulerOpts;
+
+  private state: SchedulerState = "idle";
+
+  private isDisposed(): boolean {
+    return this.state === "disposed";
+  }
+
+  private scheduledTimeout: ReturnType<typeof setTimeout> | undefined;
+
+  constructor({
+    run,
+    opts,
+  }: {
+    run: () => Promise<DeletedCoValuesEraserSchedulerRunResult>;
+    opts?: DeletedCoValuesEraserSchedulerOpts;
+  }) {
+    this.runCallback = run;
+    this.opts = opts || DEFAULT_DELETE_SCHEDULE_OPTS;
+  }
+
+  scheduleStartupDrain() {
+    if (this.isDisposed()) return;
+
+    // Only schedule startup drain if nothing is already scheduled/running.
+    if (this.state !== "idle") return;
+
+    this.scheduleTimer("startup_scheduled", this.opts.startupDelayMs);
+  }
+
+  onEnqueueDeletedCoValue() {
+    if (this.isDisposed()) return;
+
+    // While we're already draining (or have a follow-up scheduled), ignore enqueue
+    // to avoid overlapping phases. The active drain loop will pick up new work.
+    if (this.state !== "idle") return;
+
+    // Only idle reaches here.
+    this.scheduleTimer("throttle_scheduled", this.opts.throttleMs);
+  }
+
+  dispose() {
+    if (this.isDisposed()) return;
+    this.state = "disposed";
+
+    if (this.scheduledTimeout) clearTimeout(this.scheduledTimeout);
+    this.scheduledTimeout = undefined;
+  }
+
+  private scheduleTimer(
+    state: Exclude<SchedulerState, "idle" | "running" | "disposed">,
+    delayMs: number,
+  ) {
+    if (this.isDisposed()) return;
+    if (this.scheduledTimeout) return;
+
+    this.state = state;
+    this.scheduledTimeout = setTimeout(() => {
+      this.scheduledTimeout = undefined;
+      void this.run();
+    }, delayMs);
+  }
+
+  private async run() {
+    if (this.isDisposed()) return;
+
+    // Clear any pre-run scheduled state and enter running state.
+    this.state = "running";
+
+    let result: DeletedCoValuesEraserSchedulerRunResult;
+    try {
+      result = await this.runCallback();
+    } catch (error) {
+      logger.error("Error running deleted co values eraser scheduler", {
+        err: error,
+      });
+      // If the run callback fails, recover to idle so future enqueues/startup drains
+      // can retry instead of getting stuck in "running".
+      if (!this.isDisposed()) {
+        this.state = "idle";
+      }
+      return;
+    }
+
+    if (this.isDisposed()) return;
+
+    if (result.hasMore) {
+      // One follow-up phase at a time. Further enqueues while follow-up is scheduled
+      // are ignored.
+      this.scheduleTimer("followup_scheduled", this.opts.followUpDelayMs);
+      return;
+    }
+
+    this.state = "idle";
+  }
+}

package/src/storage/sqlite/client.ts

@@ -16,6 +16,7 @@ import type {
   StoredSessionRow,
   TransactionRow,
 } from "../types.js";
+import { DeletedCoValueDeletionStatus } from "../types.js";
 import type { SQLiteDatabaseDriver } from "./types.js";
 
 export type RawCoValueRow = {
@@ -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";
 }
@@ -143,6 +148,78 @@ export class SQLiteClient
     return result.rowID;
   }
 
+  markCoValueAsDeleted(id: RawCoID) {
+    // Work queue entry. Table only stores the coValueID.
+    // Idempotent by design.
+    this.db.run(
+      `INSERT INTO deletedCoValues (coValueID) VALUES (?) ON CONFLICT(coValueID) DO NOTHING`,
+      [id],
+    );
+  }
+
+  eraseCoValueButKeepTombstone(coValueId: RawCoID) {
+    const coValueRow = this.db.get<{ rowID: number }>(
+      "SELECT rowID FROM coValues WHERE id = ?",
+      [coValueId],
+    );
+
+    if (!coValueRow) {
+      logger.warn(`CoValue ${coValueId} not found, skipping deletion`);
+      return;
+    }
+
+    this.transaction(() => {
+      this.db.run(
+        `DELETE FROM transactions
+       WHERE ses IN (
+         SELECT rowID FROM sessions
+         WHERE coValue = ?
+           AND sessionID NOT LIKE '%$'
+       )`,
+        [coValueRow.rowID],
+      );
+
+      this.db.run(
+        `DELETE FROM signatureAfter
+       WHERE ses IN (
+         SELECT rowID FROM sessions
+         WHERE coValue = ?
+           AND sessionID NOT LIKE '%$'
+       )`,
+        [coValueRow.rowID],
+      );
+
+      this.db.run(
+        `DELETE FROM sessions
+       WHERE coValue = ?
+         AND sessionID NOT LIKE '%$'`,
+        [coValueRow.rowID],
+      );
+
+      // Mark the delete as done
+      this.db.run(
+        `INSERT INTO deletedCoValues (coValueID, status) VALUES (?, ?)
+       ON CONFLICT(coValueID) DO UPDATE SET status=?`,
+        [
+          coValueId,
+          DeletedCoValueDeletionStatus.Done,
+          DeletedCoValueDeletionStatus.Done,
+        ],
+      );
+    });
+  }
+
+  getAllCoValuesWaitingForDelete(): RawCoID[] {
+    return this.db
+      .query<DeletedCoValueQueueRow>(
+        `SELECT coValueID as id
+         FROM deletedCoValues
+         WHERE status = ?`,
+        [DeletedCoValueDeletionStatus.Pending],
+      )
+      .map((r) => r.id);
+  }
+
   addSessionUpdate({ sessionUpdate }: { sessionUpdate: SessionRow }): number {
     const result = this.db.get<{ rowID: number }>(
       `INSERT INTO sessions (coValue, sessionID, lastIdx, lastSignature, bytesSinceLastSignature) VALUES (?, ?, ?, ?, ?)

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 = {