@underpostnet/cyberia 3.2.80

package/src/server/process.js

@@ -0,0 +1,299 @@
+/**
+ * Module for process and shell command management.
+ * Provides utilities for executing shell commands, managing signals, and
+ * handling environment details.
+ *
+ * Execution semantics:
+ *   - `shellExec(cmd)` throws `ShellExecError` on non-zero exit (fail-fast
+ *     is the default). CI/CD chains observe the failure end-to-end.
+ *   - `shellExec(cmd, { silentOnError: true })` opts out — returns the
+ *     `ShellString` result with `.code/.stdout/.stderr` so callers can
+ *     branch on the exit code themselves. Use for existence checks
+ *     (`test -x …`, `command -v …`, `kubectl get` when "missing" is a
+ *     normal answer).
+ *   - `shellExec(cmd, { cwd: "..." })` runs hermetically in `cwd` without
+ *      touching shelljs's global state.
+ *   - All children spawned by `shellExec` register in
+ *     `ProcessController.children` so SIGINT/SIGTERM forwarding can reach
+ *     them before the parent exits.
+ *
+ * @module src/server/process.js
+ * @namespace Process
+ */
+// https://nodejs.org/api/process
+import shell from 'shelljs';
+import { loggerFactory } from './logger.js';
+import clipboard from 'clipboardy';
+import Underpost from '../index.js';
+import { getNpmRootPath } from './conf.js';
+const logger = loggerFactory(import.meta);
+/**
+ * Gets the current working directory, replacing backslashes with forward slashes for consistency.
+ * @memberof Process
+ * @returns {string} The root directory path.
+ */
+const getRootDirectory = () => process.cwd().replace(/\\/g, '/');
+/**
+ * Controls and manages process-level events and signals.
+ *
+ * Subprocess registry: any child process tracked here will receive
+ * SIGTERM (followed by SIGKILL after a short grace period) when the
+ * parent receives SIGINT or SIGTERM. This prevents orphaned children
+ * during Ctrl+C in dev and during pod-termination in K8S.
+ *
+ * @namespace ProcessController
+ */
+class ProcessController {
+  /**
+   * List of signals to listen for for graceful shutdown/handling.
+   * @memberof ProcessController
+   * @type {string[]}
+   */
+  static SIG = [
+    'SIGPIPE',
+    'SIGHUP',
+    'SIGTERM',
+    'SIGINT',
+    'SIGBREAK',
+    'SIGWINCH',
+    // 'SIGKILL',
+    // 'SIGSTOP',
+    'SIGBUS',
+    'SIGFPE',
+    'SIGSEGV',
+    'SIGILL',
+  ];
+
+  /**
+   * Registry of currently running tracked child processes.
+   * Populated when callers spawn via the streaming Node-native path
+   * (future expansion). The sets are exposed so signal handlers and
+   * test harnesses can introspect / clean up the registry.
+   */
+  static children = new Set();
+
+  /** Internal: forward terminating signals to all tracked children. */
+  static _forwardToChildren(sig) {
+    if (ProcessController.children.size === 0) return;
+    for (const child of [...ProcessController.children]) {
+      try {
+        if (!child.killed) child.kill(sig);
+      } catch (_) {
+        // child may already have exited; ignore.
+      }
+    }
+    // Hard SIGKILL after 5s grace if any child is still alive.
+    setTimeout(() => {
+      for (const child of [...ProcessController.children]) {
+        try {
+          if (!child.killed) child.kill('SIGKILL');
+        } catch (_) {
+          /* noop */
+        }
+      }
+    }, 5000).unref();
+  }
+
+  /**
+   * Sets up listeners for various process signals defined in {@link ProcessController.SIG}.
+   * Handles graceful exit on 'SIGINT' (Ctrl+C) — but first forwards the
+   * signal to every tracked child so they get a chance to clean up.
+   * @memberof ProcessController
+   * @returns {Array<process.Process>} An array of process listener handles.
+   */
+  static onSigListen() {
+    return ProcessController.SIG.map((sig) =>
+      process.on(sig, (...args) => {
+        ProcessController.logger.info(`process on ${sig}`, args);
+        switch (sig) {
+          case 'SIGINT':
+          case 'SIGTERM':
+          case 'SIGHUP':
+            ProcessController._forwardToChildren('SIGTERM');
+            // Give children a moment to exit cleanly before our own exit.
+            if (sig === 'SIGINT') {
+              setTimeout(() => process.exit(130), 200).unref();
+            }
+            break;
+          default:
+            break;
+        }
+      }),
+    );
+  }
+  /**
+   * Initializes the ProcessController.
+   * Sets up signal listeners, registers a listener for the 'exit' event, and cleans up temporary deployment environment variables.
+   * @memberof ProcessController
+   * @param {Object} logger - The logger instance to use for internal logging.
+   * @returns {void}
+   */
+  static init(logger) {
+    ProcessController.logger = logger;
+    process.on('exit', (...args) => {
+      ProcessController.logger.info(`process on exit`, args);
+      // Last-chance reap: any tracked child still alive at exit time
+      // gets a hard kill so the parent does not leak orphans into the
+      // pod / shell session.
+      ProcessController._forwardToChildren('SIGKILL');
+    });
+    ProcessController.onSigListen();
+  }
+}
+/**
+ * `ShellExecError` — thrown by `shellExec` when the underlying command
+ * exits with a non-zero code (the default fail-fast behaviour). Carries
+ * the exit code, stdout, and stderr for inspection by callers / CI
+ * pipelines that need structured failure data.
+ */
+class ShellExecError extends Error {
+  constructor(cmd, code, stdout, stderr) {
+    super(`shellExec failed (exit=${code}): ${cmd}`);
+    this.name = 'ShellExecError';
+    this.cmd = cmd;
+    this.code = code;
+    this.stdout = stdout;
+    this.stderr = stderr;
+  }
+}
+/**
+ * Executes a shell command using shelljs.
+ *
+ * **Default behaviour is fail-fast**: a non-zero exit code throws
+ * `ShellExecError`. Callers that need to branch on the exit code
+ * (existence checks, optional commands) must pass `silentOnError: true`
+ * to opt out of throwing.
+ *
+ * The async-callback path is exempt from the throw — shelljs delivers
+ * `(code, stdout, stderr)` to the callback, which owns its own error
+ * handling.
+ *
+ * @memberof Process
+ * @param {string} cmd - The command string to execute.
+ * @param {Object} [options] - Options for execution.
+ * @param {boolean} [options.silent=false] - Suppress child stdout/stderr to the parent terminal.
+ * @param {boolean} [options.async=false] - Run the command asynchronously (use with `callback`).
+ * @param {boolean} [options.stdout=false] - Return stdout string instead of the `ShellString` result object.
+ * @param {boolean} [options.disableLog=false] - Skip the `[process] cmd …` info log line.
+ * @param {Function} [options.callback=null] - Async callback `(code, stdout, stderr) => void` when `async: true`.
+ * @param {boolean} [options.silentOnError=false] - When `true`, swallow non-zero exits and return the `ShellString` instead of throwing. Inverse of the previous `throwOnError` flag.
+ * @param {string} [options.cwd] - Hermetic working directory (snapshotted + restored — does NOT leak).
+ * @returns {string|shelljs.ShellString} `ShellString` by default; the stdout string when `stdout: true`.
+ * @throws {ShellExecError} On non-zero exit when `silentOnError` is not set.
+ */
+const shellExec = (cmd, options = {}) => {
+  if (!options.disableLog) logger.info(`cmd`, cmd);
+
+  // Whitelist exactly the keys `shelljs.exec` understands. Passing our own
+  // bookkeeping keys through (or a literal `cwd: undefined`) makes shelljs
+  // call `path.resolve(undefined)` and crash with ERR_INVALID_ARG_TYPE.
+  const shellOpts = {};
+  if (options.silent !== undefined) shellOpts.silent = options.silent;
+  if (options.async !== undefined) shellOpts.async = options.async;
+
+  // Hermetic cwd. shelljs.cd mutates a process-wide global; instead we
+  // snapshot the current cwd here, switch for the duration of this call,
+  // and restore in `finally`. We deliberately do NOT forward `cwd` to
+  // shelljs — leaving its `cwd` unset means it inherits our just-changed
+  // `process.cwd()`, and we keep full control of restore semantics.
+  const previousCwd = options.cwd ? process.cwd() : null;
+  if (options.cwd) {
+    try {
+      process.chdir(options.cwd);
+    } catch (err) {
+      if (Underpost.env.isInsideContainer()) Underpost.env.set('container-status', 'error')
+      throw new ShellExecError(cmd, -1, '', `chdir(${options.cwd}) failed: ${err.message}`);
+    }
+  }
+  try {
+    if (options.callback) {
+      // Async path. shelljs invokes the callback with (code, stdout, stderr).
+      // The callback owns its own error handling; the throw default does
+      // not apply here.
+      return shell.exec(cmd, shellOpts, options.callback);
+    }
+    const result = shell.exec(cmd, shellOpts);
+
+    if (!options.silentOnError && result && typeof result.code === 'number' && result.code !== 0) {
+      if (Underpost.env.isInsideContainer()) Underpost.env.set('container-status', 'error')
+      throw new ShellExecError(cmd, result.code, result.stdout || '', result.stderr || '');
+    }
+
+    return options.stdout ? result.stdout : result;
+  } finally {
+    if (previousCwd) {
+      try {
+        process.chdir(previousCwd);
+      } catch (_) {
+        /* best-effort restore */
+      }
+    }
+  }
+};
+/**
+ * Changes the current working directory using shelljs.
+ *
+ * Note: `shellCd` mutates global state. Prefer `shellExec(cmd, { cwd })`
+ * for one-shot directory-scoped commands; use `shellCd` only for the
+ * outermost shell where the cwd should persist across many calls.
+ *
+ * @memberof Process
+ * @param {string} cd - The path to change the directory to.
+ * @param {Object} [options] - Options for the CD operation.
+ * @param {boolean} [options.disableLog=false] - Prevent logging of the CD command.
+ * @returns {shelljs.ShellString} The result of the shelljs cd command.
+ */
+const shellCd = (cd, options = { disableLog: false }) => {
+  if (!options.disableLog) logger.info(`cd`, cd);
+  return shell.cd(cd);
+};
+/**
+ * Wraps a command to run it as a daemon process in a shell (keeping the process alive/terminal open).
+ *
+ * NB: callers must ensure `cmd` does not contain unescaped single quotes —
+ * the wrapper uses `bash -c '<cmd>; …'`. For arbitrary user input prefer
+ * a heredoc or a temporary script file.
+ *
+ * @memberof Process
+ * @param {string} cmd - The command to daemonize.
+ * @returns {string} The shell command string for the daemon process.
+ */
+const daemonProcess = (cmd) => `exec bash -c '${cmd}; exec tail -f /dev/null'`;
+/**
+ * Retrieves the process ID (PID) of the most recently created gnome-terminal instance.
+ * Note: This function is environment-specific (GNOME/Linux) and uses `pgrep -n`.
+ * @memberof Process
+ * @returns {number|null} The PID of the last gnome-terminal process, or null if none running.
+ */
+// list all terminals: pgrep gnome-terminal
+// list last terminal: pgrep -n gnome-terminal
+const getTerminalPid = () => {
+  const raw = shellExec(`pgrep -n gnome-terminal`, { stdout: true, silent: true, silentOnError: true });
+  if (!raw || !raw.trim()) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+};
+/**
+ * Copies text content to the system clipboard using clipboardy.
+ * Logs the copied content for confirmation.
+ * @memberof Process
+ * @param {string} [data='🦄'] - The data to copy. Defaults to '🦄'.
+ * @returns {void}
+ */
+function pbcopy(data) {
+  clipboard.writeSync(data || '🦄');
+  logger.info(`copied to clipboard`, clipboard.readSync());
+}
+export {
+  ProcessController,
+  ShellExecError,
+  getRootDirectory,
+  shellExec,
+  shellCd,
+  pbcopy,
+  getTerminalPid,
+  daemonProcess,
+};

