@rljson/fs-agent 0.0.8 → 0.0.10

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,7 +73,21 @@ 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";
 /**
  * Orchestrates filesystem operations with tree structures and blob storage
  */
@@ -111,6 +125,13 @@ export declare class FsAgent {
      * Gets the current timeout configuration
      */
     get timeouts(): Required<TimeoutConfig>;
+    /**
+     * Appends a sync error entry to the error log file in the sync folder.
+     * Uses synchronous I/O to guarantee the write completes even in catch blocks.
+     * @param context - Label identifying where the error occurred
+     * @param err - The error value caught
+     */
+    _writeSyncError(context: string, err: unknown): void;
     /**
      * Wraps a promise with a timeout.
      * Rejects with a descriptive error if the promise does not settle

package/dist/fs-agent.js

@@ -1,9 +1,9 @@
 import { BsMem } from "@rljson/bs";
 import { Route, createTreesTableCfg } from "@rljson/rljson";
+import { watch, appendFileSync } from "fs";
 import { stat, readFile, mkdir, writeFile, readdir, utimes, rm } from "fs/promises";
 import { dirname, join, sep } from "path";
 import { hip } from "@rljson/hash";
-import { watch } from "fs";
 import { Db } from "@rljson/db";
 import { IoMem, createSocketPair } from "@rljson/io";
 import { Server, Client } from "@rljson/server";
@@ -484,8 +484,11 @@ 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 {
   _scanner;
   _adapter;
@@ -505,7 +508,11 @@ class FsAgent {
     this._db = options.db;
     this._treeKey = options.treeKey;
     this._timeouts = { ...DEFAULT_TIMEOUTS, ...options.timeouts };
-    this._scanner = new FsScanner(rootPath, { ...options, bs: this._bs });
+    this._scanner = new FsScanner(rootPath, {
+      ...options,
+      ignore: [...options.ignore || [], SYNC_ERROR_FILE],
+      bs: this._bs
+    });
     this._adapter = new FsBlobAdapter(this._bs);
     if (this._db && this._treeKey) {
       this._startAutoSync().catch(() => {
@@ -544,6 +551,23 @@ class FsAgent {
   get timeouts() {
     return this._timeouts;
   }
+  /**
+   * Appends a sync error entry to the error log file in the sync folder.
+   * Uses synchronous I/O to guarantee the write completes even in catch blocks.
+   * @param context - Label identifying where the error occurred
+   * @param err - The error value caught
+   */
+  _writeSyncError(context, err) {
+    try {
+      const ts = (/* @__PURE__ */ new Date()).toISOString();
+      const msg = err instanceof Error ? `${err.message}
+${err.stack}` : String(err);
+      const entry = `[${ts}] ${context}: ${msg}
+`;
+      appendFileSync(join(this._rootPath, SYNC_ERROR_FILE), entry);
+    } catch {
+    }
+  }
   /**
    * Wraps a promise with a timeout.
    * Rejects with a descriptive error if the promise does not settle
@@ -772,6 +796,14 @@ class FsAgent {
         if (error instanceof Error && error.message.startsWith("Timeout")) {
           throw error;
         }
+        const errMsg = error instanceof Error ? error.message : String(error);
+        console.warn(
+          `[FsAgent] _fetchTreeRecursively: db.get failed for hash=${currentHash.slice(0, 8)}…: ${errMsg}`
+        );
+        this._writeSyncError(
+          `fetchTree/db.get(${currentHash.slice(0, 8)}…)`,
+          error
+        );
         continue;
       }
       const treeData = result?.rljson?.[treeKey];
@@ -938,7 +970,9 @@ class FsAgent {
             if (ref) {
               await this._sendRef(connector, ref);
             }
-          } catch {
+          } catch (err) {
+            console.error("[FsAgent] syncToDb failed:", err);
+            this._writeSyncError("syncToDb", err);
           }
         }
       }, this._timeouts.debounceMs);
@@ -1020,36 +1054,64 @@ class FsAgent {
     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 currentTree = await FsAgent._withTimeout(
-          this.extract(),
-          this._timeouts.extract,
-          `syncFromDb → extract(${this._rootPath})`
-        );
-        if (this._treesHaveEquivalentContent(currentTree, incomingTree)) {
+      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: 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 {
-      } finally {
-        this._scanner.resumeWatch();
       }
     };
     const syncCallback = async (treeRef) => {
@@ -1201,5 +1263,6 @@ export {
   FsBlobAdapter,
   FsDbAdapter,
   FsScanner,
+  SYNC_ERROR_FILE,
   runClientServerSetup
 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { FsAgent, type FsAgentOptions, type RestoreOptions, type TimeoutConfig, } from './fs-agent.ts';
+export { FsAgent, SYNC_ERROR_FILE, type FsAgentOptions, type RestoreOptions, type TimeoutConfig, } from './fs-agent.ts';
 export { FsBlobAdapter, type BlobToFileOptions, type FileBlobMeta, type FileToBlobOptions, } from './fs-blob-adapter.ts';
 export { FsDbAdapter, type StoreFsTreeOptions } from './fs-db-adapter.ts';
 export { FsScanner, type FsChange, type FsChangeCallback, type FsChangeType, type FsNodeMeta, type FsScanOptions, type FsTree, } from './fs-scanner.ts';

package/package.json

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