cojson 0.20.0 → 0.20.2

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/sync.ts

@@ -401,22 +401,18 @@ export class SyncManager {
     };
 
     for (const coValue of this.local.allCoValues()) {
-      if (!coValue.isAvailable()) {
-        // If the coValue is unavailable and we never tried this peer
-        // we try to load it from the peer
-        if (!peer.loadRequestSent.has(coValue.id)) {
-          peer.trackLoadRequestSent(coValue.id);
-          this.trySendToPeer(peer, {
-            action: "load",
-            header: false,
-            id: coValue.id,
-            sessions: {},
-          });
-        }
-      } else {
-        // Build the list of coValues ordered by dependency
-        // so we can send the load message in the correct order
+      if (coValue.isAvailable()) {
+        // In memory - build ordered list for dependency-aware sending
         buildOrderedCoValueList(coValue);
+      } else if (coValue.loadingState === "unknown") {
+        // Skip unknown CoValues - we never tried to load them, so don't
+        // restore a subscription we never had. This prevents loading
+        // content for CoValues we don't actually care about.
+        continue;
+      } else if (!peer.loadRequestSent.has(coValue.id)) {
+        // For garbageCollected/onlyKnownState: knownState() returns lastKnownState
+        // For unavailable/loading/errored: knownState() returns empty state
+        peer.sendLoadRequest(coValue, "low-priority");
       }
 
       // Fill the missing known states with empty known states
@@ -431,12 +427,11 @@ export class SyncManager {
        * - Subscribe to the coValue updates
        * - Start the sync process in case we or the other peer
        *   lacks some transactions
+       *
+       * Use low priority for reconciliation loads so that user-initiated
+       * loads take precedence.
        */
-      peer.trackLoadRequestSent(coValue.id);
-      this.trySendToPeer(peer, {
-        action: "load",
-        ...coValue.knownState(),
-      });
+      peer.sendLoadRequest(coValue, "low-priority");
     }
   }
 
@@ -515,7 +510,7 @@ export class SyncManager {
         currentTimer - lastTimer >
         SYNC_SCHEDULER_CONFIG.INCOMING_MESSAGES_TIME_BUDGET
       ) {
-        await new Promise<void>((resolve) => setTimeout(resolve));
+        await waitForNextTick();
         lastTimer = performance.now();
       }
     }
@@ -733,6 +728,8 @@ export class SyncManager {
     if (coValue.isAvailable()) {
       this.sendNewContent(msg.id, peer);
     }
+
+    peer.trackLoadRequestComplete(coValue);
   }
 
   recordTransactionsSize(newTransactions: Transaction[], source: string) {
@@ -751,6 +748,7 @@ export class SyncManager {
   ) {
     const coValue = this.local.getCoValue(msg.id);
     const peer = from === "storage" || from === "import" ? undefined : from;
+
     const sourceRole =
       from === "storage"
         ? "storage"
@@ -767,6 +765,7 @@ export class SyncManager {
       };
     }
 
+    peer?.trackLoadRequestUpdate(coValue);
     coValue.addDependenciesFromContentMessage(msg);
 
     // If some of the dependencies are missing, we wait for them to be available
@@ -786,7 +785,12 @@ export class SyncManager {
             peers.push(peer);
           }
 
-          dependencyCoValue.load(peers);
+          // Use immediate mode to bypass the concurrency limit for dependencies
+          // We do this to avoid that the dependency load is blocked
+          // by the pending dependendant load
+          // Also these should be done with the highest priority, because we need to
+          // unblock the coValue wait
+          dependencyCoValue.load(peers, "immediate");
         }
       }
 
@@ -1014,8 +1018,6 @@ export class SyncManager {
       peer.trackToldKnownState(msg.id);
     }
 
-    const syncedPeers = [];
-
     /**
      * Store the content and propagate it to the server peers and the subscribed client peers
      */
@@ -1029,6 +1031,8 @@ export class SyncManager {
       }
     }
 
