rollbridge 0.1.2 → 0.1.5

package/package.json

@@ -1,7 +1,26 @@
 {
   "name": "rollbridge",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Zero-downtime process supervisor and local traffic switcher for deploy-managed apps.",
+  "keywords": [
+    "deploy",
+    "zero-downtime",
+    "process-supervisor",
+    "reverse-proxy",
+    "websocket",
+    "rollbridge",
+    "velocious"
+  ],
+  "homepage": "https://github.com/kaspernj/rollbridge#readme",
+  "bugs": {
+    "url": "https://github.com/kaspernj/rollbridge/issues"
+  },
+  "license": "MIT",
+  "author": "kaspernj <kasper@diestoeckels.de>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kaspernj/rollbridge.git"
+  },
   "type": "module",
   "bin": {
     "rollbridge": "./bin/rollbridge"
@@ -9,7 +28,7 @@
   "scripts": {
     "all-checks": "npm run typecheck && npm run lint && npm test",
     "lint": "eslint",
-    "release:patch": "node scripts/release-patch.js",
+    "release:patch": "release-patch",
     "test": "node --test test/*.test.js",
     "typecheck": "tsc --noEmit"
   },
@@ -27,6 +46,7 @@
     "eslint": "^10.4.0",
     "eslint-plugin-jsdoc": "^62.9.0",
     "globals": "^17.6.0",
+    "release-patch": "^1.0.0",
     "typescript": "^6.0.3"
   }
 }

package/src/cli.js

@@ -7,6 +7,7 @@ import {spawn} from "node:child_process"
 import {Command} from "commander"
 import RollbridgeDaemon from "./daemon.js"
 import {loadConfig, parseConfigFile, resolveConfigPath, validateConfig} from "./config.js"
+import {runEnvironmentChecks} from "./doctor.js"
 import {sendControlCommand} from "./control-client.js"
 
 const DEFAULT_DAEMON_START_TIMEOUT_MS = 10000
@@ -135,6 +136,33 @@ export async function runCli(argv) {
       console.log(JSON.stringify(response, null, 2))
     })
 
+  program
+    .command("restart")
+    .description("Restart running non-proxied processes (by id, by policy, or all).")
+    .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--process <id>", "Restart only the process with this id")
+    .option("--policy <policy>", "Restart only processes with this policy (companion, singleton, or service)")
+    .action(async (options) => {
+      if (options.policy !== undefined && !["companion", "service", "singleton"].includes(options.policy)) {
+        console.error("--policy must be one of: companion, singleton, service.")
+        process.exitCode = 1
+        return
+      }
+
+      const configPath = await resolveConfigPath(options.config)
+      const config = await loadConfig(configPath)
+      const response = await sendControlCommand({
+        command: {
+          command: "restart",
+          policy: options.policy,
+          processId: options.process
+        },
+        path: config.control.path
+      })
+
+      console.log(JSON.stringify(response, null, 2))
+    })
+
   program
     .command("shutdown")
     .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
