rollbridge 0.1.15 → 0.1.17

package/README.md

@@ -162,10 +162,13 @@ owns cleaning up on-disk release directories.
 releaseRetention: {keep: 5, maxAgeMs: 86400000}
 ```
 
-Set `statePath` to have the daemon persist its state to a file (active/draining
-releases, process pids, counters, recent events). On the next startup it reads
-any leftover file and reports managed processes still alive from a daemon that
-didn't shut down cleanly — advisory orphan detection. After a crash, run
+Set `statePath` to have the daemon persist secret-safe recovery state to a file
+(active/draining releases, process pids, counters, sanitized recent events).
+Commands, environment mappings, child command lines, and captured process output
+are deliberately excluded; those diagnostics remain available through the live
+status/log/event APIs. On the next startup Rollbridge reads any leftover file and
+reports managed processes still alive from a daemon that didn't shut down cleanly
+— advisory orphan detection. After a crash, run
 `rollbridge recover` to list those leftovers and `rollbridge recover --force` to
 stop them before restarting the daemon. A clean `shutdown` removes the file. See
 [`docs/config.md`](docs/config.md#statepath).

package/docs/config.md

@@ -90,10 +90,13 @@ release records; the deploy tool still owns on-disk release directories.
 
 ## `statePath`
 
-When set, the daemon persists a state snapshot — the active and draining
-releases, each managed process's metadata (including pid), restart counters, and
-recent events — to this file (atomically, on changes and every few seconds). On a
-clean `shutdown` the file is removed.
+When set, the daemon persists a secret-safe state snapshot — the active and
+draining releases, each managed process's recovery metadata (including pid),
+restart counters, and recent structured events — to this file (atomically, on
+changes and every few seconds). Process commands, working directories,
+environment mappings, child command lines, and retained stdout/stderr are never
+persisted. They remain available from the live `status`, `logs`, and `events`
+APIs while the daemon is running. On a clean `shutdown` the file is removed.
 
 On the **next startup**, the daemon reads any leftover file and reports managed
 processes whose pids are still alive — likely orphans from a daemon that crashed

package/docs/logging.md

@@ -36,6 +36,12 @@ events. It is distinct from the two in-memory views:
 - `rollbridge events` — the recent structured daemon event history (the most
   recent 1000 events), the same events written to the log file.
 
+When `statePath` is configured, its recovery snapshot is intentionally not a
+log archive: process commands, environment mappings, child command lines, and
+captured stdout/stderr are excluded. Use the live APIs above or the configured
+daemon log for those diagnostics, and protect that log according to the
+sensitivity of application output.
+
 Both are cleared when the daemon restarts; the log file persists.
 
 ## Rotation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rollbridge",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Zero-downtime process supervisor and local traffic switcher for deploy-managed apps.",
   "keywords": [
     "deploy",

package/src/daemon.js

@@ -721,8 +721,9 @@ export default class RollbridgeDaemon {
     if (!this.statePath || this.stopping) return
 
     const statePath = this.statePath
-    const status = this.status()
-    const snapshot = {...status, events: this.eventLog.recent(), persistedAt: new Date().toISOString()}
+    const status = /** @type {Record<string, JsonValue>} */ (secretSafeStateValue(this.status()))
+    const events = secretSafeStateValue(this.eventLog.recent())
+    const snapshot = {...status, events, persistedAt: new Date().toISOString()}
 
     // Serialize writes (and track the tail) so shutdown can wait for an in-flight write before
     // clearing the file — otherwise a write started before shutdown could recreate it afterward.
@@ -851,6 +852,30 @@ function stringOrUndefined(value) {
   return value
 }
 
+const SECRET_BEARING_STATE_KEYS = new Set(["children", "command", "cwd", "env", "environment", "logs", "output"])
+
+/**
+ * Removes process definitions and captured output from a value before it reaches statePath.
+ * The live status/events APIs retain those diagnostics in memory; persistent state is only a
+ * secret-safe recovery aid and must not become a second process log or configuration store.
+ * @param {JsonValue} value - JSON value to sanitize.
+ * @returns {JsonValue} A secret-safe copy.
+ */
+function secretSafeStateValue(value) {
+  if (Array.isArray(value)) return value.map((entry) => secretSafeStateValue(entry))
+  if (!value || typeof value !== "object") return value
+
+  /** @type {Record<string, JsonValue>} */
+  const safe = {}
+
+  for (const [key, entry] of Object.entries(value)) {
+    if (SECRET_BEARING_STATE_KEYS.has(key)) continue
+    safe[key] = secretSafeStateValue(entry)
+  }
+
+  return safe
+}
+
 /**
  * @param {JsonValue} value - Value.
  * @param {string} key - Key.

package/src/managed-process.js

@@ -2,7 +2,7 @@
 
 import {EventEmitter} from "node:events"
 import {spawn} from "node:child_process"
-import {processGroupMembers} from "./process-memory.js"
+import {processGroupHasLiveMembers, processGroupMembers} from "./process-memory.js"
 
 /**
  * @typedef {import("./json.js").JsonValue} JsonValue
@@ -353,6 +353,9 @@ export default class ManagedProcess extends EventEmitter {
       return
     }
 
+    const pgid = child.pid
+    const exitPromise = this.exitPromise
+
     this.state = "stopping"
 
     const {drainCommand, drainTimeoutMs, quietCommand, stopCommand} = this.lifecycle
@@ -370,19 +373,21 @@ export default class ManagedProcess extends EventEmitter {
     }
 
     // 3. Stop whatever is still running, then SIGKILL if it outlasts the graceful window.
-    if (this.child) {
-      if (stopCommand) await this.runHook(stopCommand, hookTimeoutMs, "stop command")
-      else this.killProcessGroup(this.stopSignal)
+    if (this.processGroupExists(pgid)) {
+      if (stopCommand) await this.runHook(stopCommand, hookTimeoutMs, "stop command", pgid)
+      else this.killProcessGroup(this.stopSignal, pgid)
 
       const timeoutMs = options.timeoutMs ?? this.stopTimeoutMs
 
-      if (this.child && !(await this.waitForExit(timeoutMs))) {
-        this.logger("process stop timed out; sending SIGKILL", {id: this.id, pid: this.pid})
-        this.killProcessGroup("SIGKILL")
-        await this.waitForExit(5000)
+      if (!(await this.waitForProcessGroupExit(pgid, timeoutMs))) {
+        this.logger("process stop timed out; sending SIGKILL", {id: this.id, pid: pgid})
+        this.killProcessGroup("SIGKILL", pgid)
+        await this.waitForProcessGroupExit(pgid, 5000)
       }
     }
 
+    if (exitPromise) await exitPromise
+
     this.state = "stopped"
   }
 
@@ -400,9 +405,10 @@ export default class ManagedProcess extends EventEmitter {
    * @param {string} command - Shell command to run.
    * @param {number} timeoutMs - Maximum time to wait for the hook before killing it.
    * @param {string} label - Hook name, for log messages.
+   * @param {number | undefined} [pid] - Process-group leader exposed to the hook.
    * @returns {Promise<void>} Resolves when the hook exits, errors, or times out.
    */
-  async runHook(command, timeoutMs, label) {
+  async runHook(command, timeoutMs, label, pid = this.pid) {
     await new Promise((resolve) => {
       let settled = false
       const finish = () => { if (!settled) { settled = true; resolve(undefined) } }
@@ -414,7 +420,7 @@ export default class ManagedProcess extends EventEmitter {
         hook = spawn(command, {
           cwd: this.cwd,
           detached: true,
-          env: {...process.env, ...this.env, ROLLBRIDGE_PID: this.pid ? String(this.pid) : ""},
+          env: {...process.env, ...this.env, ROLLBRIDGE_PID: pid ? String(pid) : ""},
           shell: true,
           stdio: "ignore"
         })
@@ -461,19 +467,55 @@ export default class ManagedProcess extends EventEmitter {
 
   /**
    * @param {string} signal - Signal name to send (the configured stop signal, or "SIGKILL").
+   * @param {number | undefined} [pgid] - Process group id (the current child pid by default).
    * @returns {void}
    */
-  killProcessGroup(signal) {
-    if (!this.child || !this.child.pid) return
+  killProcessGroup(signal, pgid = this.pid) {
+    if (!pgid) return
 
     try {
-      process.kill(-this.child.pid, signal)
+      process.kill(-pgid, signal)
     } catch (error) {
       if (error && typeof error === "object" && "code" in error && error.code === "ESRCH") return
       throw error
     }
   }
 
+  /**
+   * @param {number} pgid - Process group id.
+   * @returns {boolean} True until the process group no longer exists.
+   */
+  processGroupExists(pgid) {
+    const hasLiveMembers = processGroupHasLiveMembers(pgid)
+
+    if (hasLiveMembers !== undefined) return hasLiveMembers
+
+    try {
+      process.kill(-pgid, 0)
+
+      return true
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ESRCH") return false
+      throw error
+    }
+  }
+
+  /**
+   * @param {number} pgid - Process group id.
+   * @param {StopTimeoutMs} timeoutMs - Timeout.
+   * @returns {Promise<boolean>} True once the process group no longer exists.
+   */
+  async waitForProcessGroupExit(pgid, timeoutMs) {
+    const deadline = timeoutMs === "indefinite" ? undefined : Date.now() + timeoutMs
+
+    while (this.processGroupExists(pgid)) {
+      if (deadline !== undefined && Date.now() >= deadline) return false
+      await new Promise((resolve) => setTimeout(resolve, 10))
+    }
+
+    return true
+  }
+
   /**
    * @param {StopTimeoutMs} timeoutMs - Timeout.
    * @returns {Promise<boolean>} True when the process exited before timeout.

package/src/process-memory.js

@@ -42,6 +42,34 @@ export function processGroupMembers(pgid) {
   return members
 }
 
+/**
+ * Reports whether a process group has a member that can still run. Defunct members remain
+ * visible to kill(2) until their parent reaps them, but cannot handle signals or do work.
+ * @param {number} pgid - Process-group id.
+ * @param {string} [procPath] - Procfs root (overridable for deterministic tests).
+ * @returns {boolean | undefined} Whether a live member exists, or undefined without procfs.
+ */
+export function processGroupHasLiveMembers(pgid, procPath = "/proc") {
+  /** @type {string[]} */
+  let entries
+
+  try {
+    entries = fs.readdirSync(procPath)
+  } catch {
+    return undefined
+  }
+
+  for (const entry of entries) {
+    if (!/^\d+$/.test(entry)) continue
+
+    const stat = processStat(entry, procPath)
+
+    if (stat?.pgrp === pgid && stat.state !== "Z" && stat.state !== "X") return true
+  }
+
+  return false
+}
+
 /**
  * Measures the total resident memory (RSS) of a managed process group.
  * @param {number} pgid - Process-group id (the detached spawn's pid).
@@ -72,10 +100,19 @@ function commandName(pid) {
  * @returns {number | undefined} The process-group id, or undefined when the process is gone.
  */
 function processGroupId(pid) {
+  return processStat(pid, "/proc")?.pgrp
+}
+
+/**
+ * @param {string} pid - Process id.
+ * @param {string} procPath - Procfs root.
+ * @returns {{pgrp: number, state: string} | undefined} Parsed process state and group.
+ */
+function processStat(pid, procPath) {
   let stat
 
   try {
-    stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8")
+    stat = fs.readFileSync(`${procPath}/${pid}/stat`, "utf8")
   } catch {
     return undefined
   }
@@ -86,9 +123,10 @@ function processGroupId(pid) {
 
   if (commEnd < 0) return undefined
 
-  const pgrp = Number(stat.slice(commEnd + 2).split(" ")[2])
+  const fields = stat.slice(commEnd + 2).split(" ")
+  const pgrp = Number(fields[2])
 
-  return Number.isInteger(pgrp) ? pgrp : undefined
+  return Number.isInteger(pgrp) ? {pgrp, state: fields[0]} : undefined
 }
 
 /**

package/test/daemon-bootstrap.test.js

@@ -20,6 +20,8 @@ test("daemon bootstrap requires complete, safe, absolute inputs before binding l
     {args: ["--config", "CONFIG", "--release-path", "RELEASE", "--release-id", "v1"], message: /must be provided together/},
     {args: ["--config", "relative/config.js", "--release-path", "RELEASE", "--release-id", "v1", "--revision", "abc123"], message: /--config must be an absolute path/},
     {args: ["--config", "CONFIG", "--release-path", "relative/release", "--release-id", "v1", "--revision", "abc123"], message: /--release-path must be an absolute path/},
+    {args: ["--config", "CONFIG", "--release-path", "RELEASE_UNNORMALIZED", "--release-id", "v1", "--revision", "abc123"], message: /--release-path must be normalized/},
+    {args: ["--config", "CONFIG", "--release-path", "RELEASE_MISSING", "--release-id", "v1", "--revision", "abc123"], message: /--release-path is not accessible/},
     {args: ["--config", "CONFIG", "--release-path", "RELEASE", "--release-id", "unsafe id", "--revision", "abc123"], message: /--release-id/},
     {args: ["--config", "CONFIG", "--release-path", "RELEASE", "--release-id", "v1", "--revision", "unsafe revision"], message: /--revision/}
   ]
@@ -27,7 +29,13 @@ test("daemon bootstrap requires complete, safe, absolute inputs before binding l
   for (const testCase of cases) {
     await t.test(testCase.message.source, async () => {
       const fixture = await createFixture()
-      const args = testCase.args.map((arg) => arg === "CONFIG" ? fixture.configPath : arg === "RELEASE" ? fixture.root : arg)
+      const args = testCase.args.map((arg) => {
+        if (arg === "CONFIG") return fixture.configPath
+        if (arg === "RELEASE") return fixture.root
+        if (arg === "RELEASE_UNNORMALIZED") return `${fixture.root}/child/..`
+        if (arg === "RELEASE_MISSING") return path.join(fixture.root, "missing")
+        return arg
+      })
 
       try {
         const result = await runDaemon(args)

package/test/managed-process.test.js

@@ -292,6 +292,41 @@ test("a configured stopCommand is used instead of the stop signal", async () =>
   }
 })
 
+test("stopCommand receives the retained process group id after the shell exits", async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "rollbridge-hooks-"))
+  const pidPath = path.join(dir, "stop-pid")
+  const managed = new ManagedProcess({
+    command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify("setInterval(() => {}, 1000)")} & wait`,
+    cwd: undefined,
+    env: {},
+    id: "worker",
+    lifecycle: {
+      drainTimeoutMs: 0,
+      quietCommand: "kill -TERM $ROLLBRIDGE_PID; sleep 0.1",
+      stopCommand: `echo $ROLLBRIDGE_PID > ${JSON.stringify(pidPath)}; kill -TERM -$ROLLBRIDGE_PID`
+    },
+    logger: () => {},
+    outputLines: 50,
+    restartDelayMs: 10,
+    shouldRestart: () => false,
+    stopSignal: "SIGTERM",
+    stopTimeoutMs: 1000
+  })
+
+  try {
+    await managed.start()
+
+    const pgid = managed.pid
+
+    await managed.stop()
+
+    assert.equal(fs.readFileSync(pidPath, "utf8").trim(), String(pgid))
+  } finally {
+    await managed.stop()
+    fs.rmSync(dir, {force: true, recursive: true})
+  }
+})
+
 test("a failing lifecycle hook is logged but does not fail the stop", async () => {
   /** @type {string[]} */
   const messages = []
@@ -414,6 +449,48 @@ test("indefinite stop waits for the process to exit without SIGKILL", async () =
   }
 })
 
