unitup 0.2.0 → 0.4.0

package/src/core/supervisor.js

@@ -0,0 +1,222 @@
+import { DeploymentManager } from '../deploy/deployment-manager.js';
+import { RollbackManager } from '../deploy/rollback-manager.js';
+import { readAppMetadata, sanitizeServiceName } from '../utils.js';
+import { DrainManager } from './drain-manager.js';
+import { GenerationManager } from './generation-manager.js';
+import { IPCServer } from './ipc.js';
+import { DeploymentLock } from './lock.js';
+import { ProcessManager } from './process-manager.js';
+import { ReadinessChecker } from './readiness.js';
+import { Router } from './router.js';
+
+/**
+ * Supervisor is the long-running host managed by the OS service manager (unitupd).
+ * It owns Router, child application generation processes, and IPC for control.
+ */
+export class Supervisor {
+  /**
+   * @param {string} serviceName
+   * @param {object} [serviceConfig]
+   * @param {object} [options]
+   */
+  constructor(serviceName, serviceConfig = null, options = {}) {
+    this.serviceName = sanitizeServiceName(serviceName);
+    this.config = serviceConfig || readAppMetadata(this.serviceName) || {};
+    this.options = options;
+
+    this.processManager = new ProcessManager({
+      defaultShutdownTimeout: this.config.shutdownTimeout || 5000
+    });
+
+    this.generationManager = new GenerationManager({
+      processManager: this.processManager,
+      stateDir: options.stateDir
+    });
+
+    this.router = new Router();
+    this.readiness = new ReadinessChecker({ processManager: this.processManager });
+    this.drainManager = new DrainManager({
+      router: this.router,
+      processManager: this.processManager
+    });
+
+    this.lock = new DeploymentLock({
+      lockDir: options.lockDir,
+      processManager: this.processManager
+    });
+
+    this.deploymentManager = new DeploymentManager({
+      generationManager: this.generationManager,
+      router: this.router,
+      readiness: this.readiness,
+      drainManager: this.drainManager,
+      processManager: this.processManager,
+      lock: this.lock,
+      defaultStabilizationMs: options.stabilizationWindowMs !== undefined ? options.stabilizationWindowMs : 5000
+    });
+
+    this.rollbackManager = new RollbackManager({
+      generationManager: this.generationManager,
+      router: this.router,
+      readiness: this.readiness,
+      drainManager: this.drainManager,
+      processManager: this.processManager,
+      lock: this.lock
+    });
+
+    this.ipcServer = new IPCServer({
+      serviceName: this.serviceName,
+      ipcDir: options.ipcDir,
+      handler: this._handleIpcMessage.bind(this)
+    });
+
+    this.running = false;
+  }
+
+  async _handleIpcMessage(message, sendProgress) {
+    if (!message || typeof message !== 'object') {
+      throw new Error('Invalid IPC request format');
+    }
+
+    const action = message.action;
+
+    if (action === 'deploy') {
+      // Reload config in case it changed on disk
+      const freshConfig = readAppMetadata(this.serviceName) || this.config;
+      return this.deploymentManager.deploy(this.serviceName, freshConfig, {
+        ...message.options,
+        onProgress: sendProgress
+      });
+    }
+
+    if (action === 'rollback') {
+      const freshConfig = readAppMetadata(this.serviceName) || this.config;
+      return this.rollbackManager.rollback(this.serviceName, freshConfig, {
+        ...message.options,
+        onProgress: sendProgress
+      });
+    }
+
+    if (action === 'promote') {
+      const freshConfig = readAppMetadata(this.serviceName) || this.config;
+      return this.deploymentManager.promote(this.serviceName, freshConfig, {
+        ...message.options,
+        onProgress: sendProgress
+      });
+    }
+
+    if (action === 'status') {
+      const active = this.generationManager.getActive(this.serviceName);
+      const canaryGen = this.generationManager.getCanary(this.serviceName);
+      const canaryRouter = this.router.getCanary(this.serviceName);
+      return {
+        service: this.serviceName,
+        activeGeneration: active,
+        previousGeneration: this.generationManager.getPrevious(this.serviceName),
+        canaryGeneration: canaryGen,
+        canaryWeight: canaryRouter?.weight ?? canaryGen?.canaryWeight ?? null,
+        generations: this.generationManager.listGenerations(this.serviceName),
+        routerPort: this.router.listeningPort,
+        inFlightRequests: active ? this.router.getInFlightCount(active.id) : 0
+      };
+    }
+
+    if (action === 'stop') {
+      setTimeout(() => this.stop(), 50);
+      return { stopped: true };
+    }
+
+    throw new Error(`Unknown supervisor action: "${action}"`);
+  }
+
+  /**
+   * Starts the supervisor, IPC server, and initial generation.
+   */
+  async start() {
+    this.running = true;
+
+    // 1. Start IPC server for remote CLI commands
+    await this.ipcServer.start();
+
+    // 2. Load state and cleanup stale dead PIDs from previous runs
+    this.generationManager.loadState(this.serviceName);
+    this.generationManager.cleanupStale(this.serviceName);
+
+    const publicPort = this.options.publicPort || this.config.port || this.config.deploy?.port;
+
+    // 3. Check if there is an active running generation from persisted state
+    const active = this.generationManager.getActive(this.serviceName);
+    if (active && this.processManager.isAlive(active.pid)) {
+      if (publicPort) {
+        await this.router.listen(publicPort, '0.0.0.0', this.serviceName);
+      }
+      this.router.switchBackend(this.serviceName, active, publicPort);
+    } else {
+      // Start initial generation
+      await this.deploymentManager.deploy(this.serviceName, this.config, {
+        publicPort,
+        stabilizationWindowMs: this.options.stabilizationWindowMs
+      });
+    }
+
+    return this;
+  }
+
+  /**
+   * Stops the supervisor, closes router, and drains all active generations.
+   */
+  async stop() {
+    if (!this.running) return;
+    this.running = false;
+
+    // 1. Close IPC server
+    await this.ipcServer.close();
+
+    // 2. Close router
+    await this.router.close();
+
+    // 3. Drain and stop active generations
+    const active = this.generationManager.getActive(this.serviceName);
+    if (active) {
+      await this.drainManager.drain(active, { timeout: 5000, stopProcess: true });
+      this.generationManager.remove(active, false);
+    }
+
+    // Stop any other untracked or running child processes
+    for (const [pid] of this.processManager.processes.entries()) {
+      await this.processManager.stop(pid, { timeout: 2000 });
+    }
+  }
+
+  /**
+   * Standalone entry point when running `unitup supervisor <serviceName>`.
+   *
+   * @param {string} serviceName
+   */
+  static async run(serviceName) {
+    if (!serviceName) {
+      process.stderr.write('Error: Service name is required to run supervisor.\n');
+      process.exit(1);
+    }
+
+    const supervisor = new Supervisor(serviceName);
+
+    const onSignal = async (sig) => {
+      try {
+        await supervisor.stop();
+      } finally {
+        process.exit(0);
+      }
+    };
+
+    process.on('SIGINT', () => onSignal('SIGINT'));
+    process.on('SIGTERM', () => onSignal('SIGTERM'));
+
+    try {
+      await supervisor.start();
+    } catch (err) {
+      process.stderr.write(`[unitup supervisor] Failed to start: ${err.message}\n`);
+      process.exit(1);
+    }
+  }
+}