@@ -153,20 +181,33 @@ export async function runCli(argv) {
     .command("validate")
     .description("Parse the config and report all errors without starting the daemon.")
     .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--json", "Output machine-readable JSON")
     .action(async (options) => {
       let configPath
 
       try {
         configPath = await resolveConfigPath(options.config)
       } catch (error) {
-        console.error(error instanceof Error ? error.message : String(error))
+        const message = error instanceof Error ? error.message : String(error)
+
+        if (options.json) console.log(JSON.stringify({config: null, issues: [{fix: "Pass --config or add a rollbridge.js.", message}], path: null, valid: false}, null, 2))
+        else console.error(message)
         process.exitCode = 1
         return
       }
 
       const {config, issues} = await validateConfigFile(configPath)
+      const valid = issues.length === 0
+
+      if (options.json) {
+        const summary = valid ? {application: config.application, processes: config.processes.length, proxy: {host: config.proxy.host, port: config.proxy.port}} : null
 
-      if (issues.length === 0) {
+        console.log(JSON.stringify({config: summary, issues, path: configPath, valid}, null, 2))
+        if (!valid) process.exitCode = 1
+        return
+      }
+
+      if (valid) {
         const processCount = config.processes.length
 
         console.log(`${configPath} is valid: ${processCount} ${processCount === 1 ? "process" : "processes"}, proxy on ${config.proxy.host}:${config.proxy.port}.`)
@@ -183,9 +224,134 @@ export async function runCli(argv) {
       process.exitCode = 1
     })
 
+  program
+    .command("doctor")
+    .description("Check the environment before starting the daemon: config, control socket, and proxy port.")
+    .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--json", "Output machine-readable JSON")
+    .action(async (options) => {
+      let configPath
+
+      try {
+        configPath = await resolveConfigPath(options.config)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+
+        if (options.json) console.log(JSON.stringify({checks: [{detail: message, name: "config", ok: false}], ok: false}, null, 2))
+        else console.error(message)
+        process.exitCode = 1
+        return
+      }
+
+      const {config, issues} = await validateConfigFile(configPath)
+      /** @type {import("./doctor.js").DoctorCheck[]} */
+      const checks = []
+
+      if (issues.length > 0) {
+        checks.push({detail: `${issues.length} ${issues.length === 1 ? "issue" : "issues"} — run "rollbridge validate" for details`, name: "config", ok: false})
+      } else {
+        checks.push({detail: `valid: ${config.processes.length} ${config.processes.length === 1 ? "process" : "processes"}, proxy on ${config.proxy.host}:${config.proxy.port}`, name: "config", ok: true})
+        checks.push(...await runEnvironmentChecks(config))
+      }
+
+      const failed = checks.filter((check) => !check.ok).length
+
+      if (options.json) {
+        console.log(JSON.stringify({checks, ok: failed === 0}, null, 2))
+      } else {
+        for (const check of checks) {
+          console.log(`${check.ok ? "✓" : "✗"} ${check.name}: ${check.detail}`)
+        }
+
+        if (failed === 0) console.log("\nAll checks passed.")
+        else console.error(`\n${failed} check${failed === 1 ? "" : "s"} failed.`)
+      }
+
+      if (failed > 0) process.exitCode = 1
+    })
+
+  program
+    .command("logs")
+    .description("Print recent stdout/stderr captured from managed processes.")
+    .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
+    .option("--process <id>", "Only show logs for the process with this id")
+    .option("--json", "Output machine-readable JSON")
+    .action(async (options) => {
+      const configPath = await resolveConfigPath(options.config)
+      const config = await loadConfig(configPath)
+      const response = await sendControlCommand({
+        command: {command: "status"},
+        path: config.control.path
+      })
+      const sources = collectLogSources(/** @type {import("./daemon.js").DaemonStatus} */ (response))
+
+      if (options.json) {
+        const filtered = options.process === undefined ? sources : sources.filter((source) => source.id === options.process)
+
+        console.log(JSON.stringify(filtered, null, 2))
+        return
+      }
+
+      console.log(formatLogSources(sources, options.process))
+    })
+
   await program.parseAsync(argv)
 }
 
+/**
+ * @typedef {{id: string, logs: import("./managed-process.js").ManagedProcessLog[], source: string}} LogSource
+ */
+
+/**
+ * Flattens managed-process logs from a daemon status payload, labelling each process by origin.
+ * @param {import("./daemon.js").DaemonStatus} status - Daemon status payload.
+ * @returns {LogSource[]} One entry per managed process.
+ */
+function collectLogSources(status) {
+  /** @type {LogSource[]} */
+  const sources = []
+
+  for (const release of status.releases) {
+    for (const processStatus of release.processes) {
+      sources.push({id: processStatus.id, logs: processStatus.logs, source: `release ${release.releaseId} (${release.state})`})
+    }
+  }
+
+  for (const service of status.services) {
+    sources.push({id: service.process.id, logs: service.process.logs, source: "service"})
+  }
+
+  for (const singleton of status.singletons) {
+    sources.push({id: singleton.process.id, logs: singleton.process.logs, source: "singleton"})
+  }
+
+  return sources
+}
+
+/**
+ * Formats collected log sources for display, optionally filtered to a single process id.
+ * @param {LogSource[]} sources - Collected log sources.
+ * @param {string | undefined} processFilter - Only include the process with this id when set.
+ * @returns {string} Human-readable log output.
+ */
+export function formatLogSources(sources, processFilter) {
+  const matched = processFilter === undefined ? sources : sources.filter((source) => source.id === processFilter)
+
+  if (matched.length === 0) {
+    return processFilter === undefined ? "No managed processes." : `No process found with id "${processFilter}".`
+  }
+
+  return matched
+    .map((source) => {
+      const header = `== ${source.id} [${source.source}] ==`
+
+      if (source.logs.length === 0) return `${header}\n  (no recent output)`
+
+      return `${header}\n${source.logs.map((log) => `  ${log.at} [${log.stream}] ${log.line}`).join("\n")}`
+    })
+    .join("\n\n")
+}
+
 /**
  * Reads, parses, and validates a config file, collecting read, parse, and validation issues.
  * @param {string} configPath - Config file path.

package/src/config.js

@@ -7,12 +7,14 @@ import {pathToFileURL} from "node:url"
 /**
  * @typedef {import("./json.js").JsonValue} JsonValue
  * @typedef {{from: number, to: number}} PortRange
- * @typedef {{path: string, timeoutMs: number, intervalMs: number}} HealthConfig
+ * @typedef {{path: string, startDelayMs: number, timeoutMs: number, intervalMs: number}} HealthConfig
  * @typedef {"proxied" | "companion" | "singleton" | "service"} ProcessPolicy
- * @typedef {{cwd?: string, env: Record<string, string>, gracefulStopMs: number, health?: HealthConfig, id: string, outputLines: number, policy: ProcessPolicy, port?: PortRange, restartDelayMs: number, command: string}} ProcessConfig
+ * @typedef {{backoffFactor: number, maxDelayMs: number, maxRestarts: number | undefined, windowMs: number}} RestartConfig
+ * @typedef {{cwd?: string, env: Record<string, string>, gracefulStopMs: number, health?: HealthConfig, id: string, outputLines: number, policy: ProcessPolicy, port?: PortRange, restart: RestartConfig, restartDelayMs: number, command: string}} ProcessConfig
  * @typedef {{mode?: number, path: string}} ControlConfig
- * @typedef {{drainTimeoutMs: number, forceStopTimeoutMs: number, healthPath: string, healthTimeoutMs: number, host: string, port: number}} ProxyConfig
- * @typedef {{application: string, control: ControlConfig, processes: ProcessConfig[], proxy: ProxyConfig}} RollbridgeConfig
+ * @typedef {{drainTimeoutMs: number, forceStopTimeoutMs: number, healthPath: string, healthTimeoutMs: number, host: string, port: number, upstreamHost: string}} ProxyConfig
+ * @typedef {{keep: number, maxAgeMs: number}} ReleaseRetentionConfig
+ * @typedef {{application: string, control: ControlConfig, processes: ProcessConfig[], proxy: ProxyConfig, releaseRetention: ReleaseRetentionConfig}} RollbridgeConfig
  * @typedef {{fix: string, message: string}} ConfigIssue
  */
 
@@ -127,10 +129,11 @@ export function validateConfig(rawConfig, configPath = process.cwd()) {
     path: normalizeString(controlSource.path, "control.path", issues, {default: `/tmp/rollbridge-${application}.sock`})
   }
   const processes = processesSource.map((processSource, index) => normalizeProcess(processSource, index, proxy, issues))
+  const releaseRetention = normalizeReleaseRetention(objectAt(source.releaseRetention, "releaseRetention", issues, {}), issues)
 
   validateProcessSet(processes, issues)
 
-  return {config: {application, control, processes, proxy}, issues}
+  return {config: {application, control, processes, proxy, releaseRetention}, issues}
 }
 
 /**
@@ -139,16 +142,29 @@ export function validateConfig(rawConfig, configPath = process.cwd()) {
  * @returns {ProxyConfig} Normalized proxy config.
  */
 function normalizeProxy(source, issues) {
+  const host = normalizeString(source.host, "proxy.host", issues, {default: "127.0.0.1"})
+
   return {
     drainTimeoutMs: normalizeNumber(source.drainTimeoutMs, "proxy.drainTimeoutMs", issues, {default: 60000}),
     forceStopTimeoutMs: normalizeNumber(source.forceStopTimeoutMs, "proxy.forceStopTimeoutMs", issues, {default: 10000}),
     healthPath: normalizeString(source.healthPath, "proxy.healthPath", issues, {default: "/ping"}),
     healthTimeoutMs: normalizeNumber(source.healthTimeoutMs, "proxy.healthTimeoutMs", issues, {default: 30000}),
-    host: normalizeString(source.host, "proxy.host", issues, {default: "127.0.0.1"}),
-    port: normalizeNumber(source.port, "proxy.port", issues, {default: 8182})
+    host,
+    port: normalizeNumber(source.port, "proxy.port", issues, {default: 8182}),
+    upstreamHost: normalizeString(source.upstreamHost, "proxy.upstreamHost", issues, {default: defaultUpstreamHost(host)})
   }
 }
 
+/**
+ * @param {string} host - Public proxy bind host.
+ * @returns {string} Default loopback upstream host for wildcard binds.
+ */
+function defaultUpstreamHost(host) {
+  if (host === "0.0.0.0" || host === "::") return "127.0.0.1"
+
+  return host
+}
+
 /**
  * @param {JsonValue} value - Raw process config.
  * @param {number} index - Process index.
@@ -160,7 +176,7 @@ function normalizeProcess(value, index, proxy, issues) {
   if (!isPlainObject(value)) {
     issues.push({fix: `Define processes[${index}] as a mapping with id, policy, and command.`, message: `processes[${index}] must be an object`})
 
-    return {command: "", cwd: undefined, env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", outputLines: 50, policy: "companion", port: undefined, restartDelayMs: 1000}
+    return {command: "", cwd: undefined, env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", outputLines: 50, policy: "companion", port: undefined, restart: defaultRestartConfig(), restartDelayMs: 1000}
   }
 
   const source = value
@@ -175,10 +191,80 @@ function normalizeProcess(value, index, proxy, issues) {
     outputLines: normalizeOutputLines(source.outputLines, `processes[${index}].outputLines`, issues),
     policy: normalizePolicy(source.policy, `processes[${index}].policy`, issues),
     port: normalizePortRange(source.port, `processes[${index}].port`, issues),
+    restart: normalizeRestart(source.restart, `processes[${index}].restart`, issues),
     restartDelayMs: normalizeNumber(source.restartDelayMs, `processes[${index}].restartDelayMs`, issues, {default: 1000})
   }
 }
 
+/**
+ * @returns {RestartConfig} Default restart policy: unlimited restarts with a constant delay.
+ */
+function defaultRestartConfig() {
+  return {backoffFactor: 1, maxDelayMs: 0, maxRestarts: undefined, windowMs: 0}
+}
+
+/**
+ * @param {JsonValue} value - Raw restart policy.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {RestartConfig} Normalized restart policy.
+ */
+function normalizeRestart(value, key, issues) {
+  if (value === undefined || value === null) return defaultRestartConfig()
+
+  if (!isPlainObject(value)) {
+    issues.push({fix: `Set ${key} to a mapping with maxRestarts, windowMs, backoffFactor, and maxDelayMs.`, message: `${key} must be an object`})
+
+    return defaultRestartConfig()
+  }
+
+  const windowMs = normalizeNumber(value.windowMs, `${key}.windowMs`, issues, {default: 0})
+  const maxDelayMs = normalizeNumber(value.maxDelayMs, `${key}.maxDelayMs`, issues, {default: 0})
+
+  return {
+    backoffFactor: normalizeBackoffFactor(value.backoffFactor, `${key}.backoffFactor`, issues),
+    maxDelayMs: nonNegativeOrDefault(maxDelayMs, `${key}.maxDelayMs`, issues, 0, false),
+    maxRestarts: normalizeMaxRestarts(value.maxRestarts, `${key}.maxRestarts`, issues),
+    windowMs: nonNegativeOrDefault(windowMs, `${key}.windowMs`, issues, 0, false)
+  }
+}
+
+/**
+ * @param {JsonValue} value - Raw maximum restart count.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number | undefined} Restart cap, or undefined for unlimited restarts.
+ */
+function normalizeMaxRestarts(value, key, issues) {
+  if (value === undefined || value === null) return undefined
+
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    issues.push({fix: `Set ${key} to a non-negative integer (0 disables automatic restarts), or omit it for unlimited restarts.`, message: `${key} must be a non-negative integer`})
+
+    return undefined
+  }
+
+  return value
+}
+
+/**
+ * @param {JsonValue} value - Raw backoff factor.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number} Backoff multiplier (>= 1; 1 keeps a constant delay).
+ */
+function normalizeBackoffFactor(value, key, issues) {
+  const factor = normalizeNumber(value, key, issues, {default: 1})
+
+  if (factor < 1) {
+    issues.push({fix: `Set ${key} to a number >= 1 (1 keeps a constant delay; 2 doubles the delay each restart).`, message: `${key} must be a number greater than or equal to 1`})
+
+    return 1
+  }
+
+  return factor
+}
+
 /**
  * @param {JsonValue} value - Raw output retention value.
  * @param {string} key - Config key.
@@ -197,6 +283,39 @@ function normalizeOutputLines(value, key, issues) {
   return outputLines
 }
 
+/**
+ * @param {Record<string, JsonValue>} source - Raw release retention config.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {ReleaseRetentionConfig} Normalized release retention policy.
+ */
+function normalizeReleaseRetention(source, issues) {
+  const keep = normalizeNumber(source.keep, "releaseRetention.keep", issues, {default: 10})
+  const maxAgeMs = normalizeNumber(source.maxAgeMs, "releaseRetention.maxAgeMs", issues, {default: 0})
+
+  return {
+    keep: nonNegativeOrDefault(keep, "releaseRetention.keep", issues, 10, true),
+    maxAgeMs: nonNegativeOrDefault(maxAgeMs, "releaseRetention.maxAgeMs", issues, 0, false)
+  }
+}
+
+/**
+ * @param {number} value - Already type-normalized number.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @param {number} fallback - Value to use when invalid.
+ * @param {boolean} requireInteger - Whether the value must be an integer.
+ * @returns {number} The value when non-negative (and integer when required), else the fallback.
+ */
+function nonNegativeOrDefault(value, key, issues, fallback, requireInteger) {
+  if (value < 0 || (requireInteger && !Number.isInteger(value))) {
+    issues.push({fix: `Set ${key} to a non-negative ${requireInteger ? "integer" : "number"}, e.g. ${fallback}.`, message: `${key} must be a non-negative ${requireInteger ? "integer" : "number"}`})
+
+    return fallback
+  }
+
+  return value
+}
+
 /**
  * @param {JsonValue} value - Raw socket permission mode.
  * @param {string} key - Config key.
@@ -291,10 +410,29 @@ function normalizeHealth(value, key, proxy, issues) {
   return {
     intervalMs: normalizeNumber(source.intervalMs, `${key}.intervalMs`, issues, {default: 250}),
     path: normalizeString(source.path, `${key}.path`, issues, {default: proxy.healthPath}),
+    startDelayMs: normalizeStartDelayMs(source.startDelayMs, `${key}.startDelayMs`, issues),
     timeoutMs: normalizeNumber(source.timeoutMs, `${key}.timeoutMs`, issues, {default: proxy.healthTimeoutMs})
   }
 }
 
+/**
+ * @param {JsonValue} value - Raw startup delay.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number} Milliseconds to wait before the first health probe (default 0).
+ */
+function normalizeStartDelayMs(value, key, issues) {
+  const startDelayMs = normalizeNumber(value, key, issues, {default: 0})
+
+  if (startDelayMs < 0) {
+    issues.push({fix: `Set ${key} to a non-negative number of milliseconds, e.g. 0 or 2000.`, message: `${key} must be a non-negative number`})
+
+    return 0
+  }
+
+  return startDelayMs
+}
+
 /**
  * @param {JsonValue} value - Raw env config.
  * @param {string} key - Config key.

package/src/daemon.js

@@ -10,7 +10,7 @@ import ReleaseGroup from "./release-group.js"
  * @typedef {import("./json.js").JsonValue} JsonValue
  * @typedef {{releaseId?: string, releasePath: string, revision?: string}} DeployArgs
  * @typedef {{id: string, process: import("./managed-process.js").ManagedProcessStatus}} ProcessStatus
- * @typedef {{activeReleaseId: string | null, application: string, control: import("./config.js").ControlConfig, proxy: {host: string, port: number | undefined}, releases: import("./release-group.js").ReleaseStatus[], services: ProcessStatus[], singletons: ProcessStatus[]}} DaemonStatus
+ * @typedef {{activeReleaseId: string | null, application: string, control: import("./config.js").ControlConfig, proxy: {host: string, port: number | undefined, upstreamHost: string}, releases: import("./release-group.js").ReleaseStatus[], services: ProcessStatus[], singletons: ProcessStatus[]}} DaemonStatus
  */
 
 export default class RollbridgeDaemon {
@@ -233,6 +233,13 @@ export default class RollbridgeDaemon {
       return this.status()
     }
 
+    if (commandName === "restart") {
+      return await this.restartProcesses({
+        policy: stringOrUndefined(data.policy),
+        processId: stringOrUndefined(data.processId)
+      })
+    }
+
     if (commandName === "shutdown") {
       setImmediate(() => {
         this.shutdown().catch((error) => {
@@ -286,9 +293,7 @@ export default class RollbridgeDaemon {
     await this.replaceSingletons(release)
 
     if (previousRelease) {
-      previousRelease.drainAndStop(this.config.proxy.drainTimeoutMs).catch((error) => {
-        this.logger("release drain failed", {error: error instanceof Error ? error.message : String(error), releaseId: previousRelease.releaseId})
-      })
+      void this.drainAndPrune(previousRelease)
     }
 
     return {
@@ -367,6 +372,7 @@ export default class RollbridgeDaemon {
         env: nextDefinition.env,
         logger: nextDefinition.logger,
         outputLines: nextDefinition.outputLines,
+        restart: nextDefinition.restart,
         restartDelayMs: nextDefinition.restartDelayMs,
         shouldRestart: nextDefinition.shouldRestart,
         stopTimeoutMs: nextDefinition.stopTimeoutMs
@@ -396,6 +402,75 @@ export default class RollbridgeDaemon {
     }
   }
 
+  /**
+   * Restarts non-proxied processes selected by id or policy, or all of them: running
+   * processes are bounced (stop then start) and crashed or stopped ones are revived,
+   * matching the conventional meaning of "restart".
+   *
+   * The proxied process is never restarted in place (that would drop traffic); use a
+   * deploy for a zero-downtime replacement.
+   * @param {{policy?: string, processId?: string}} selector - Restart selector; restarts all non-proxied processes when both are omitted.
+   * @returns {Promise<Record<string, JsonValue>>} The ids that were restarted.
+   */
+  async restartProcesses({policy, processId} = {}) {
+    if (policy === "proxied" || (processId !== undefined && this.isProxiedId(processId))) {
+      throw new Error('The proxied process cannot be restarted in place; use "rollbridge deploy" for a zero-downtime replacement.')
+    }
+
+    const targets = this.collectRestartTargets({policy, processId})
+
+    if (processId !== undefined && targets.length === 0) {
+      throw new Error(`No managed process with id "${processId}" to restart.`)
+    }
+
+    for (const target of targets) {
+      this.logger("process restart requested", {processId: target.id})
+      await target.process.stop()
+      await target.process.start()
+    }
+
+    return {restarted: targets.map((target) => target.id)}
+  }
+
+  /**
+   * @param {{policy?: string, processId?: string}} selector - Restart selector.
+   * @returns {{id: string, process: import("./managed-process.js").default}[]} Running non-proxied processes matching the selector.
+   */
+  collectRestartTargets({policy, processId}) {
+    const targets = /** @type {{id: string, process: import("./managed-process.js").default}[]} */ ([])
+
+    for (const processConfig of this.config.processes) {
+      if (processConfig.policy === "proxied") continue
+      if (processId !== undefined && processConfig.id !== processId) continue
+      if (policy !== undefined && processConfig.policy !== policy) continue
+
+      const process = this.findProcessInstance(processConfig)
+
+      if (process) targets.push({id: processConfig.id, process})
+    }
+
+    return targets
+  }
+
+  /**
+   * @param {import("./config.js").ProcessConfig} processConfig - Process definition.
+   * @returns {import("./managed-process.js").default | undefined} The running instance, if any.
+   */
+  findProcessInstance(processConfig) {
+    if (processConfig.policy === "service") return this.services.get(processConfig.id)
+    if (processConfig.policy === "singleton") return this.singletons.get(processConfig.id)
+
+    return this.activeRelease ? this.activeRelease.getProcess(processConfig.id) : undefined
+  }
+
+  /**
+   * @param {string} id - Process id.
+   * @returns {boolean} True when the id belongs to the proxied process.
+   */
+  isProxiedId(id) {
+    return this.config.processes.some((processConfig) => processConfig.policy === "proxied" && processConfig.id === id)
+  }
+
   /**
    * @param {string | undefined} releaseId - Release id, or active release when omitted.
    * @returns {Promise<void>} Resolves when stopped.
@@ -407,6 +482,31 @@ export default class RollbridgeDaemon {
     if (release === this.activeRelease) this.activeRelease = undefined
 
     await release.stop()
+    this.pruneStoppedReleases()
+  }
+
+  /**
+   * Drains and stops a retired release in the background, then prunes stopped releases.
+   * @param {ReleaseGroup} release - Release to drain and stop.
+   * @returns {Promise<void>} Resolves once drained, stopped, and pruned.
+   */
+  async drainAndPrune(release) {
+    try {
+      await release.drainAndStop(this.config.proxy.drainTimeoutMs)
+    } catch (error) {
+      this.logger("release drain failed", {error: error instanceof Error ? error.message : String(error), releaseId: release.releaseId})
+    } finally {
+      this.pruneStoppedReleases()
+    }
+  }
+
+  /** @returns {void} Removes stopped releases beyond the retention policy. */
+  pruneStoppedReleases() {
+    const statuses = [...this.releases.values()].map((release) => release.status())
+
+    for (const releaseId of releasesToPrune(statuses, this.config.releaseRetention, Date.now())) {
+      this.releases.delete(releaseId)
+    }
   }
 
   /** @returns {Promise<void>} Stops proxy, control socket, and child processes. */
@@ -446,7 +546,8 @@ export default class RollbridgeDaemon {
       control: {...this.config.control},
       proxy: {
         host: this.config.proxy.host,
-        port: this.proxyPort ?? this.config.proxy.port
+        port: this.proxyPort ?? this.config.proxy.port,
+        upstreamHost: this.config.proxy.upstreamHost
       },
       releases: [...this.releases.values()].map((release) => release.status()),
       services: [...this.services.entries()].map(([id, processInstance]) => ({
@@ -485,6 +586,37 @@ function requiredString(value, key) {
   return value
 }
 
+/**
+ * @typedef {{releaseId: string, state: string, stoppedAt: string | undefined}} PrunableRelease
+ */
+
+/**
+ * Selects stopped releases to prune by the retention policy, keeping the most recent.
+ * @param {PrunableRelease[]} releases - Status of all tracked releases, in deploy order (oldest first).
+ * @param {import("./config.js").ReleaseRetentionConfig} policy - Retention policy.
+ * @param {number} now - Current epoch milliseconds.
+ * @returns {string[]} Release ids to remove.
+ */
+export function releasesToPrune(releases, policy, now) {
+  const stopped = releases
+    .filter((release) => release.state === "stopped")
+    .map((release, index) => ({deployOrder: index, releaseId: release.releaseId, stoppedAtMs: release.stoppedAt ? Date.parse(release.stoppedAt) : 0}))
+    // Most recent first; ties (same stoppedAt millisecond) prefer the later-deployed release.
+    .sort((first, second) => second.stoppedAtMs - first.stoppedAtMs || second.deployOrder - first.deployOrder)
+
+  /** @type {string[]} */
+  const remove = []
+
+  stopped.forEach((release, index) => {
+    const beyondKeep = index >= policy.keep
+    const tooOld = policy.maxAgeMs > 0 && release.stoppedAtMs > 0 && now - release.stoppedAtMs > policy.maxAgeMs
+
+    if (beyondKeep || tooOld) remove.push(release.releaseId)
+  })
+
+  return remove
+}
+
 /**
  * @typedef {{alive: boolean, application?: string, activeReleaseId?: string | null}} ControlSocketInspection
  */
@@ -512,7 +644,7 @@ function controlSocketBusyMessage(socketPath, inspection) {
  * @param {number} [timeoutMs] - How long to wait for a status response before treating the socket as busy.
  * @returns {Promise<ControlSocketInspection>} Whether the socket is live and, when it is Rollbridge, its identity.
  */
-async function inspectControlSocket(socketPath, timeoutMs = 1000) {
+export async function inspectControlSocket(socketPath, timeoutMs = 1000) {
   return await new Promise((resolve, reject) => {
     const socket = net.createConnection(socketPath)
     let buffer = ""