@rljson/fs-agent 0.0.9 → 0.0.11

package/README.public.md

@@ -747,10 +747,20 @@ const agent = new FsAgent('./my-project', bs, {
     restore: 15_000,      // Filesystem restore (default: 15s)
     syncCallback: 25_000, // Overall syncFromDb callback (default: 25s)
     debounceMs: 300,      // Coalesce rapid FS events (default: 300ms)
+    processRefRetries: 3,       // Retry failed refs before dropping (default: 3)
+    processRefRetryDelayMs: 5_000, // Base delay between retries (default: 5s)
   },
 });
 ```
 
+### processRef Retry Behavior
+
+When `syncFromDb` receives a tree ref and fails to process it (e.g. `db.get`
+times out because the IoPeer transport hasn't connected yet), the ref is
+retried up to `processRefRetries` times with increasing delay
+(`attempt * processRefRetryDelayMs`). This prevents a single transient
+timeout from permanently breaking the sync pipeline.
+
 ## Bounce-Back Prevention
 
 Bidirectional sync can cause infinite loops when both clients detect each

package/dist/README.public.md

@@ -747,10 +747,20 @@ const agent = new FsAgent('./my-project', bs, {
     restore: 15_000,      // Filesystem restore (default: 15s)
     syncCallback: 25_000, // Overall syncFromDb callback (default: 25s)
     debounceMs: 300,      // Coalesce rapid FS events (default: 300ms)
+    processRefRetries: 3,       // Retry failed refs before dropping (default: 3)
+    processRefRetryDelayMs: 5_000, // Base delay between retries (default: 5s)
   },
 });
 ```
 
