unitup 0.2.0 → 0.3.0

package/src/core/lock.js

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getUnitupDir, sanitizeServiceName } from '../utils.js';
+
+export class DeploymentLockError extends Error {
+  constructor(message, service, lockedPid) {
+    super(message);
+    this.name = 'DeploymentLockError';
+    this.service = service;
+    this.lockedPid = lockedPid;
+  }
+}
+
+/**
+ * Manages per-service deployment locks to prevent concurrent deployments.
+ */
+export class DeploymentLock {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.lockDir]
+   * @param {import('./process-manager.js').ProcessManager} [options.processManager]
+   */
+  constructor(options = {}) {
+    this.lockDir = options.lockDir || path.join(getUnitupDir(), 'locks');
+    this.processManager = options.processManager;
+    this._heldLocks = new Set();
+  }
+
+  getLockFilePath(serviceName) {
+    const safeName = sanitizeServiceName(serviceName);
+    return path.join(this.lockDir, `${safeName}.deploy.lock`);
+  }
+
+  /**
+   * Acquires the deployment lock for a service.
+   * Throws DeploymentLockError if already locked by an active process.
+   *
+   * @param {string} serviceName
+   * @returns {Promise<boolean>}
+   */
+  async acquire(serviceName) {
+    const safeName = sanitizeServiceName(serviceName);
+
+    if (this._heldLocks.has(safeName)) {
+      throw new DeploymentLockError(
+        `Deployment already in progress for service "${safeName}" (PID ${process.pid}).`,
+        safeName,
+        process.pid
+      );
+    }
+
+    const lockPath = this.getLockFilePath(safeName);
+
+    if (!fs.existsSync(this.lockDir)) {
+      fs.mkdirSync(this.lockDir, { recursive: true });
+    }
+
+    if (fs.existsSync(lockPath)) {
+      try {
+        const raw = fs.readFileSync(lockPath, 'utf8');
+        const info = JSON.parse(raw);
+        const lockedPid = Number(info.pid);
+
+        // Check if the holding process is still alive
+        let isAlive = false;
+        if (this.processManager) {
+          isAlive = this.processManager.isAlive(lockedPid);
+        } else if (lockedPid > 0) {
+          try {
+            process.kill(lockedPid, 0);
+            isAlive = true;
+          } catch (err) {
+            isAlive = err.code === 'EPERM';
+          }
+        }
+
+        if (isAlive) {
+          throw new DeploymentLockError(
+            `Deployment already in progress for service "${safeName}" (PID ${lockedPid}).`,
+            safeName,
+            lockedPid
+          );
+        }
+
+        // Process is dead: break stale lock
+        try {
+          fs.unlinkSync(lockPath);
+        } catch {
+          // ignore
+        }
+      } catch (err) {
+        if (err instanceof DeploymentLockError) {
+          throw err;
+        }
+        // Stale or corrupted lock file, overwrite
+      }
+    }
+
+    const payload = {
+      service: safeName,
+      pid: process.pid,
+      timestamp: new Date().toISOString()
+    };
+
+    fs.writeFileSync(lockPath, JSON.stringify(payload, null, 2), { flag: 'wx' });
+    this._heldLocks.add(safeName);
+    return true;
+  }
+
+  /**
+   * Releases the deployment lock for a service.
+   *
+   * @param {string} serviceName
+   * @returns {Promise<boolean>}
+   */
+  async release(serviceName) {
+    const safeName = sanitizeServiceName(serviceName);
+    const lockPath = this.getLockFilePath(safeName);
+
+    this._heldLocks.delete(safeName);
+
+    if (fs.existsSync(lockPath)) {
+      try {
+        fs.unlinkSync(lockPath);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+
+    return true;
+  }
+}

package/src/core/process-manager.js

@@ -0,0 +1,313 @@
+import { spawn, execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * ProcessManager is responsible ONLY for low-level process lifecycle management.
+ * It contains NO deployment sequencing, routing, or drain logic.
+ */
+export class ProcessManager {
+  constructor(options = {}) {
+    this.processes = new Map(); // pid -> processEntry
+    this.recentExits = new Map(); // pid -> exit info { pid, exitCode, exitSignal, recentStderr }
+    this.defaultShutdownTimeout = options.defaultShutdownTimeout || 5000;
+  }
+
+  /**
+   * Spawns a new process.
+   *
+   * @param {string} command - Executable path or command name
+   * @param {string[]} [args] - Command line arguments
+   * @param {object} [options] - Spawn options
+   * @param {string} [options.cwd]
+   * @param {object} [options.env]
+   * @param {string} [options.stdoutPath]
+   * @param {string} [options.stderrPath]
+   * @returns {object} Process record { pid, child, exitPromise }
+   */
+  start(command, args = [], options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const env = { ...process.env, ...(options.env || {}) };
+
+    let cmd = command;
+    let cmdArgs = Array.isArray(args) ? [...args] : [];
+
+    // On Windows, if executing a batch script, wrap with cmd.exe
+    if (process.platform === 'win32' && /\.(bat|cmd)$/i.test(cmd)) {
+      cmdArgs = ['/d', '/s', '/c', `"${cmd}"`, ...cmdArgs];
+      cmd = process.env.COMSPEC || 'cmd.exe';
+    }
+
+    const logStreams = [];
+    let stdoutStream = null;
+    let stderrStream = null;
+
+    if (options.stdoutPath) {
+      const stdoutDir = path.dirname(options.stdoutPath);
+      if (!fs.existsSync(stdoutDir)) {
+        fs.mkdirSync(stdoutDir, { recursive: true });
+      }
+      stdoutStream = fs.createWriteStream(options.stdoutPath, { flags: 'a' });
+      logStreams.push(stdoutStream);
+    }
+
+    if (options.stderrPath) {
+      const stderrDir = path.dirname(options.stderrPath);
+      if (!fs.existsSync(stderrDir)) {
+        fs.mkdirSync(stderrDir, { recursive: true });
+      }
+      stderrStream = fs.createWriteStream(options.stderrPath, { flags: 'a' });
+      logStreams.push(stderrStream);
+    }
+
+    const child = spawn(cmd, cmdArgs, {
+      cwd,
+      env,
+      stdio: ['ignore', stdoutStream ? 'pipe' : 'inherit', 'pipe'],
+      shell: false,
+      windowsHide: true
+    });
+
+    if (stdoutStream && child.stdout) {
+      child.stdout.pipe(stdoutStream, { end: false });
+    }
+
+    let recentStderr = '';
+    if (child.stderr) {
+      child.stderr.on('data', (chunk) => {
+        recentStderr += chunk.toString();
+        if (recentStderr.length > 8192) {
+          recentStderr = recentStderr.slice(-8192);
+        }
+      });
+      if (stderrStream) {
+        child.stderr.pipe(stderrStream, { end: false });
+      }
+    }
+
+    const pid = child.pid;
+    let exitResolver;
+    const exitPromise = new Promise((resolve) => {
+      exitResolver = resolve;
+    });
+
+    const entry = {
+      pid,
+      command: cmd,
+      args: cmdArgs,
+      child,
+      exitPromise,
+      exitCode: null,
+      exitSignal: null,
+      exited: false,
+      logStreams,
+      get recentStderr() {
+        return recentStderr;
+      }
+    };
+
+    child.on('exit', (code, signal) => {
+      entry.exitCode = code;
+      entry.exitSignal = signal;
+      entry.exited = true;
+
+      // Close log streams
+      for (const stream of entry.logStreams) {
+        try {
+          if (stream && !stream.destroyed) stream.end();
+        } catch {
+          // ignore
+        }
+      }
+
+      this.processes.delete(pid);
+      this.recentExits.set(pid, {
+        pid,
+        command: cmd,
+        exitCode: code,
+        exitSignal: signal,
+        recentStderr
+      });
+      if (this.recentExits.size > 50) {
+        const first = this.recentExits.keys().next().value;
+        this.recentExits.delete(first);
+      }
+
+      exitResolver({ code, signal });
+    });
+
+    child.on('error', (err) => {
+      entry.error = err;
+      if (!entry.exited) {
+        entry.exited = true;
+        this.processes.delete(pid);
+        this.recentExits.set(pid, {
+          pid,
+          command: cmd,
+          exitCode: 1,
+          exitSignal: null,
+          recentStderr: err.message || recentStderr
+        });
+        exitResolver({ code: 1, signal: null, error: err });
+      }
+    });
+
+    if (pid) {
+      this.processes.set(pid, entry);
+    }
+
+    return {
+      pid,
+      child,
+      exitPromise
+    };
+  }
+
+  /**
+   * Retrieves process info for an active or recently exited process.
+   *
+   * @param {number|object} processOrPid
+   * @returns {object|null}
+   */
+  getProcess(processOrPid) {
+    const pid = typeof processOrPid === 'number' ? processOrPid : processOrPid?.pid;
+    return this.processes.get(pid) || this.recentExits.get(pid) || null;
+  }
+
+  /**
+   * Checks if a process is alive.
+   *
+   * @param {number|object} processOrPid
+   * @returns {boolean}
+   */
+  isAlive(processOrPid) {
+    const pid = typeof processOrPid === 'number' ? processOrPid : processOrPid?.pid;
+    if (!pid || typeof pid !== 'number' || pid <= 0) return false;
+
+    // Check internal tracked state
+    const entry = this.processes.get(pid);
+    if (entry && entry.exited) return false;
+
+    try {
+      // kill(0) tests whether the process exists without sending a signal
+      process.kill(pid, 0);
+      return true;
+    } catch (err) {
+      // ESRCH means process doesn't exist. EPERM means process exists but we lack permission to signal.
+      return err.code === 'EPERM';
+    }
+  }
+
+  /**
+   * Sends a signal to a process.
+   *
+   * @param {number|object} processOrPid
+   * @param {string|number} [signal='SIGTERM']
+   * @returns {boolean}
+   */
+  signal(processOrPid, signal = 'SIGTERM') {
+    const pid = typeof processOrPid === 'number' ? processOrPid : processOrPid?.pid;
+    if (!pid || !this.isAlive(pid)) return false;
+
+    try {
+      process.kill(pid, signal);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Waits for a process to exit up to an optional timeout.
+   *
+   * @param {number|object} processOrPid
+   * @param {number} [timeout]
+   * @returns {Promise<{ exited: boolean, code?: number, signal?: string }>}
+   */
+  async waitForExit(processOrPid, timeout) {
+    const pid = typeof processOrPid === 'number' ? processOrPid : processOrPid?.pid;
+    if (!pid) return { exited: true };
+
+    const entry = this.processes.get(pid);
+    if (!this.isAlive(pid)) {
+      return { exited: true, code: entry?.exitCode ?? null, signal: entry?.exitSignal ?? null };
+    }
+
+    if (entry && entry.exitPromise) {
+      if (!timeout || timeout <= 0) {
+        const res = await entry.exitPromise;
+        return { exited: true, code: res.code, signal: res.signal };
+      }
+
+      let timer;
+      const timeoutPromise = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ exited: false }), timeout);
+      });
+
+      const res = await Promise.race([
+        entry.exitPromise.then((r) => ({ exited: true, code: r.code, signal: r.signal })),
+        timeoutPromise
+      ]);
+      clearTimeout(timer);
+      return res;
+    }
+
+    // Process is external or untracked PID: poll liveness
+    const pollInterval = 50;
+    const start = Date.now();
+    while (this.isAlive(pid)) {
+      if (timeout && Date.now() - start >= timeout) {
+        return { exited: false };
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    return { exited: true };
+  }
+
+  /**
+   * Stops a process gracefully, then force kills if it does not exit within timeout.
+   *
+   * @param {number|object} processOrPid
+   * @param {object} [options]
+   * @param {number} [options.timeout]
+   * @param {string} [options.signal='SIGTERM']
+   * @returns {Promise<boolean>}
+   */
+  async stop(processOrPid, options = {}) {
+    const pid = typeof processOrPid === 'number' ? processOrPid : processOrPid?.pid;
+    if (!pid || !this.isAlive(pid)) return true;
+
+    const timeout = options.timeout !== undefined ? options.timeout : this.defaultShutdownTimeout;
+    const termSignal = options.signal || 'SIGTERM';
+
+    // 1. Send graceful termination signal
+    this.signal(pid, termSignal);
+
+    // 2. Wait up to timeout
+    const exitResult = await this.waitForExit(pid, timeout);
+    if (exitResult.exited) {
+      return true;
+    }
+
+    // 3. Force kill if still alive
+    if (this.isAlive(pid)) {
+      if (process.platform === 'win32') {
+        try {
+          await new Promise((resolve) => {
+            execFile('taskkill', ['/pid', String(pid), '/T', '/F'], () => resolve());
+          });
+        } catch {
+          // ignore
+        }
+      }
+
+      this.signal(pid, 'SIGKILL');
+
+      // Final short grace period for SIGKILL to take effect
+      const finalWait = await this.waitForExit(pid, 2000);
+      return finalWait.exited;
+    }
+
+    return true;
+  }
+}

package/src/core/readiness.js

@@ -0,0 +1,243 @@
+import http from 'node:http';
+import net from 'node:net';
+
+/**
+ * Custom error thrown when a generation fails readiness within the timeout.
+ */
+export class ReadinessTimeoutError extends Error {
+  constructor(message, generation) {
+    super(message);
+    this.name = 'ReadinessTimeoutError';
+    this.generation = generation;
+  }
+}
+
+/**
+ * Custom error thrown when a generation's process exits unexpectedly during startup.
+ */
+export class ProcessStartupError extends Error {
+  constructor(message, generation) {
+    super(message);
+    this.name = 'ProcessStartupError';
+    this.generation = generation;
+  }
+}
+
+/**
+ * Custom error thrown when an application listens on a hardcoded port instead of process.env.PORT.
+ */
+export class PortMismatchError extends Error {
+  constructor(message, generation, detectedPort) {
+    super(message);
+    this.name = 'PortMismatchError';
+    this.generation = generation;
+    this.detectedPort = detectedPort;
+  }
+}
+
+/**
+ * ReadinessChecker provides reusable TCP and HTTP readiness verification.
+ */
+export class ReadinessChecker {
+  /**
+   * @param {object} options
+   * @param {import('./process-manager.js').ProcessManager} options.processManager
+   */
+  constructor(options = {}) {
+    this.processManager = options.processManager;
+  }
+
+  /**
+   * Checks if an internal TCP port is accepting connections.
+   *
+   * @param {number} port
+   * @param {string} [host='127.0.0.1']
+   * @param {number} [timeout=1000]
+   * @returns {Promise<boolean>}
+   */
+  checkTcp(port, host = '127.0.0.1', timeout = 1000) {
+    return new Promise((resolve) => {
+      const socket = net.connect({ port, host, timeout });
+      let connected = false;
+
+      socket.once('connect', () => {
+        connected = true;
+        socket.end();
+        resolve(true);
+      });
+
+      socket.once('timeout', () => {
+        socket.destroy();
+        resolve(false);
+      });
+
+      socket.once('error', () => {
+        socket.destroy();
+        resolve(false);
+      });
+    });
+  }
+
+  /**
+   * Checks if an HTTP readiness endpoint returns a healthy status (2xx).
+   *
+   * @param {number} port
+   * @param {string} [path='/']
+   * @param {number} [timeout=1500]
+   * @returns {Promise<boolean>}
+   */
+  checkHttp(port, path = '/', timeout = 1500) {
+    return new Promise((resolve) => {
+      const req = http.request(
+        {
+          hostname: '127.0.0.1',
+          port,
+          path,
+          method: 'GET',
+          timeout
+        },
+        (res) => {
+          // Read response data to avoid socket leak
+          res.resume();
+          const is2xx = res.statusCode >= 200 && res.statusCode < 300;
+          resolve(is2xx);
+        }
+      );
+
+      req.on('timeout', () => {
+        req.destroy();
+        resolve(false);
+      });
+
+      req.on('error', () => {
+        resolve(false);
+      });
+
+      req.end();
+    });
+  }
+
+  /**
+   * Performs an immediate one-shot readiness check on a generation.
+   *
+   * @param {object} generation - { id, pid, internalPort }
+   * @param {object} [options]
+   * @param {string} [options.path]
+   * @returns {Promise<boolean>}
+   */
+  async ensure(generation, options = {}) {
+    if (!generation) return false;
+
+    // 1. Process liveness
+    if (generation.pid && this.processManager && !this.processManager.isAlive(generation.pid)) {
+      return false;
+    }
+
+    // 2. TCP connectivity
+    const tcpOk = await this.checkTcp(generation.internalPort);
+    if (!tcpOk) return false;
+
+    // 3. Optional HTTP endpoint
+    if (options.path) {
+      const httpOk = await this.checkHttp(generation.internalPort, options.path);
+      if (!httpOk) return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Polls readiness until the generation is ready, process crashes, or timeout is reached.
+   *
+   * @param {object} generation - { id, pid, internalPort }
+   * @param {object} [options]
+   * @param {number} [options.timeout=15000] - Timeout in milliseconds
+   * @param {number} [options.interval=50] - Polling interval in milliseconds
+   * @param {string} [options.path] - Optional HTTP health check path (e.g. '/health')
+   * @returns {Promise<boolean>} Resolves true when ready
+   */
+  async wait(generation, options = {}) {
+    if (!generation || !generation.internalPort) {
+      throw new Error('Valid generation with internalPort is required for readiness check.');
+    }
+
+    const timeout = options.timeout !== undefined ? options.timeout : 15000;
+    const interval = options.interval !== undefined ? options.interval : 50;
+    const healthPath = options.path;
+
+    const startTime = Date.now();
+
+    while (true) {
+      // 1. Fail fast if process has crashed during startup
+      if (generation.pid && this.processManager && !this.processManager.isAlive(generation.pid)) {
+        const procInfo = typeof this.processManager.getProcess === 'function' ? this.processManager.getProcess(generation.pid) : null;
+        const stderr = procInfo?.recentStderr || '';
+
+        if (stderr.includes('EADDRINUSE') || stderr.includes('address already in use')) {
+          const portHint = options.configuredPort ? ` (such as configured port :${options.configuredPort})` : '';
+          throw new ProcessStartupError(
+            `Generation #${generation.id} (PID ${generation.pid}) crashed with EADDRINUSE during startup. ` +
+              `The application likely attempted to bind to a hardcoded port${portHint} instead of reading process.env.PORT (${generation.internalPort}).` +
+              `\nDetails:\n${stderr.trim()}`,
+            generation
+          );
+        }
+
+        throw new ProcessStartupError(
+          `Generation #${generation.id} (PID ${generation.pid}) process exited unexpectedly during startup.` +
+            (stderr ? `\nDetails:\n${stderr.trim()}` : ''),
+          generation
+        );
+      }
+
+      // 2. Check TCP port
+      const tcpReady = await this.checkTcp(generation.internalPort);
+      if (tcpReady) {
+        // 3. If HTTP health check path is configured, verify HTTP 2xx
+        if (healthPath) {
+          const httpReady = await this.checkHttp(generation.internalPort, healthPath);
+          if (httpReady) {
+            return true;
+          }
+        } else {
+          return true;
+        }
+      } else {
+        // Port mismatch fast-detection: If application is listening on configured public port instead of internalPort
+        const isRouterOnConfiguredPort =
+          options.router && options.router.server && options.router.listeningPort === options.configuredPort;
+
+        if (!isRouterOnConfiguredPort && options.configuredPort && options.configuredPort !== generation.internalPort) {
+          const isConfiguredPortOpen = await this.checkTcp(options.configuredPort);
+          if (isConfiguredPortOpen) {
+            throw new PortMismatchError(
+              `Port mismatch detected: Generation #${generation.id} (PID ${generation.pid}) is listening on configured public port ${options.configuredPort} ` +
+                `instead of the dynamically allocated process.env.PORT (${generation.internalPort}). ` +
+                `Please ensure your application code reads process.env.PORT (e.g. app.listen(process.env.PORT || ${options.configuredPort})).`,
+              generation,
+              options.configuredPort
+            );
+          }
+        }
+      }
+
+      // 4. Check timeout
+      if (Date.now() - startTime >= timeout) {
+        if (generation.pid && this.processManager && this.processManager.isAlive(generation.pid)) {
+          throw new ReadinessTimeoutError(
+            `Generation #${generation.id} (PID ${generation.pid}) is still running, but did not accept connections on process.env.PORT (${generation.internalPort}) within ${timeout}ms. ` +
+              `Ensure your application listens on process.env.PORT (e.g. app.listen(process.env.PORT)).`,
+            generation
+          );
+        }
+
+        throw new ReadinessTimeoutError(
+          `Generation #${generation.id} on port ${generation.internalPort} failed readiness check within ${timeout}ms.`,
+          generation
+        );
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  }
+}