+    peer?.trackLoadRequestComplete(coValue);
+
     for (const peer of this.getPeers(coValue.id)) {
       /**
        * We sync the content against the source peer if it is a client or server peers
@@ -1042,25 +1046,8 @@ export class SyncManager {
       // We directly forward the new content to peers that have an active subscription
       if (peer.isCoValueSubscribedToPeer(coValue.id)) {
         this.sendNewContent(coValue.id, peer);
-        syncedPeers.push(peer);
-      } else if (
-        peer.role === "server" &&
-        !peer.loadRequestSent.has(coValue.id)
-      ) {
-        const state = coValue.getLoadingStateForPeer(peer.id);
-
-        // Check if there is a inflight load operation and we
-        // are waiting for other peers to send the load request
-        if (state === "unknown") {
-          // Sending a load message to the peer to get to know how much content is missing
-          // before sending the new content
-          this.trySendToPeer(peer, {
-            action: "load",
-            ...coValue.knownStateWithStreaming(),
-          });
-          peer.trackLoadRequestSent(coValue.id);
-          syncedPeers.push(peer);
-        }
+      } else if (peer.role === "server") {
+        peer.sendLoadRequest(coValue);
       }
     }
   }
@@ -1344,3 +1331,10 @@ export function hwrServerPeerSelector(n: number): ServerPeerSelector {
       .map((wp) => wp.peer);
   };
 }
+
+let waitForNextTick = () =>
+  new Promise<void>((resolve) => queueMicrotask(resolve));
+
+if (typeof setImmediate === "function") {
+  waitForNextTick = () => new Promise<void>((resolve) => setImmediate(resolve));
+}

package/src/tests/LinkedList.test.ts

@@ -76,6 +76,117 @@ describe("LinkedList", () => {
     });
   });
 
+  describe("remove", () => {
+    it("should remove the only element in the list", () => {
+      const node = list.push(1);
+      list.remove(node);
+
+      expect(list.length).toBe(0);
+      expect(list.head).toBeUndefined();
+      expect(list.tail).toBeUndefined();
+      expect(node.prev).toBeUndefined();
+      expect(node.next).toBeUndefined();
+    });
+
+    it("should remove the head element", () => {
+      const node1 = list.push(1);
+      const node2 = list.push(2);
+      const node3 = list.push(3);
+
+      list.remove(node1);
+
+      expect(list.length).toBe(2);
+      expect(list.head).toBe(node2);
+      expect(list.tail).toBe(node3);
+      expect(node2.prev).toBeUndefined();
+      expect(node1.prev).toBeUndefined();
+      expect(node1.next).toBeUndefined();
+    });
+
+    it("should remove the tail element", () => {
+      const node1 = list.push(1);
+      const node2 = list.push(2);
+      const node3 = list.push(3);
+
+      list.remove(node3);
+
+      expect(list.length).toBe(2);
+      expect(list.head).toBe(node1);
+      expect(list.tail).toBe(node2);
+      expect(node2.next).toBeUndefined();
+      expect(node3.prev).toBeUndefined();
+      expect(node3.next).toBeUndefined();
+    });
+
+    it("should remove a middle element", () => {
+      const node1 = list.push(1);
+      const node2 = list.push(2);
+      const node3 = list.push(3);
+
+      list.remove(node2);
+
+      expect(list.length).toBe(2);
+      expect(list.head).toBe(node1);
+      expect(list.tail).toBe(node3);
+      expect(node1.next).toBe(node3);
+      expect(node3.prev).toBe(node1);
+      expect(node2.prev).toBeUndefined();
+      expect(node2.next).toBeUndefined();
+    });
+
+    it("should maintain correct state after multiple removes", () => {
+      const node1 = list.push(1);
+      const node2 = list.push(2);
+      const node3 = list.push(3);
+      const node4 = list.push(4);
+
+      // Remove middle
+      list.remove(node2);
+      expect(list.length).toBe(3);
+      expect(node1.next).toBe(node3);
+      expect(node3.prev).toBe(node1);
+
+      // Remove head
+      list.remove(node1);
+      expect(list.length).toBe(2);
+      expect(list.head).toBe(node3);
+
+      // Remove tail
+      list.remove(node4);
+      expect(list.length).toBe(1);
+      expect(list.head).toBe(node3);
+      expect(list.tail).toBe(node3);
+
+      // Remove last
+      list.remove(node3);
+      expect(list.length).toBe(0);
+      expect(list.head).toBeUndefined();
+      expect(list.tail).toBeUndefined();
+    });
+
+    it("should allow shift after remove", () => {
+      const node1 = list.push(1);
+      list.push(2);
+      list.push(3);
+
+      list.remove(node1);
+
+      expect(list.shift()).toBe(2);
+      expect(list.shift()).toBe(3);
+      expect(list.length).toBe(0);
+    });
+
+    it("should allow push after remove", () => {
+      const node1 = list.push(1);
+      list.remove(node1);
+
+      list.push(2);
+      expect(list.length).toBe(1);
+      expect(list.head?.value).toBe(2);
+      expect(list.tail?.value).toBe(2);
+    });
+  });
+
   describe("edge cases", () => {
     it("should handle push after all elements have been shifted", () => {
       list.push(1);