package/src/deploy/deployment-manager.js

@@ -0,0 +1,388 @@
+import { EventEmitter } from 'node:events';
+import { DrainManager } from '../core/drain-manager.js';
+import { GenerationManager } from '../core/generation-manager.js';
+import { IPCClient } from '../core/ipc.js';
+import { DeploymentLock } from '../core/lock.js';
+import { ProcessManager } from '../core/process-manager.js';
+import { ReadinessChecker } from '../core/readiness.js';
+import { Router } from '../core/router.js';
+import { readAppMetadata } from '../utils.js';
+
+/**
+ * Deployment State Machine states.
+ */
+export const DeploymentState = {
+  IDLE: 'IDLE',
+  CREATING_GENERATION: 'CREATING_GENERATION',
+  STARTING: 'STARTING',
+  WAITING_READY: 'WAITING_READY',
+  SWITCHING: 'SWITCHING',
+  STABILIZING: 'STABILIZING',
+  SETTING_CANARY: 'SETTING_CANARY',
+  PROMOTING: 'PROMOTING',
+  DRAINING: 'DRAINING',
+  STOPPING_PREVIOUS: 'STOPPING_PREVIOUS',
+  COMPLETE: 'COMPLETE',
+  FAILED: 'FAILED'
+};
+
+/**
+ * DeploymentManager is orchestration only.
+ * It strictly composes the Unitup core primitives to achieve zero-downtime deployment.
+ */
+export class DeploymentManager extends EventEmitter {
+  /**
+   * @param {object} [options]
+   * @param {import('../core/generation-manager.js').GenerationManager} [options.generationManager]
+   * @param {import('../core/router.js').Router} [options.router]
+   * @param {import('../core/readiness.js').ReadinessChecker} [options.readiness]
+   * @param {import('../core/drain-manager.js').DrainManager} [options.drainManager]
+   * @param {import('../core/process-manager.js').ProcessManager} [options.processManager]
+   * @param {import('../core/lock.js').DeploymentLock} [options.lock]
+   * @param {number} [options.defaultStabilizationMs=5000]
+   */
+  constructor(options = {}) {
+    super();
+    this.generationManager = options.generationManager;
+    this.router = options.router;
+    this.readiness = options.readiness;
+    this.drainManager = options.drainManager;
+    this.processManager = options.processManager;
+    this.lock = options.lock;
+    this.defaultStabilizationMs = options.defaultStabilizationMs !== undefined ? options.defaultStabilizationMs : 5000;
+    this.state = DeploymentState.IDLE;
+  }
+
+  _ensurePrimitives(serviceName, options = {}) {
+    if (!this.processManager) {
+      this.processManager = new ProcessManager();
+    }
+    if (!this.generationManager) {
+      this.generationManager = new GenerationManager({
+        processManager: this.processManager,
+        stateDir: options.stateDir
+      });
+    }
+    if (!this.router) {
+      this.router = new Router();
+    }
+    if (!this.readiness) {
+      this.readiness = new ReadinessChecker({ processManager: this.processManager });
+    }
+    if (!this.drainManager) {
+      this.drainManager = new DrainManager({
+        router: this.router,
+        processManager: this.processManager
+      });
+    }
+    if (!this.lock) {
+      this.lock = new DeploymentLock({
+        lockDir: options.lockDir,
+        processManager: this.processManager
+      });
+    }
+  }
+
+  /**
+   * Emits state change event and optional progress notification.
+   * @param {string} newState
+   * @param {object} [details]
+   * @param {function} [onProgress]
+   */
+  _setState(newState, details = {}, onProgress) {
+    const oldState = this.state;
+    this.state = newState;
+    const payload = { from: oldState, to: newState, state: newState, ...details };
+    this.emit('stateChange', payload);
+    if (onProgress) {
+      onProgress(payload);
+    }
+  }
+
+  /**
+   * Executes a zero-downtime deployment for a service.
+   *
+   * @param {string} serviceName
+   * @param {object} [serviceConfig] - Config containing command, args, cwd, env, port, deploy opts
+   * @param {object} [options]
+   * @param {number} [options.publicPort]
+   * @param {number} [options.stabilizationWindowMs]
+   * @param {number} [options.readinessTimeout]
+   * @param {string} [options.readyPath]
+   * @param {number} [options.drainTimeout]
+   * @param {function(object): void} [options.onProgress]
+   * @returns {Promise<object>} Deployment summary
+   */
+  async deploy(serviceName, serviceConfig = {}, options = {}) {
+    if (!serviceName) {
+      throw new Error('Service name is required for deployment.');
+    }
+
+    // Check if a supervisor daemon is running for this service via IPC
+    const ipcClient = new IPCClient(serviceName, options.ipcDir);
+    const isRemote = await ipcClient.isAlive();
+    if (isRemote) {
+      return ipcClient.send(
+        {
+          action: 'deploy',
+          options: { ...options, ...serviceConfig }
+        },
+        options.onProgress
+      );
+    }
+
+    this._ensurePrimitives(serviceName, options);
+
+    const config =
+      serviceConfig && (serviceConfig.command || serviceConfig.script)
+        ? serviceConfig
+        : readAppMetadata(serviceName) || serviceConfig || {};
+
+    // 1. Acquire per-service deployment lock
+    await this.lock.acquire(serviceName);
+
+    let next = null;
+    let previous = null;
+
+    try {
+      this._setState(DeploymentState.IDLE, { service: serviceName }, options.onProgress);
+
+      previous = this.generationManager.getActive(serviceName);
+
+      // 2. CREATING_GENERATION
+      this._setState(
+        DeploymentState.CREATING_GENERATION,
+        { service: serviceName, previousGeneration: previous?.id },
+        options.onProgress
+      );
+
+      next = await this.generationManager.create(serviceName, config, options);
+
+      // 3. STARTING
+      this._setState(
+        DeploymentState.STARTING,
+        {
+          service: serviceName,
+          generation: next.id,
+          pid: next.pid,
+          internalPort: next.internalPort
+        },
+        options.onProgress
+      );
+
+      // 4. WAITING_READY
+      this._setState(DeploymentState.WAITING_READY, { service: serviceName, generation: next.id }, options.onProgress);
+
+      try {
+        const readyPath = options.readyPath || config.deploy?.ready;
+        const readinessTimeout = options.readinessTimeout || 15000;
+        await this.readiness.wait(next, {
+          path: readyPath,
+          timeout: readinessTimeout,
+          configuredPort: options.publicPort || config.port,
+          router: this.router
+        });
+      } catch (readinessErr) {
+        // Readiness failed: clean up next generation, leave router pointing at previous
+        await this.processManager.stop(next.pid, { timeout: 2000 });
+        this.generationManager.remove(next, true);
+        this._setState(
+          DeploymentState.FAILED,
+          { service: serviceName, error: readinessErr.message },
+          options.onProgress
+        );
+        throw readinessErr;
+      }
+
+      const isCanary = Boolean(options.canary);
+      const rawWeight =
+        options.weight !== undefined ? options.weight : options.canaryWeight !== undefined ? options.canaryWeight : 0.1;
+      const parsedWeight =
+        typeof rawWeight === 'string' ? Number.parseFloat(rawWeight.replace('%', '')) : Number(rawWeight);
+      const numWeight = Number.isNaN(parsedWeight) ? 0.1 : parsedWeight;
+      const canaryWeight = Math.max(0, Math.min(1, numWeight > 1 ? numWeight / 100 : numWeight));
+
+      if (isCanary) {
+        const publicPort = options.publicPort || config.port;
+        if (publicPort) {
+          await this.router.listen(publicPort, '0.0.0.0', serviceName);
+        }
+
+        if (!previous) {
+          this.router.switchBackend(serviceName, next, publicPort);
+          this.generationManager.markActive(next);
+        }
+
+        this._setState(
+          DeploymentState.SETTING_CANARY,
+          { service: serviceName, generation: next.id, weight: canaryWeight },
+          options.onProgress
+        );
+
+        this.router.setCanary(serviceName, next, canaryWeight, publicPort);
+        this.generationManager.markCanary(next, canaryWeight);
+
+        const result = {
+          service: serviceName,
+          isCanary: true,
+          activeGeneration: previous?.id ?? next.id,
+          canaryGeneration: next.id,
+          canaryWeight,
+          downtimeMs: 0,
+          status: 'canary'
+        };
+
+        this._setState(DeploymentState.COMPLETE, result, options.onProgress);
+        return result;
+      }
+
+      // 5. SWITCHING
+      this._setState(DeploymentState.SWITCHING, { service: serviceName, generation: next.id }, options.onProgress);
+
+      const publicPort = options.publicPort || config.port;
+      if (publicPort) {
+        await this.router.listen(publicPort, '0.0.0.0', serviceName);
+      }
+
+      this.router.switchBackend(serviceName, next, publicPort);
+      this.generationManager.markActive(next);
+
+      // 6. STABILIZING
+      this._setState(DeploymentState.STABILIZING, { service: serviceName, generation: next.id }, options.onProgress);
+
+      const stabilizationMs =
+        options.stabilizationWindowMs !== undefined ? options.stabilizationWindowMs : this.defaultStabilizationMs;
+
+      if (stabilizationMs > 0) {
+        const checkInterval = 50;
+        const stabStart = Date.now();
+        while (Date.now() - stabStart < stabilizationMs) {
+          if (!this.processManager.isAlive(next.pid)) {
+            // New generation crashed during stabilization window! Revert to previous!
+            if (previous && this.processManager.isAlive(previous.pid)) {
+              this.router.switchBackend(serviceName, previous, publicPort);
+              this.generationManager.markActive(previous);
+            }
+            this.generationManager.remove(next, true);
+            this._setState(
+              DeploymentState.FAILED,
+              {
+                service: serviceName,
+                error: `Generation #${next.id} crashed during stabilization window.`
+              },
+              options.onProgress
+            );
+            throw new Error(
+              `Generation #${next.id} crashed during stabilization window. Rolled back traffic to previous generation #${previous?.id || 'none'}.`
+            );
+          }
+          await new Promise((resolve) => setTimeout(resolve, checkInterval));
+        }
+      }
+
+      // 7. DRAINING
+      if (previous && previous.id !== next.id) {
+        this._setState(DeploymentState.DRAINING, { service: serviceName, generation: previous.id }, options.onProgress);
+
+        this.generationManager.markDraining(previous);
+        const drainTimeout = options.drainTimeout || config.deploy?.drainTimeout || 10000;
+        await this.drainManager.drain(previous, { timeout: drainTimeout, stopProcess: false });
+      }
+
+      // 8. STOPPING_PREVIOUS
+      if (previous && previous.id !== next.id) {
+        this._setState(
+          DeploymentState.STOPPING_PREVIOUS,
+          { service: serviceName, generation: previous.id },
+          options.onProgress
+        );
+
+        await this.processManager.stop(previous.pid, { timeout: 3000 });
+        this.generationManager.remove(previous, false);
+      }
+
+      // 9. COMPLETE
+      const result = {
+        service: serviceName,
+        previousGeneration: previous?.id ?? null,
+        currentGeneration: next.id,
+        downtimeMs: 0,
+        status: 'complete'
+      };
+
+      this._setState(DeploymentState.COMPLETE, result, options.onProgress);
+      return result;
+    } finally {
+      await this.lock.release(serviceName);
+    }
+  }
+
+  /**
+   * Promotes an existing canary generation to 100% active primary and drains previous.
+   *
+   * @param {string} serviceName
+   * @param {object} [config]
+   * @param {object} [options]
+   * @returns {Promise<object>}
+   */
+  async promote(serviceName, config = {}, options = {}) {
+    this._ensurePrimitives(serviceName, options);
+
+    const ipcClient = new IPCClient(serviceName, options.ipcDir);
+    if (await ipcClient.isAlive()) {
+      return ipcClient.send({ action: 'promote', options }, options.onProgress);
+    }
+
+    await this.lock.acquire(serviceName, { timeout: options.lockTimeout || 10000 });
+
+    try {
+      const canaryGen = this.generationManager.getCanary(serviceName);
+      if (!canaryGen) {
+        throw new Error(`No canary generation found for service "${serviceName}" to promote.`);
+      }
+
+      const previous = this.generationManager.getActive(serviceName);
+
+      this._setState(
+        DeploymentState.PROMOTING,
+        { service: serviceName, generation: canaryGen.id, previousGeneration: previous?.id },
+        options.onProgress
+      );
+
+      // 1. Promote in Router (clears canary, makes it primary)
+      this.router.promoteCanary(serviceName);
+      this.generationManager.markActive(canaryGen);
+
+      // 2. Drain previous generation
+      if (previous && previous.id !== canaryGen.id) {
+        this._setState(DeploymentState.DRAINING, { service: serviceName, generation: previous.id }, options.onProgress);
+        this.generationManager.markDraining(previous);
+        const drainTimeout = options.drainTimeout || config.deploy?.drainTimeout || 10000;
+        await this.drainManager.drain(previous, { timeout: drainTimeout, stopProcess: false });
+
+        this._setState(
+          DeploymentState.STOPPING_PREVIOUS,
+          { service: serviceName, generation: previous.id },
+          options.onProgress
+        );
+        await this.processManager.stop(previous.pid, { timeout: 3000 });
+        this.generationManager.remove(previous, false);
+      }
+
+      const result = {
+        service: serviceName,
+        promotedGeneration: canaryGen.id,
+        previousGeneration: previous?.id ?? null,
+        downtimeMs: 0,
+        status: 'promoted'
+      };
+
+      this._setState(DeploymentState.COMPLETE, result, options.onProgress);
+      return result;
+    } finally {
+      await this.lock.release(serviceName);
+    }
+  }
+}
+
+export const defaultDeploymentManager = new DeploymentManager();

package/src/deploy/index.js

@@ -0,0 +1,9 @@
+export {
+  DeploymentManager,
+  DeploymentState,
+  defaultDeploymentManager
+} from './deployment-manager.js';
+export {
+  RollbackManager,
+  defaultRollbackManager
+} from './rollback-manager.js';