chainlesschain 0.165.1 → 0.165.3

package/src/lib/with-file-lock.js

@@ -14,14 +14,18 @@
  * reclaimed merely because the directory is old, and corrupt ownership fails
  * closed. The default filesystem publishes a fully populated, uniquely staged
  * directory in one rename so a process killed during acquisition cannot expose
- * an ownerless lock. Confirmed-dead owners are reclaimed with an exact-token
- * marker inside the lock directory so a delayed contender cannot delete a
- * replacement lock. Strict callers may use bounded jittered retries and an
+ * an ownerless lock. Confirmed-dead owners are reclaimed with an exact-token,
+ * process-owned claim inside the lock directory so a delayed contender cannot
+ * delete a replacement lock and another contender can take over if the first
+ * reclaimer is killed. Strict callers may use bounded jittered retries and an
  * after-release yield to avoid Windows sharing transients and fixed-interval
  * lock convoys.
  *
  * @param {string} targetPath  the file being guarded (lock is `${targetPath}.lock`)
- * @param {(ctx:{locked:boolean})=>T} fn  critical section; receives whether the lock was held
+ * @param {(ctx:{locked:boolean,publishReleaseAfterPathRemoved:(pendingPath:string)=>boolean})=>T} fn
+ *   critical section; `publishReleaseAfterPathRemoved` lets a transaction
+ *   publish an exact, contender-completable handoff before its final atomic
+ *   rename removes a uniquely named staging path
  * @returns {T} whatever `fn` returns
  */
 export function withFileLock(targetPath, fn, opts = {}) {
@@ -54,7 +58,9 @@ export function withFileLock(targetPath, fn, opts = {}) {
   };
   let held = false;
   let acquisitionError = null;
+  let lastOwnerObservation = null;
   let retryAttempt = 0;
+  let releasePublished = false;
   const deadline = _now() + timeoutMs;
 
   for (;;) {
@@ -88,10 +94,44 @@ export function withFileLock(targetPath, fn, opts = {}) {
       const incumbent = ownerRead.owner;
       acquisitionError = ownerRead.error;
       if (incumbent) {
-        if (!isOwnerAlive(incumbent)) {
-          if (reclaimOwnedDirectory(_fs, lockDir, incumbent, isOwnerAlive)) {
+        let incumbentAlive = true;
+        try {
+          incumbentAlive = isOwnerAlive(incumbent);
+        } catch {
+          // An unavailable identity probe must retain the lock.
+        }
+        lastOwnerObservation = {
+          pid: incumbent.pid,
+          startedAt: incumbent.startedAt,
+          alive: incumbentAlive,
+        };
+        // The owner writes this exact-token marker only after its critical
+        // section has finished. A Windows sharing violation can then prevent
+        // the final recursive removal while the owner process remains alive,
+        // which would otherwise strand every later strict caller behind a
+        // lock that no longer protects any work. Complete only the release
+        // explicitly published by the still-current owner; a missing,
+        // corrupt or mismatched marker remains fail-closed.
+        const publishedRelease = completePublishedRelease(
+          _fs,
+          lockDir,
+          incumbent,
+          owner,
+          isOwnerAlive,
+        );
+        lastOwnerObservation.releasePublished = publishedRelease.published;
+        if (publishedRelease.completed) continue;
+        if (!incumbentAlive) {
+          // A published handoff can still retain its unique staging path when
+          // the owner is killed between marker publication and the atomic
+          // replacement. No process can commit that staging file after the
+          // exact owner is proven dead, so the lock directory is reclaimable
+          // whether the transaction committed or not. Leave the private
+          // staging file untouched; it cannot affect the guarded target.
+          if (
+            reclaimOwnedDirectory(_fs, lockDir, incumbent, owner, isOwnerAlive)
+          )
             continue;
-          }
         }
       } else if (!failIfUnavailable) {
         // Compatibility for legacy best-effort locks that predate owner.json.
@@ -124,12 +164,21 @@ export function withFileLock(targetPath, fn, opts = {}) {
   }
 
   if (!held && failIfUnavailable) {
+    const ownerDetails = lastOwnerObservation
+      ? `; owner pid=${lastOwnerObservation.pid}, ageMs=${Math.max(
+          0,
+          _now() - lastOwnerObservation.startedAt,
+        )}, alive=${lastOwnerObservation.alive}, releasePublished=${Boolean(lastOwnerObservation.releasePublished)}`
+      : "";
     const error = new Error(
-      `Could not acquire state lock: ${targetPath}`,
+      `Could not acquire state lock: ${targetPath}${ownerDetails}`,
       acquisitionError ? { cause: acquisitionError } : undefined,
     );
     error.code = "STATE_LOCK_UNAVAILABLE";
     error.attempts = retryAttempt + 1;
+    error.lockOwner = lastOwnerObservation
+      ? Object.freeze({ ...lastOwnerObservation })
+      : null;
     throw error;
   }
 
@@ -137,7 +186,32 @@ export function withFileLock(targetPath, fn, opts = {}) {
   let bodyThrew = false;
   let result;
   try {
-    result = fn({ locked: held });
+    result = fn({
+      locked: held,
+      publishReleaseAfterPathRemoved(pendingPath) {
+        if (!held || typeof pendingPath !== "string" || !pendingPath) {
+          return false;
+        }
+        const current = readOwner(_fs, ownerPath);
+        if (!sameOwner(current, owner)) return false;
+        const markerPath = path.join(lockDir, `.release-${owner.token}`);
+        const marker = { ...owner, releaseAfterPathRemoved: pendingPath };
+        try {
+          writeOwnerMarker(_fs, markerPath, marker);
+        } catch (error) {
+          if (error?.code !== "EEXIST") throw error;
+          const existing = readOwner(_fs, markerPath);
+          if (
+            !sameOwner(existing, owner) ||
+            existing?.releaseAfterPathRemoved !== pendingPath
+          ) {
+            return false;
+          }
+        }
+        releasePublished = true;
+        return true;
+      },
+    });
   } catch (error) {
     bodyThrew = true;
     bodyError = error;
@@ -146,7 +220,13 @@ export function withFileLock(targetPath, fn, opts = {}) {
   let releaseError = null;
   if (held) {
     try {
-      released = releaseOwnedDirectory(_fs, lockDir, owner);
+      released = releaseOwnedDirectory(
+        _fs,
+        lockDir,
+        owner,
+        isOwnerAlive,
+        releasePublished,
+      );
     } catch (error) {
       releaseError = error;
     }
@@ -160,8 +240,9 @@ export function withFileLock(targetPath, fn, opts = {}) {
     throw error;
   }
   if (held && released && yieldAfterReleaseMs > 0) {
-    // The lock is already gone. This lets an existing waiter run before a
-    // process performing many tiny transactions can immediately reacquire it.
+    // The lock is gone or its exact release marker has transferred cleanup to
+    // contenders. Let an existing waiter run before a process performing many
+    // tiny transactions can immediately reacquire it.
     _sleep(yieldAfterReleaseMs);
   }
   return result;
@@ -235,6 +316,15 @@ function directoryExists(_fs, target) {
   }
 }
 
+function pathStatus(_fs, target) {
+  try {
+    _fs.statSync(target);
+    return "present";
+  } catch (error) {
+    return error?.code === "ENOENT" ? "absent" : "unknown";
+  }
+}
+
 function isProcessAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -345,21 +435,65 @@ function writeOwnerMarker(_fs, markerPath, owner) {
   });
 }
 
-function reclaimOwnedDirectory(_fs, lockDir, owner, ownerAlive) {
-  const markerPath = path.join(lockDir, `.reclaim-${owner.token}`);
-  try {
-    writeOwnerMarker(_fs, markerPath, owner);
-  } catch (error) {
-    if (error?.code === "ENOENT" || error?.code === "EEXIST") return false;
-    throw error;
+function reclaimOwnedDirectory(_fs, lockDir, incumbent, claimant, ownerAlive) {
+  const claimPath = path.join(lockDir, `.reclaim-${incumbent.token}`);
+  for (;;) {
+    const existingClaim = readOwner(_fs, claimPath);
+    if (existingClaim) {
+      if (sameOwner(existingClaim, claimant)) break;
+      if (!ownerAlive(existingClaim)) {
+        if (removeOwnMarker(_fs, claimPath, existingClaim)) continue;
+      }
+      return false;
+    }
+    try {
+      // The claim belongs to the contender, not the dead incumbent. If this
+      // contender is killed before detaching the directory, another process
+      // can prove that exact claimant dead and safely take over.
+      writeOwnerMarker(_fs, claimPath, claimant);
+      break;
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        return !directoryExists(_fs, lockDir);
+      }
+      if (error?.code === "EEXIST" || isTransientLockError(error)) {
+        return false;
+      }
+      throw error;
+    }
   }
+
   const current = readOwner(_fs, path.join(lockDir, "owner.json"));
-  if (!sameOwner(current, owner) || ownerAlive(owner)) {
-    removeOwnMarker(_fs, markerPath, owner);
+  if (!sameOwner(current, incumbent) || ownerAlive(incumbent)) {
+    removeOwnMarker(_fs, claimPath, claimant);
     return false;
   }
-  _fs.rmSync(lockDir, { recursive: true, force: true });
-  return true;
+
+  if (typeof _fs.renameSync !== "function") {
+    _fs.rmSync(lockDir, { recursive: true, force: true });
+    return true;
+  }
+
+  const cleanupDir = `${lockDir}.reclaimed-${incumbent.token}-${claimant.token}`;
+  try {
+    // Free the acquisition path atomically before recursive cleanup. A killed
+    // reclaimer can therefore leave only uniquely named debris, never a
+    // claimant marker that permanently fences the shared lock path.
+    _fs.renameSync(lockDir, cleanupDir);
+    try {
+      _fs.rmSync(cleanupDir, { recursive: true, force: true });
+    } catch {
+      /* private reclaim debris is harmless after the lock path is detached */
+    }
+    return true;
+  } catch (error) {
+    removeOwnMarker(_fs, claimPath, claimant);
+    if (error?.code === "ENOENT") {
+      return !directoryExists(_fs, lockDir);
+    }
+    if (isTransientLockError(error)) return false;
+    throw error;
+  }
 }
 
 function reclaimLegacyDirectory(_fs, lockDir, stat) {
@@ -383,9 +517,96 @@ function reclaimLegacyDirectory(_fs, lockDir, stat) {
   return true;
 }
 
-function releaseOwnedDirectory(_fs, lockDir, owner) {
+function completePublishedRelease(_fs, lockDir, owner, claimant, ownerAlive) {
+  const markerPath = path.join(lockDir, `.release-${owner.token}`);
+  const marker = readOwner(_fs, markerPath);
+  if (!sameOwner(marker, owner)) {
+    return { published: false, completed: false };
+  }
+  // A state transaction can stage its exact replacement, publish this marker,
+  // and only then atomically rename the staging file over the guarded target.
+  // Contenders may complete the release only after that unique staging path is
+  // gone. This closes the otherwise unbounded scheduler-preemption window
+  // between a committed rename and the owner's first release syscall without
+  // ever exposing an in-progress write to a competing critical section.
+  if (
+    typeof marker.releaseAfterPathRemoved === "string" &&
+    marker.releaseAfterPathRemoved &&
+    pathStatus(_fs, marker.releaseAfterPathRemoved) !== "absent"
+  ) {
+    return { published: true, completed: false };
+  }
+  const claimPath = path.join(lockDir, `.release-claim-${owner.token}`);
+  for (;;) {
+    const existingClaim = readOwner(_fs, claimPath);
+    if (existingClaim) {
+      if (sameOwner(existingClaim, claimant)) break;
+      if (!ownerAlive(existingClaim)) {
+        if (removeOwnMarker(_fs, claimPath, existingClaim)) continue;
+      }
+      return { published: true, completed: false };
+    }
+    try {
+      writeOwnerMarker(_fs, claimPath, claimant);
+      break;
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        return { published: true, completed: !directoryExists(_fs, lockDir) };
+      }
+      if (error?.code === "EEXIST" || isTransientLockError(error)) {
+        return { published: true, completed: false };
+      }
+      throw error;
+    }
+  }
   if (!sameOwner(readOwner(_fs, path.join(lockDir, "owner.json")), owner)) {
-    return false;
+    removeOwnMarker(_fs, claimPath, claimant);
+    return { published: true, completed: false };
+  }
+  const cleanupDir = `${lockDir}.released-${owner.token}-${claimant.token}`;
+  try {
+    // Detach the exact released directory from the acquisition path before
+    // cleaning it. Recursive removal may span several Windows filesystem
+    // operations; deleting `lockDir` in place lets a new atomic acquirer
+    // install a replacement between those operations and risks deleting that
+    // replacement. The claimant token makes delayed cleanup private to this
+    // handoff, just like the owner's normal rename-first release path.
+    _fs.renameSync(lockDir, cleanupDir);
+    try {
+      _fs.rmSync(cleanupDir, { recursive: true, force: true });
+    } catch {
+      // The acquisition path is already free. A uniquely named released
+      // directory is harmless bounded debris if Windows still holds a handle.
+    }
+    return { published: true, completed: true };
+  } catch (error) {
+    removeOwnMarker(_fs, claimPath, claimant);
+    if (error?.code === "ENOENT") {
+      return { published: true, completed: !directoryExists(_fs, lockDir) };
+    }
+    // A Windows sharing transient leaves the exact release marker in place so
+    // this or another contender can retry within its normal deadline.
+    if (isTransientLockError(error)) {
+      return { published: true, completed: false };
+    }
+    throw error;
+  }
+}
+
+function releaseOwnedDirectory(
+  _fs,
+  lockDir,
+  owner,
+  ownerAlive,
+  releaseWasPublished = false,
+) {
+  if (!sameOwner(readOwner(_fs, path.join(lockDir, "owner.json")), owner)) {
+    // Once this exact owner published a guarded handoff, a contender is allowed
+    // to detach the old directory as soon as the final staging path disappears.
+    // A missing or replacement lock therefore proves successful release, not
+    // ownership loss. Without that publication the strict legacy verdict stays
+    // fail-closed.
+    return releaseWasPublished;
   }
   // Atomically move the exact owned directory out of the acquisition path,
   // then remove that uniquely-tokened directory. A replacement owner may
@@ -404,7 +625,7 @@ function releaseOwnedDirectory(_fs, lockDir, owner) {
       }
       return true;
     } catch (error) {
-      if (error?.code === "ENOENT") return false;
+      if (error?.code === "ENOENT") return releaseWasPublished;
       // Windows sharing transients fall back to the marker-based release.
     }
   }
@@ -412,13 +633,31 @@ function releaseOwnedDirectory(_fs, lockDir, owner) {
   try {
     writeOwnerMarker(_fs, markerPath, owner);
   } catch (error) {
-    if (error?.code === "ENOENT" || error?.code === "EEXIST") return false;
+    if (error?.code === "ENOENT") return releaseWasPublished;
+    if (error?.code === "EEXIST") {
+      const existing = readOwner(_fs, markerPath);
+      if (!sameOwner(existing, owner)) return false;
+      return completePublishedRelease(_fs, lockDir, owner, owner, ownerAlive)
+        .published;
+    }
     throw error;
   }
   if (!sameOwner(readOwner(_fs, path.join(lockDir, "owner.json")), owner)) {
     removeOwnMarker(_fs, markerPath, owner);
     return false;
   }
+  if (typeof _fs.renameSync === "function") {
+    // After publishing the marker, use the same exclusive claim protocol as a
+    // later contender. The releasing process must not perform an unclaimed,
+    // delayed delete: another process could complete the release and install a
+    // replacement lock before that delete resumes.
+    // Publishing the exact release marker is the logical handoff point. A
+    // contender may win the cleanup claim before this owner does; that is a
+    // successful release, not lost ownership, because every acquirer must
+    // complete or wait behind the published marker before entering its body.
+    return completePublishedRelease(_fs, lockDir, owner, owner, ownerAlive)
+      .published;
+  }
   _fs.rmSync(lockDir, { recursive: true, force: true });
   return true;
 }