rollbridge 0.1.15 → 0.1.16

package/package.json

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

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/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)
 

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})
+  }
+})