aether-colony 3.1.5 → 3.1.16

package/bin/lib/file-lock.js

@@ -10,7 +10,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { FileSystemError } = require('./errors');
+const { FileSystemError, ConfigurationError } = require('./errors');
 
 /**
  * Default configuration for lock behavior
@@ -20,8 +20,15 @@ const DEFAULT_OPTIONS = {
   timeout: 5000,        // 5 seconds total timeout
   retryInterval: 50,    // 50ms between retries
   maxRetries: 100,      // Total 5 seconds max wait
+  maxLockAge: 5 * 60 * 1000,  // 5 minutes - configurable stale lock threshold
 };
 
+/**
+ * Module-level set of registered cleanup functions (PLAN-006 fix #4)
+ * Prevents duplicate cleanup handler registration across multiple FileLock instances
+ */
+const registeredCleanups = new Set();
+
 /**
  * FileLock class for exclusive file locking with stale detection
  *
@@ -37,9 +44,51 @@ class FileLock {
    * @param {number} options.timeout - Total timeout in milliseconds (default: 5000)
    * @param {number} options.retryInterval - Milliseconds between retries (default: 50)
    * @param {number} options.maxRetries - Maximum retry attempts (default: 100)
+   * @param {number} options.maxLockAge - Maximum lock age in ms before considered stale (default: 300000)
    */
   constructor(options = {}) {
     this.options = { ...DEFAULT_OPTIONS, ...options };
+
+    // Validate lockDir (PLAN-006 fix #2)
+    if (!this.options.lockDir || typeof this.options.lockDir !== 'string') {
+      throw new ConfigurationError(
+        'lockDir must be a non-empty string',
+        { lockDir: this.options.lockDir }
+      );
+    }
+
+    // Validate timeout (PLAN-006 fix #5)
+    if (typeof this.options.timeout !== 'number' || this.options.timeout < 0) {
+      throw new ConfigurationError(
+        'timeout must be a non-negative number',
+        { timeout: this.options.timeout }
+      );
+    }
+
+    // Validate retryInterval
+    if (typeof this.options.retryInterval !== 'number' || this.options.retryInterval < 0) {
+      throw new ConfigurationError(
+        'retryInterval must be a non-negative number',
+        { retryInterval: this.options.retryInterval }
+      );
+    }
+
+    // Validate maxRetries
+    if (typeof this.options.maxRetries !== 'number' || this.options.maxRetries < 0) {
+      throw new ConfigurationError(
+        'maxRetries must be a non-negative number',
+        { maxRetries: this.options.maxRetries }
+      );
+    }
+
+    // Validate maxLockAge (PLAN-007 Fix 1)
+    if (typeof this.options.maxLockAge !== 'number' || this.options.maxLockAge < 0) {
+      throw new ConfigurationError(
+        'maxLockAge must be a non-negative number',
+        { maxLockAge: this.options.maxLockAge }
+      );
+    }
+
     this.currentLock = null;
     this.currentPidFile = null;
 
@@ -69,9 +118,20 @@ class FileLock {
 
   /**
    * Register process cleanup handlers to ensure locks are released on exit
+   * Uses module-level tracking to prevent duplicate registrations (PLAN-006 fix #4)
    * @private
    */
   _registerCleanupHandlers() {
+    // Create unique identifier for this cleanup based on lock directory
+    const cleanupId = `filelock-${this.options.lockDir}`;
+
+    // Only register if not already registered
+    if (registeredCleanups.has(cleanupId)) {
+      return;
+    }
+
+    registeredCleanups.add(cleanupId);
+
     const cleanup = () => {
       this.release();
     };
@@ -131,50 +191,111 @@ class FileLock {
     }
   }
 
+  /**
+   * Safely unlink a file, ignoring ENOENT errors
+   *
+   * @param {string} filePath - Path to file to unlink
+   * @private
+   */
+  _safeUnlink(filePath) {
+    try {
+      fs.unlinkSync(filePath);
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        // Log but don't throw - we're cleaning up
+        console.warn(`Warning: Failed to clean up ${filePath}: ${error.message}`);
+      }
+    }
+  }
+
   /**
    * Clean up stale lock files
    *
+   * Checks both PID file and lock file for PID (handles crash scenarios
+   * where only one file was created). Also checks lock age to handle
+   * PID reuse race condition.
+   *
    * @param {string} lockFile - Path to lock file
    * @param {string} pidFile - Path to PID file
+   * @returns {boolean} True if lock was cleaned up, false if still held
    * @private
    */
   _cleanupStaleLock(lockFile, pidFile) {
+    // Maximum lock age before considering stale (configurable, default 5 minutes)
+    // This handles PID reuse race condition
+    const maxLockAgeMs = this.options.maxLockAge;
+
     try {
-      // Try to read the PID from the pid file
-      if (fs.existsSync(pidFile)) {
-        const pidData = fs.readFileSync(pidFile, 'utf8').trim();
-        const pid = parseInt(pidData, 10);
-
-        if (!isNaN(pid)) {
-          // Check if the process is still running
-          if (this._isProcessRunning(pid)) {
-            // Process is running, lock is not stale
-            return false;
+      // Check lock file age first (handles PID reuse)
+      if (fs.existsSync(lockFile)) {
+        try {
+          const stat = fs.statSync(lockFile);
+          const lockAge = Date.now() - stat.mtimeMs;
+
+          if (lockAge > maxLockAgeMs) {
+            // Lock is old enough to be considered stale regardless of PID
+            this._safeUnlink(lockFile);
+            this._safeUnlink(pidFile);
+            return true;
           }
+        } catch {
+          // Cannot stat, proceed with PID check
         }
       }
 
-      // Either no valid PID or process not running - clean up stale lock
-      try {
-        fs.unlinkSync(lockFile);
-      } catch (error) {
-        if (error.code !== 'ENOENT') {
-          throw error;
+      let pid = null;
+
+      // Try to read PID from PID file first
+      if (fs.existsSync(pidFile)) {
+        try {
+          const pidData = fs.readFileSync(pidFile, 'utf8').trim();
+
+          // Validate PID is a positive integer (PLAN-006 fix #3)
+          if (!/^\d+$/.test(pidData)) {
+            // PID file contains invalid data - clean it up
+            this._safeUnlink(lockFile);
+            this._safeUnlink(pidFile);
+            return true;
+          }
+
+          pid = parseInt(pidData, 10);
+        } catch (readError) {
+          // PID file unreadable - will clean up
         }
       }
 
-      try {
-        fs.unlinkSync(pidFile);
-      } catch (error) {
-        if (error.code !== 'ENOENT') {
-          throw error;
+      // If no valid PID from PID file, try lock file itself
+      if ((pid === null || isNaN(pid)) && fs.existsSync(lockFile)) {
+        try {
+          const lockData = fs.readFileSync(lockFile, 'utf8').trim();
+
+          // Validate PID is a positive integer
+          if (!/^\d+$/.test(lockData)) {
+            // Lock file contains invalid data - clean it up
+            this._safeUnlink(lockFile);
+            this._safeUnlink(pidFile);
+            return true;
+          }
+
+          pid = parseInt(lockData, 10);
+        } catch (readError) {
+          // Lock file unreadable - will clean up
         }
       }
 
+      // Check if process is running
+      if (!isNaN(pid) && this._isProcessRunning(pid)) {
+        // Process is running, lock is valid
+        return false;
+      }
+
+      // Either no valid PID or process not running - clean up stale lock
+      this._safeUnlink(lockFile);
+      this._safeUnlink(pidFile);
+
       return true;
     } catch (error) {
       if (error.code === 'ENOENT') {
-        // Lock file doesn't exist, consider it cleaned
         return true;
       }
       throw new FileSystemError(
@@ -187,39 +308,73 @@ class FileLock {
   /**
    * Attempt to acquire a lock atomically
    *
+   * Uses PID-file-first ordering for crash recovery:
+   * 1. Write PID file first (if this fails, no lock file created)
+   * 2. Create lock file atomically
+   * 3. On failure, clean up both files
+   *
    * @param {string} lockFile - Path to lock file
    * @param {string} pidFile - Path to PID file
    * @returns {boolean} True if lock acquired, false otherwise
+   * @throws {FileSystemError} On unexpected filesystem errors
    * @private
    */
   _tryAcquire(lockFile, pidFile) {
-    try {
-      // Attempt atomic creation using 'wx' flag (fails if file exists)
-      const fd = fs.openSync(lockFile, 'wx');
+    let pidFileCreated = false;
+    let lockFileCreated = false;
 
+    try {
+      // Step 1: Write PID file first (easier to clean up if lock fails)
       try {
-        // Write current PID to lock file
-        const pid = process.pid;
-        fs.writeFileSync(fd, pid.toString(), 'utf8');
-      } finally {
-        fs.closeSync(fd);
+        fs.writeFileSync(pidFile, process.pid.toString(), 'utf8');
+        pidFileCreated = true;
+      } catch (pidError) {
+        // Cannot write PID file - cannot proceed
+        throw new FileSystemError(
+          `Failed to write PID file: ${pidFile}`,
+          { error: pidError.message, code: pidError.code }
+        );
       }
 
-      // Also write to separate PID file for easy reading
-      fs.writeFileSync(pidFile, process.pid.toString(), 'utf8');
+      // Step 2: Create lock file atomically
+      try {
+        const fd = fs.openSync(lockFile, 'wx');
+        lockFileCreated = true;
+
+        try {
+          // Write PID to lock file as well (for redundancy)
+          fs.writeFileSync(fd, process.pid.toString(), 'utf8');
+        } finally {
+          fs.closeSync(fd);
+        }
+      } catch (lockError) {
+        if (lockError.code === 'EEXIST') {
+          // Lock file exists - clean up our PID file
+          this._safeUnlink(pidFile);
+          return false;
+        }
+        throw lockError;
+      }
 
-      // Track current lock
+      // Step 3: Track current lock (only after both files created)
       this.currentLock = lockFile;
       this.currentPidFile = pidFile;
 
       return true;
+
     } catch (error) {
-      if (error.code === 'EEXIST') {
-        // Lock file already exists
-        return false;
+      // Clean up on any failure
+      if (lockFileCreated) {
+        this._safeUnlink(lockFile);
+      }
+      if (pidFileCreated) {
+        this._safeUnlink(pidFile);
+      }
+
+      if (error instanceof FileSystemError) {
+        throw error;
       }
 
-      // Unexpected error
       throw new FileSystemError(
         `Failed to acquire lock: ${lockFile}`,
         { error: error.message, code: error.code }
@@ -228,7 +383,10 @@ class FileLock {
   }
 
   /**
-   * Acquire an exclusive lock on a file
+   * Acquire an exclusive lock on a file (SYNCHRONOUS - may block event loop)
+   *
+   * WARNING: This method uses a busy-wait loop that blocks the Node.js event loop
+   * during retry intervals. For non-blocking operation, use acquireAsync() instead.
    *
    * @param {string} filePath - Path to the file to lock
    * @returns {boolean} True if lock acquired, false on timeout
@@ -281,25 +439,26 @@ class FileLock {
    *
    * This method is idempotent - safe to call multiple times.
    *
-   * @returns {boolean} True if a lock was released, false if no lock was held
+   * @returns {boolean} True if lock was fully released, false if no lock was held
+   *                    or if deletion failed (check console.warn for details)
    */
   release() {
     if (!this.currentLock) {
       return false;
     }
 
-    let released = false;
+    let success = true;
 
     // Delete lock file
     try {
       if (fs.existsSync(this.currentLock)) {
         fs.unlinkSync(this.currentLock);
-        released = true;
       }
     } catch (error) {
       if (error.code !== 'ENOENT') {
         // Log but don't throw - we're cleaning up
         console.warn(`Warning: Failed to remove lock file: ${error.message}`);
+        success = false;
       }
     }
 
@@ -312,6 +471,7 @@ class FileLock {
       } catch (error) {
         if (error.code !== 'ENOENT') {
           console.warn(`Warning: Failed to remove PID file: ${error.message}`);
+          success = false;
         }
       }
     }
@@ -320,7 +480,7 @@ class FileLock {
     this.currentLock = null;
     this.currentPidFile = null;
 
-    return released;
+    return success;
   }
 
   /**
@@ -358,7 +518,10 @@ class FileLock {
   }
 
   /**
-   * Wait for a lock to be released
+   * Wait for a lock to be released (SYNCHRONOUS - may block event loop)
+   *
+   * WARNING: This method uses a busy-wait loop that blocks the Node.js event loop.
+   * For non-blocking operation, use waitForLockAsync() instead.
    *
    * @param {string} filePath - Path to wait for
    * @param {number} maxWait - Maximum milliseconds to wait (default: timeout option)
@@ -383,6 +546,78 @@ class FileLock {
     return true;
   }
 
+  /**
+   * Acquire an exclusive lock asynchronously (yields to event loop)
+   *
+   * This is the non-blocking version of acquire(). It uses setTimeout for
+   * delays, allowing other async operations to run during wait periods.
+   *
+   * @param {string} filePath - Path to the file to lock
+   * @returns {Promise<boolean>} True if lock acquired, false on timeout
+   * @throws {FileSystemError} On unexpected filesystem errors
+   */
+  async acquireAsync(filePath) {
+    const { lockFile, pidFile } = this._getLockPaths(filePath);
+
+    // Check for existing lock and handle stale locks
+    if (fs.existsSync(lockFile)) {
+      this._cleanupStaleLock(lockFile, pidFile);
+      // Lock is held by running process if not cleaned
+    }
+
+    // Try to acquire lock with retries
+    let retryCount = 0;
+    const startTime = Date.now();
+
+    while (retryCount < this.options.maxRetries) {
+      // Try to acquire the lock
+      if (this._tryAcquire(lockFile, pidFile)) {
+        return true;
+      }
+
+      // Check timeout
+      if (Date.now() - startTime >= this.options.timeout) {
+        return false;
+      }
+
+      // Wait before retry (ASYNC - yields to event loop)
+      retryCount++;
+      if (retryCount < this.options.maxRetries) {
+        await new Promise(resolve =>
+          setTimeout(resolve, this.options.retryInterval)
+        );
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Wait for a lock to be released asynchronously (yields to event loop)
+   *
+   * This is the non-blocking version of waitForLock(). It uses setTimeout
+   * for delays, allowing other async operations to run during wait periods.
+   *
+   * @param {string} filePath - Path to wait for
+   * @param {number} maxWait - Maximum milliseconds to wait (default: timeout option)
+   * @returns {Promise<boolean>} True if lock was released, false on timeout
+   */
+  async waitForLockAsync(filePath, maxWait = null) {
+    const waitTime = maxWait || this.options.timeout;
+    const startTime = Date.now();
+
+    while (this.isLocked(filePath)) {
+      if (Date.now() - startTime >= waitTime) {
+        return false;
+      }
+
+      // Small async delay (yields to event loop)
+      await new Promise(resolve => setTimeout(resolve, 10));
+    }
+
+    return true;
+  }
+
   /**
    * Force cleanup of all locks in the lock directory
    *