rollbridge 0.1.5 → 0.1.7

package/src/predeploy-cleanup.js

@@ -0,0 +1,340 @@
+// @ts-check
+
+import fs from "node:fs"
+import path from "node:path"
+import {spawnSync} from "node:child_process"
+import {setTimeout as sleep} from "node:timers/promises"
+import {inspectControlSocket} from "./daemon.js"
+import {recoverOrphans} from "./recover.js"
+import {sendControlCommand} from "./control-client.js"
+
+/**
+ * @typedef {import("./json.js").JsonValue} JsonValue
+ * @typedef {{pid: number, parentPid: number, args: string}} ProcessRow
+ * @typedef {{action: string, legacyProcesses: ProcessRow[], recoveredOrphans: number}} PredeployCleanupResult
+ */
+
+/**
+ * Prepares a host for a Rollbridge deploy by handling the two cases that can block a fresh
+ * daemon startup: orphaned Rollbridge-managed pids from a crashed daemon, and explicitly
+ * configured legacy processes from the pre-Rollbridge supervisor.
+ * @param {object} args - Options.
+ * @param {import("./config.js").RollbridgeConfig} args.config - Rollbridge config.
+ * @param {(socketPath: string) => Promise<import("./daemon.js").ControlSocketInspection>} [args.inspectSocket] - Control socket probe.
+ * @param {string} [args.releasePath] - Pending release path, used to restart the daemon when this release changes Rollbridge itself.
+ * @param {(args: {command: Record<string, JsonValue>, path: string}) => Promise<Record<string, JsonValue>>} [args.sendCommand] - Control command sender.
+ * @param {(command: string, args: string[]) => import("node:child_process").SpawnSyncReturns<Buffer>} [args.runCommand] - Command runner.
+ * @param {(pid: number, signal: string) => void} [args.killProcess] - Signal sender.
+ * @param {(args: {config: import("./config.js").RollbridgeConfig, force: boolean}) => Promise<import("./recover.js").RecoverResult>} [args.recover] - Orphan recovery function.
+ * @returns {Promise<PredeployCleanupResult>} Cleanup result.
+ */
+export async function predeployCleanup({
+  config,
+  inspectSocket = inspectControlSocket,
+  killProcess = process.kill,
+  releasePath,
+  recover = recoverOrphans,
+  runCommand = spawnSync,
+  sendCommand = sendControlCommand
+}) {
+  const inspection = await inspectSocket(config.control.path)
+
+  if (inspection.alive) {
+    const status = await activeDaemonStatus({config, inspection, sendCommand})
+
+    if (status.activeReleaseId && daemonMatchesPendingRelease({config, releasePath, status})) {
+      return {action: "daemon-active", legacyProcesses: [], recoveredOrphans: 0}
+    }
+
+    await sendCommand({command: {command: "shutdown"}, path: config.control.path})
+    await waitForControlSocketShutdown({config, inspectSocket})
+  }
+
+  const recoveredOrphans = await recoverConfiguredOrphans(config, recover)
+  const legacyProcesses = await stopLegacyProcesses({config, killProcess, runCommand})
+
+  return {
+    action: inspection.alive ? "daemon-stopped" : "no-daemon-cleaned",
+    legacyProcesses,
+    recoveredOrphans
+  }
+}
+
+/**
+ * @param {object} args - Options.
+ * @param {import("./config.js").RollbridgeConfig} args.config - Rollbridge config.
+ * @param {import("./daemon.js").ControlSocketInspection} args.inspection - Socket inspection.
+ * @param {(args: {command: Record<string, JsonValue>, path: string}) => Promise<Record<string, JsonValue>>} args.sendCommand - Control command sender.
+ * @returns {Promise<import("./daemon.js").DaemonStatus>} Daemon status.
+ */
+async function activeDaemonStatus({config, inspection, sendCommand}) {
+  if (inspection.application === undefined) {
+    throw new Error(`A non-Rollbridge process is using ${config.control.path}; refusing predeploy cleanup.`)
+  }
+
+  if (inspection.application !== config.application) {
+    throw new Error(`A Rollbridge daemon for "${inspection.application}" is using ${config.control.path}; expected "${config.application}".`)
+  }
+
+  const status = await sendCommand({command: {command: "status"}, path: config.control.path})
+
+  return /** @type {import("./daemon.js").DaemonStatus} */ (status)
+}
+
+/**
+ * @param {object} args - Options.
+ * @param {import("./config.js").RollbridgeConfig} args.config - Rollbridge config.
+ * @param {string} [args.releasePath] - Pending release path.
+ * @param {import("./daemon.js").DaemonStatus} args.status - Active daemon status.
+ * @returns {boolean} True when the active daemon can be reused for this deploy.
+ */
+function daemonMatchesPendingRelease({config, releasePath, status}) {
+  if (!proxyMatchesConfig(status.proxy, config.proxy)) return false
+  if (releasePath !== undefined && rollbridgePackageChanged({releasePath, status})) return false
+
+  return true
+}
+
+/**
+ * @param {import("./daemon.js").DaemonStatus["proxy"]} currentProxy - Current proxy status.
+ * @param {import("./config.js").ProxyConfig} expectedProxy - Pending release proxy config.
+ * @returns {boolean} True when the current daemon proxy matches the pending config.
+ */
+function proxyMatchesConfig(currentProxy, expectedProxy) {
+  return currentProxy.host === expectedProxy.host &&
+    currentProxy.port === expectedProxy.port &&
+    currentProxy.upstreamHost === expectedProxy.upstreamHost
+}
+
+/**
+ * @param {object} args - Options.
+ * @param {string} args.releasePath - Pending release path.
+ * @param {import("./daemon.js").DaemonStatus} args.status - Active daemon status.
+ * @returns {boolean} True when the pending release uses a different Rollbridge package version.
+ */
+function rollbridgePackageChanged({releasePath, status}) {
+  const activeRelease = status.releases.find((release) => release.releaseId === status.activeReleaseId)
+  if (activeRelease === undefined) return false
+
+  const releaseVersion = rollbridgePackageVersion(releasePath)
+  const activeVersion = rollbridgePackageVersion(activeRelease.releasePath)
+
+  return releaseVersion !== undefined &&
+    activeVersion !== undefined &&
+    releaseVersion !== activeVersion
+}
+
+/**
+ * @param {string} releasePath - Release path containing node_modules.
+ * @returns {string | undefined} Installed Rollbridge package version.
+ */
+function rollbridgePackageVersion(releasePath) {
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(path.join(releasePath, "node_modules", "rollbridge", "package.json"), "utf8"))
+
+    if (packageJson && typeof packageJson === "object" && "version" in packageJson && typeof packageJson.version === "string") {
+      return packageJson.version
+    }
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return undefined
+
+    throw error
+  }
+
+  return undefined
+}
+
+/**
+ * @param {object} args - Options.
+ * @param {import("./config.js").RollbridgeConfig} args.config - Rollbridge config.
+ * @param {(socketPath: string) => Promise<import("./daemon.js").ControlSocketInspection>} args.inspectSocket - Control socket probe.
+ * @returns {Promise<void>} Resolves after the socket stops accepting Rollbridge commands.
+ */
+async function waitForControlSocketShutdown({config, inspectSocket}) {
+  const deadline = Date.now() + 30000
+
+  while (true) {
+    const inspection = await inspectSocket(config.control.path)
+    if (!inspection.alive) return
+
+    if (Date.now() >= deadline) {
+      throw new Error(`Timed out waiting for Rollbridge daemon at ${config.control.path} to shut down.`)
+    }
+
+    await sleep(250)
+  }
+}
+
+/**
+ * @param {import("./config.js").RollbridgeConfig} config - Rollbridge config.
+ * @param {(args: {config: import("./config.js").RollbridgeConfig, force: boolean}) => Promise<import("./recover.js").RecoverResult>} recover - Orphan recovery function.
+ * @returns {Promise<number>} Number of orphans found.
+ */
+async function recoverConfiguredOrphans(config, recover) {
+  if (config.statePath === undefined) return 0
+
+  const result = await recover({config, force: true})
+
+  if ("error" in result) {
+    throw new Error(result.error)
+  }
+
+  if (result.remaining.length > 0) {
+    throw new Error(`Could not stop ${result.remaining.length} Rollbridge orphaned process${result.remaining.length === 1 ? "" : "es"}.`)
+  }
+
+  return result.orphans.length
+}
+
+/**
+ * @param {object} args - Options.
+ * @param {import("./config.js").RollbridgeConfig} args.config - Rollbridge config.
+ * @param {(command: string, args: string[]) => import("node:child_process").SpawnSyncReturns<Buffer>} args.runCommand - Command runner.
+ * @param {(pid: number, signal: string) => void} args.killProcess - Signal sender.
+ * @returns {Promise<ProcessRow[]>} Stopped legacy processes.
+ */
+async function stopLegacyProcesses({config, killProcess, runCommand}) {
+  const takeoverConfig = config.legacyTakeover
+  if (takeoverConfig === undefined) return []
+
+  for (const screenName of takeoverConfig.screens) {
+    runCommand("screen", ["-S", screenName, "-X", "quit"])
+  }
+
+  const stoppedProcesses = await stopProcessTree({
+    killProcess,
+    processRows: legacyProcesses(config),
+    timeoutMs: takeoverConfig.forceStopTimeoutMs
+  })
+  const remainingProcesses = legacyProcesses(config)
+
+  if (remainingProcesses.length > 0) {
+    const details = remainingProcesses.map((row) => `${row.pid} ${row.args}`).join("\n")
+
+    throw new Error(`Refusing Rollbridge deploy while legacy processes are still running:\n${details}`)
+  }
+
+  return stoppedProcesses
+}
+
+/**
+ * @param {import("./config.js").RollbridgeConfig} config - Rollbridge config.
+ * @returns {ProcessRow[]} Legacy process rows and their descendants.
+ */
+function legacyProcesses(config) {
+  const rows = processRows()
+  const protectedPids = protectedProcessIds(rows)
+  const legacyPids = new Set(rows.filter((row) => legacySeedProcess(row, config, protectedPids)).map((row) => row.pid))
+  let changed = true
+
+  while (changed) {
+    changed = false
+
+    for (const row of rows) {
+      if (!legacyPids.has(row.pid) && legacyPids.has(row.parentPid)) {
+        legacyPids.add(row.pid)
+        changed = true
+      }
+    }
+  }
+
+  return rows.filter((row) => legacyPids.has(row.pid))
+}
+
+/**
+ * @param {ProcessRow} row - Process row.
+ * @param {import("./config.js").RollbridgeConfig} config - Rollbridge config.
+ * @param {Set<number>} protectedPids - Current cleanup process and ancestors.
+ * @returns {boolean} True when the row identifies a configured legacy process.
+ */
+function legacySeedProcess(row, config, protectedPids) {
+  const takeoverConfig = config.legacyTakeover
+  if (takeoverConfig === undefined || protectedPids.has(row.pid)) return false
+
+  if (takeoverConfig.screens.some((screenName) => row.args.includes(`SCREEN -dmS ${screenName}`))) {
+    return true
+  }
+
+  return takeoverConfig.processes.some((processConfig) => (
+    processConfig.includes.every((matcher) => row.args.includes(matcher))
+  ))
+}
+
+/**
+ * @param {ProcessRow[]} rows - Current process table rows.
+ * @returns {Set<number>} Pids that belong to the running cleanup command.
+ */
+function protectedProcessIds(rows) {
+  const byPid = new Map(rows.map((row) => [row.pid, row]))
+  const protectedPids = new Set([process.pid])
+  let parentPid = process.ppid
+
+  while (parentPid > 0 && !protectedPids.has(parentPid)) {
+    protectedPids.add(parentPid)
+    parentPid = byPid.get(parentPid)?.parentPid || 0
+  }
+
+  return protectedPids
+}
+
+/** @returns {ProcessRow[]} Current process table rows. */
+function processRows() {
+  const result = spawnSync("ps", ["-eo", "pid=,ppid=,args="], {encoding: "utf8"})
+
+  if (result.error) throw result.error
+  if (result.status !== 0) throw new Error(`Failed to inspect running processes: ${result.stderr}`)
+
+  return result.stdout.split("\n").flatMap((line) => {
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.+)$/)
+    if (!match) return []
+
+    const pid = Number(match[1])
+    const parentPid = Number(match[2])
+
+    return [{args: match[3], parentPid, pid}]
+  })
+}
+
+/**
+ * @param {object} args - Options.
+ * @param {(pid: number, signal: string) => void} args.killProcess - Signal sender.
+ * @param {ProcessRow[]} args.processRows - Processes to stop.
+ * @param {number} args.timeoutMs - Grace period before SIGKILL.
+ * @returns {Promise<ProcessRow[]>} Processes that were signaled.
+ */
+async function stopProcessTree({killProcess, processRows, timeoutMs}) {
+  /** @type {ProcessRow[]} */
+  const stoppedProcesses = []
+
+  for (const row of processRows) {
+    if (sendSignal(row.pid, "SIGTERM", killProcess)) stoppedProcesses.push(row)
+  }
+
+  if (stoppedProcesses.length === 0) return []
+
+  await sleep(timeoutMs)
+
+  for (const row of processRows) {
+    sendSignal(row.pid, "SIGKILL", killProcess)
+  }
+
+  return stoppedProcesses
+}
+
+/**
+ * @param {number} pid - Process id.
+ * @param {string} signal - Signal name.
+ * @param {(pid: number, signal: string) => void} killProcess - Signal sender.
+ * @returns {boolean} True when the signal was sent, false when the process was already gone.
+ */
+function sendSignal(pid, signal, killProcess) {
+  try {
+    killProcess(pid, signal)
+
+    return true
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ESRCH") return false
+
+    throw error
+  }
+}

