rollbridge 0.1.2 → 0.1.5

package/src/doctor.js

@@ -0,0 +1,114 @@
+// @ts-check
+
+import {constants as fsConstants} from "node:fs"
+import fs from "node:fs/promises"
+import net from "node:net"
+import path from "node:path"
+import {inspectControlSocket} from "./daemon.js"
+
+/**
+ * @typedef {{detail: string, name: string, ok: boolean}} DoctorCheck
+ */
+
+/**
+ * Runs pre-flight environment checks for a validated config: control socket
+ * reachability, control-socket directory writability, and proxy port availability.
+ * @param {import("./config.js").RollbridgeConfig} config - Normalized config.
+ * @returns {Promise<DoctorCheck[]>} One check per probed aspect.
+ */
+export async function runEnvironmentChecks(config) {
+  /** @type {DoctorCheck[]} */
+  const checks = []
+  const socketInspection = await inspectControlSocketSafely(config.control.path)
+
+  checks.push(controlSocketCheck(config, socketInspection))
+  checks.push(await controlSocketDirectoryCheck(config))
+  checks.push(await proxyPortCheck(config))
+
+  return checks
+}
+
+/**
+ * @param {string} socketPath - Control socket path.
+ * @returns {Promise<{alive: boolean, application?: string} | {error: string}>} Probe result, or the probe error.
+ */
+async function inspectControlSocketSafely(socketPath) {
+  try {
+    return await inspectControlSocket(socketPath)
+  } catch (error) {
+    return {error: error instanceof Error ? error.message : String(error)}
+  }
+}
+
+/**
+ * @param {import("./config.js").RollbridgeConfig} config - Normalized config.
+ * @param {{alive: boolean, application?: string} | {error: string}} inspection - Control socket probe result.
+ * @returns {DoctorCheck} Control socket reachability check.
+ */
+function controlSocketCheck(config, inspection) {
+  const socketPath = config.control.path
+
+  if ("error" in inspection) {
+    return {detail: `could not probe ${socketPath}: ${inspection.error}`, name: "control socket", ok: false}
+  }
+
+  if (!inspection.alive) {
+    return {detail: `no daemon running; ${socketPath} is free to bind`, name: "control socket", ok: true}
+  }
+
+  if (inspection.application === undefined) {
+    return {detail: `another process is already listening on ${socketPath}; the daemon would fail to bind it`, name: "control socket", ok: false}
+  }
+
+  return {detail: `a Rollbridge daemon for "${inspection.application}" is already running on ${socketPath}; stop it before starting another`, name: "control socket", ok: false}
+}
+
+/**
+ * @param {import("./config.js").RollbridgeConfig} config - Normalized config.
+ * @returns {Promise<DoctorCheck>} Whether the control socket's directory is writable.
+ */
+async function controlSocketDirectoryCheck(config) {
+  const directory = path.dirname(path.resolve(config.control.path))
+
+  try {
+    // Creating a Unix socket needs both write and search (execute) permission on the directory.
+    await fs.access(directory, fsConstants.W_OK | fsConstants.X_OK)
+
+    return {detail: `${directory} is writable`, name: "control socket directory", ok: true}
+  } catch {
+    return {detail: `${directory} is missing or not writable`, name: "control socket directory", ok: false}
+  }
+}
+
+/**
+ * @param {import("./config.js").RollbridgeConfig} config - Normalized config.
+ * @returns {Promise<DoctorCheck>} Whether the proxy port can be bound.
+ */
+async function proxyPortCheck(config) {
+  const address = `${config.proxy.host}:${config.proxy.port}`
+  const bind = await canBindPort(config.proxy.host, config.proxy.port)
+
+  if (bind.ok) {
+    return {detail: `${address} is available`, name: "proxy port", ok: true}
+  }
+
+  return {detail: `${address} is unavailable (${bind.code})`, name: "proxy port", ok: false}
+}
+
+/**
+ * @param {string} host - Bind host.
+ * @param {number} port - Candidate port.
+ * @returns {Promise<{ok: true} | {code: string, ok: false}>} Whether the port can be bound.
+ */
+async function canBindPort(host, port) {
+  return await new Promise((resolve) => {
+    const server = net.createServer()
+
+    server.once("error", (error) => {
+      const code = error && typeof error === "object" && "code" in error ? String(error.code) : "EUNKNOWN"
+
+      resolve({code, ok: false})
+    })
+    server.listen(port, host, () => server.close(() => resolve({ok: true})))
+  })
+}

package/src/health.js

