@rljson/fs-agent 0.0.21 → 0.0.23

package/dist/fs-agent.d.ts

@@ -131,6 +131,21 @@ export declare const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
 /**
  * Orchestrates filesystem operations with tree structures and blob storage
  */
+/**
+ * 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 Error {
+    readonly lockedPaths: string[];
+    constructor(lockedPaths: string[]);
+}
 export declare class FsAgent {
     private _scanner;
     private _adapter;
@@ -159,6 +174,16 @@ export declare class FsAgent {
      * view — and undo a deletion the peer just made.
      */
     private _remoteApplyInFlight;
+    /** 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.
+     */
+    private _restoredBlobs;
     private _timeouts;
     /** Client-only: resolve DAG-branch conflicts into merge revisions. */
     private _resolveConflicts;
@@ -292,8 +317,59 @@ export declare class FsAgent {
      * @param treeHash - Hash of the tree node to restore
      * @param trees - Map of all tree nodes
      * @param targetPath - Target directory path
+     * @param isOwnRoot - Whether `targetPath` is this agent's own folder, which
+     *   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.
+     *
+     * Two sources, both anchored on a real blobId rather than a guess:
+     * what this agent last wrote there, and what the scanner hashed at its last
+     * scan of the folder (which survives a restart, so a fresh process still
+     * skips an unchanged 80 GB catalogue).
+     * @param filePath - Absolute path of the file.
+     * @param relativePath - Its path within the tree.
+     * @param isOwnRoot - Whether the restore target is this agent's own folder,
+     *   which is the only case where the scanner's view describes this file.
+     * @returns The believed content identity, or `undefined`.
+     */
+    private _knownOnDisk;
+    /**
+     * Whether the file at `filePath` is already the content `meta` describes.
+     *
+     * The decision is anchored on the blobId: a different blobId is always
+     * rewritten, whatever the timestamps say. Hashing the file instead would
+     * mean reading 80 GB to avoid writing 80 GB, which saves nothing — so the
+     * known blobId is verified against a `stat`, which catches a file edited
+     * since this agent last had an opinion about it.
+     *
+     * Deliberately one-directional in its uncertainty: every unclear case
+     * answers `false` and the file is rewritten. A needless write costs time; a
+     * wrongly skipped write leaves the wrong bytes on disk indefinitely.
+     *
+     * Anchoring on the blobId is not belt-and-braces. Size and mtime alone
+     * cannot see a same-size edit made inside the same millisecond — the scan
+     * cache tolerates that, but a restore must not: there the cost is not a
+     * stale cache entry, it is the wrong file contents left in place.
+     * @param filePath - Absolute path of the file to check.
+     * @param meta - The metadata describing the content that should be there.
+     * @param isOwnRoot - Whether the target is this agent's own folder.
+     * @returns `true` only when the file is certainly already correct.
+     */
+    private _alreadyOnDisk;
     /**
      * Gets the current tree structure
      */

package/dist/fs-agent.js

@@ -1022,6 +1022,15 @@ const DEFAULT_TIMEOUTS = {
 const DISCONNECT_PAUSE_MAX_MS = 3e4;
 const SYNC_ERROR_FILE = ".sync-errors.log";
 const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
+class PartialRestoreError extends Error {
+  constructor(lockedPaths) {
+    super(
+      `restore could not write ${lockedPaths.length} locked file${lockedPaths.length === 1 ? "" : "s"}: ${lockedPaths.join(", ")}`
+    );
+    this.lockedPaths = lockedPaths;
+    this.name = "PartialRestoreError";
+  }
+}
 class FsAgent {
   _scanner;
   _adapter;
@@ -1050,6 +1059,16 @@ class FsAgent {
    * view — and undo a deletion the peer just made.
    */
   _remoteApplyInFlight = false;
+  /** 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.
+   */
+  _restoredBlobs = /* @__PURE__ */ new Map();
   _timeouts;
   /** Client-only: resolve DAG-branch conflicts into merge revisions. */
   _resolveConflicts;
@@ -1313,7 +1332,20 @@ ${err.stack}` : String(err);
       target
     );
     const preRestore = options?.cleanTarget ? await this._collectAllFiles(target) : /* @__PURE__ */ new Set();
-    await this._restoreTree(tree.rootHash, tree.trees, target);
+    this._restoreWritten = 0;
+    this._restoreSkipped = 0;
+    this._restoreLocked = [];
+    await this._restoreTree(
+      tree.rootHash,
+      tree.trees,
+      target,
+      target === this._rootPath
+    );
+    if (this._restoreSkipped > 0) {
+      console.log(
+        `[FsAgent] restore: wrote ${this._restoreWritten}, left ${this._restoreSkipped} already-correct file${this._restoreSkipped === 1 ? "" : "s"} untouched`
+      );
+    }
     if (options?.cleanTarget) {
       await this._pruneExtraneous(
         target,
@@ -1322,6 +1354,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`.
@@ -1353,8 +1388,10 @@ ${err.stack}` : String(err);
    * @param treeHash - Hash of the tree node to restore
    * @param trees - Map of all tree nodes
    * @param targetPath - Target directory path
+   * @param isOwnRoot - Whether `targetPath` is this agent's own folder, which
+   *   is the only case where the scanner's view describes these files
    */
-  async _restoreTree(treeHash, trees, targetPath) {
+  async _restoreTree(treeHash, trees, targetPath, isOwnRoot) {
     const treeNode = trees.get(treeHash);
     if (!treeNode) {
       throw new Error(`Tree node not found: ${treeHash}`);
@@ -1366,6 +1403,10 @@ ${err.stack}` : String(err);
     if (meta.type === "file") {
       const filePath = join(targetPath, meta.relativePath);
       if (meta.blobId) {
+        if (await this._alreadyOnDisk(filePath, meta, isOwnRoot)) {
+          this._restoreSkipped++;
+          return;
+        }
         let fileBlob;
         try {
           fileBlob = await this._bs.getBlob(meta.blobId);
@@ -1380,10 +1421,26 @@ ${err.stack}` : String(err);
           );
         }
         await mkdir(dirname(filePath), { recursive: true });
-        await FsAgent._atomicWriteFile(filePath, fileBlob.content);
-        if (meta.mtime) {
-          const mtime = new Date(meta.mtime);
-          await utimes(filePath, mtime, 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") {
@@ -1391,11 +1448,89 @@ ${err.stack}` : String(err);
       await mkdir(dirPath, { recursive: true });
       if (treeNode.children && Array.isArray(treeNode.children)) {
         for (const childHash of treeNode.children) {
-          await this._restoreTree(childHash, trees, targetPath);
+          await this._restoreTree(childHash, trees, targetPath, isOwnRoot);
         }
       }
     }
   }
+  /**
+   * 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.
+   *
+   * Two sources, both anchored on a real blobId rather than a guess:
+   * what this agent last wrote there, and what the scanner hashed at its last
+   * scan of the folder (which survives a restart, so a fresh process still
+   * skips an unchanged 80 GB catalogue).
+   * @param filePath - Absolute path of the file.
+   * @param relativePath - Its path within the tree.
+   * @param isOwnRoot - Whether the restore target is this agent's own folder,
+   *   which is the only case where the scanner's view describes this file.
+   * @returns The believed content identity, or `undefined`.
+   */
+  _knownOnDisk(filePath, relativePath, isOwnRoot) {
+    const written = this._restoredBlobs.get(filePath);
+    if (written) return written;
+    if (!isOwnRoot) return void 0;
+    const scanned = this._scanner.getTreeByPath(relativePath)?.meta;
+    if (scanned?.blobId === void 0 || scanned.size === void 0 || scanned.mtime === void 0) {
+      return void 0;
+    }
+    return {
+      blobId: scanned.blobId,
+      size: scanned.size,
+      mtime: scanned.mtime
+    };
+  }
+  /**
+   * Whether the file at `filePath` is already the content `meta` describes.
+   *
+   * The decision is anchored on the blobId: a different blobId is always
+   * rewritten, whatever the timestamps say. Hashing the file instead would
+   * mean reading 80 GB to avoid writing 80 GB, which saves nothing — so the
+   * known blobId is verified against a `stat`, which catches a file edited
+   * since this agent last had an opinion about it.
+   *
+   * Deliberately one-directional in its uncertainty: every unclear case
+   * answers `false` and the file is rewritten. A needless write costs time; a
+   * wrongly skipped write leaves the wrong bytes on disk indefinitely.
+   *
+   * Anchoring on the blobId is not belt-and-braces. Size and mtime alone
+   * cannot see a same-size edit made inside the same millisecond — the scan
+   * cache tolerates that, but a restore must not: there the cost is not a
+   * stale cache entry, it is the wrong file contents left in place.
+   * @param filePath - Absolute path of the file to check.
+   * @param meta - The metadata describing the content that should be there.
+   * @param isOwnRoot - Whether the target is this agent's own folder.
+   * @returns `true` only when the file is certainly already correct.
+   */
+  async _alreadyOnDisk(filePath, meta, isOwnRoot) {
+    const known = this._knownOnDisk(
+      filePath,
+      meta.relativePath,
+      isOwnRoot
+    );
+    if (!known || known.blobId !== meta.blobId) return false;
+    try {
+      const st = await stat(filePath);
+      return st.size === known.size && Math.abs(st.mtimeMs - known.mtime) < 1;
+    } catch {
+      return false;
+    }
+  }
   /**
    * Gets the current tree structure
    */
@@ -2021,6 +2156,13 @@ ${err.stack}` : String(err);
           this._currentRef = postRestoreRef;
           return;
         } catch (err) {
+          if (err instanceof PartialRestoreError) {
+            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.21",
+  "version": "0.0.23",
   "description": "Rljson fs-agent description",
   "homepage": "https://github.com/rljson/fs-agent",
   "bugs": "https://github.com/rljson/fs-agent/issues",