rollbridge 0.1.1 → 0.1.2

package/README.md

@@ -55,7 +55,8 @@ export default {
       id: "background-jobs-worker",
       policy: "companion",
       cwd: "{{releasePath}}",
-      command: "npx velocious background-jobs-worker"
+      command: "npx velocious background-jobs-worker",
+      outputLines: 200
     },
     {
       id: "background-jobs-main",
@@ -75,6 +76,15 @@ export default {
 }
 ```
 
+Each process retains its most recent stdout/stderr lines and reports them in
+`status`. Set `outputLines` (a positive integer, default 50) per process to keep
+more or fewer lines for chatty or quiet processes.
+
+Set `control.mode` to an octal permission string (for example `"660"`) to
+chmod the control socket after it binds. This restricts which users can send
+control commands — useful when several deploy users share a group. When unset,
+the socket keeps the default permissions from the daemon's umask.
+
 A function export receives no arguments and lets you build the config at load
 time:
 
@@ -90,6 +100,19 @@ export default () => ({
 })
 ```
 
+### Template variables
+
+A process `command`, `cwd`, and `env` values support `{{...}}` placeholders
+rendered when the process starts:
+
+- `{{releasePath}}`, `{{releaseId}}`, `{{revision}}`, `{{application}}`, `{{processId}}`
+- `{{port}}` — the port allocated to this process; `{{ports.<id>}}` — another process's allocated port
+- `{{proxy.host}}`, `{{proxy.port}}`
+- `{{env.<NAME>}}` — a variable from the daemon's own environment, e.g. `{{env.HOME}}`
+
+Referencing a placeholder with no value (including an unset `{{env.<NAME>}}`)
+fails the process start with a clear error, so typos surface immediately.
+
 Production-ready examples live in `examples/`, including
 `examples/tensorbuzz.com.js` for the current TensorBuzz backend deployment.
 
@@ -187,6 +210,38 @@ location / {
 }
 ```
 
+## Running under systemd
+
+Run the long-lived daemon as a systemd service so it starts on boot and is
+restarted if it crashes. A ready-to-edit unit lives at
+`examples/rollbridge.service`:
+
+```bash
+sudo cp examples/rollbridge.service /etc/systemd/system/rollbridge.service
+# edit User/Group, WorkingDirectory, the ExecStart path, and --config
+sudo systemctl daemon-reload
+sudo systemctl enable --now rollbridge
+sudo systemctl status rollbridge
+```
+
+The unit runs `rollbridge daemon --config <stable-config>` in the foreground,
+so its output goes to the journal (`journalctl -u rollbridge`). Key directives:
+
+- `KillMode=mixed` / `KillSignal=SIGTERM`: Rollbridge stops its own managed
+  child process groups on `SIGTERM`, so systemd signals only the daemon and
+  lets it shut down gracefully before escalating to `SIGKILL`.
+- `TimeoutStopSec`: give the daemon time to stop its managed processes; size it
+  above the largest process `gracefulStopMs` (the daemon `SIGKILL`s stragglers
+  after that). Note that `systemctl stop`/reboot stops processes but does **not**
+  drain HTTP/WebSocket connections — connection draining happens only during
+  `rollbridge deploy` release transitions.
+
+The daemon is long-lived and survives deploys. **Deploy with
+`rollbridge deploy` (or `rollbridge deploy --ensure-daemon`), not
+`systemctl restart`** — pointing `--config` at a stable, daemon-wide file while
+release paths are passed per deploy. Use `command -v rollbridge` to find the
+absolute CLI path for `ExecStart`.
+
 ## Deployment Notes
 
 Run migrations before `rollbridge deploy`, and keep migrations backwards-compatible while old and new web releases overlap. For stable local brokers such as Velocious Beacon or `background-jobs-main`, use `service` when the process should survive deploys and restart from the latest successful release if it crashes.

package/TODO.md

@@ -65,20 +65,21 @@ This roadmap tracks planned Rollbridge features and documentation. Rollbridge sh
 
 ## Minor Features
 
-- [ ] Add socket permission and socket owner/group options for shared deploy users.
+- [x] Add a control-socket permission option (`control.mode`) for shared deploy users.
+- [ ] Add control-socket owner/group options for shared deploy users (needs name-to-id resolution).
 - [x] Make stale control socket diagnostics clearer when another daemon is still alive.
 - [ ] Add old-release cleanup policies by age, count, and stopped state.
 - [x] Add port allocation diagnostics when a range is exhausted.
 - [ ] Add optional startup command timeout before health checks begin.
-- [ ] Add process output retention config instead of a fixed recent-log count.
-- [ ] Add environment variable interpolation from the daemon environment.
+- [x] Add process output retention config instead of a fixed recent-log count.
+- [x] Add environment variable interpolation from the daemon environment.
 - [x] Add `--config` default lookup resolving to `rollbridge.js` when no path is given.
 - [ ] Add shell completion generation for common shells.
 - [ ] Add npm package metadata such as repository, license, bugs, and homepage.
-- [ ] Add systemd service examples for the Rollbridge daemon.
-- [ ] Add tests for malformed control socket JSON and unknown control commands.
+- [x] Add systemd service examples for the Rollbridge daemon.
+- [x] Add tests for malformed control socket JSON and unknown control commands.
 - [ ] Add tests for duplicate IDs and singleton replacement failure behavior.
-- [ ] Add tests for proxy behavior when the active release exits unexpectedly.
+- [x] Add tests for proxy behavior when the active release exits unexpectedly.
 
 ## Documentation TODO
 

package/examples/rollbridge.service

@@ -0,0 +1,48 @@
+# Example systemd unit for the long-running Rollbridge daemon.
+#
+# Install:
+#   sudo cp examples/rollbridge.service /etc/systemd/system/rollbridge.service
+#   # edit User/Group, WorkingDirectory, ExecStart path, and --config below
+#   sudo systemctl daemon-reload
+#   sudo systemctl enable --now rollbridge
+#
+# The daemon is long-lived and survives deploys. Deploys go through
+# `rollbridge deploy` (optionally `--ensure-daemon`), NOT `systemctl restart`.
+# Point --config at a stable, daemon-wide config file (release paths are passed
+# per deploy with `rollbridge deploy --release-path ...`).
+#
+# Find the absolute path to the installed CLI for ExecStart with:
+#   command -v rollbridge
+
+[Unit]
+Description=Rollbridge zero-downtime process supervisor
+After=network.target
+
+[Service]
+Type=simple
+User=deploy
+Group=deploy
+WorkingDirectory=/srv/ticket-server
+ExecStart=/usr/local/bin/rollbridge daemon --config /etc/rollbridge/rollbridge.js
+
+# Optional: variables here are visible to the JS config (process.env) and to
+# `{{env.NAME}}` templates in process commands.
+# EnvironmentFile=/etc/rollbridge/ticket-server.env
+
+Restart=on-failure
+RestartSec=2
+
+# Rollbridge supervises its own child process groups and stops them on SIGTERM,
+# so send SIGTERM to the daemon only and let it drain/stop releases itself;
+# systemd SIGKILLs anything still alive after the timeout.
+KillMode=mixed
+KillSignal=SIGTERM
+
+# Allow time for the daemon to stop its managed processes. Size this above the
+# largest process gracefulStopMs in your config (the daemon SIGKILLs stragglers
+# after that). Note: `systemctl stop` does not drain HTTP/WebSocket connections;
+# draining happens only during `rollbridge deploy` release transitions.
+TimeoutStopSec=120
+
+[Install]
+WantedBy=multi-user.target

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rollbridge",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Zero-downtime process supervisor and local traffic switcher for deploy-managed apps.",
   "type": "module",
   "bin": {

package/src/config.js

@@ -9,8 +9,8 @@ import {pathToFileURL} from "node:url"
  * @typedef {{from: number, to: number}} PortRange
  * @typedef {{path: string, timeoutMs: number, intervalMs: number}} HealthConfig
  * @typedef {"proxied" | "companion" | "singleton" | "service"} ProcessPolicy
- * @typedef {{cwd?: string, env: Record<string, string>, gracefulStopMs: number, health?: HealthConfig, id: string, policy: ProcessPolicy, port?: PortRange, restartDelayMs: number, command: string}} ProcessConfig
- * @typedef {{path: string}} ControlConfig
+ * @typedef {{cwd?: string, env: Record<string, string>, gracefulStopMs: number, health?: HealthConfig, id: string, outputLines: number, policy: ProcessPolicy, port?: PortRange, restartDelayMs: number, command: string}} ProcessConfig
+ * @typedef {{mode?: number, path: string}} ControlConfig
  * @typedef {{drainTimeoutMs: number, forceStopTimeoutMs: number, healthPath: string, healthTimeoutMs: number, host: string, port: number}} ProxyConfig
  * @typedef {{application: string, control: ControlConfig, processes: ProcessConfig[], proxy: ProxyConfig}} RollbridgeConfig
  * @typedef {{fix: string, message: string}} ConfigIssue
@@ -123,6 +123,7 @@ export function validateConfig(rawConfig, configPath = process.cwd()) {
   const processesSource = arrayAt(source.processes, "processes", issues)
   const proxy = normalizeProxy(proxySource, issues)
   const control = {
+    mode: normalizeSocketMode(controlSource.mode, "control.mode", issues),
     path: normalizeString(controlSource.path, "control.path", issues, {default: `/tmp/rollbridge-${application}.sock`})
   }
   const processes = processesSource.map((processSource, index) => normalizeProcess(processSource, index, proxy, issues))
@@ -159,7 +160,7 @@ function normalizeProcess(value, index, proxy, issues) {
   if (!isPlainObject(value)) {
     issues.push({fix: `Define processes[${index}] as a mapping with id, policy, and command.`, message: `processes[${index}] must be an object`})
 
-    return {command: "", cwd: undefined, env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", policy: "companion", port: undefined, restartDelayMs: 1000}
+    return {command: "", cwd: undefined, env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", outputLines: 50, policy: "companion", port: undefined, restartDelayMs: 1000}
   }
 
   const source = value
@@ -171,12 +172,54 @@ function normalizeProcess(value, index, proxy, issues) {
     gracefulStopMs: normalizeNumber(source.gracefulStopMs, `processes[${index}].gracefulStopMs`, issues, {default: proxy.forceStopTimeoutMs}),
     health: normalizeHealth(source.health, `processes[${index}].health`, proxy, issues),
     id: normalizeString(source.id, `processes[${index}].id`, issues),
+    outputLines: normalizeOutputLines(source.outputLines, `processes[${index}].outputLines`, issues),
     policy: normalizePolicy(source.policy, `processes[${index}].policy`, issues),
     port: normalizePortRange(source.port, `processes[${index}].port`, issues),
     restartDelayMs: normalizeNumber(source.restartDelayMs, `processes[${index}].restartDelayMs`, issues, {default: 1000})
   }
 }
 
+/**
+ * @param {JsonValue} value - Raw output retention value.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number} Recent output lines to retain and report (default 50).
+ */
+function normalizeOutputLines(value, key, issues) {
+  const outputLines = normalizeNumber(value, key, issues, {default: 50})
+
+  if (!Number.isInteger(outputLines) || outputLines < 1) {
+    issues.push({fix: `Set ${key} to a positive integer number of lines, e.g. 50.`, message: `${key} must be a positive integer`})
+
+    return 50
+  }
+
+  return outputLines
+}
+
+/**
+ * @param {JsonValue} value - Raw socket permission mode.
+ * @param {string} key - Config key.
+ * @param {ConfigIssue[]} issues - Issue collector.
+ * @returns {number | undefined} File mode bits (0 to 0o777), or undefined when unset.
+ */
+function normalizeSocketMode(value, key, issues) {
+  if (value === undefined || value === null) return undefined
+
+  if (typeof value === "number") {
+    if (Number.isInteger(value) && value >= 0 && value <= 0o777) return value
+  } else if (typeof value === "string") {
+    const cleaned = value.startsWith("0o") ? value.slice(2) : value
+    const mode = /^[0-7]{1,4}$/.test(cleaned) ? parseInt(cleaned, 8) : Number.NaN
+
+    if (Number.isInteger(mode) && mode >= 0 && mode <= 0o777) return mode
+  }
+
+  issues.push({fix: `Set ${key} to an octal permission string like "660" (or an octal number such as 0o660).`, message: `${key} must be an octal file mode between 0 and 0o777`})
+
+  return undefined
+}
+
 /**
  * Validates cross-process rules: unique ids, exactly one proxied process, and proxied ports.
  * @param {ProcessConfig[]} processes - Normalized processes.

package/src/daemon.js

@@ -74,6 +74,10 @@ export default class RollbridgeDaemon {
         resolve(undefined)
       })
     })
+
+    if (this.config.control.mode !== undefined) {
+      await fs.chmod(this.config.control.path, this.config.control.mode)
+    }
   }
 
   /** @returns {Promise<void>} Removes a stale Unix socket before binding, or fails clearly when a daemon is alive. */
@@ -362,6 +366,7 @@ export default class RollbridgeDaemon {
         cwd: nextDefinition.cwd,
         env: nextDefinition.env,
         logger: nextDefinition.logger,
+        outputLines: nextDefinition.outputLines,
         restartDelayMs: nextDefinition.restartDelayMs,
         shouldRestart: nextDefinition.shouldRestart,
         stopTimeoutMs: nextDefinition.stopTimeoutMs

package/src/managed-process.js

@@ -8,7 +8,7 @@ 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, restartDelayMs: number, shouldRestart: () => boolean, stopTimeoutMs: number}} ManagedProcessDefinition
+ * @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
  */
 
@@ -20,11 +20,12 @@ export default class ManagedProcess extends EventEmitter {
    * @param {Record<string, string | undefined>} args.env - Environment.
    * @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 {number} args.restartDelayMs - Restart delay.
    * @param {() => boolean} args.shouldRestart - Restart policy callback.
    * @param {number} args.stopTimeoutMs - Stop timeout.
    */
-  constructor({command, cwd, env, id, logger, restartDelayMs, shouldRestart, stopTimeoutMs}) {
+  constructor({command, cwd, env, id, logger, outputLines, restartDelayMs, shouldRestart, stopTimeoutMs}) {
     super()
 
     this.command = command
@@ -32,6 +33,7 @@ export default class ManagedProcess extends EventEmitter {
     this.env = env
     this.id = id
     this.logger = logger
+    this.outputLines = outputLines
     this.restartDelayMs = restartDelayMs
     this.shouldRestart = shouldRestart
     this.stopTimeoutMs = stopTimeoutMs
@@ -100,6 +102,7 @@ export default class ManagedProcess extends EventEmitter {
     this.cwd = definition.cwd
     this.env = definition.env
     this.logger = definition.logger
+    this.outputLines = definition.outputLines
     this.restartDelayMs = definition.restartDelayMs
     this.shouldRestart = definition.shouldRestart
     this.stopTimeoutMs = definition.stopTimeoutMs
@@ -116,8 +119,8 @@ export default class ManagedProcess extends EventEmitter {
 
       this.logs.push({at: new Date().toISOString(), line, stream})
 
-      if (this.logs.length > 200) {
-        this.logs.splice(0, this.logs.length - 200)
+      if (this.logs.length > this.outputLines) {
+        this.logs.splice(0, this.logs.length - this.outputLines)
       }
     }
   }
@@ -224,7 +227,7 @@ export default class ManagedProcess extends EventEmitter {
       exitCode: this.exitCode,
       exitSignal: this.exitSignal,
       id: this.id,
-      logs: this.logs.slice(-20),
+      logs: this.logs.slice(-this.outputLines),
       pid: this.pid,
       state: this.state
     }

package/src/release-group.js

@@ -141,6 +141,7 @@ export default class ReleaseGroup extends EventEmitter {
       env: processEnv,
       id: processConfig.id,
       logger: (message, data = {}) => this.logger(message, {processId: processConfig.id, releaseId: this.releaseId, ...data}),
+      outputLines: processConfig.outputLines,
       restartDelayMs: processConfig.restartDelayMs,
       shouldRestart: options.shouldRestart || (() => this.state === "active" || this.state === "starting"),
       stopTimeoutMs: processConfig.gracefulStopMs
@@ -179,6 +180,7 @@ export default class ReleaseGroup extends EventEmitter {
   contextForProcess(processConfig) {
     return {
       application: this.config.application,
+      env: {...process.env},
       port: this.ports[processConfig.id],
       ports: this.ports,
       processId: processConfig.id,

package/test/config-validation.test.js

@@ -55,6 +55,68 @@ test("validateConfig returns a normalized config and no issues for a valid confi
   assert.equal(config.proxy.port, 8182)
 })
 
+test("validateConfig defaults outputLines and accepts a positive override", () => {
+  const {config, issues} = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}},
+      {command: "run worker", id: "worker", outputLines: 5, policy: "companion"}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  assert.deepEqual(issues, [])
+  assert.equal(config.processes[0].outputLines, 50)
+  assert.equal(config.processes[1].outputLines, 5)
+})
+
+test("validateConfig rejects a non-positive-integer outputLines with a fix", () => {
+  const {issues} = validateConfig({
+    application: "demo",
+    control: {path: "/tmp/demo.sock"},
+    processes: [
+      {command: "run web", id: "web", outputLines: 0, policy: "proxied", port: {from: 18000, to: 18099}}
+    ],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  const issue = issues.find((candidate) => candidate.message === "processes[0].outputLines must be a positive integer")
+
+  assert.ok(issue, `expected an outputLines issue in ${JSON.stringify(issues.map((candidate) => candidate.message))}`)
+  assert.match(issue.fix, /positive integer/)
+})
+
+test("validateConfig parses control.mode, defaults it to unset, and rejects invalid modes", () => {
+  /**
+   * @param {import("../src/json.js").JsonValue} control - Control config under test.
+   * @returns {{config: import("../src/config.js").RollbridgeConfig, issues: import("../src/config.js").ConfigIssue[]}} Validation result.
+   */
+  const validateControl = (control) => validateConfig({
+    application: "demo",
+    control,
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: 8182}
+  })
+
+  const parsed = validateControl({mode: "660", path: "/tmp/demo.sock"})
+
+  assert.deepEqual(parsed.issues, [])
+  assert.equal(parsed.config.control.mode, 0o660)
+
+  // Minimal octal strings are accepted, matching the numeric boundary (e.g. 0).
+  const minimal = validateControl({mode: "0", path: "/tmp/demo.sock"})
+
+  assert.deepEqual(minimal.issues, [])
+  assert.equal(minimal.config.control.mode, 0)
+
+  assert.equal(validateControl({path: "/tmp/demo.sock"}).config.control.mode, undefined)
+
+  const invalid = validateControl({mode: "abc", path: "/tmp/demo.sock"})
+
+  assert.ok(invalid.issues.some((issue) => issue.message === "control.mode must be an octal file mode between 0 and 0o777"))
+})
+
 test("normalizeConfig throws an aggregated error listing every issue", () => {
   assert.throws(
     () => normalizeConfig({

package/test/control-protocol.test.js

@@ -0,0 +1,94 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import fs from "node:fs/promises"
+import net from "node:net"
+import os from "node:os"
+import path from "node:path"
+import test, {after, before} from "node:test"
+import RollbridgeDaemon from "../src/daemon.js"
+import {normalizeConfig} from "../src/config.js"
+import {sendControlCommand} from "../src/control-client.js"
+
+let root = ""
+let socketPath = ""
+let daemon = /** @type {RollbridgeDaemon | undefined} */ (undefined)
+
+before(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-control-"))
+  socketPath = path.join(root, "rollbridge.sock")
+
+  const config = normalizeConfig({
+    application: "rollbridge-control-test",
+    control: {path: socketPath},
+    processes: [{command: "true", id: "web", policy: "proxied", port: {from: 0, to: 0}}],
+    proxy: {host: "127.0.0.1", port: 0}
+  })
+
+  daemon = new RollbridgeDaemon({config, logger: () => {}})
+  await daemon.start()
+})
+
+after(async () => {
+  if (daemon) await daemon.shutdown()
+  await fs.rm(root, {force: true, recursive: true})
+})
+
+/**
+ * Writes a single raw line to the control socket and returns the parsed response.
+ * @param {string} rawLine - Exact line to send (no trailing newline).
+ * @returns {Promise<Record<string, import("../src/json.js").JsonValue>>} Parsed response.
+ */
+async function sendRawControlLine(rawLine) {
+  return await new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath)
+    let buffer = ""
+
+    socket.setEncoding("utf8")
+    socket.once("error", reject)
+    socket.on("data", (chunk) => {
+      buffer += chunk
+
+      const newlineIndex = buffer.indexOf("\n")
+
+      if (newlineIndex < 0) return
+
+      socket.end()
+      resolve(JSON.parse(buffer.slice(0, newlineIndex)))
+    })
+    socket.once("connect", () => socket.write(`${rawLine}\n`))
+  })
+}
+
+test("malformed JSON returns an error response without crashing the daemon", async () => {
+  const response = await sendRawControlLine("this is not json")
+
+  assert.equal(response.status, "error")
+  assert.match(String(response.error), /JSON/)
+
+  // The daemon stays up and still answers valid commands afterwards.
+  const status = await sendControlCommand({command: {command: "status"}, path: socketPath})
+
+  assert.equal(status.application, "rollbridge-control-test")
+})
+
+test("non-object JSON is rejected as an invalid control command", async () => {
+  const response = await sendRawControlLine("123")
+
+  assert.equal(response.status, "error")
+  assert.equal(response.error, "Control command must be an object")
+})
+
+test("an unknown control command returns a clear error", async () => {
+  const response = await sendRawControlLine(JSON.stringify({command: "bogus"}))
+
+  assert.equal(response.status, "error")
+  assert.equal(response.error, "Unknown command: bogus")
+})
+
+test("a known command missing a required field returns a field error", async () => {
+  const response = await sendRawControlLine(JSON.stringify({command: "deploy"}))
+
+  assert.equal(response.status, "error")
+  assert.equal(response.error, "releasePath is required")
+})

package/test/managed-process.test.js

@@ -0,0 +1,46 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import test from "node:test"
+import ManagedProcess from "../src/managed-process.js"
+
+/**
+ * Builds a managed process that is never spawned, for exercising output retention directly.
+ * @param {number} outputLines - Recent output lines to retain and report.
+ * @returns {ManagedProcess} Managed process.
+ */
+function buildProcess(outputLines) {
+  return new ManagedProcess({
+    command: "true",
+    cwd: undefined,
+    env: {},
+    id: "web",
+    logger: () => {},
+    outputLines,
+    restartDelayMs: 1000,
+    shouldRestart: () => false,
+    stopTimeoutMs: 1000
+  })
+}
+
+test("retains and reports only the configured number of recent output lines", () => {
+  const managed = buildProcess(3)
+
+  managed.appendLog("stdout", "a\nb\nc\nd\ne\n")
+
+  const {logs} = managed.status()
+
+  assert.equal(logs.length, 3)
+  assert.deepEqual(logs.map((entry) => entry.line), ["c", "d", "e"])
+  assert.equal(logs[0].stream, "stdout")
+})
+
+test("keeps every output line when fewer than the retention limit are produced", () => {
+  const managed = buildProcess(50)
+
+  managed.appendLog("stderr", "one\ntwo\n")
+
+  const {logs} = managed.status()
+
+  assert.deepEqual(logs.map((entry) => entry.line), ["one", "two"])
+})

package/test/proxy.test.js

@@ -0,0 +1,128 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import fs from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import test from "node:test"
+import {fileURLToPath} from "node:url"
+import RollbridgeDaemon from "../src/daemon.js"
+import {normalizeConfig} from "../src/config.js"
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url))
+const dummyAppPath = path.join(currentDir, "fixtures", "dummy-app.js")
+
+/**
+ * @param {string} root - Fixture root used for the control socket.
+ * @param {number} restartDelayMs - Delay before a crashed process is restarted.
+ * @returns {import("../src/config.js").RollbridgeConfig} Normalized config with one proxied web process.
+ */
+function buildConfig(root, restartDelayMs) {
+  return normalizeConfig({
+    application: "rollbridge-proxy-test",
+    control: {path: path.join(root, "rollbridge.sock")},
+    processes: [
+      {
+        command: `${JSON.stringify(process.execPath)} ${JSON.stringify(dummyAppPath)}`,
+        health: {intervalMs: 50, path: "/ping", timeoutMs: 3000},
+        id: "web",
+        policy: "proxied",
+        port: {from: 0, to: 0},
+        restartDelayMs
+      }
+    ],
+    proxy: {drainTimeoutMs: 1000, forceStopTimeoutMs: 500, healthPath: "/ping", healthTimeoutMs: 3000, host: "127.0.0.1", port: 0}
+  })
+}
+
+/**
+ * @param {RollbridgeDaemon} daemon - Daemon.
+ * @param {string} pathName - Request path.
+ * @returns {Promise<Response>} Proxy response.
+ */
+async function proxyFetch(daemon, pathName) {
+  return await fetch(`http://127.0.0.1:${daemon.getProxyPort()}${pathName}`)
+}
+
+/**
+ * @param {RollbridgeDaemon} daemon - Daemon.
+ * @param {string} releaseId - Active release id.
+ * @returns {number} The web process pid reported by status.
+ */
+function webPid(daemon, releaseId) {
+  const release = daemon.status().releases.find((candidate) => candidate.releaseId === releaseId)
+
+  assert.ok(release, `Release ${releaseId} should be present`)
+
+  const web = release.processes.find((candidate) => candidate.id === "web")
+
+  assert.ok(web && typeof web.pid === "number", "web process should report a pid")
+
+  return web.pid
+}
+
+/**
+ * @param {() => Promise<boolean> | boolean} callback - Probe.
+ * @returns {Promise<void>} Resolves once the probe returns true.
+ */
+async function waitFor(callback) {
+  const deadline = Date.now() + 3000
+
+  while (Date.now() < deadline) {
+    if (await callback()) return
+    await new Promise((resolve) => setTimeout(resolve, 25))
+  }
+
+  throw new Error("Timed out waiting for condition")
+}
+
+test("proxy returns 502 while the active release web process is down", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-proxy-"))
+  const daemon = new RollbridgeDaemon({config: buildConfig(root, 60000), logger: () => {}})
+
+  await daemon.start()
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: root, revision: "v1"})
+    assert.equal((await proxyFetch(daemon, "/release")).status, 200)
+
+    // Kill the web process group so the active release exits unexpectedly; restart is held off for 60s.
+    process.kill(-webPid(daemon, "v1"), "SIGKILL")
+
+    let lastStatus = 0
+
+    await waitFor(async () => {
+      lastStatus = (await proxyFetch(daemon, "/release")).status
+
+      return lastStatus === 502
+    })
+
+    assert.equal(lastStatus, 502)
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("proxy recovers once the crashed web process restarts", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-proxy-"))
+  const daemon = new RollbridgeDaemon({config: buildConfig(root, 300), logger: () => {}})
+
+  await daemon.start()
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: root, revision: "v1"})
+    assert.equal((await proxyFetch(daemon, "/release")).status, 200)
+
+    process.kill(-webPid(daemon, "v1"), "SIGKILL")
+
+    // First confirm the crash actually takes the proxy down (502), so passing requires
+    // observing the outage, then confirm the restart brings the proxy back to 200.
+    await waitFor(async () => (await proxyFetch(daemon, "/release")).status === 502)
+    await waitFor(async () => (await proxyFetch(daemon, "/release")).status === 200)
+    assert.equal((await proxyFetch(daemon, "/release")).status, 200)
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})

