@rljson/fs-agent 0.0.22 → 0.0.24

package/dist/fs-agent.d.ts

@@ -131,6 +131,61 @@ export declare const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
 /**
  * Orchestrates filesystem operations with tree structures and blob storage
  */
+/**
+ * A prune smaller than this many files is always allowed through.
+ *
+ * Below it, "most of the folder" is not a meaningful statement: emptying a
+ * three-file folder is an ordinary edit, and a guard that blocked it would
+ * fire constantly on small trees and be turned off.
+ */
+export declare const MASS_DELETE_MIN_FILES = 100;
+/**
+ * Above this share of the folder, a prune is treated as suspicious rather than
+ * intentional.
+ */
+export declare const MASS_DELETE_MAX_RATIO = 0.3;
+/**
+ * A restore that could not put the folder into the state the tree describes.
+ *
+ * The distinction that matters to callers is not why. It is that the folder
+ * does NOT match the tree afterwards, so the ref must not be recorded as
+ * applied and the resulting state must not be advertised to peers.
+ */
+export declare class RestoreIncompleteError extends Error {
+}
+/**
+ * Thrown when a restore wrote everything it could but at least one file was
+ * held open by another process.
+ *
+ * Not a failure of the restore so much as a "not yet": the bytes are still
+ * available, the file is simply busy. It is an error rather than a silent
+ * partial success because the folder does NOT match the tree afterwards, and
+ * anything that treats it as if it did — advertising the state, recording the
+ * ref as applied — would make one locked file look like an edit that everyone
+ * else must adopt.
+ */
+export declare class PartialRestoreError extends RestoreIncompleteError {
+    readonly lockedPaths: string[];
+    constructor(lockedPaths: string[]);
+}
+/**
+ * Thrown when `cleanTarget` would have deleted most of the folder.
+ *
+ * The dangerous direction of sync is a POPULATED node receiving a tree that
+ * lacks its files: a peer that comes up empty — a fresh clone, a folder not
+ * yet mounted, a bootstrap that raced its own first scan — advertises an empty
+ * tree, and every other node faithfully deletes everything it has.
+ *
+ * Nothing downstream can tell that apart from a genuine bulk deletion, so the
+ * judgement has to be made here, and it is deliberately biased: refusing a
+ * real mass delete costs one manual step, applying a false one costs the data.
+ */
+export declare class MassDeleteRefusedError extends RestoreIncompleteError {
+    readonly wouldPrune: number;
+    readonly totalFiles: number;
+    readonly incomingFiles: number;
+    constructor(wouldPrune: number, totalFiles: number, incomingFiles: number);
+}
 export declare class FsAgent {
     private _scanner;
     private _adapter;
@@ -162,6 +217,8 @@ export declare class FsAgent {
     /** Files written vs left alone by the current {@link restore}. */
     private _restoreWritten;
     private _restoreSkipped;
+    /** Paths the current {@link restore} could not write because they were held open. */
+    private _restoreLocked;
     /**
      * What this agent last wrote to each absolute path, so a repeat restore can
      * recognise its own work without re-reading the file.
@@ -304,6 +361,17 @@ export declare class FsAgent {
      *   is the only case where the scanner's view describes these files
      */
     private _restoreTree;
+    /**
+     * Whether a caught value means "another process is holding this file".
+     *
+     * Windows reports a locked file as EPERM or EBUSY; EACCES covers the
+     * permission-denied shape. Deliberately narrow — anything else is a real
+     * write failure and must still abort, because a restore that shrugged off
+     * every error would report success while leaving the folder wrong.
+     * @param err - The caught value.
+     * @returns `true` for a lock-shaped error.
+     */
+    private static _isLocked;
     /**
      * The content identity this agent believes is on disk at `filePath`, or
      * `undefined` when it has no basis for an opinion.

package/dist/fs-agent.js

@@ -1022,6 +1022,32 @@ const DEFAULT_TIMEOUTS = {
 const DISCONNECT_PAUSE_MAX_MS = 3e4;
 const SYNC_ERROR_FILE = ".sync-errors.log";
 const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
+const MASS_DELETE_MIN_FILES = 100;
+const MASS_DELETE_MAX_RATIO = 0.3;
+class RestoreIncompleteError extends Error {
+}
+class PartialRestoreError extends RestoreIncompleteError {
+  constructor(lockedPaths) {
+    super(
+      `restore could not write ${lockedPaths.length} locked file${lockedPaths.length === 1 ? "" : "s"}: ${lockedPaths.join(", ")}`
+    );
+    this.lockedPaths = lockedPaths;
+    this.name = "PartialRestoreError";
+  }
+}
+class MassDeleteRefusedError extends RestoreIncompleteError {
+  constructor(wouldPrune, totalFiles, incomingFiles) {
+    super(
+      // No pluralisation: the guard only fires above MASS_DELETE_MIN_FILES,
+      // so this is never one file.
+      `refusing to prune ${wouldPrune} of ${totalFiles} local files: the incoming tree has ${incomingFiles === 0 ? "NO files at all" : `only ${incomingFiles}`}, which looks like a peer that came up empty rather than a deletion. Nothing was deleted.`
+    );
+    this.wouldPrune = wouldPrune;
+    this.totalFiles = totalFiles;
+    this.incomingFiles = incomingFiles;
+    this.name = "MassDeleteRefusedError";
+  }
+}
 class FsAgent {
   _scanner;
   _adapter;
@@ -1053,6 +1079,8 @@ class FsAgent {
   /** Files written vs left alone by the current {@link restore}. */
   _restoreWritten = 0;
   _restoreSkipped = 0;
+  /** Paths the current {@link restore} could not write because they were held open. */
+  _restoreLocked = [];
   /**
    * What this agent last wrote to each absolute path, so a repeat restore can
    * recognise its own work without re-reading the file.
@@ -1323,6 +1351,7 @@ ${err.stack}` : String(err);
     const preRestore = options?.cleanTarget ? await this._collectAllFiles(target) : /* @__PURE__ */ new Set();
     this._restoreWritten = 0;
     this._restoreSkipped = 0;
+    this._restoreLocked = [];
     await this._restoreTree(
       tree.rootHash,
       tree.trees,
@@ -1335,6 +1364,26 @@ ${err.stack}` : String(err);
       );
     }
     if (options?.cleanTarget) {
+      let wouldPrune = 0;
+      for (const existing of preRestore) {
+        if (!expectedFiles.has(existing)) wouldPrune++;
+      }
+      if (wouldPrune > MASS_DELETE_MIN_FILES && (expectedFiles.size === 0 || wouldPrune / preRestore.size > MASS_DELETE_MAX_RATIO)) {
+        console.error(
+          `[FsAgent] MASS DELETE REFUSED on ${target}: the incoming tree would remove ${wouldPrune} of ${preRestore.size} files (incoming tree has ${expectedFiles.size}). Nothing was deleted. If this deletion is real, it has to be applied deliberately.`
+        );
+        this._writeSyncError(
+          "restore/massDeleteGuard",
+          new Error(
+            `refused to prune ${wouldPrune}/${preRestore.size} files; incoming tree had ${expectedFiles.size}`
+          )
+        );
+        throw new MassDeleteRefusedError(
+          wouldPrune,
+          preRestore.size,
+          expectedFiles.size
+        );
+      }
       await this._pruneExtraneous(
         target,
         expectedDirs,
@@ -1342,6 +1391,9 @@ ${err.stack}` : String(err);
         preRestore
       );
     }
+    if (this._restoreLocked.length > 0) {
+      throw new PartialRestoreError([...this._restoreLocked]);
+    }
   }
   /**
    * Recursively collects the absolute paths of all files under `currentDir`.
@@ -1406,18 +1458,26 @@ ${err.stack}` : String(err);
           );
         }
         await mkdir(dirname(filePath), { recursive: true });
-        await FsAgent._atomicWriteFile(filePath, fileBlob.content);
-        this._restoreWritten++;
-        if (meta.mtime) {
-          const mtime = new Date(meta.mtime);
-          await utimes(filePath, mtime, mtime);
-        }
-        if (meta.size !== void 0 && meta.mtime !== void 0) {
-          this._restoredBlobs.set(filePath, {
-            blobId: meta.blobId,
-            size: meta.size,
-            mtime: meta.mtime
-          });
+        try {
+          await FsAgent._atomicWriteFile(filePath, fileBlob.content);
+          this._restoreWritten++;
+          if (meta.mtime) {
+            const mtime = new Date(meta.mtime);
+            await utimes(filePath, mtime, mtime);
+          }
+          if (meta.size !== void 0 && meta.mtime !== void 0) {
+            this._restoredBlobs.set(filePath, {
+              blobId: meta.blobId,
+              size: meta.size,
+              mtime: meta.mtime
+            });
+          }
+        } catch (error) {
+          if (!FsAgent._isLocked(error)) throw error;
+          console.warn(
+            `[FsAgent] restore: "${meta.relativePath}" is held open by another process (${error.code}) — skipped, will retry`
+          );
+          this._restoreLocked.push(meta.relativePath);
         }
       }
     } else if (meta.type === "directory") {
@@ -1430,6 +1490,20 @@ ${err.stack}` : String(err);
       }
     }
   }
+  /**
+   * Whether a caught value means "another process is holding this file".
+   *
+   * Windows reports a locked file as EPERM or EBUSY; EACCES covers the
+   * permission-denied shape. Deliberately narrow — anything else is a real
+   * write failure and must still abort, because a restore that shrugged off
+   * every error would report success while leaving the folder wrong.
+   * @param err - The caught value.
+   * @returns `true` for a lock-shaped error.
+   */
+  static _isLocked(err) {
+    const code = err?.code;
+    return code === "EPERM" || code === "EBUSY" || code === "EACCES";
+  }
   /**
    * The content identity this agent believes is on disk at `filePath`, or
    * `undefined` when it has no basis for an opinion.
@@ -2119,6 +2193,13 @@ ${err.stack}` : String(err);
           this._currentRef = postRestoreRef;
           return;
         } catch (err) {
+          if (err instanceof RestoreIncompleteError) {
+            try {
+              const halfApplied = await this._scanner.scan();
+              this._lastSentContentKey = this._contentKeyFromTree(halfApplied);
+            } catch {
+            }
+          }
           if (attempt === maxAttempts) {
             if (recoveryAttempt >= this._timeouts.recoveryRetries) {
               console.error(

package/package.json

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