+test("stop waits for process group descendants after the detached shell exits", async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "rollbridge-process-group-"))
+  const readyPath = path.join(dir, "ready")
+  const latePath = path.join(dir, "late")
+  const descendant = [
+    "const fs = require('node:fs')",
+    `process.on('SIGTERM', () => setTimeout(() => { fs.writeFileSync(${JSON.stringify(latePath)}, 'late'); process.exit(0) }, 300))`,
+    `fs.writeFileSync(${JSON.stringify(readyPath)}, 'ready')`,
+    "setInterval(() => {}, 1000)"
+  ].join("; ")
+  const managed = new ManagedProcess({
+    command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify(descendant)} & wait`,
+    cwd: undefined,
+    env: {},
+    id: "worker",
+    logger: () => {},
+    outputLines: 50,
+    restartDelayMs: 10,
+    shouldRestart: () => false,
+    stopSignal: "SIGTERM",
+    stopTimeoutMs: 2000
+  })
+
+  try {
+    await managed.start()
+    await waitFor(() => fs.existsSync(readyPath))
+
+    const startedAt = Date.now()
+
+    await managed.stop()
+
+    const elapsedMs = Date.now() - startedAt
+
+    assert.ok(elapsedMs >= 250, `stop resolved after only ${elapsedMs}ms`)
+    assert.ok(elapsedMs < 1500, `stop took ${elapsedMs}ms`)
+    assert.equal(fs.readFileSync(latePath, "utf8"), "late")
+  } finally {
+    await managed.stop()
+    fs.rmSync(dir, {force: true, recursive: true})
+  }
+})
+
 test("a memory restart respawns and is counted when the supervisor still wants the process", async () => {
   const managed = buildLongLived(() => true)
 
@@ -467,6 +544,10 @@ test("does not auto-restart when the restart policy is disabled (maxRestarts: 0)
 
 test("stops auto-restarting once maxRestarts within the window is reached", async () => {
   const managed = buildCrasher({backoffFactor: 1, maxDelayMs: 0, maxRestarts: 2, windowMs: 60000})
+  /** @type {{data: Record<string, import("../src/json.js").JsonValue>, message: string}[]} */
+  const events = []
+
+  managed.logger = (message, data = {}) => { events.push({data, message}) }
 
   try {
     await managed.start()
@@ -477,6 +558,11 @@ test("stops auto-restarting once maxRestarts within the window is reached", asyn
 
     assert.equal(managed.status().restarts, 2)
     assert.equal(managed.status().state, "failed")
+    assert.deepEqual(events.find((event) => event.message === "restart limit reached")?.data, {
+      id: "crasher",
+      maxRestarts: 2,
+      windowMs: 60000
+    })
   } finally {
     await managed.stop()
   }

package/test/process-memory.test.js

@@ -3,7 +3,9 @@
 import assert from "node:assert/strict"
 import fs from "node:fs"
 import test from "node:test"
-import {measureProcessGroupRssBytes, processGroupMembers} from "../src/process-memory.js"
+import os from "node:os"
+import path from "node:path"
+import {measureProcessGroupRssBytes, processGroupHasLiveMembers, processGroupMembers} from "../src/process-memory.js"
 
 const linuxOnly = process.platform !== "linux" && "requires /proc (Linux)"
 
@@ -38,3 +40,21 @@ test("lists process-group members with their command and resident memory", {skip
 test("returns an empty list for a process group with no members", {skip: linuxOnly}, () => {
   assert.deepEqual(processGroupMembers(2147483646), [])
 })
+
+test("treats a process group containing only defunct members as stopped", () => {
+  const procPath = fs.mkdtempSync(path.join(os.tmpdir(), "rollbridge-proc-"))
+
+  try {
+    fs.mkdirSync(path.join(procPath, "101"))
+    fs.writeFileSync(path.join(procPath, "101", "stat"), "101 (worker) Z 1 77 0 0")
+
+    assert.equal(processGroupHasLiveMembers(77, procPath), false)
+
+    fs.mkdirSync(path.join(procPath, "102"))
+    fs.writeFileSync(path.join(procPath, "102", "stat"), "102 (worker) S 1 77 0 0")
+
+    assert.equal(processGroupHasLiveMembers(77, procPath), true)
+  } finally {
+    fs.rmSync(procPath, {force: true, recursive: true})
+  }
+})

package/test/rollbridge.test.js

@@ -8,11 +8,11 @@ import net from "node:net"
 import os from "node:os"
 import path from "node:path"
 import test from "node:test"
-import {fileURLToPath} from "node:url"
+import {fileURLToPath, pathToFileURL} from "node:url"
 import RollbridgeDaemon from "../src/daemon.js"
 import {normalizeConfig} from "../src/config.js"
 import {sendControlCommand} from "../src/control-client.js"
-import {readState, writeState} from "../src/state-store.js"
+import {liveProcesses, readState, writeState} from "../src/state-store.js"
 import {runCli} from "../src/cli.js"
 
 const currentDir = path.dirname(fileURLToPath(import.meta.url))
@@ -635,6 +635,37 @@ test("persists daemon state to statePath and removes it on a clean shutdown", as
   assert.equal(stateAfterShutdown, undefined, "state file removed on clean shutdown")
 })
 
+test("persisted daemon state excludes process commands, environment values, and output", async () => {
+  const secret = "state-secret-value"
+  const fixture = await createFixture({persistState: true})
+  const web = fixture.config.processes.find((processConfig) => processConfig.id === "web")
+
+  assert.ok(web)
+  web.env.ROLLBRIDGE_TEST_SECRET = secret
+  web.command = `${JSON.stringify(process.execPath)} -e ${JSON.stringify(`console.log(process.env.ROLLBRIDGE_TEST_SECRET); import(${JSON.stringify(pathToFileURL(dummyAppPath).href)})`)}`
+
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+    await waitFor(() => Boolean(daemon.activeRelease?.getProcess("web")?.status().logs.some((entry) => entry.line === secret)))
+
+    daemon.persistState()
+    await waitFor(async () => (await fs.readFile(fixture.statePath, "utf8")).includes('"activeReleaseId": "v1"'))
+
+    const persisted = await fs.readFile(fixture.statePath, "utf8")
+
+    assert.doesNotMatch(persisted, /state-secret-value/)
+    assert.doesNotMatch(persisted, /ROLLBRIDGE_TEST_SECRET/)
+    assert.doesNotMatch(persisted, /"command"/)
+    assert.doesNotMatch(persisted, /"logs"/)
+    assert.deepEqual(liveProcesses(JSON.parse(persisted), () => true).map(({id, releaseId}) => ({id, releaseId})), [{id: "web", releaseId: "v1"}])
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
 test("a clean shutdown clears the state file even when a persist write is in flight", async () => {
   const fixture = await createFixture({persistState: true})
   const daemon = await startDaemon(fixture.config)