package/test/release-group.test.js

@@ -0,0 +1,58 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import test from "node:test"
+import ReleaseGroup from "../src/release-group.js"
+import {normalizeConfig} from "../src/config.js"
+
+/**
+ * @param {import("../src/json.js").JsonValue} webProcess - The single proxied process definition.
+ * @returns {ReleaseGroup} A release group ready for buildProcess.
+ */
+function buildRelease(webProcess) {
+  const config = normalizeConfig({
+    application: "demo",
+    control: {path: "/tmp/rollbridge-release-group.sock"},
+    processes: [webProcess],
+    proxy: {host: "127.0.0.1", port: 0}
+  })
+
+  return new ReleaseGroup({config, logger: () => {}, releaseId: "v1", releasePath: "/tmp/rel", revision: "v1"})
+}
+
+test("templates interpolate values from the daemon environment", () => {
+  const release = buildRelease({
+    command: "run --token {{env.ROLLBRIDGE_ENV_TEST}}",
+    env: {DOWNSTREAM_TOKEN: "{{env.ROLLBRIDGE_ENV_TEST}}"},
+    id: "web",
+    policy: "proxied",
+    port: {from: 0, to: 0}
+  })
+
+  process.env.ROLLBRIDGE_ENV_TEST = "from-daemon"
+
+  try {
+    const managed = release.buildProcess(release.config.processes[0])
+
+    assert.equal(managed.command, "run --token from-daemon")
+    assert.equal(managed.env.DOWNSTREAM_TOKEN, "from-daemon")
+  } finally {
+    delete process.env.ROLLBRIDGE_ENV_TEST
+  }
+})
+
+test("a referenced daemon environment variable that is unset fails fast", () => {
+  const release = buildRelease({
+    command: "run {{env.ROLLBRIDGE_ENV_MISSING}}",
+    id: "web",
+    policy: "proxied",
+    port: {from: 0, to: 0}
+  })
+
+  delete process.env.ROLLBRIDGE_ENV_MISSING
+
+  assert.throws(
+    () => release.buildProcess(release.config.processes[0]),
+    /Missing template value for \{\{env.ROLLBRIDGE_ENV_MISSING\}\}/
+  )
+})

package/test/rollbridge.test.js

@@ -213,6 +213,29 @@ test("a control socket held by a non-Rollbridge process reports a generic confli
   }
 })
 
+test("applies the configured control socket permission mode", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-test-"))
+  const socketPath = path.join(root, "rollbridge.sock")
+  const config = normalizeConfig({
+    application: "rollbridge-test",
+    control: {mode: "660", path: socketPath},
+    processes: [{command: "true", id: "web", policy: "proxied", port: {from: 0, to: 0}}],
+    proxy: {host: "127.0.0.1", port: 0}
+  })
+  const daemon = new RollbridgeDaemon({config, logger: () => {}})
+
+  await daemon.start()
+
+  try {
+    const stats = await fs.stat(socketPath)
+
+    assert.equal(stats.mode & 0o777, 0o660)
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
 test("deploy can ensure the daemon before sending the release command", async () => {
   const fixture = await createFixture()
   const configPath = await writeConfigFile(fixture.config, fixture.root)