unitup 0.2.0 → 0.4.0

package/src/core/ipc.js

@@ -0,0 +1,236 @@
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { getUnitupDir, sanitizeServiceName } from '../utils.js';
+
+/**
+ * Returns the IPC endpoint path for a service (Unix domain socket or Windows Named Pipe).
+ * @param {string} serviceName
+ * @param {string} [ipcDir]
+ * @returns {string}
+ */
+export function getIpcPath(serviceName, ipcDir) {
+  const safeName = sanitizeServiceName(serviceName);
+  if (process.platform === 'win32') {
+    return `\\\\.\\pipe\\unitup-${safeName}`;
+  }
+  const dir = ipcDir || path.join(getUnitupDir(), 'ipc');
+  return path.join(dir, `${safeName}.sock`);
+}
+
+/**
+ * Lightweight IPC Server hosted by the supervisor.
+ */
+export class IPCServer {
+  /**
+   * @param {object} options
+   * @param {string} options.serviceName
+   * @param {function(object, function(object): void): Promise<object>} options.handler
+   * @param {string} [options.ipcDir]
+   */
+  constructor(options) {
+    this.serviceName = options.serviceName;
+    this.handler = options.handler;
+    this.ipcPath = getIpcPath(this.serviceName, options.ipcDir);
+    this.server = null;
+  }
+
+  async start() {
+    if (process.platform !== 'win32') {
+      const dir = path.dirname(this.ipcPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      if (fs.existsSync(this.ipcPath)) {
+        try {
+          fs.unlinkSync(this.ipcPath);
+        } catch {
+          // ignore
+        }
+      }
+    }
+
+    return new Promise((resolve, reject) => {
+      const server = net.createServer((socket) => {
+        let buffer = '';
+
+        socket.on('data', async (chunk) => {
+          buffer += chunk.toString('utf8');
+          const lines = buffer.split('\n');
+          buffer = lines.pop(); // preserve unfinished line
+
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+
+            let message;
+            try {
+              message = JSON.parse(trimmed);
+            } catch (err) {
+              socket.write(`${JSON.stringify({ type: 'error', error: 'Invalid JSON' })}\n`);
+              continue;
+            }
+
+            const sendProgress = (progressData) => {
+              if (!socket.destroyed) {
+                socket.write(`${JSON.stringify({ type: 'progress', ...progressData })}\n`);
+              }
+            };
+
+            try {
+              const result = await this.handler(message, sendProgress);
+              if (!socket.destroyed) {
+                socket.write(`${JSON.stringify({ type: 'result', data: result })}\n`);
+              }
+            } catch (err) {
+              if (!socket.destroyed) {
+                socket.write(
+                  `${JSON.stringify({
+                    type: 'error',
+                    error: err.message,
+                    name: err.name,
+                    stack: err.stack
+                  })}\n`
+                );
+              }
+            }
+          }
+        });
+      });
+
+      server.on('error', reject);
+      server.listen(this.ipcPath, () => {
+        this.server = server;
+        resolve();
+      });
+    });
+  }
+
+  async close() {
+    if (!this.server) return;
+    return new Promise((resolve) => {
+      this.server.close(() => {
+        this.server = null;
+        if (process.platform !== 'win32' && fs.existsSync(this.ipcPath)) {
+          try {
+            fs.unlinkSync(this.ipcPath);
+          } catch {
+            // ignore
+          }
+        }
+        resolve();
+      });
+    });
+  }
+
+  async stop() {
+    return this.close();
+  }
+}
+
+/**
+ * Lightweight IPC Client used by CLI to talk to the running supervisor.
+ */
+export class IPCClient {
+  /**
+   * @param {string} serviceName
+   * @param {string} [ipcDir]
+   */
+  constructor(serviceName, ipcDir) {
+    this.serviceName = serviceName;
+    this.ipcPath = getIpcPath(serviceName, ipcDir);
+  }
+
+  /**
+   * Checks if the supervisor IPC socket is reachable.
+   * @param {number} [timeout=1000]
+   * @returns {Promise<boolean>}
+   */
+  async isAlive(timeout = 1000) {
+    return new Promise((resolve) => {
+      const socket = net.connect(this.ipcPath);
+      let connected = false;
+
+      socket.once('connect', () => {
+        connected = true;
+        socket.destroy();
+        resolve(true);
+      });
+
+      socket.setTimeout(timeout, () => {
+        socket.destroy();
+        resolve(false);
+      });
+
+      socket.once('error', () => {
+        resolve(false);
+      });
+    });
+  }
+
+  /**
+   * Sends a request to the supervisor and streams progress updates.
+   *
+   * @param {object} payload
+   * @param {function(object): void} [onProgress]
+   * @param {number} [timeout=120000]
+   * @returns {Promise<any>}
+   */
+  async send(payload, onProgress, timeout = 120000) {
+    return new Promise((resolve, reject) => {
+      const socket = net.connect(this.ipcPath);
+      let buffer = '';
+      let timer = null;
+
+      if (timeout > 0) {
+        timer = setTimeout(() => {
+          socket.destroy();
+          reject(new Error(`IPC request timed out after ${timeout}ms.`));
+        }, timeout);
+      }
+
+      socket.once('connect', () => {
+        socket.write(`${JSON.stringify(payload)}\n`);
+      });
+
+      socket.on('data', (chunk) => {
+        buffer += chunk.toString('utf8');
+        const lines = buffer.split('\n');
+        buffer = lines.pop();
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+
+          try {
+            const msg = JSON.parse(trimmed);
+            if (msg.type === 'progress') {
+              if (onProgress) onProgress(msg);
+            } else if (msg.type === 'result') {
+              if (timer) clearTimeout(timer);
+              socket.destroy();
+              resolve(msg.data);
+            } else if (msg.type === 'error') {
+              if (timer) clearTimeout(timer);
+              socket.destroy();
+              const err = new Error(msg.error);
+              err.name = msg.name || 'Error';
+              reject(err);
+            }
+          } catch {
+            // Ignore parse errors on individual chunks
+          }
+        }
+      });
+
+      socket.once('error', (err) => {
+        if (timer) clearTimeout(timer);
+        reject(err);
+      });
+
+      socket.once('close', () => {
+        if (timer) clearTimeout(timer);
+      });
+    });
+  }
+}

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 { execFile, spawn } 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;
+  }
+}