package/src/server/proxy.js

@@ -0,0 +1,139 @@
+/**
+ * Manages the creation and configuration of the reverse proxy server,
+ * including handling HTTP/HTTPS listeners and routing based on host configuration.
+ * @module src/server/proxy.js
+ * @namespace ProxyService
+ */
+'use strict';
+
+import express from 'express';
+import { createProxyMiddleware } from 'http-proxy-middleware';
+import { loggerFactory, loggerMiddleware } from './logger.js';
+import {
+  buildPortProxyRouter,
+  buildProxyRouter,
+  etcHostFactory,
+  getTlsHosts,
+  isDevProxyContext,
+  isTlsDevProxy,
+} from './conf.js';
+
+import { shellExec } from './process.js';
+import fs from 'fs-extra';
+import Underpost from '../index.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * Main class for building and running the proxy server.
+ * All utility methods are implemented as static to serve as a namespace container.
+ * @class ProxyService
+ * @memberof ProxyService
+ */
+class ProxyService {
+  /**
+   * Builds and starts the proxy server with appropriate routing and SSL configuration.
+   * @static
+   * @returns {Promise<void>} Resolves when the server is successfully started.
+   */
+  static async build() {
+    if (process.env.NODE_ENV === 'production') process.env.DEV_PROXY_PORT_OFFSET = 0;
+
+    // Start a default Express listener on process.env.PORT (potentially unused, but ensures Express is initialized)
+    process.env.PORT = parseInt(process.env.PORT) + parseInt(process.env.DEV_PROXY_PORT_OFFSET);
+    express().listen(process.env.PORT);
+
+    const proxyRouter = buildProxyRouter();
+
+    for (let port of Object.keys(proxyRouter)) {
+      const hosts = proxyRouter[port];
+      port = parseInt(port) + parseInt(process.env.DEV_PROXY_PORT_OFFSET);
+      const proxyPath = '/';
+      const proxyHost = 'localhost';
+      const runningData = { host: proxyHost, path: proxyPath, client: null, runtime: 'nodejs', meta: import.meta };
+      const app = express();
+
+      // Set logger middleware
+      app.use(loggerMiddleware(import.meta));
+
+      // Proxy middleware options
+      /** @type {import('http-proxy-middleware/dist/types').Options} */
+      const options = {
+        pathFilter: proxyPath, // Use '/' as the general filter (v3 API)
+        ws: true, // Enable websocket proxying
+        target: `http://localhost:${parseInt(process.env.PORT - 1)}`, // Default target (should be overridden by router)
+        router: {},
+        // changeOrigin: true,
+        logger: logger,
+        xfwd: true, // Adds x-forward headers (Host, Proto, etc.)
+        onProxyReq: (proxyReq, req, res, options) => {},
+        pathRewrite: {},
+      };
+
+      options.router = buildPortProxyRouter({
+        port,
+        proxyRouter,
+        hosts,
+        orderByPathLength: true,
+        devProxyContext: process.env.NODE_ENV !== 'production',
+      });
+
+      app.use(proxyPath, createProxyMiddleware(options));
+
+      // Determine which server to start (HTTP or HTTPS) based on port and environment
+      switch (process.env.NODE_ENV) {
+        case 'production':
+          switch (port) {
+            case 443:
+              // For port 443 (HTTPS), create the SSL server
+              const { ServerSSL } = await Underpost.tls.createSslServer(app, hosts);
+              await Underpost.start.listenPortController(ServerSSL, port, runningData);
+              break;
+
+            default:
+              // For other ports in production, use standard HTTP
+              await Underpost.start.listenPortController(app, port, runningData);
+              break;
+          }
+          break;
+
+        default:
+          switch (port) {
+            case 443: {
+              let tlsHosts = hosts;
+              if (isDevProxyContext() && isTlsDevProxy()) {
+                tlsHosts = {};
+                for (const tlsHost of getTlsHosts(hosts)) {
+                  if (fs.existsSync(Underpost.tls.SSL_BASE(tlsHost))) fs.removeSync(Underpost.tls.SSL_BASE(tlsHost));
+                  if (!Underpost.tls.validateSecureContext(tlsHost)) shellExec(`node bin/deploy tls "${tlsHost}"`);
+                  tlsHosts[tlsHost] = {};
+                }
+              }
+              const { ServerSSL } = await Underpost.tls.createSslServer(app, tlsHosts);
+              await Underpost.start.listenPortController(ServerSSL, port, runningData);
+              break;
+            }
+            default: // In non-production, always use standard HTTP listener
+              await Underpost.start.listenPortController(app, port, runningData);
+              break;
+          }
+      }
+      logger.info('Proxy running', { port, router: options.router });
+      if (process.env.NODE_ENV === 'development')
+        logger.info(
+          etcHostFactory(Object.keys(options.router), {
+            append: true,
+          }).renderHosts,
+        );
+    }
+  }
+}
+
+/**
+ * Backward compatibility export
+ * @type {function(): Promise<void>}
+ * @memberof ProxyService
+ */
+const buildProxy = ProxyService.build;
+
+export { ProxyService, buildProxy };

