rollbridge 0.1.2 → 0.1.5

package/test/doctor.test.js

@@ -0,0 +1,228 @@
+// @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 from "node:test"
+import RollbridgeDaemon from "../src/daemon.js"
+import {normalizeConfig} from "../src/config.js"
+import {runEnvironmentChecks} from "../src/doctor.js"
+import {runCli} from "../src/cli.js"
+
+/**
+ * @param {object} args - Options.
+ * @param {string} args.controlPath - Control socket path.
+ * @param {number} args.proxyPort - Proxy port.
+ * @returns {import("../src/config.js").RollbridgeConfig} Normalized config.
+ */
+function buildConfig({controlPath, proxyPort}) {
+  return normalizeConfig({
+    application: "doctor-test",
+    control: {path: controlPath},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: proxyPort}
+  })
+}
+
+/**
+ * @returns {Promise<number>} A port that was free when probed.
+ */
+async function freePort() {
+  return await new Promise((resolve) => {
+    const server = net.createServer()
+
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address()
+      const port = address && typeof address === "object" ? address.port : 0
+
+      server.close(() => resolve(port))
+    })
+  })
+}
+
+/**
+ * @returns {Promise<{port: number, server: import("node:net").Server}>} An occupied port and its server.
+ */
+async function occupyPort() {
+  const server = net.createServer()
+  const port = await new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address()
+
+      resolve(address && typeof address === "object" ? address.port : 0)
+    })
+  })
+
+  return {port, server}
+}
+
+/**
+ * @param {DoctorCheck[]} checks - Checks.
+ * @param {string} name - Check name.
+ * @returns {DoctorCheck} The matching check.
+ * @typedef {import("../src/doctor.js").DoctorCheck} DoctorCheck
+ */
+function checkNamed(checks, name) {
+  const check = checks.find((candidate) => candidate.name === name)
+
+  assert.ok(check, `expected a "${name}" check`)
+
+  return check
+}
+
+test("runEnvironmentChecks passes when no daemon runs, the port is free, and the directory is writable", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+
+  try {
+    const checks = await runEnvironmentChecks(buildConfig({controlPath: path.join(root, "rollbridge.sock"), proxyPort: await freePort()}))
+
+    assert.equal(checkNamed(checks, "control socket").ok, true)
+    assert.equal(checkNamed(checks, "control socket directory").ok, true)
+    assert.equal(checkNamed(checks, "proxy port").ok, true)
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("runEnvironmentChecks reports an unavailable proxy port", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const {port, server} = await occupyPort()
+
+  try {
+    const checks = await runEnvironmentChecks(buildConfig({controlPath: path.join(root, "rollbridge.sock"), proxyPort: port}))
+    const proxyCheck = checkNamed(checks, "proxy port")
+
+    assert.equal(proxyCheck.ok, false)
+    assert.match(proxyCheck.detail, /unavailable/)
+  } finally {
+    await new Promise((resolve) => server.close(() => resolve(undefined)))
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("runEnvironmentChecks reports a missing control socket directory", async () => {
+  const checks = await runEnvironmentChecks(buildConfig({controlPath: "/rollbridge-doctor-missing-dir/rollbridge.sock", proxyPort: await freePort()}))
+  const directoryCheck = checkNamed(checks, "control socket directory")
+
+  assert.equal(directoryCheck.ok, false)
+  assert.match(directoryCheck.detail, /missing or not writable/)
+})
+
+test("runEnvironmentChecks fails when a Rollbridge daemon already holds the socket and port", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const config = buildConfig({controlPath: path.join(root, "rollbridge.sock"), proxyPort: await freePort()})
+  const daemon = new RollbridgeDaemon({config, logger: () => {}})
+
+  await daemon.start()
+
+  try {
+    const checks = await runEnvironmentChecks(config)
+    const socketCheck = checkNamed(checks, "control socket")
+
+    // A daemon already running means `rollbridge daemon` would fail to bind, so doctor must fail too.
+    assert.equal(socketCheck.ok, false)
+    assert.match(socketCheck.detail, /a Rollbridge daemon for "doctor-test" is already running/)
+    assert.equal(checkNamed(checks, "proxy port").ok, false)
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+/**
+ * Runs the CLI while capturing console output.
+ * @param {string[]} argv - Process argv.
+ * @returns {Promise<string>} Captured stdout and stderr lines.
+ */
+async function captureCli(argv) {
+  const originalLog = console.log
+  const originalError = console.error
+  /** @type {string[]} */
+  const lines = []
+  const collect = (/** @type {string[]} */ ...args) => { lines.push(args.map((arg) => String(arg)).join(" ")) }
+
+  console.log = collect
+  console.error = collect
+
+  try {
+    await runCli(argv)
+  } finally {
+    console.log = originalLog
+    console.error = originalError
+  }
+
+  return lines.join("\n")
+}
+
+test("doctor CLI passes for a valid, bindable config", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const rawConfig = {
+    application: "doctor-cli-test",
+    control: {path: path.join(root, "rollbridge.sock")},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: await freePort()}
+  }
+
+  await fs.writeFile(path.join(root, "rollbridge.js"), `module.exports = ${JSON.stringify(rawConfig)}\n`)
+
+  try {
+    const output = await captureCli(["node", "rollbridge", "doctor", "-c", path.join(root, "rollbridge.js")])
+
+    assert.match(output, /All checks passed\./)
+    assert.notEqual(process.exitCode, 1)
+  } finally {
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("doctor CLI fails and exits non-zero for an invalid config", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+
+  await fs.writeFile(path.join(root, "rollbridge.js"), "module.exports = {application: \"x\", proxy: {port: 8182}, processes: []}\n")
+
+  try {
+    const output = await captureCli(["node", "rollbridge", "doctor", "-c", path.join(root, "rollbridge.js")])
+
+    assert.equal(process.exitCode, 1)
+    assert.match(output, /✗ config:/)
+  } finally {
+    process.exitCode = 0
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("doctor --json emits structured checks", async () => {
+  const okRoot = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+  const okConfig = {
+    application: "doctor-json-test",
+    control: {path: path.join(okRoot, "rollbridge.sock")},
+    processes: [{command: "run web", id: "web", policy: "proxied", port: {from: 18000, to: 18099}}],
+    proxy: {host: "127.0.0.1", port: await freePort()}
+  }
+
+  await fs.writeFile(path.join(okRoot, "rollbridge.js"), `module.exports = ${JSON.stringify(okConfig)}\n`)
+
+  const badRoot = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-doctor-"))
+
+  await fs.writeFile(path.join(badRoot, "rollbridge.js"), "module.exports = {application: \"x\", proxy: {port: 8182}, processes: []}\n")
+
+  try {
+    const passing = JSON.parse(await captureCli(["node", "rollbridge", "doctor", "--json", "-c", path.join(okRoot, "rollbridge.js")]))
+
+    assert.equal(passing.ok, true)
+    assert.ok(passing.checks.some((/** @type {{name: string, ok: boolean}} */ check) => check.name === "proxy port" && check.ok === true))
+    assert.notEqual(process.exitCode, 1)
+
+    const failing = JSON.parse(await captureCli(["node", "rollbridge", "doctor", "--json", "-c", path.join(badRoot, "rollbridge.js")]))
+
+    assert.equal(failing.ok, false)
+    assert.ok(failing.checks.some((/** @type {{name: string, ok: boolean}} */ check) => check.name === "config" && check.ok === false))
+    assert.equal(process.exitCode, 1)
+  } finally {
+    process.exitCode = 0
+    await fs.rm(okRoot, {force: true, recursive: true})
+    await fs.rm(badRoot, {force: true, recursive: true})
+  }
+})

package/test/fixtures/crasher.js

@@ -0,0 +1,2 @@
+// Exits non-zero shortly after starting, to exercise auto-restart behavior.
+setTimeout(() => process.exit(1), 40)

package/test/health.test.js

@@ -0,0 +1,63 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import http from "node:http"
+import test from "node:test"
+import {waitForHealth} from "../src/health.js"
+
+/**
+ * Starts a health server that records when it first receives a probe.
+ * @returns {Promise<{firstProbeDelay: () => number, port: number, close: () => Promise<void>}>} Server handle.
+ */
+async function startHealthServer() {
+  const start = Date.now()
+  let firstProbeAt = 0
+  const server = http.createServer((request, response) => {
+    if (firstProbeAt === 0) firstProbeAt = Date.now()
+
+    response.writeHead(200, {"Content-Type": "text/plain"})
+    response.end("ok")
+  })
+
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve(undefined)))
+
+  const address = server.address()
+
+  return {
+    close: () => new Promise((resolve) => server.close(() => resolve(undefined))),
+    firstProbeDelay: () => firstProbeAt - start,
+    port: address && typeof address === "object" ? address.port : 0
+  }
+}
+
+test("waitForHealth delays the first probe by startDelayMs", async () => {
+  const server = await startHealthServer()
+
+  try {
+    await waitForHealth({
+      health: {intervalMs: 25, path: "/ping", startDelayMs: 200, timeoutMs: 2000},
+      host: "127.0.0.1",
+      port: server.port
+    })
+
+    assert.ok(server.firstProbeDelay() >= 180, `expected first probe to be delayed ~200ms, was ${server.firstProbeDelay()}ms`)
+  } finally {
+    await server.close()
+  }
+})
+
+test("waitForHealth probes immediately when startDelayMs is 0", async () => {
+  const server = await startHealthServer()
+
+  try {
+    await waitForHealth({
+      health: {intervalMs: 25, path: "/ping", startDelayMs: 0, timeoutMs: 2000},
+      host: "127.0.0.1",
+      port: server.port
+    })
+
+    assert.ok(server.firstProbeDelay() < 150, `expected an immediate first probe, was ${server.firstProbeDelay()}ms`)
+  } finally {
+    await server.close()
+  }
+})

package/test/logs.test.js

@@ -0,0 +1,99 @@
+// @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"
+import {formatLogSources, runCli} from "../src/cli.js"
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url))
+const dummyAppPath = path.join(currentDir, "fixtures", "dummy-app.js")
+
+test("formatLogSources renders a section per process with timestamped lines", () => {
+  const output = formatLogSources([
+    {id: "web", logs: [{at: "2026-05-22T00:00:00.000Z", line: "listening", stream: "stdout"}], source: "release v1 (active)"},
+    {id: "beacon", logs: [], source: "service"}
+  ], undefined)
+
+  assert.match(output, /== web \[release v1 \(active\)\] ==/)
+  assert.match(output, /2026-05-22T00:00:00\.000Z \[stdout\] listening/)
+  assert.match(output, /== beacon \[service\] ==/)
+  assert.match(output, /\(no recent output\)/)
+})
+
+test("formatLogSources filters to a single process id", () => {
+  const sources = [
+    {id: "web", logs: [], source: "release v1 (active)"},
+    {id: "beacon", logs: [], source: "service"}
+  ]
+
+  const output = formatLogSources(sources, "web")
+
+  assert.match(output, /== web /)
+  assert.doesNotMatch(output, /beacon/)
+})
+
+test("formatLogSources reports when there are no processes or no match", () => {
+  assert.equal(formatLogSources([], undefined), "No managed processes.")
+  assert.equal(
+    formatLogSources([{id: "web", logs: [], source: "release v1 (active)"}], "missing"),
+    'No process found with id "missing".'
+  )
+})
+
+test("logs CLI prints captured output per managed process", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-logs-"))
+  const socketPath = path.join(root, "rollbridge.sock")
+  const rawConfig = {
+    application: "rollbridge-logs-test",
+    control: {path: socketPath},
+    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}
+      }
+    ],
+    proxy: {host: "127.0.0.1", port: 0}
+  }
+
+  // CommonJS config file so the CLI can load it from a temp dir on any Node version.
+  await fs.writeFile(path.join(root, "rollbridge.js"), `module.exports = ${JSON.stringify(rawConfig)}\n`)
+
+  const daemon = new RollbridgeDaemon({config: normalizeConfig(rawConfig), logger: () => {}})
+
+  await daemon.start()
+
+  const originalLog = console.log
+  /** @type {string[]} */
+  const lines = []
+
+  console.log = (/** @type {string[]} */ ...args) => { lines.push(args.map((arg) => String(arg)).join(" ")) }
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: root, revision: "v1"})
+    await runCli(["node", "rollbridge", "logs", "-c", path.join(root, "rollbridge.js")])
+
+    assert.match(lines.join("\n"), /== web \[release v1 \(active\)\] ==/)
+
+    lines.length = 0
+    await runCli(["node", "rollbridge", "logs", "--json", "-c", path.join(root, "rollbridge.js")])
+
+    const parsed = JSON.parse(lines.join("\n"))
+    const web = parsed.find((/** @type {{id: string, logs: import("../src/managed-process.js").ManagedProcessLog[], source: string}} */ entry) => entry.id === "web")
+
+    assert.ok(web, "expected a web entry in the JSON output")
+    assert.match(web.source, /release v1 \(active\)/)
+    assert.ok(Array.isArray(web.logs))
+  } finally {
+    console.log = originalLog
+    await daemon.shutdown()
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})