package/src/process-memory.js

@@ -0,0 +1,110 @@
+// @ts-check
+
+import fs from "node:fs"
+
+/**
+ * @typedef {{command: string, pid: number, rssBytes: number | undefined}} ProcessGroupMember
+ */
+
+/**
+ * Lists the members of a managed process group with each member's resident memory.
+ * Rollbridge spawns each process detached, so the spawned pid is the process-group
+ * leader and every process in the tree (the shell wrapper, the app, any children)
+ * shares that group id.
+ *
+ * Reads `/proc` (Linux); returns an empty array when unavailable (no `/proc`, e.g.
+ * non-Linux) or the group has no members.
+ * @param {number} pgid - Process-group id (the detached spawn's pid).
+ * @returns {ProcessGroupMember[]} Group members, ordered by pid.
+ */
+export function processGroupMembers(pgid) {
+  /** @type {string[]} */
+  let entries
+
+  try {
+    entries = fs.readdirSync("/proc")
+  } catch {
+    return []
+  }
+
+  /** @type {ProcessGroupMember[]} */
+  const members = []
+
+  for (const entry of entries) {
+    if (!/^\d+$/.test(entry)) continue
+    if (processGroupId(entry) !== pgid) continue
+
+    members.push({command: commandName(entry), pid: Number(entry), rssBytes: residentBytes(entry)})
+  }
+
+  members.sort((first, second) => first.pid - second.pid)
+
+  return members
+}
+
+/**
+ * Measures the total resident memory (RSS) of a managed process group.
+ * @param {number} pgid - Process-group id (the detached spawn's pid).
+ * @returns {number | undefined} Total resident memory in bytes, or undefined when unmeasurable.
+ */
+export function measureProcessGroupRssBytes(pgid) {
+  const measured = processGroupMembers(pgid).filter((member) => member.rssBytes !== undefined)
+
+  if (measured.length === 0) return undefined
+
+  return measured.reduce((total, member) => total + (member.rssBytes ?? 0), 0)
+}
+
+/**
+ * @param {string} pid - Process id.
+ * @returns {string} The process command name (`/proc/<pid>/comm`), or "" when unavailable.
+ */
+function commandName(pid) {
+  try {
+    return fs.readFileSync(`/proc/${pid}/comm`, "utf8").trim()
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * @param {string} pid - Process id.
+ * @returns {number | undefined} The process-group id, or undefined when the process is gone.
+ */
+function processGroupId(pid) {
+  let stat
+
+  try {
+    stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8")
+  } catch {
+    return undefined
+  }
+
+  // The comm field is wrapped in parens and may itself contain spaces or parens, so the
+  // numeric fields are parsed from after the final ")". They are: state, ppid, pgrp, ...
+  const commEnd = stat.lastIndexOf(")")
+
+  if (commEnd < 0) return undefined
+
+  const pgrp = Number(stat.slice(commEnd + 2).split(" ")[2])
+
+  return Number.isInteger(pgrp) ? pgrp : undefined
+}
+
+/**
+ * @param {string} pid - Process id.
+ * @returns {number | undefined} Resident memory in bytes, or undefined when unavailable.
+ */
+function residentBytes(pid) {
+  let status
+
+  try {
+    status = fs.readFileSync(`/proc/${pid}/status`, "utf8")
+  } catch {
+    return undefined
+  }
+
+  const match = status.match(/^VmRSS:\s+(\d+)\s+kB/m)
+
+  return match ? Number(match[1]) * 1024 : undefined
+}

package/src/recover.js

@@ -0,0 +1,134 @@
+// @ts-check
+
+import {inspectControlSocket} from "./daemon.js"
+import {clearState, isProcessAlive, liveProcesses, readState} from "./state-store.js"
+
+// How long to confirm a SIGKILL'd group has actually exited before reporting it un-stoppable.
+const KILL_CONFIRM_TIMEOUT_MS = 500
+
+/**
+ * @typedef {{id: string, pid: number, releaseId: string | null}} OrphanProcess
+ * @typedef {{error: string}} RecoverError
+ * @typedef {{cleared: boolean, forced: boolean, orphans: OrphanProcess[], remaining: OrphanProcess[]}} RecoverReport
+ * @typedef {RecoverError | RecoverReport} RecoverResult
+ */
+
+/**
+ * Cleans up orphaned managed processes left by a crashed daemon. Reads the persisted state
+ * (config.statePath) and finds managed processes whose pids are still alive. By default it
+ * only reports them; with `force` it stops each one's process group (SIGTERM, then SIGKILL
+ * after the configured timeout) and clears the stale state file.
+ *
+ * When `force` leaves any orphan still running (for example a process owned by another user
+ * that can't be signaled), the state file is **kept** so the operator can investigate and
+ * re-run recovery — the survivors are returned in `remaining` and `cleared` stays false.
+ *
+ * Refuses to run while a daemon (or another process) holds the control socket — those pids
+ * belong to a live daemon, not a crash. A recycled pid can be a false positive, so review the
+ * dry-run list before using `force`.
+ * @param {object} args - Options.
+ * @param {import("./config.js").RollbridgeConfig} args.config - Normalized config.
+ * @param {boolean} args.force - Whether to actually stop the orphans (otherwise list them).
+ * @param {(pid: number, timeoutMs: number) => Promise<boolean>} [args.stopGroup] - Stops a process group and resolves to whether it is gone afterward (defaults to the real implementation; injectable for tests).
+ * @returns {Promise<RecoverResult>} The orphans found and whether they were stopped, or an error.
+ */
+export async function recoverOrphans({config, force, stopGroup = stopProcessGroup}) {
+  if (config.statePath === undefined) {
+    return {error: "No statePath is configured; set statePath in the config to enable recovery."}
+  }
+
+  if (await daemonIsRunning(config.control.path)) {
+    return {error: `A daemon (or another process) is using ${config.control.path}; stop it before recovering — recover is for cleaning up after a crash.`}
+  }
+
+  const orphans = liveProcesses(await readState(config.statePath))
+
+  if (!force) return {cleared: false, forced: false, orphans, remaining: []}
+
+  /** @type {OrphanProcess[]} */
+  const remaining = []
+
+  for (const orphan of orphans) {
+    const stopped = await stopGroup(orphan.pid, config.proxy.forceStopTimeoutMs)
+
+    if (!stopped) remaining.push(orphan)
+  }
+
+  // Only clear the state file once every orphan is confirmed gone; otherwise keep it so the
+  // operator can still find and retry the survivors on the next run.
+  if (remaining.length === 0) await clearState(config.statePath)
+
+  return {cleared: remaining.length === 0, forced: true, orphans, remaining}
+}
+
+/**
+ * @param {string} socketPath - Control socket path.
+ * @returns {Promise<boolean>} True when a process is live on the socket (or it can't be probed).
+ */
+async function daemonIsRunning(socketPath) {
+  try {
+    return (await inspectControlSocket(socketPath)).alive
+  } catch {
+    // Can't tell — be conservative and refuse to stop processes.
+    return true
+  }
+}
+
+/**
+ * Stops a detached process group: SIGTERM, then SIGKILL if it outlives the timeout.
+ * @param {number} pid - Process-group leader pid (the detached spawn's pid).
+ * @param {number} timeoutMs - Grace period before SIGKILL.
+ * @returns {Promise<boolean>} True once the process is gone; false if it is still alive afterward (for example owned by another user, so it can't be signaled).
+ */
+async function stopProcessGroup(pid, timeoutMs) {
+  const term = sendSignal(pid, "SIGTERM")
+
+  if (term === "gone") return true
+  if (term === "denied") return false
+
+  if (await waitForExit(pid, timeoutMs)) return true
+
+  const kill = sendSignal(pid, "SIGKILL")
+
+  if (kill === "gone") return true
+  if (kill === "denied") return false
+
+  return waitForExit(pid, KILL_CONFIRM_TIMEOUT_MS)
+}
+
+/**
+ * Polls until the pid is no longer alive or the timeout elapses.
+ * @param {number} pid - Process pid to watch.
+ * @param {number} timeoutMs - How long to wait for it to exit.
+ * @returns {Promise<boolean>} True once the process is gone, false if it is still alive at the deadline.
+ */
+async function waitForExit(pid, timeoutMs) {
+  const deadline = Date.now() + timeoutMs
+
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) return true
+
+    await new Promise((resolve) => setTimeout(resolve, 50))
+  }
+
+  return !isProcessAlive(pid)
+}
+
+/**
+ * Sends a signal to a detached process group, classifying the outcome.
+ * @param {number} pid - Process-group leader pid.
+ * @param {"SIGTERM" | "SIGKILL"} signal - Signal to send to the group.
+ * @returns {"denied" | "gone" | "sent"} `gone` when the group no longer exists (ESRCH), `denied` when it can't be signaled (for example EPERM), otherwise `sent`.
+ */
+function sendSignal(pid, signal) {
+  try {
+    process.kill(-pid, signal)
+
+    return "sent"
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ESRCH") return "gone"
+
+    // EPERM (owned by another user) or anything else: we could not deliver the signal.
+    return "denied"
+  }
+}