package/src/server/runtime-status.js

@@ -0,0 +1,252 @@
+/**
+ * Runtime status contract and the in-pod internal status endpoint.
+ *
+ * Single source of truth for the Underpost runtime readiness signal (Phase 2 of
+ * the two-phase deployment monitor). The runtime publishes its lifecycle here;
+ * the CD-side monitor (`src/cli/monitor.js`) reads it over HTTP via
+ * `kubectl port-forward`. Kubernetes pod readiness (Phase 1) is owned by kubelet
+ * and is intentionally not modeled in this module.
+ *
+ * Cross-process contract:
+ *   - In-pod, the canonical value lives in the underpost root env key
+ *     `container-status`, written by `start.js`. For non-error phases it carries
+ *     the namespaced form `<deployId>-<env>-<phase>`; a fatal fault collapses to
+ *     the bare value `error`.
+ *   - The internal HTTP server exposes that value (normalized to the bare
+ *     contract phase) and never exposes secrets, env dumps, or configuration.
+ *
+ * @module src/server/runtime-status.js
+ * @namespace RuntimeStatus
+ */
+
+import http from 'node:http';
+import fs from 'fs-extra';
+import dotenv from 'dotenv';
+import Underpost from '../index.js';
+import { loggerFactory } from './logger.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * Allowed runtime status contract values. These are the only Phase-2 signals
+ * the monitor reasons about.
+ * @memberof RuntimeStatus
+ */
+const RUNTIME_STATUS = {
+  BUILD: 'build-deployment',
+  INIT: 'initializing-deployment',
+  RUNNING: 'running-deployment',
+  ERROR: 'error',
+};
+
+const CONTAINER_STATUS_KEY = 'container-status';
+const START_CONTAINER_STATUS_KEY = 'start-container-status';
+const INTERNAL_STATUS_PATH = '/_internal/status';
+const INTERNAL_READY_PATH = '/_internal/ready';
+const INTERNAL_HEALTH_PATH = '/_internal/health';
+
+/**
+ * Resolves the internal status port. Defaults to the deployment base `PORT`
+ * (app instances bind `PORT + 1` upward, so the base port is free inside the
+ * pod). An explicit `UNDERPOST_INTERNAL_PORT` override wins.
+ * @memberof RuntimeStatus
+ * @returns {number|undefined}
+ */
+const resolveInternalStatusPort = () => {
+  const raw = process.env.UNDERPOST_INTERNAL_PORT || process.env.PORT;
+  const port = parseInt(raw);
+  return Number.isNaN(port) ? undefined : port;
+};
+
+/**
+ * Single source of truth for the internal status port of a specific deployment,
+ * used identically by the in-pod server bind (`start.js`) and the CD-side
+ * monitor target (`monitor.js`) so the two can never disagree.
+ *
+ * Resolution order: `UNDERPOST_INTERNAL_PORT` override → the deployment's
+ * `.env.<env>` `PORT` → the ambient `PORT`.
+ *
+ * @memberof RuntimeStatus
+ * @param {string} deployId
+ * @param {string} env
+ * @returns {number|undefined}
+ */
+const deployStatusPort = (deployId, env) => {
+  const override = parseInt(process.env.UNDERPOST_INTERNAL_PORT);
+  if (!Number.isNaN(override)) return override;
+  try {
+    const envPath = `./engine-private/conf/${deployId}/.env.${env}`;
+    if (fs.existsSync(envPath)) {
+      const port = parseInt(dotenv.parse(fs.readFileSync(envPath, 'utf8')).PORT);
+      if (!Number.isNaN(port)) return port;
+    }
+  } catch (_) {
+    /* fall through to ambient resolution */
+  }
+  return resolveInternalStatusPort();
+};
+
+/**
+ * Builds the `container-status` env value for a lifecycle phase.
+ * @memberof RuntimeStatus
+ */
+const containerStatusValue = (deployId, env, phase) =>
+  phase === RUNTIME_STATUS.ERROR ? RUNTIME_STATUS.ERROR : `${deployId}-${env}-${phase}`;
+
+/**
+ * Normalizes a raw `container-status` value to a bare contract phase.
+ * Strips the `<deployId>-<env>-` prefix; `error` and unknown/empty values are
+ * passed through (empty → undefined).
+ * @memberof RuntimeStatus
+ * @param {string} raw
+ * @returns {string|undefined}
+ */
+const normalizeContainerStatus = (raw) => {
+  if (!raw || typeof raw !== 'string') return undefined;
+  const value = raw.trim();
+  if (!value || value === 'undefined' || value.toLowerCase().includes('empty')) return undefined;
+  if (value === RUNTIME_STATUS.ERROR) return RUNTIME_STATUS.ERROR;
+  for (const phase of [RUNTIME_STATUS.BUILD, RUNTIME_STATUS.INIT, RUNTIME_STATUS.RUNNING])
+    if (value.endsWith(`-${phase}`)) return phase;
+  return value;
+};
+
+/**
+ * Reads the current normalized runtime status from the env file.
+ * @memberof RuntimeStatus
+ * @returns {string|undefined}
+ */
+const getRuntimeStatus = () =>
+  normalizeContainerStatus(Underpost.env.get(CONTAINER_STATUS_KEY, undefined, { disableLog: true }));
+
+/**
+ * Reads the start-container-status env key — an insulated marker set by the
+ * start pipeline after it completes the running phase. Unlike container-status
+ * (which external scripts / backup failures may clobber), this key is written
+ * once and survives globalSecretClean. Used exclusively by the readinessProbe
+ * endpoint so K8s pod readiness is never derailed by lifecycle noise.
+ * @memberof RuntimeStatus
+ * @returns {string|undefined}
+ */
+const getStartContainerStatus = () => {
+  const raw = Underpost.env.get(START_CONTAINER_STATUS_KEY, undefined, { disableLog: true });
+  return raw && typeof raw === 'string' && raw.trim() ? raw.trim() : undefined;
+};
+
+/**
+ * Minimal, secret-free payload served by the internal status endpoint and used
+ * by the monitor for failure classification and observability.
+ * @memberof RuntimeStatus
+ * @returns {{status: (string|null), deployId: (string|null), env: (string|null)}}
+ */
+const runtimeStatusPayload = () => ({
+  status: getRuntimeStatus() ?? null,
+  deployId: process.env.DEPLOY_ID ?? null,
+  env: process.env.NODE_ENV ?? null,
+});
+
+/**
+ * Emits a structured, secret-free deployment transition event.
+ * @memberof RuntimeStatus
+ */
+const emitRuntimeEvent = ({ deployId, env, phase }) => {
+  logger.info('runtime-status', {
+    deployId,
+    env,
+    phase: 'runtime',
+    status: phase,
+    timestamp: new Date().toISOString(),
+  });
+};
+
+/**
+ * Publishes a runtime lifecycle phase to the cross-process contract.
+ * @memberof RuntimeStatus
+ * @param {string} deployId
+ * @param {string} env
+ * @param {string} phase - One of {@link RUNTIME_STATUS}.
+ */
+const setRuntimeStatus = (deployId, env, phase) => {
+  Underpost.env.set(CONTAINER_STATUS_KEY, containerStatusValue(deployId, env, phase));
+  emitRuntimeEvent({ deployId, env, phase });
+};
+
+let internalServer;
+
+/**
+ * Starts the in-pod internal status server. Idempotent: repeated calls return
+ * the already-listening server. Exposes only the three internal endpoints and
+ * never serves secrets or configuration.
+ *
+ *   GET /_internal/status  → 200, `{status, deployId, env}` (monitor transport)
+ *   GET /_internal/ready   → 200 iff running-deployment, else 503 (readinessProbe)
+ *   GET /_internal/health  → 200 while the process is alive (livenessProbe)
+ *
+ * @memberof RuntimeStatus
+ * @param {number} [port]
+ * @returns {import('node:http').Server|undefined}
+ */
+const startInternalStatusServer = (port = resolveInternalStatusPort()) => {
+  if (internalServer) return internalServer;
+  if (!port) {
+    logger.warn('Internal status server not started: no resolvable port');
+    return undefined;
+  }
+  const server = http.createServer((req, res) => {
+    const url = (req.url || '').split('?')[0];
+    const sendJson = (code, body) => {
+      res.writeHead(code, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(body));
+    };
+    if (req.method !== 'GET') return sendJson(405, { error: 'method_not_allowed' });
+    switch (url) {
+      case INTERNAL_HEALTH_PATH:
+        return sendJson(200, { status: 'ok' });
+      case INTERNAL_READY_PATH:
+        return getStartContainerStatus()
+          ? sendJson(200, { status: RUNTIME_STATUS.RUNNING })
+          : sendJson(503, { status: getRuntimeStatus() ?? null });
+      case INTERNAL_STATUS_PATH:
+        return sendJson(200, runtimeStatusPayload());
+      default:
+        return sendJson(404, { error: 'not_found' });
+    }
+  });
+  server.on('error', (error) => logger.error('internal status server error', error?.message ?? error));
+  server.listen(port, () => logger.info(`Internal status endpoint listening on :${port}${INTERNAL_STATUS_PATH}`));
+  internalServer = server;
+  return internalServer;
+};
+
+/**
+ * Stops the internal status server if running. Returns a promise that resolves
+ * once the listener is closed. Primarily a test/teardown hook.
+ * @memberof RuntimeStatus
+ * @returns {Promise<void>}
+ */
+const stopInternalStatusServer = () =>
+  new Promise((resolve) => {
+    if (!internalServer) return resolve();
+    const server = internalServer;
+    internalServer = undefined;
+    server.close(() => resolve());
+  });
+
+export {
+  RUNTIME_STATUS,
+  CONTAINER_STATUS_KEY,
+  START_CONTAINER_STATUS_KEY,
+  INTERNAL_STATUS_PATH,
+  INTERNAL_READY_PATH,
+  INTERNAL_HEALTH_PATH,
+  resolveInternalStatusPort,
+  deployStatusPort,
+  containerStatusValue,
+  normalizeContainerStatus,
+  getRuntimeStatus,
+  getStartContainerStatus,
+  runtimeStatusPayload,
+  setRuntimeStatus,
+  startInternalStatusServer,
+  stopInternalStatusServer,
+};