package/test/managed-process.test.js

@@ -1,9 +1,13 @@
 // @ts-check
 
 import assert from "node:assert/strict"
+import path from "node:path"
 import test from "node:test"
+import {fileURLToPath} from "node:url"
 import ManagedProcess from "../src/managed-process.js"
 
+const crasherPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "fixtures", "crasher.js")
+
 /**
  * Builds a managed process that is never spawned, for exercising output retention directly.
  * @param {number} outputLines - Recent output lines to retain and report.
@@ -23,6 +27,21 @@ function buildProcess(outputLines) {
   })
 }
 
+/**
+ * @param {() => 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 (callback()) return
+    await new Promise((resolve) => setTimeout(resolve, 25))
+  }
+
+  throw new Error("Timed out waiting for condition")
+}
+
 test("retains and reports only the configured number of recent output lines", () => {
   const managed = buildProcess(3)
 
@@ -44,3 +63,130 @@ test("keeps every output line when fewer than the retention limit are produced",
 
   assert.deepEqual(logs.map((entry) => entry.line), ["one", "two"])
 })
+
+test("reports zeroed restart and uptime fields before the process starts", () => {
+  const status = buildProcess(50).status()
+
+  assert.equal(status.restarts, 0)
+  assert.equal(status.startedAt, undefined)
+  assert.equal(status.uptimeMs, undefined)
+  assert.equal(status.state, "stopped")
+})
+
+test("counts automatic restarts and reports startedAt and uptime while running", async () => {
+  const managed = new ManagedProcess({
+    command: `${JSON.stringify(process.execPath)} ${JSON.stringify(crasherPath)}`,
+    cwd: undefined,
+    env: {},
+    id: "crasher",
+    logger: () => {},
+    outputLines: 50,
+    restartDelayMs: 20,
+    shouldRestart: () => true,
+    stopTimeoutMs: 500
+  })
+
+  try {
+    await managed.start()
+
+    const initial = managed.status()
+
+    assert.equal(initial.restarts, 0)
+    assert.equal(initial.state, "running")
+    assert.equal(typeof initial.startedAt, "string")
+    assert.ok(typeof initial.uptimeMs === "number" && initial.uptimeMs >= 0)
+
+    // The fixture exits non-zero ~40ms after each start, so it keeps auto-restarting.
+    await waitFor(() => managed.status().restarts >= 2)
+
+    assert.ok(managed.status().restarts >= 2)
+  } finally {
+    await managed.stop()
+  }
+})
+
+/**
+ * Builds a managed crasher with a specific restart policy.
+ * @param {import("../src/config.js").RestartConfig} restart - Restart policy.
+ * @returns {ManagedProcess} Managed process.
+ */
+function buildCrasher(restart) {
+  return new ManagedProcess({
+    command: `${JSON.stringify(process.execPath)} ${JSON.stringify(crasherPath)}`,
+    cwd: undefined,
+    env: {},
+    id: "crasher",
+    logger: () => {},
+    outputLines: 50,
+    restart,
+    restartDelayMs: 10,
+    shouldRestart: () => true,
+    stopTimeoutMs: 500
+  })
+}
+
+test("does not auto-restart when the restart policy is disabled (maxRestarts: 0)", async () => {
+  const managed = buildCrasher({backoffFactor: 1, maxDelayMs: 0, maxRestarts: 0, windowMs: 0})
+
+  try {
+    await managed.start()
+
+    // The fixture exits ~40ms after start; with restarts disabled it should stay failed.
+    await waitFor(() => managed.status().state === "failed")
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    assert.equal(managed.status().restarts, 0)
+    assert.equal(managed.status().state, "failed")
+  } finally {
+    await managed.stop()
+  }
+})
+
+test("stops auto-restarting once maxRestarts within the window is reached", async () => {
+  const managed = buildCrasher({backoffFactor: 1, maxDelayMs: 0, maxRestarts: 2, windowMs: 60000})
+
+  try {
+    await managed.start()
+
+    // It restarts at most twice within the window, then gives up and stays failed.
+    await waitFor(() => managed.status().restarts === 2 && managed.status().state === "failed")
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    assert.equal(managed.status().restarts, 2)
+    assert.equal(managed.status().state, "failed")
+  } finally {
+    await managed.stop()
+  }
+})
+
+test("applies exponential backoff to restart delays, capped by maxDelayMs", () => {
+  const capped = buildCrasher({backoffFactor: 2, maxDelayMs: 500, maxRestarts: undefined, windowMs: 0})
+
+  // restartDelayMs (10) * 2 ** attempt, capped at 500.
+  assert.equal(capped.restartDelayFor(0), 10)
+  assert.equal(capped.restartDelayFor(1), 20)
+  assert.equal(capped.restartDelayFor(2), 40)
+  assert.equal(capped.restartDelayFor(6), 500) // 10 * 64 = 640, capped to 500
+  assert.equal(capped.restartDelayFor(7), 500)
+
+  // maxDelayMs: 0 means no cap.
+  const uncapped = buildCrasher({backoffFactor: 3, maxDelayMs: 0, maxRestarts: undefined, windowMs: 0})
+
+  assert.equal(uncapped.restartDelayFor(0), 10)
+  assert.equal(uncapped.restartDelayFor(2), 90)
+})
+
+test("the unlimited constant-delay fast path still applies maxDelayMs", () => {
+  // restartDelayMs (10) above maxDelayMs (5), with no backoff and unlimited restarts.
+  const managed = buildCrasher({backoffFactor: 1, maxDelayMs: 5, maxRestarts: undefined, windowMs: 0})
+
+  assert.equal(managed.restartDelayFor(0), 5)
+
+  /** @type {number | undefined} */
+  let queued
+
+  managed.queueRestart = (delayMs) => { queued = delayMs }
+  managed.scheduleRestart()
+
+  assert.equal(queued, 5)
+})

