rollbridge 0.1.4 → 0.1.6

package/src/release-group.js

@@ -3,7 +3,7 @@
 import {EventEmitter} from "node:events"
 import ManagedProcess from "./managed-process.js"
 import {findAvailablePort} from "./port-allocator.js"
-import {renderObject, renderTemplate} from "./template.js"
+import {processTemplateContext, renderObject, renderTemplate} from "./template.js"
 import {waitForHealth} from "./health.js"
 
 /**
@@ -11,7 +11,7 @@ import {waitForHealth} from "./health.js"
  * @typedef {"starting" | "active" | "draining" | "stopped" | "failed"} ReleaseState
  * @typedef {{http: number, websocket: number}} ReleaseConnections
  * @typedef {{activatedAt: string | undefined, connectionCount: number, connections: ReleaseConnections, drainStartedAt: string | undefined, ports: Record<string, number>, processes: import("./managed-process.js").ManagedProcessStatus[], releaseId: string, releasePath: string, revision: string, state: ReleaseState, stoppedAt: string | undefined}} ReleaseStatus
- * @typedef {{shouldRestart?: () => boolean}} BuildProcessOptions
+ * @typedef {{count?: number, index?: number, instanceId?: string, shouldRestart?: () => boolean}} BuildProcessOptions
  */
 
 /**
@@ -22,6 +22,15 @@ function envId(id) {
   return id.replace(/[^a-zA-Z0-9]+/g, "_").toUpperCase()
 }
 
+/**
+ * @param {import("./config.js").ProcessConfig} processConfig - Process config.
+ * @param {number} index - Zero-based replica index.
+ * @returns {string} The instance id: the bare process id for a single replica, or `id#index`.
+ */
+function replicaInstanceId(processConfig, index) {
+  return processConfig.replicas > 1 ? `${processConfig.id}#${index}` : processConfig.id
+}
+
 export default class ReleaseGroup extends EventEmitter {
   /**
    * @param {object} args - Options.
@@ -44,6 +53,7 @@ export default class ReleaseGroup extends EventEmitter {
     this.connectionCount = 0
     this.connections = /** @type {ReleaseConnections} */ ({http: 0, websocket: 0})
     this.processes = /** @type {Map<string, ManagedProcess>} */ (new Map())
+    this.nonBlockingDrainIds = /** @type {Set<string>} */ (new Set())
     this.ports = /** @type {Record<string, number>} */ ({})
     this.servicePorts = servicePorts
     this.portsAllocated = false
@@ -60,9 +70,14 @@ export default class ReleaseGroup extends EventEmitter {
       await this.allocatePorts()
 
       for (const processConfig of this.releaseProcessStartOrder()) {
-        const processInstance = this.buildProcess(processConfig)
-        this.processes.set(processConfig.id, processInstance)
-        await processInstance.start()
+        for (let index = 0; index < processConfig.replicas; index += 1) {
+          const instanceId = replicaInstanceId(processConfig, index)
+          const processInstance = this.buildProcess(processConfig, {count: processConfig.replicas, index, instanceId})
+
+          this.processes.set(instanceId, processInstance)
+          if (processConfig.nonBlockingDrain) this.nonBlockingDrainIds.add(instanceId)
+          await processInstance.start("deploy")
+        }
 
         if (processConfig.policy === "proxied" && processConfig.port && processConfig.health) {
           await waitForHealth({
@@ -80,6 +95,33 @@ export default class ReleaseGroup extends EventEmitter {
     }
   }
 
+  /**
+   * @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)
+  }
+
+  /**
+   * Returns the running instances of a process config — one for a single process, or every
+   * replica (`id#0`, `id#1`, …) for a replicated one.
+   * @param {string} configId - Base process id from the config.
+   * @returns {{id: string, process: ManagedProcess}[]} Matching instances, ordered by instance id.
+   */
+  getProcesses(configId) {
+    /** @type {{id: string, process: ManagedProcess}[]} */
+    const instances = []
+
+    for (const [instanceId, processInstance] of this.processes) {
+      if (instanceId === configId || instanceId.startsWith(`${configId}#`)) {
+        instances.push({id: instanceId, process: processInstance})
+      }
+    }
+
+    return instances
+  }
+
   /**
    * Logs process diagnostics before failed startup cleanup stops and removes the release processes.
    * @param {Error | string} error - Startup failure.
@@ -156,10 +198,13 @@ export default class ReleaseGroup extends EventEmitter {
    * @returns {ManagedProcess} Managed process.
    */
   buildProcess(processConfig, options = {}) {
-    const context = this.contextForProcess(processConfig)
+    const index = options.index ?? 0
+    const count = options.count ?? 1
+    const instanceId = options.instanceId ?? processConfig.id
+    const context = this.contextForProcess(processConfig, {count, index})
     const renderedEnv = /** @type {Record<string, string>} */ (renderObject(processConfig.env, context))
     const processEnv = {
-      ...this.baseEnvironment(processConfig),
+      ...this.baseEnvironment(processConfig, {count, index}),
       ...renderedEnv
     }
 
@@ -167,26 +212,33 @@ export default class ReleaseGroup extends EventEmitter {
       command: renderTemplate(processConfig.command, context),
       cwd: processConfig.cwd ? renderTemplate(processConfig.cwd, context) : this.releasePath,
       env: processEnv,
-      id: processConfig.id,
-      logger: (message, data = {}) => this.logger(message, {processId: processConfig.id, releaseId: this.releaseId, ...data}),
+      id: instanceId,
+      lifecycle: processConfig.lifecycle,
+      logger: (message, data = {}) => this.logger(message, {processId: instanceId, releaseId: this.releaseId, ...data}),
+      memory: processConfig.memory,
       outputLines: processConfig.outputLines,
+      restart: processConfig.restart,
       restartDelayMs: processConfig.restartDelayMs,
       shouldRestart: options.shouldRestart || (() => this.state === "active" || this.state === "starting"),
+      stopSignal: processConfig.stopSignal,
       stopTimeoutMs: processConfig.gracefulStopMs
     })
   }
 
   /**
    * @param {import("./config.js").ProcessConfig} processConfig - Process config.
+   * @param {{count: number, index: number}} replica - Replica index and total count.
    * @returns {Record<string, string>} Base environment.
    */
-  baseEnvironment(processConfig) {
+  baseEnvironment(processConfig, replica = {count: 1, index: 0}) {
     /** @type {Record<string, string>} */
     const env = {
       ROLLBRIDGE_APPLICATION: this.config.application,
       ROLLBRIDGE_PROCESS_ID: processConfig.id,
       ROLLBRIDGE_RELEASE_ID: this.releaseId,
       ROLLBRIDGE_RELEASE_PATH: this.releasePath,
+      ROLLBRIDGE_REPLICA_COUNT: String(replica.count),
+      ROLLBRIDGE_REPLICA_INDEX: String(replica.index),
       ROLLBRIDGE_REVISION: this.revision
     }
 
@@ -203,24 +255,21 @@ export default class ReleaseGroup extends EventEmitter {
 
   /**
    * @param {import("./config.js").ProcessConfig} processConfig - Process config.
+   * @param {{count: number, index: number}} replica - Replica index and total count.
    * @returns {Record<string, JsonValue>} Template context.
    */
-  contextForProcess(processConfig) {
-    return {
+  contextForProcess(processConfig, replica = {count: 1, index: 0}) {
+    return processTemplateContext({
       application: this.config.application,
-      env: {...process.env},
-      port: this.ports[processConfig.id],
       ports: this.ports,
       processId: processConfig.id,
-      proxy: {
-        host: this.config.proxy.host,
-        port: this.config.proxy.port,
-        upstreamHost: this.config.proxy.upstreamHost
-      },
+      proxy: this.config.proxy,
       releaseId: this.releaseId,
       releasePath: this.releasePath,
+      replicaCount: replica.count,
+      replicaIndex: replica.index,
       revision: this.revision
-    }
+    })
   }
 
   /**
@@ -277,6 +326,13 @@ export default class ReleaseGroup extends EventEmitter {
     this.state = "draining"
     this.drainStartedAt = new Date().toISOString()
 
+    // Stop nonBlockingDrain processes (e.g. job workers) immediately and in the background, so
+    // their lifecycle drain runs as soon as the release is retired — in parallel with the
+    // connection drain, not held until after it. The rest stop once connections have closed.
+    const entries = [...this.processes.entries()]
+    const nonBlockingStops = entries.filter(([id]) => this.nonBlockingDrainIds.has(id)).map(([, processInstance]) => processInstance.stop())
+    const connectionDependent = entries.filter(([id]) => !this.nonBlockingDrainIds.has(id)).map(([, processInstance]) => processInstance)
+
     if (this.connectionCount > 0) {
       await new Promise((resolve) => {
         const timer = setTimeout(resolve, timeoutMs)
@@ -287,7 +343,10 @@ export default class ReleaseGroup extends EventEmitter {
       })
     }
 
-    await this.stop()
+    await Promise.allSettled(connectionDependent.map((processInstance) => processInstance.stop()))
+    await Promise.allSettled(nonBlockingStops)
+    this.state = "stopped"
+    this.stoppedAt = new Date().toISOString()
   }
 
   /** @returns {Promise<void>} Stops all release-owned processes. */

package/src/state-store.js

@@ -0,0 +1,103 @@
+// @ts-check
+
+import fs from "node:fs/promises"
+
+/**
+ * @typedef {import("./json.js").JsonValue} JsonValue
+ */
+
+let tempCounter = 0
+
+/**
+ * Atomically writes a daemon state snapshot to a file (write to a unique temp file, then
+ * rename), so a reader never sees a partially written file and concurrent writes don't race
+ * a shared temp path.
+ * @param {string} path - State file path.
+ * @param {JsonValue} state - State snapshot to persist.
+ * @returns {Promise<void>} Resolves once written.
+ */
+export async function writeState(path, state) {
+  tempCounter += 1
+
+  const tempPath = `${path}.${process.pid}.${tempCounter}.tmp`
+
+  await fs.writeFile(tempPath, `${JSON.stringify(state, null, 2)}\n`)
+  await fs.rename(tempPath, path)
+}
+
+/**
+ * Reads a previously persisted state snapshot.
+ * @param {string} path - State file path.
+ * @returns {Promise<JsonValue | undefined>} The parsed snapshot, or undefined when missing or unparseable.
+ */
+export async function readState(path) {
+  let contents
+
+  try {
+    contents = await fs.readFile(path, "utf8")
+  } catch {
+    return undefined
+  }
+
+  try {
+    return JSON.parse(contents)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Removes a state file, ignoring a missing file.
+ * @param {string} path - State file path.
+ * @returns {Promise<void>} Resolves once removed.
+ */
+export async function clearState(path) {
+  await fs.rm(path, {force: true})
+}
+
+/**
+ * @param {number} pid - Process id to probe.
+ * @returns {boolean} True when a process with this pid exists (alive).
+ */
+export function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0)
+
+    return true
+  } catch (error) {
+    // EPERM means the process exists but is owned by another user — still alive.
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "EPERM")
+  }
+}
+
+/**
+ * Finds managed processes recorded in a persisted snapshot whose pids are still alive — the
+ * orphans left by a daemon that did not shut down cleanly. Advisory (a recycled pid can be a
+ * false positive); returns an empty list for a missing or unexpectedly shaped snapshot.
+ * @param {JsonValue | undefined} state - A persisted state snapshot (from {@link readState}).
+ * @param {(pid: number) => boolean} [alive] - Process-liveness probe (defaults to {@link isProcessAlive}).
+ * @returns {{id: string, pid: number, releaseId: string | null}[]} Live persisted processes.
+ */
+export function liveProcesses(state, alive = isProcessAlive) {
+  if (!state) return []
+
+  const live = /** @type {{id: string, pid: number, releaseId: string | null}[]} */ ([])
+
+  try {
+    const snapshot = /** @type {import("./daemon.js").DaemonStatus} */ (state)
+
+    for (const release of snapshot.releases) {
+      for (const process of release.processes) {
+        if (typeof process.pid === "number" && alive(process.pid)) live.push({id: process.id, pid: process.pid, releaseId: release.releaseId})
+      }
+    }
+
+    for (const {id, process} of [...snapshot.services, ...snapshot.singletons]) {
+      if (typeof process.pid === "number" && alive(process.pid)) live.push({id, pid: process.pid, releaseId: null})
+    }
+  } catch {
+    return []
+  }
+
+  return live
+}

package/src/system-ids.js

@@ -0,0 +1,71 @@
+// @ts-check
+
+import fs from "node:fs"
+
+/**
+ * Resolves a control-socket owner (a numeric uid, a numeric string, or a user name)
+ * to a numeric uid. Names are looked up in `/etc/passwd`.
+ * @param {number | string} owner - User id or name.
+ * @returns {number} The numeric uid.
+ */
+export function resolveUserId(owner) {
+  return resolvePrincipalId(owner, "/etc/passwd", "user")
+}
+
+/**
+ * Resolves a control-socket group (a numeric gid, a numeric string, or a group name)
+ * to a numeric gid. Names are looked up in `/etc/group`.
+ * @param {number | string} group - Group id or name.
+ * @returns {number} The numeric gid.
+ */
+export function resolveGroupId(group) {
+  return resolvePrincipalId(group, "/etc/group", "group")
+}
+
+/**
+ * @param {number | string} value - Numeric id, numeric string, or name.
+ * @param {string} file - System database file mapping names to ids.
+ * @param {"user" | "group"} kind - Principal kind, for error messages.
+ * @returns {number} The numeric id.
+ */
+function resolvePrincipalId(value, file, kind) {
+  if (typeof value === "number") return value
+  if (/^\d+$/.test(value)) return Number(value)
+
+  const id = lookupByName(value, file)
+
+  if (id === undefined) {
+    throw new Error(`Unknown ${kind} "${value}". Use a numeric id, or ensure the ${kind} exists in ${file} (name resolution covers local ${kind}s only).`)
+  }
+
+  return id
+}
+
+/**
+ * @param {string} name - Principal name.
+ * @param {string} file - `/etc/passwd` or `/etc/group`.
+ * @returns {number | undefined} The numeric id, or undefined when the name is not found.
+ */
+function lookupByName(name, file) {
+  let contents
+
+  try {
+    contents = fs.readFileSync(file, "utf8")
+  } catch {
+    return undefined
+  }
+
+  for (const line of contents.split("\n")) {
+    if (!line || line.startsWith("#")) continue
+
+    const fields = line.split(":")
+
+    if (fields[0] === name) {
+      const id = Number(fields[2])
+
+      if (Number.isInteger(id)) return id
+    }
+  }
+
+  return undefined
+}

package/src/template.js

@@ -44,6 +44,38 @@ export function renderTemplate(value, context) {
   })
 }
 
+/**
+ * Builds the template context for rendering one process's command, cwd, and env. It is the
+ * single source of truth for the render context so callers stay in sync — the daemon uses it at
+ * deploy time, and `doctor` uses it (with representative ports) to pre-flight a release.
+ * @param {object} args - Context inputs.
+ * @param {string} args.application - Application name.
+ * @param {Record<string, number>} args.ports - Allocated (or representative) ports by process id.
+ * @param {string} args.processId - The process this context renders.
+ * @param {{host: string, port: number, upstreamHost: string}} args.proxy - Proxy address.
+ * @param {string} args.releaseId - Release id.
+ * @param {string} args.releasePath - Release directory.
+ * @param {number} args.replicaCount - Total replicas configured for this process.
+ * @param {number} args.replicaIndex - This replica's index.
+ * @param {string} args.revision - Release revision.
+ * @returns {TemplateContext} The render context.
+ */
+export function processTemplateContext({application, ports, processId, proxy, releaseId, releasePath, replicaCount, replicaIndex, revision}) {
+  return {
+    application,
+    env: {...process.env},
+    port: ports[processId],
+    ports,
+    processId,
+    proxy: {host: proxy.host, port: proxy.port, upstreamHost: proxy.upstreamHost},
+    releaseId,
+    releasePath,
+    replicaCount,
+    replicaIndex,
+    revision
+  }
+}
+
 /**
  * Renders all string values in a plain JSON-like object.
  * @param {JsonValue} value - Value to render.

package/test/completion.test.js

@@ -0,0 +1,64 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import test from "node:test"
+import {runCli} from "../src/cli.js"
+
+/**
+ * Runs the CLI while capturing stdout, stderr, and the resulting exit code.
+ * @param {string[]} argv - Process argv.
+ * @returns {Promise<{code: number | string | undefined, errorOutput: string, output: string}>} Captured output and exit code.
+ */
+async function capture(argv) {
+  const originalLog = console.log
+  const originalError = console.error
+  const originalExitCode = process.exitCode
+  /** @type {string[]} */
+  const out = []
+  /** @type {string[]} */
+  const err = []
+
+  console.log = (/** @type {string[]} */ ...args) => { out.push(args.map((arg) => String(arg)).join(" ")) }
+  console.error = (/** @type {string[]} */ ...args) => { err.push(args.map((arg) => String(arg)).join(" ")) }
+  process.exitCode = 0
+
+  try {
+    await runCli(argv)
+  } finally {
+    console.log = originalLog
+    console.error = originalError
+  }
+
+  const code = process.exitCode
+
+  process.exitCode = originalExitCode
+
+  return {code, errorOutput: err.join("\n"), output: out.join("\n")}
+}
+
+test("completion bash prints a sourceable script with commands and option flags", async () => {
+  const {code, output} = await capture(["node", "rollbridge", "completion", "bash"])
+
+  assert.notEqual(code, 1)
+  assert.match(output, /complete -F _rollbridge rollbridge/)
+  assert.match(output, /compgen -W "daemon deploy rollback ensure-daemon status stop restart shutdown validate doctor logs events recover completion"/)
+  // A command's own options are completed after the command.
+  assert.match(output, /deploy\)\n\s+opts="[^"]*--release-path[^"]*"/)
+  assert.match(output, /restart\)\n\s+opts="[^"]*--policy[^"]*"/)
+})
+
+test("completion zsh prints a #compdef script with per-command options", async () => {
+  const {output} = await capture(["node", "rollbridge", "completion", "zsh"])
+
+  assert.match(output, /^#compdef rollbridge/)
+  assert.match(output, /compdef _rollbridge rollbridge/)
+  assert.match(output, /commands=\(daemon deploy rollback ensure-daemon status stop restart shutdown validate doctor logs events recover completion\)/)
+  assert.match(output, /events\) compadd -- [^\n]*--limit/)
+})
+
+test("completion rejects an unsupported shell with a non-zero exit code", async () => {
+  const {code, errorOutput} = await capture(["node", "rollbridge", "completion", "fish"])
+
+  assert.equal(code, 1)
+  assert.match(errorOutput, /Unsupported shell "fish"\. Supported shells: bash, zsh\./)
+})