@@ -9,6 +9,10 @@
  * @returns {Promise<void>} Resolves when healthy.
  */
 export async function waitForHealth({health, host, port}) {
+  if (health.startDelayMs > 0) {
+    await new Promise((resolve) => setTimeout(resolve, health.startDelayMs))
+  }
+
   const deadline = Date.now() + health.timeoutMs
   const url = `http://${host}:${port}${health.path}`
   let lastError = "no attempts"

package/src/managed-process.js

@@ -8,8 +8,8 @@ import {spawn} from "node:child_process"
  * @typedef {"starting" | "running" | "stopping" | "stopped" | "failed"} ManagedProcessState
  * @typedef {import("node:child_process").ChildProcess["signalCode"]} ProcessExitSignal
  * @typedef {{at: string, line: string, stream: "stdout" | "stderr"}} ManagedProcessLog
- * @typedef {{command: string, cwd: string | undefined, env: Record<string, string | undefined>, logger: (message: string, data?: Record<string, import("./json.js").JsonValue>) => void, outputLines: number, restartDelayMs: number, shouldRestart: () => boolean, stopTimeoutMs: number}} ManagedProcessDefinition
- * @typedef {{command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, id: string, logs: ManagedProcessLog[], pid: number | undefined, state: ManagedProcessState}} ManagedProcessStatus
+ * @typedef {{command: string, cwd: string | undefined, env: Record<string, string | undefined>, logger: (message: string, data?: Record<string, import("./json.js").JsonValue>) => void, outputLines: number, restart: import("./config.js").RestartConfig, restartDelayMs: number, shouldRestart: () => boolean, stopTimeoutMs: number}} ManagedProcessDefinition
+ * @typedef {{command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, id: string, logs: ManagedProcessLog[], pid: number | undefined, restarts: number, startedAt: string | undefined, state: ManagedProcessState, uptimeMs: number | undefined}} ManagedProcessStatus
  */
 
 export default class ManagedProcess extends EventEmitter {
@@ -21,11 +21,12 @@ export default class ManagedProcess extends EventEmitter {
    * @param {string} args.id - Process id.
    * @param {(message: string, data?: Record<string, JsonValue>) => void} args.logger - Logger callback.
    * @param {number} args.outputLines - Recent stdout/stderr lines to retain and report.
+   * @param {import("./config.js").RestartConfig} [args.restart] - Restart policy (defaults to unlimited restarts with a constant delay).
    * @param {number} args.restartDelayMs - Restart delay.
    * @param {() => boolean} args.shouldRestart - Restart policy callback.
    * @param {number} args.stopTimeoutMs - Stop timeout.
    */
-  constructor({command, cwd, env, id, logger, outputLines, restartDelayMs, shouldRestart, stopTimeoutMs}) {
+  constructor({command, cwd, env, id, logger, outputLines, restart = {backoffFactor: 1, maxDelayMs: 0, maxRestarts: undefined, windowMs: 0}, restartDelayMs, shouldRestart, stopTimeoutMs}) {
     super()
 
     this.command = command
@@ -34,11 +35,15 @@ export default class ManagedProcess extends EventEmitter {
     this.id = id
     this.logger = logger
     this.outputLines = outputLines
+    this.restart = restart
     this.restartDelayMs = restartDelayMs
     this.shouldRestart = shouldRestart
     this.stopTimeoutMs = stopTimeoutMs
     this.state = /** @type {ManagedProcessState} */ ("stopped")
     this.logs = /** @type {ManagedProcessLog[]} */ ([])
+    this.restarts = 0
+    this.recentRestarts = /** @type {number[]} */ ([])
+    this.startedAtMs = /** @type {number | undefined} */ (undefined)
     this.intentionalStop = false
     this.restartTimer = undefined
     this.child = undefined
@@ -77,6 +82,7 @@ export default class ManagedProcess extends EventEmitter {
 
       child.once("spawn", () => {
         this.state = "running"
+        this.startedAtMs = Date.now()
         this.logger("process started", {command: this.command, id: this.id, pid: child.pid || null})
         this.emit("started")
         resolve(undefined)
@@ -103,6 +109,7 @@ export default class ManagedProcess extends EventEmitter {
     this.env = definition.env
     this.logger = definition.logger
     this.outputLines = definition.outputLines
+    this.restart = definition.restart
     this.restartDelayMs = definition.restartDelayMs
     this.shouldRestart = definition.shouldRestart
     this.stopTimeoutMs = definition.stopTimeoutMs
@@ -143,13 +150,66 @@ export default class ManagedProcess extends EventEmitter {
     this.emit("exit", {code, signal})
 
     if (!wasIntentional && this.shouldRestart()) {
-      this.restartTimer = setTimeout(() => {
-        this.restartTimer = undefined
-        this.start().catch((error) => {
-          this.logger("process restart failed", {error: error instanceof Error ? error.message : String(error), id: this.id})
-        })
-      }, this.restartDelayMs)
+      this.scheduleRestart()
+    }
+  }
+
+  /**
+   * Schedules an automatic restart per the restart policy, or gives up once the policy's limit is reached.
+   * @returns {void}
+   */
+  scheduleRestart() {
+    const {backoffFactor, maxRestarts, windowMs} = this.restart
+
+    // Fast path: unlimited restarts with a constant delay needs no per-restart bookkeeping.
+    // The delay is constant across attempts here (backoffFactor is 1), so restartDelayFor(0)
+    // gives the right value while still applying any maxDelayMs cap.
+    if (maxRestarts === undefined && backoffFactor === 1) {
+      this.queueRestart(this.restartDelayFor(0))
+
+      return
+    }
+
+    const now = Date.now()
+
+    if (windowMs > 0) {
+      this.recentRestarts = this.recentRestarts.filter((time) => time > now - windowMs)
     }
+
+    if (maxRestarts !== undefined && this.recentRestarts.length >= maxRestarts) {
+      this.logger("restart limit reached", {id: this.id, maxRestarts, windowMs})
+
+      return
+    }
+
+    const delay = this.restartDelayFor(this.recentRestarts.length)
+
+    this.recentRestarts.push(now)
+    this.queueRestart(delay)
+  }
+
+  /**
+   * @param {number} attempt - Number of restarts already counted in the current window.
+   * @returns {number} Backed-off restart delay in milliseconds, capped by maxDelayMs when set.
+   */
+  restartDelayFor(attempt) {
+    const backedOff = this.restartDelayMs * this.restart.backoffFactor ** attempt
+
+    return this.restart.maxDelayMs > 0 ? Math.min(backedOff, this.restart.maxDelayMs) : backedOff
+  }
+
+  /**
+   * @param {number} delayMs - Delay before the restart attempt.
+   * @returns {void}
+   */
+  queueRestart(delayMs) {
+    this.restartTimer = setTimeout(() => {
+      this.restartTimer = undefined
+      this.restarts += 1
+      this.start().catch((error) => {
+        this.logger("process restart failed", {error: error instanceof Error ? error.message : String(error), id: this.id})
+      })
+    }, delayMs)
   }
 
   /**
@@ -229,7 +289,10 @@ export default class ManagedProcess extends EventEmitter {
       id: this.id,
       logs: this.logs.slice(-this.outputLines),
       pid: this.pid,
-      state: this.state
+      restarts: this.restarts,
+      startedAt: this.startedAtMs === undefined ? undefined : new Date(this.startedAtMs).toISOString(),
+      state: this.state,
+      uptimeMs: this.state === "running" && this.startedAtMs !== undefined ? Date.now() - this.startedAtMs : undefined
     }
   }
 }

package/src/release-group.js

@@ -67,18 +67,54 @@ export default class ReleaseGroup extends EventEmitter {
         if (processConfig.policy === "proxied" && processConfig.port && processConfig.health) {
           await waitForHealth({
             health: processConfig.health,
-            host: this.config.proxy.host,
+            host: this.config.proxy.upstreamHost,
             port: this.ports[processConfig.id]
           })
         }
       }
     } catch (error) {
       this.state = "failed"
+      this.logStartupFailure(error instanceof Error ? error : String(error))
       await this.stop()
       throw error
     }
   }
 
+  /**
+   * @param {string} id - Process id.
+   * @returns {ManagedProcess | undefined} This release's managed process with the given id, if present.
+   */
+  getProcess(id) {
+    return this.processes.get(id)
+  }
+
+  /**
+   * Logs process diagnostics before failed startup cleanup stops and removes the release processes.
+   * @param {Error | string} error - Startup failure.
+   * @returns {void}
+   */
+  logStartupFailure(error) {
+    this.logger("release startup failed", {
+      error: error instanceof Error ? error.message : error,
+      releaseId: this.releaseId
+    })
+
+    for (const processInstance of this.processes.values()) {
+      const status = processInstance.status()
+
+      this.logger("release startup process status", {
+        command: status.command,
+        exitCode: status.exitCode ?? null,
+        exitSignal: status.exitSignal ?? null,
+        logs: status.logs,
+        pid: status.pid ?? null,
+        processId: status.id,
+        releaseId: this.releaseId,
+        state: status.state
+      })
+    }
+  }
+
   /**
    * Starts companions before the proxied process so release-local dependencies are available before health checks.
    * @returns {import("./config.js").ProcessConfig[]} Ordered process configs.
@@ -112,7 +148,7 @@ export default class ReleaseGroup extends EventEmitter {
       }
 
       this.ports[processConfig.id] = await findAvailablePort({
-        host: this.config.proxy.host,
+        host: this.config.proxy.upstreamHost,
         range: processConfig.port,
         usedPorts
       })
@@ -142,6 +178,7 @@ export default class ReleaseGroup extends EventEmitter {
       id: processConfig.id,
       logger: (message, data = {}) => this.logger(message, {processId: processConfig.id, releaseId: this.releaseId, ...data}),
       outputLines: processConfig.outputLines,
+      restart: processConfig.restart,
       restartDelayMs: processConfig.restartDelayMs,
       shouldRestart: options.shouldRestart || (() => this.state === "active" || this.state === "starting"),
       stopTimeoutMs: processConfig.gracefulStopMs
@@ -186,7 +223,8 @@ export default class ReleaseGroup extends EventEmitter {
       processId: processConfig.id,
       proxy: {
         host: this.config.proxy.host,
-        port: this.config.proxy.port
+        port: this.config.proxy.port,
+        upstreamHost: this.config.proxy.upstreamHost
       },
       releaseId: this.releaseId,
       releasePath: this.releasePath,
@@ -211,7 +249,7 @@ export default class ReleaseGroup extends EventEmitter {
 
     return {
       process: processInstance,
-      target: `http://${this.config.proxy.host}:${port}`
+      target: `http://${this.config.proxy.upstreamHost}:${port}`
     }
   }
 

package/test/config-validation.test.js

@@ -55,6 +55,21 @@ test("validateConfig returns a normalized config and no issues for a valid confi
   assert.equal(config.proxy.port, 8182)
 })
 
+test("validateConfig defaults wildcard proxy upstreams to loopback", () => {
+  const {config, issues} = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", health: {path: "/ping"}, id: "web", policy: "proxied", port: {from: 18000, to: 18099}}
+    ],
+    proxy: {host: "0.0.0.0", port: 8182}
+  })
+
+  assert.deepEqual(issues, [])
+  assert.equal(config.proxy.host, "0.0.0.0")
+  assert.equal(config.proxy.upstreamHost, "127.0.0.1")
+})
+
 test("validateConfig defaults outputLines and accepts a positive override", () => {
   const {config, issues} = validateConfig({
     application: "demo",
@@ -71,6 +86,46 @@ test("validateConfig defaults outputLines and accepts a positive override", () =
   assert.equal(config.processes[1].outputLines, 5)
 })
 
+test("validateConfig defaults the restart policy, accepts overrides, and rejects bad values", () => {
+  /**
+   * @param {import("../src/json.js").JsonValue} restart - Restart policy under test, or undefined to omit it.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateRestart = (restart) => validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}, restart}],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  const defaulted = validateRestart(undefined)
+
+  assert.deepEqual(defaulted.issues, [])
+  assert.deepEqual(defaulted.config.processes[0].restart, {backoffFactor: 1, maxDelayMs: 0, maxRestarts: undefined, windowMs: 0})
+
+  const custom = validateRestart({backoffFactor: 2, maxDelayMs: 30000, maxRestarts: 5, windowMs: 60000})
+
+  assert.deepEqual(custom.issues, [])
+  assert.deepEqual(custom.config.processes[0].restart, {backoffFactor: 2, maxDelayMs: 30000, maxRestarts: 5, windowMs: 60000})
+
+  // maxRestarts: 0 disables automatic restarts.
+  const disabled = validateRestart({maxRestarts: 0})
+
+  assert.deepEqual(disabled.issues, [])
+  assert.equal(disabled.config.processes[0].restart.maxRestarts, 0)
+
+  const invalid = validateRestart({backoffFactor: 0.5, maxDelayMs: -1, maxRestarts: -2, windowMs: -3})
+  const messages = invalid.issues.map((issue) => issue.message)
+
+  assert.ok(messages.includes("processes[0].restart.backoffFactor must be a number greater than or equal to 1"), JSON.stringify(messages))
+  assert.ok(messages.includes("processes[0].restart.maxRestarts must be a non-negative integer"), JSON.stringify(messages))
+  assert.ok(messages.includes("processes[0].restart.maxDelayMs must be a non-negative number"), JSON.stringify(messages))
+  assert.ok(messages.includes("processes[0].restart.windowMs must be a non-negative number"), JSON.stringify(messages))
+
+  // A fractional maxRestarts is rejected (it must be a whole number of restarts).
+  assert.ok(validateRestart({maxRestarts: 1.5}).issues.some((issue) => issue.message === "processes[0].restart.maxRestarts must be a non-negative integer"))
+})
+
 test("validateConfig rejects a non-positive-integer outputLines with a fix", () => {
   const {issues} = validateConfig({
     application: "demo",
@@ -117,6 +172,62 @@ test("validateConfig parses control.mode, defaults it to unset, and rejects inva
   assert.ok(invalid.issues.some((issue) => issue.message === "control.mode must be an octal file mode between 0 and 0o777"))
 })
 
+test("validateConfig defaults health.startDelayMs to 0, accepts an override, and rejects negatives", () => {
+  /**
+   * @param {import("../src/json.js").JsonValue} health - Health config under test, or undefined to omit it.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateHealth = (health) => validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [{command: "run web", health, id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  const defaulted = validateHealth({path: "/ping"})
+
+  assert.deepEqual(defaulted.issues, [])
+  assert.equal(defaulted.config.processes[0].health?.startDelayMs, 0)
+
+  const custom = validateHealth({path: "/ping", startDelayMs: 2000})
+
+  assert.deepEqual(custom.issues, [])
+  assert.equal(custom.config.processes[0].health?.startDelayMs, 2000)
+
+  const negative = validateHealth({path: "/ping", startDelayMs: -1})
+
+  assert.ok(negative.issues.some((issue) => issue.message === "processes[0].health.startDelayMs must be a non-negative number"))
+})
+
+test("validateConfig defaults releaseRetention, accepts overrides, and rejects bad values", () => {
+  /**
+   * @param {import("../src/json.js").JsonValue} releaseRetention - Retention config under test, or undefined.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateRetention = (releaseRetention) => validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: 8182},
+    releaseRetention
+  })
+
+  const defaulted = validateRetention(undefined)
+
+  assert.deepEqual(defaulted.issues, [])
+  assert.deepEqual(defaulted.config.releaseRetention, {keep: 10, maxAgeMs: 0})
+
+  const custom = validateRetention({keep: 3, maxAgeMs: 60000})
+
+  assert.deepEqual(custom.issues, [])
+  assert.deepEqual(custom.config.releaseRetention, {keep: 3, maxAgeMs: 60000})
+
+  const invalid = validateRetention({keep: -1, maxAgeMs: -5})
+
+  assert.ok(invalid.issues.some((issue) => issue.message === "releaseRetention.keep must be a non-negative integer"))
+  assert.ok(invalid.issues.some((issue) => issue.message === "releaseRetention.maxAgeMs must be a non-negative number"))
+})
+
 test("normalizeConfig throws an aggregated error listing every issue", () => {
   assert.throws(
     () => normalizeConfig({
@@ -178,6 +289,40 @@ test("validate CLI command accepts a valid config without setting a failure exit
   }
 })
 
+test("validate --json emits a machine-readable result", async () => {
+  const validPath = await writeConfig({
+    application: "demo",
+    control: {path: "/tmp/rollbridge-json-valid.sock"},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+  const invalidPath = await writeConfig({
+    application: "demo",
+    processes: [{command: "run web", id: "web", policy: "proxied"}],
+    proxy: {port: 8182}
+  })
+
+  try {
+    const valid = JSON.parse((await captureCli(["node", "rollbridge", "validate", "--json", "-c", validPath])).output)
+
+    assert.equal(valid.valid, true)
+    assert.deepEqual(valid.issues, [])
+    assert.equal(valid.config.processes, 1)
+    assert.notEqual(process.exitCode, 1)
+
+    const invalid = JSON.parse((await captureCli(["node", "rollbridge", "validate", "--json", "-c", invalidPath])).output)
+
+    assert.equal(invalid.valid, false)
+    assert.equal(invalid.config, null)
+    assert.ok(invalid.issues.some((/** @type {{message: string}} */ issue) => /must define a port range/.test(issue.message)))
+    assert.equal(process.exitCode, 1)
+  } finally {
+    process.exitCode = 0
+    await fs.rm(path.dirname(validPath), {force: true, recursive: true})
+    await fs.rm(path.dirname(invalidPath), {force: true, recursive: true})
+  }
+})
+
 /**
  * @param {Record<string, import("../src/json.js").JsonValue>} config - Raw config object.
  * @returns {Promise<string>} Path to the written config module.