unitup 0.1.5 → 0.3.0

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));
+    }
+  }
+}

package/src/core/router.js

@@ -0,0 +1,390 @@
+import http from 'node:http';
+import net from 'node:net';
+
+/**
+ * Router owns a stable public port and reverse-proxies HTTP & WebSocket traffic
+ * to whichever internal generation is marked active.
+ *
+ * It contains NO deployment sequencing decisions.
+ */
+export class Router {
+  constructor(options = {}) {
+    this.activeBackends = new Map(); // serviceName -> generation { id, internalPort }
+    this.canaryBackends = new Map(); // serviceName -> { generation, weight }
+    this.inFlightRequests = new Map(); // generationId -> number
+    this.server = null;
+    this.listeningPort = null;
+    this.listeningHost = null;
+    this.closing = false;
+  }
+
+  /**
+   * Sets a canary backend with a specific traffic weight (0 to 1, or 1 to 100).
+   *
+   * @param {string} serviceName
+   * @param {object} generation
+   * @param {number} [weight=0.1] - Probability (0 to 1) or percentage (1 to 100)
+   */
+  setCanary(serviceName, generation, weight = 0.1) {
+    const parsed = typeof weight === 'string' ? Number.parseFloat(weight.replace('%', '')) : Number(weight);
+    const num = Number.isNaN(parsed) ? 0.1 : parsed;
+    const normalizedWeight = num > 1 ? num / 100 : num;
+    this.canaryBackends.set(serviceName, {
+      generation,
+      weight: Math.max(0, Math.min(1, normalizedWeight))
+    });
+  }
+
+  /**
+   * Clears the canary backend for a service.
+   *
+   * @param {string} serviceName
+   */
+  clearCanary(serviceName) {
+    this.canaryBackends.delete(serviceName);
+  }
+
+  /**
+   * Promotes the canary generation to the active primary generation,
+   * clearing the canary state.
+   *
+   * @param {string} serviceName
+   * @returns {object|null} The promoted generation
+   */
+  promoteCanary(serviceName) {
+    const canary = this.canaryBackends.get(serviceName);
+    if (!canary || !canary.generation) return null;
+    this.switchBackend(serviceName, canary.generation);
+    this.canaryBackends.delete(serviceName);
+    return canary.generation;
+  }
+
+  /**
+   * Gets the canary config for a service.
+   *
+   * @param {string} serviceName
+   * @returns {{ generation: object, weight: number }|null}
+   */
+  getCanary(serviceName) {
+    return this.canaryBackends.get(serviceName) || null;
+  }
+
+  /**
+   * Resolves the target backend generation for an incoming request.
+   *
+   * @param {string} serviceName
+   * @param {import('node:http').IncomingMessage} [req]
+   * @returns {object|null}
+   */
+  resolveBackend(serviceName, req = null) {
+    const primary = this.activeBackends.get(serviceName);
+    const canary = this.canaryBackends.get(serviceName);
+
+    if (!canary || !canary.generation) {
+      return primary || null;
+    }
+
+    if (!primary) {
+      return canary.generation;
+    }
+
+    // Optional header-based override (e.g. x-canary: true or x-canary: always)
+    if (req?.headers) {
+      const canaryHeader = req.headers['x-canary'];
+      if (canaryHeader === 'true' || canaryHeader === 'always' || canaryHeader === '1') {
+        return canary.generation;
+      }
+      if (canaryHeader === 'false' || canaryHeader === 'never' || canaryHeader === '0') {
+        return primary;
+      }
+    }
+
+    // Probabilistic routing based on weight
+    if (canary.weight > 0 && Math.random() < canary.weight) {
+      return canary.generation;
+    }
+
+    return primary;
+  }
+
+  /**
+   * Helper to find the service name matching the request.
+   * @param {import('node:http').IncomingMessage} [req]
+   * @returns {string|null}
+   */
+  _resolveServiceName(req) {
+    if (this.activeBackends.size === 1) {
+      return this.activeBackends.keys().next().value;
+    }
+    if (this.activeBackends.size > 1 && req?.headers?.host) {
+      for (const srv of this.activeBackends.keys()) {
+        if (req.headers.host.includes(srv)) {
+          return srv;
+        }
+      }
+    }
+    if (this.activeBackends.size > 0) {
+      return this.activeBackends.keys().next().value;
+    }
+    if (this.canaryBackends.size > 0) {
+      return this.canaryBackends.keys().next().value;
+    }
+    return null;
+  }
+
+  /**
+   * Increments in-flight request counter for a generation.
+   * @param {number|string} generationId
+   */
+  _incrementInFlight(generationId) {
+    const id = String(generationId);
+    const count = this.inFlightRequests.get(id) || 0;
+    this.inFlightRequests.set(id, count + 1);
+  }
+
+  /**
+   * Decrements in-flight request counter for a generation.
+   * @param {number|string} generationId
+   */
+  _decrementInFlight(generationId) {
+    const id = String(generationId);
+    const count = this.inFlightRequests.get(id) || 0;
+    if (count <= 1) {
+      this.inFlightRequests.delete(id);
+    } else {
+      this.inFlightRequests.set(id, count - 1);
+    }
+  }
+
+  /**
+   * Gets the current number of in-flight requests for a generation.
+   *
+   * @param {number|string} generationId
+   * @returns {number}
+   */
+  getInFlightCount(generationId) {
+    return this.inFlightRequests.get(String(generationId)) || 0;
+  }
+
+  /**
+   * Switches the active backend generation for a service.
+   * Switching is atomic and lock-free for incoming requests.
+   *
+   * @param {string} serviceName
+   * @param {object} generation - { id, internalPort, service }
+   */
+  switchBackend(serviceName, generation) {
+    this.activeBackends.set(serviceName, generation);
+  }
+
+  /**
+   * Gets the active backend generation for a service.
+   *
+   * @param {string} serviceName
+   * @returns {object|null}
+   */
+  getActiveBackend(serviceName) {
+    return this.activeBackends.get(serviceName) || null;
+  }
+
+  /**
+   * Starts listening on the public port.
+   *
+   * @param {number} publicPort
+   * @param {string} [host='0.0.0.0']
+   * @returns {Promise<{ port: number, host: string }>}
+   */
+  async listen(publicPort, host = '0.0.0.0') {
+    if (this.server && this.listeningPort === publicPort) {
+      return { port: this.listeningPort, host: this.listeningHost };
+    }
+
+    if (this.server) {
+      await this.close();
+    }
+
+    this.closing = false;
+
+    return new Promise((resolve, reject) => {
+      const server = http.createServer((req, res) => {
+        this._handleHttpRequest(req, res);
+      });
+
+      server.on('upgrade', (req, clientSocket, head) => {
+        this._handleWebSocketUpgrade(req, clientSocket, head);
+      });
+
+      server.once('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          reject(new Error(`Public port ${publicPort} is already occupied by another process.`));
+        } else {
+          reject(err);
+        }
+      });
+
+      server.listen(publicPort, host, () => {
+        this.server = server;
+        const actualPort = server.address() ? server.address().port : publicPort;
+        this.listeningPort = actualPort;
+        this.listeningHost = host;
+        resolve({ port: actualPort, host });
+      });
+    });
+  }
+
+  /**
+   * Dispatches and proxies an HTTP request to the active backend.
+   *
+   * @param {import('node:http').IncomingMessage} req
+   * @param {import('node:http').ServerResponse} res
+   */
+  _handleHttpRequest(req, res) {
+    const serviceName = this._resolveServiceName(req);
+    const backend = serviceName ? this.resolveBackend(serviceName, req) : null;
+
+    if (!backend || !backend.internalPort) {
+      res.writeHead(503, {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Retry-After': '1'
+      });
+      res.end('503 Service Unavailable: No active generation backend available.');
+      return;
+    }
+
+    const genId = backend.id;
+    this._incrementInFlight(genId);
+
+    let decremented = false;
+    const cleanupInFlight = () => {
+      if (!decremented) {
+        decremented = true;
+        this._decrementInFlight(genId);
+      }
+    };
+
+    res.once('finish', cleanupInFlight);
+    res.once('close', cleanupInFlight);
+
+    // Forward headers
+    const forwardedHeaders = { ...req.headers };
+    const clientIp = req.socket?.remoteAddress || '127.0.0.1';
+    forwardedHeaders['x-forwarded-for'] = forwardedHeaders['x-forwarded-for']
+      ? `${forwardedHeaders['x-forwarded-for']}, ${clientIp}`
+      : clientIp;
+    forwardedHeaders['x-forwarded-proto'] = forwardedHeaders['x-forwarded-proto'] || 'http';
+    forwardedHeaders['x-forwarded-host'] = req.headers.host || `localhost:${this.listeningPort}`;
+    forwardedHeaders['x-forwarded-port'] = String(this.listeningPort);
+
+    const proxyReq = http.request(
+      {
+        hostname: '127.0.0.1',
+        port: backend.internalPort,
+        path: req.url,
+        method: req.method,
+        headers: forwardedHeaders
+      },
+      (proxyRes) => {
+        res.writeHead(proxyRes.statusCode, proxyRes.headers);
+        proxyRes.pipe(res);
+      }
+    );
+
+    req.on('error', () => {
+      cleanupInFlight();
+      proxyReq.destroy();
+    });
+
+    proxyReq.on('error', (err) => {
+      cleanupInFlight();
+      if (!res.headersSent) {
+        res.writeHead(502, { 'Content-Type': 'text/plain; charset=utf-8' });
+        res.end(`502 Bad Gateway: Error communicating with generation #${genId} (${err.message}).`);
+      } else {
+        res.destroy();
+      }
+    });
+
+    req.pipe(proxyReq);
+  }
+
+  /**
+   * Dispatches and proxies WebSocket / Upgrade connections to the active backend.
+   */
+  _handleWebSocketUpgrade(req, clientSocket, head) {
+    const serviceName = this._resolveServiceName(req);
+    const backend = serviceName ? this.resolveBackend(serviceName, req) : null;
+    if (!backend || !backend.internalPort) {
+      clientSocket.destroy();
+      return;
+    }
+
+    const genId = backend.id;
+    this._incrementInFlight(genId);
+
+    let decremented = false;
+    const cleanupInFlight = () => {
+      if (!decremented) {
+        decremented = true;
+        this._decrementInFlight(genId);
+      }
+    };
+
+    let backendSocket = null;
+
+    const onClientEnded = () => {
+      cleanupInFlight();
+      if (backendSocket && !backendSocket.destroyed) {
+        backendSocket.destroy();
+      }
+    };
+
+    clientSocket.once('close', onClientEnded);
+    clientSocket.once('end', onClientEnded);
+    clientSocket.once('error', onClientEnded);
+
+    backendSocket = net.connect(backend.internalPort, '127.0.0.1', () => {
+      backendSocket.write(
+        `${req.method} ${req.url} HTTP/${req.httpVersion}\r\n` +
+          Object.entries(req.headers)
+            .map(([k, v]) => `${k}: ${v}\r\n`)
+            .join('') +
+          '\r\n'
+      );
+      if (head && head.length > 0) {
+        backendSocket.write(head);
+      }
+      backendSocket.pipe(clientSocket);
+      clientSocket.pipe(backendSocket);
+    });
+
+    const onBackendEnded = () => {
+      cleanupInFlight();
+      if (!clientSocket.destroyed) {
+        clientSocket.destroy();
+      }
+    };
+
+    backendSocket.once('close', onBackendEnded);
+    backendSocket.once('end', onBackendEnded);
+    backendSocket.on('error', onBackendEnded);
+  }
+
+  /**
+   * Closes the public router HTTP listener.
+   *
+   * @returns {Promise<void>}
+   */
+  async close() {
+    this.closing = true;
+    if (!this.server) return;
+
+    return new Promise((resolve) => {
+      this.server.close(() => {
+        this.server = null;
+        this.listeningPort = null;
+        this.listeningHost = null;
+        resolve();
+      });
+    });
+  }
+}