+### processRef Retry Behavior
+
+When `syncFromDb` receives a tree ref and fails to process it (e.g. `db.get`
+times out because the IoPeer transport hasn't connected yet), the ref is
+retried up to `processRefRetries` times with increasing delay
+(`attempt * processRefRetryDelayMs`). This prevents a single transient
+timeout from permanently breaking the sync pipeline.
+
 ## Bounce-Back Prevention
 
 Bidirectional sync can cause infinite loops when both clients detect each

package/dist/fs-agent.d.ts

@@ -73,6 +73,18 @@ export interface TimeoutConfig {
      * Also applies to incoming database refs in syncFromDb.
      */
     debounceMs?: number;
+    /**
+     * Number of retries for processRef in syncFromDb. Default: 3.
+     * When a ref fails to process (e.g. db.get timeout because the IoPeer
+     * transport hasn't connected yet), the ref is retried this many times
+     * with increasing delay before being dropped.
+     */
+    processRefRetries?: number;
+    /**
+     * Base delay between processRef retries (milliseconds). Default: 5 000 ms.
+     * Each retry waits `attempt * processRefRetryDelayMs` (i.e. 5s, 10s, 15s).
+     */
+    processRefRetryDelayMs?: number;
 }
 /** Filename for sync error log written to the sync folder */
 export declare const SYNC_ERROR_FILE = ".sync-errors.log";

package/dist/fs-agent.js

@@ -178,6 +178,7 @@ class FsScanner {
   _options;
   _bs;
   _paused = false;
+  _missedChangesDuringPause = false;
   constructor(rootPath, options = {}) {
     this._rootPath = rootPath;
     this._options = {
@@ -365,6 +366,7 @@ class FsScanner {
   }
   async _handleFileChange(_eventType, filename) {
     if (this._paused) {
+      this._missedChangesDuringPause = true;
       return;
     }
     const relativePath = filename.replace(/\\/g, "/");
@@ -442,12 +444,34 @@ class FsScanner {
    */
   pauseWatch() {
     this._paused = true;
+    this._missedChangesDuringPause = false;
   }
   /**
-   * Resume file change notifications
+   * Resume file change notifications.
+   * If any filesystem events were missed during the pause, triggers
+   * an asynchronous rescan so that syncToDb can detect and push the changes.
    */
   resumeWatch() {
+    const missedChanges = this._missedChangesDuringPause;
     this._paused = false;
+    this._missedChangesDuringPause = false;
+    if (missedChanges) {
+      void this._rescanAfterPause();
+    }
+  }
+  /**
+   * Re-scan the filesystem and fire onChange callbacks to catch modifications
+   * that were missed while watching was paused.
+   */
+  async _rescanAfterPause() {
+    try {
+      await this.scan();
+      if (this._paused) {
+        return;
+      }
+      await this._notifyChange({ type: "modified", path: "." });
+    } catch {
+    }
   }
   getTreeByHash(treeHash) {
     return this._tree?.trees.get(treeHash);
@@ -484,7 +508,9 @@ const DEFAULT_TIMEOUTS = {
   extract: 15e3,
   restore: 15e3,
   syncCallback: 25e3,
-  debounceMs: 300
+  debounceMs: 300,
+  processRefRetries: 3,
+  processRefRetryDelayMs: 5e3
 };
 const SYNC_ERROR_FILE = ".sync-errors.log";
 class FsAgent {
@@ -1052,47 +1078,64 @@ ${err.stack}` : String(err);
     let pendingRef = null;
     let fromDbTimer = null;
     const processRef = async (treeRef) => {
-      this._scanner.pauseWatch();
-      try {
-        const incomingTree = await FsAgent._withTimeout(
-          this._fetchTreeFromDb(db, treeKey, treeRef),
-          this._timeouts.fetchTree,
-          `syncFromDb → fetchTree(${treeKey}@${treeRef.slice(0, 8)}…)`
-        );
-        const incomingNodeCount = incomingTree.trees.size;
-        console.log(
-          `[FsAgent] syncFromDb: fetched tree with ${incomingNodeCount} nodes for ref=${treeRef.slice(0, 8)}…`
-        );
-        const currentTree = await FsAgent._withTimeout(
-          this.extract(),
-          this._timeouts.extract,
-          `syncFromDb → extract(${this._rootPath})`
-        );
-        if (this._treesHaveEquivalentContent(currentTree, incomingTree)) {
-          const incomingFiles = this._getFileContentMap(incomingTree);
-          const currentFiles = this._getFileContentMap(currentTree);
+      const maxAttempts = this._timeouts.processRefRetries + 1;
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        this._scanner.pauseWatch();
+        try {
+          const incomingTree = await FsAgent._withTimeout(
+            this._fetchTreeFromDb(db, treeKey, treeRef),
+            this._timeouts.fetchTree,
+            `syncFromDb → fetchTree(${treeKey}@${treeRef.slice(0, 8)}…)`
+          );
+          const incomingNodeCount = incomingTree.trees.size;
           console.log(
-            `[FsAgent] syncFromDb: equivalent content, skipping restore (incoming=${incomingFiles.size} entries, current=${currentFiles.size} entries, ref=${treeRef.slice(0, 8)}…)`
+            `[FsAgent] syncFromDb: fetched tree with ${incomingNodeCount} nodes for ref=${treeRef.slice(0, 8)}…`
+          );
+          const currentTree = await FsAgent._withTimeout(
+            this.extract(),
+            this._timeouts.extract,
+            `syncFromDb → extract(${this._rootPath})`
+          );
+          if (this._treesHaveEquivalentContent(currentTree, incomingTree)) {
+            const incomingFiles = this._getFileContentMap(incomingTree);
+            const currentFiles = this._getFileContentMap(currentTree);
+            console.log(
+              `[FsAgent] syncFromDb: equivalent content, skipping restore (incoming=${incomingFiles.size} entries, current=${currentFiles.size} entries, ref=${treeRef.slice(0, 8)}…)`
+            );
+            return;
+          }
+          await FsAgent._withTimeout(
+            this.restore(incomingTree, void 0, restoreOptions),
+            this._timeouts.restore,
+            `syncFromDb → restore(${treeKey})`
           );
+          const postRestoreTree = await this._scanner.scan();
+          const dbAdapter = new FsDbAdapter(db, treeKey);
+          const postRestoreRef = await dbAdapter.storeFsTree(postRestoreTree, {
+            skipNotification: true
+          });
+          this._lastSentRef = postRestoreRef;
+          this._lastSentContentKey = this._contentKeyFromTree(postRestoreTree);
           return;
+        } catch (err) {
+          if (attempt === maxAttempts) {
+            console.error(
+              `[FsAgent] syncFromDb processRef failed after ${maxAttempts} attempts:`,
+              err
+            );
+            this._writeSyncError("syncFromDb/processRef", err);
+          } else {
+            const delaySec = attempt * this._timeouts.processRefRetryDelayMs / 1e3;
+            console.warn(
+              `[FsAgent] syncFromDb: attempt ${attempt}/${maxAttempts} failed for ref=${treeRef.slice(0, 8)}…, retrying in ${delaySec}s: ${err instanceof Error ? err.message : String(err)}`
+            );
+          }
+        } finally {
+          this._scanner.resumeWatch();
         }
-        await FsAgent._withTimeout(
-          this.restore(incomingTree, void 0, restoreOptions),
-          this._timeouts.restore,
-          `syncFromDb → restore(${treeKey})`
+        await new Promise(
+          (r) => setTimeout(r, attempt * this._timeouts.processRefRetryDelayMs)
         );
-        const postRestoreTree = await this._scanner.scan();
-        const dbAdapter = new FsDbAdapter(db, treeKey);
-        const postRestoreRef = await dbAdapter.storeFsTree(postRestoreTree, {
-          skipNotification: true
-        });
-        this._lastSentRef = postRestoreRef;
-        this._lastSentContentKey = this._contentKeyFromTree(postRestoreTree);
-      } catch (err) {
-        console.error("[FsAgent] syncFromDb processRef failed:", err);
-        this._writeSyncError("syncFromDb/processRef", err);
-      } finally {
-        this._scanner.resumeWatch();
       }
     };
     const syncCallback = async (treeRef) => {

package/dist/fs-scanner.d.ts

@@ -72,6 +72,7 @@ export declare class FsScanner {
     private _options;
     private _bs;
     private _paused;
+    private _missedChangesDuringPause;
     constructor(rootPath: string, options?: FsScanOptions);
     get tree(): FsTree | null;
     get rootPath(): string;
@@ -92,9 +93,16 @@ export declare class FsScanner {
      */
     pauseWatch(): void;
     /**
-     * Resume file change notifications
+     * Resume file change notifications.
+     * If any filesystem events were missed during the pause, triggers
+     * an asynchronous rescan so that syncToDb can detect and push the changes.
      */
     resumeWatch(): void;
+    /**
+     * Re-scan the filesystem and fire onChange callbacks to catch modifications
+     * that were missed while watching was paused.
+     */
+    private _rescanAfterPause;
     getTreeByHash(treeHash: TreeRef): Tree | undefined;
     getTreeByPath(relativePath: string): Tree | undefined;
     getAllTrees(): Tree[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/fs-agent",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Rljson fs-agent description",
   "homepage": "https://github.com/rljson/fs-agent",
   "bugs": "https://github.com/rljson/fs-agent/issues",