package/test/package-metadata.test.js

@@ -0,0 +1,29 @@
+// @ts-check
+
+import assert from "node:assert/strict"
+import fs from "node:fs/promises"
+import path from "node:path"
+import test from "node:test"
+import {fileURLToPath} from "node:url"
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+
+test("package.json declares publish metadata", async () => {
+  const pkg = JSON.parse(await fs.readFile(path.join(repoRoot, "package.json"), "utf8"))
+
+  assert.equal(pkg.name, "rollbridge")
+  assert.equal(pkg.license, "MIT")
+  assert.equal(pkg.homepage, "https://github.com/kaspernj/rollbridge#readme")
+  assert.equal(pkg.bugs.url, "https://github.com/kaspernj/rollbridge/issues")
+  assert.equal(pkg.repository.type, "git")
+  assert.match(pkg.repository.url, /github\.com\/kaspernj\/rollbridge/)
+  assert.ok(typeof pkg.author === "string" && pkg.author.length > 0)
+  assert.ok(Array.isArray(pkg.keywords) && pkg.keywords.length > 0)
+})
+
+test("a LICENSE file matching the declared license exists", async () => {
+  const license = await fs.readFile(path.join(repoRoot, "LICENSE"), "utf8")
+
+  assert.match(license, /MIT License/)
+  assert.match(license, /Copyright \(c\) \d{4} kaspernj/)
+})