rollbridge 0.1.5 → 0.1.6

package/test/rollbridge.test.js

@@ -1,6 +1,8 @@
 // @ts-check
 
 import assert from "node:assert/strict"
+import {spawn} from "node:child_process"
+import {once} from "node:events"
 import fs from "node:fs/promises"
 import net from "node:net"
 import os from "node:os"
@@ -10,15 +12,51 @@ import {fileURLToPath} 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 {runCli} from "../src/cli.js"
 
 const currentDir = path.dirname(fileURLToPath(import.meta.url))
 const binPath = path.join(currentDir, "..", "bin", "rollbridge")
 const dependentAppPath = path.join(currentDir, "fixtures", "dependent-app.js")
 const dummyAppPath = path.join(currentDir, "fixtures", "dummy-app.js")
+const memoryHogPath = path.join(currentDir, "fixtures", "memory-hog.js")
 const serviceAppPath = path.join(currentDir, "fixtures", "service-app.js")
 const singletonAppPath = path.join(currentDir, "fixtures", "singleton-app.js")
 
+test("a nonBlockingDrain worker stops immediately while its release is still draining", async () => {
+  const fixture = await createFixture({nonBlockingDrainWorker: true})
+  const daemon = await startDaemon(fixture.config)
+  /** @type {WebSocket | undefined} */
+  let socket
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+
+    // An open WebSocket keeps v1's connection drain pending after v2 takes over.
+    socket = await openWebSocket(daemon)
+    await daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"})
+
+    // The nonBlockingDrain worker is stopped right away, in parallel with the connection drain.
+    await waitFor(() => {
+      const draining = daemon.status().releases.find((release) => release.releaseId === "v1")
+
+      return draining?.processes.find((processStatus) => processStatus.id === "worker")?.state === "stopped"
+    })
+
+    const v1 = statusRelease(daemon, "v1")
+
+    // The release is still draining (the WebSocket is held) and its proxied process is still
+    // serving, but the worker has already drained.
+    assert.equal(v1.state, "draining")
+    assert.equal(v1.processes.find((processStatus) => processStatus.id === "web")?.state, "running")
+    assert.equal(v1.processes.find((processStatus) => processStatus.id === "worker")?.state, "stopped")
+  } finally {
+    if (socket) socket.close()
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
 test("deploy switches new HTTP traffic while old WebSockets drain", async () => {
   const fixture = await createFixture()
   const daemon = await startDaemon(fixture.config)
@@ -205,6 +243,36 @@ test("service processes start before releases and restart with the latest deploy
   }
 })
 
+test("a replicated companion starts one instance per replica, and restart targets one or all", async () => {
+  const fixture = await createFixture({companionReplicas: 3})
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+
+    const release = daemon.status().releases.find((candidate) => candidate.state === "active")
+
+    assert.ok(release)
+
+    const workerIds = release.processes.filter((processStatus) => processStatus.id.startsWith("worker")).map((processStatus) => processStatus.id).sort()
+
+    assert.deepEqual(workerIds, ["worker#0", "worker#1", "worker#2"])
+
+    // A specific replica id restarts only that replica.
+    const one = await daemon.restartProcesses({processId: "worker#1"})
+
+    assert.deepEqual(one.restarted, ["worker#1"])
+
+    // The base id restarts every replica.
+    const all = /** @type {string[]} */ ((await daemon.restartProcesses({processId: "worker"})).restarted)
+
+    assert.deepEqual([...all].sort(), ["worker#0", "worker#1", "worker#2"])
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
 test("restart bounces a single process by id", async () => {
   const fixture = await createFixture({includeService: true})
   const daemon = await startDaemon(fixture.config)
@@ -336,6 +404,383 @@ test("the restart control command bounces a process over the socket", async () =
   }
 })
 
+test("status and events distinguish deploy starts from manual restarts", async () => {
+  const fixture = await createFixture({includeService: true})
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+
+    const afterDeploy = daemon.status().services.find((service) => service.id === "beacon")
+
+    assert.ok(afterDeploy)
+    assert.equal(afterDeploy.process.lastStartReason, "deploy")
+
+    await daemon.restartProcesses({processId: "beacon"})
+
+    const afterRestart = daemon.status().services.find((service) => service.id === "beacon")
+
+    assert.ok(afterRestart)
+    assert.equal(afterRestart.process.lastStartReason, "manual")
+
+    const events = /** @type {import("../src/event-log.js").DaemonEvent[]} */ ((await sendControlCommand({
+      command: {command: "events"},
+      path: fixture.config.control.path
+    })).events)
+    const startReasons = events.filter((event) => event.message === "process started").map((event) => event.data.reason)
+
+    assert.ok(startReasons.includes("deploy"), JSON.stringify(startReasons))
+    assert.ok(startReasons.includes("manual"), JSON.stringify(startReasons))
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("persists daemon state to statePath and removes it on a clean shutdown", async () => {
+  const fixture = await createFixture({persistState: true})
+  const daemon = await startDaemon(fixture.config)
+  let stateAfterShutdown
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+
+    // The state write is fire-and-forget (deploy doesn't block on it), so wait for it to land.
+    await waitFor(async () => {
+      const persisted = /** @type {{activeReleaseId: string} | undefined} */ (await readState(fixture.statePath))
+
+      return persisted?.activeReleaseId === "v1"
+    })
+
+    await daemon.shutdown()
+    stateAfterShutdown = await readState(fixture.statePath)
+  } finally {
+    if (!daemon.stopping) await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+
+  assert.equal(stateAfterShutdown, undefined, "state file removed on clean shutdown")
+})
+
+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)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+
+    // Shut down immediately — the deploy's fire-and-forget persist may still be in flight.
+    await daemon.shutdown()
+
+    assert.equal(await readState(fixture.statePath), undefined, "state file must not be recreated by an in-flight write")
+  } finally {
+    if (!daemon.stopping) await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("reports orphaned managed processes from a previous daemon's state", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-test-"))
+  const statePath = path.join(dir, "state.json")
+  // A live process standing in for a leftover managed child from a crashed daemon.
+  const leftover = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], {stdio: "ignore"})
+
+  await once(leftover, "spawn")
+
+  /** @type {{data: Record<string, import("../src/json.js").JsonValue>, message: string}[]} */
+  const logs = []
+  const config = normalizeConfig({
+    application: "rollbridge-test",
+    control: {path: path.join(dir, "rollbridge.sock")},
+    processes: [{command: "true", id: "web", policy: "proxied", port: {from: 0, to: 0}}],
+    proxy: {host: "127.0.0.1", port: 0},
+    statePath
+  })
+  const daemon = new RollbridgeDaemon({config, logger: (message, data = {}) => { logs.push({data, message}) }})
+
+  try {
+    // A prior daemon left a worker with this (still-alive) pid.
+    await writeState(statePath, {
+      activeReleaseId: "v1",
+      releases: [{processes: [{id: "worker", pid: leftover.pid}], releaseId: "v1"}],
+      services: [],
+      singletons: []
+    })
+
+    await daemon.reportOrphans()
+
+    assert.ok(logs.some((entry) => entry.message === "orphaned managed process detected" && entry.data.pid === leftover.pid), JSON.stringify(logs))
+
+    // A dead pid is not reported.
+    logs.length = 0
+    await writeState(statePath, {
+      activeReleaseId: "v1",
+      releases: [{processes: [{id: "worker", pid: 2147483646}], releaseId: "v1"}],
+      services: [],
+      singletons: []
+    })
+    await daemon.reportOrphans()
+
+    assert.ok(!logs.some((entry) => entry.message === "orphaned managed process detected"))
+  } finally {
+    leftover.kill("SIGKILL")
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})
+
+test("status surfaces still-alive orphaned processes from a previous daemon and drops them once gone", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-test-"))
+  const statePath = path.join(dir, "state.json")
+  const leftover = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], {stdio: "ignore"})
+
+  await once(leftover, "spawn")
+
+  const config = normalizeConfig({
+    application: "rollbridge-test",
+    control: {path: path.join(dir, "rollbridge.sock")},
+    processes: [{command: "true", id: "web", policy: "proxied", port: {from: 0, to: 0}}],
+    proxy: {host: "127.0.0.1", port: 0},
+    statePath
+  })
+  const daemon = new RollbridgeDaemon({config, logger: () => {}})
+
+  try {
+    // A prior daemon left a worker with this (still-alive) pid.
+    await writeState(statePath, {
+      activeReleaseId: "v1",
+      releases: [{processes: [{id: "worker", pid: leftover.pid}], releaseId: "v1"}],
+      services: [],
+      singletons: []
+    })
+
+    await daemon.reportOrphans()
+
+    // status reflects the still-running child even though the daemon cannot re-manage it.
+    assert.deepEqual(daemon.status().orphans, [{id: "worker", pid: leftover.pid, releaseId: "v1"}])
+
+    // Once the leftover is stopped, status re-checks liveness and drops it.
+    leftover.kill("SIGKILL")
+    await waitFor(() => daemon.status().orphans.length === 0)
+    assert.deepEqual(daemon.status().orphans, [])
+
+    // The dead entry is pruned from the underlying list, not merely filtered, so a recycled pid
+    // can't resurrect a cleared orphan.
+    assert.deepEqual(daemon.orphans, [])
+  } finally {
+    leftover.kill("SIGKILL")
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})
+
+test("the daemon records a structured event history served by the events command", async () => {
+  const fixture = await createFixture()
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+
+    const response = await sendControlCommand({
+      command: {command: "events"},
+      path: fixture.config.control.path
+    })
+    const events = /** @type {import("../src/event-log.js").DaemonEvent[]} */ (response.events)
+    const messages = events.map((event) => event.message)
+
+    assert.ok(messages.includes("deploy starting"), JSON.stringify(messages))
+    assert.ok(messages.includes("traffic switched"), JSON.stringify(messages))
+
+    const switched = events.find((event) => event.message === "traffic switched")
+
+    assert.ok(switched)
+    assert.equal(switched.data.releaseId, "v1")
+    assert.match(switched.at, /^\d{4}-\d{2}-\d{2}T.*Z$/)
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("the events command honors --limit and records failed commands", async () => {
+  const fixture = await createFixture()
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+
+    // An unknown command is rejected and recorded as a "command failed" event.
+    await assert.rejects(() => sendControlCommand({
+      command: {command: "bogus"},
+      path: fixture.config.control.path
+    }))
+
+    const all = /** @type {import("../src/event-log.js").DaemonEvent[]} */ ((await sendControlCommand({
+      command: {command: "events"},
+      path: fixture.config.control.path
+    })).events)
+
+    assert.ok(all.some((event) => event.message === "command failed"))
+
+    const limited = /** @type {import("../src/event-log.js").DaemonEvent[]} */ ((await sendControlCommand({
+      command: {command: "events", limit: 1},
+      path: fixture.config.control.path
+    })).events)
+
+    assert.equal(limited.length, 1)
+    assert.deepEqual(limited[0], all[all.length - 1])
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("a process over its memory limit is restarted with reason memory", {skip: process.platform !== "linux" && "requires /proc (Linux)"}, async () => {
+  const limitBytes = 64 * 1024 * 1024
+  const fixture = await createFixture({memoryLimitBytes: limitBytes})
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+
+    // The hog allocates ~4x the limit, so the monitor restarts it.
+    await waitFor(() => (activeProcessStatus(daemon, "hog")?.memoryRestarts ?? 0) >= 1, 10000)
+
+    const hog = activeProcessStatus(daemon, "hog")
+
+    assert.ok(hog, "hog process should be present")
+    assert.ok(hog.memoryRestarts >= 1, `expected a memory restart, got ${hog.memoryRestarts}`)
+    assert.equal(hog.lastStartReason, "memory")
+    assert.equal(typeof hog.lastMemoryRestartAt, "string")
+
+    // rssBytes is sampled on the monitor's interval; wait for a measurement of the running process.
+    await waitFor(() => {
+      const rssBytes = activeProcessStatus(daemon, "hog")?.rssBytes
+
+      return typeof rssBytes === "number" && rssBytes > 0
+    }, 5000)
+
+    // The same monitor sample reports the process tree.
+    const monitored = activeProcessStatus(daemon, "hog")
+
+    assert.ok(monitored)
+    assert.ok(monitored.children.length >= 1, "status should include the process tree")
+    assert.ok(monitored.children.some((child) => typeof child.rssBytes === "number" && child.rssBytes > 0))
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("rollback re-activates the previous release and switches traffic back", async () => {
+  const fixture = await createFixture()
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+    await daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"})
+
+    assert.equal(await fetchText(daemon, "/release"), "v2")
+
+    const result = await daemon.rollback()
+
+    assert.equal(result.activeReleaseId, "v1")
+    assert.equal(result.previousReleaseId, "v2")
+    assert.equal(daemon.status().activeReleaseId, "v1")
+    assert.equal(await fetchText(daemon, "/release"), "v1")
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("rollback --release-id targets a specific retained release", async () => {
+  const fixture = await createFixture()
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+    await daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"})
+    await daemon.deploy({releaseId: "v3", releasePath: fixture.root, revision: "v3"})
+
+    const result = await daemon.rollback({releaseId: "v1"})
+
+    assert.equal(result.activeReleaseId, "v1")
+    assert.equal(await fetchText(daemon, "/release"), "v1")
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("rollback rejects no-previous, unknown, and already-active targets", async () => {
+  const fixture = await createFixture()
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+
+    await assert.rejects(() => daemon.rollback(), /No previous release/)
+    await assert.rejects(() => daemon.rollback({releaseId: "v1"}), /already active/)
+    await assert.rejects(() => daemon.rollback({releaseId: "nope"}), /No retained release "nope"/)
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("rollback to a still-draining release stops the old instance instead of orphaning it", async () => {
+  const fixture = await createFixture()
+  const daemon = await startDaemon(fixture.config)
+  /** @type {WebSocket | undefined} */
+  let socket
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+
+    // An open WebSocket keeps v1's connection count > 0, so it stays draining after v2.
+    socket = await openWebSocket(daemon)
+    await daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"})
+
+    const draining = statusRelease(daemon, "v1")
+
+    assert.equal(draining.state, "draining")
+
+    const oldWebPid = draining.processes.find((processStatus) => processStatus.id === "web")?.pid
+
+    assert.ok(oldWebPid, "the draining release should have a running web process")
+
+    await daemon.rollback({releaseId: "v1"})
+
+    assert.equal(daemon.status().activeReleaseId, "v1")
+    // The old draining instance was stopped before its id was reused, so its process is gone.
+    assert.throws(() => process.kill(/** @type {number} */ (oldWebPid), 0), /ESRCH/)
+  } finally {
+    if (socket) socket.close()
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
+test("the rollback control command switches traffic over the socket", async () => {
+  const fixture = await createFixture()
+  const daemon = await startDaemon(fixture.config)
+
+  try {
+    await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
+    await daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"})
+
+    const response = await sendControlCommand({
+      command: {command: "rollback"},
+      path: fixture.config.control.path
+    })
+
+    assert.equal(response.activeReleaseId, "v1")
+    assert.equal(await fetchText(daemon, "/release"), "v1")
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
 test("control socket accepts deploy and status commands", async () => {
   const fixture = await createFixture()
   const daemon = await startDaemon(fixture.config)
@@ -394,6 +839,34 @@ test("starting a second daemon on a live control socket reports the running daem
   }
 })
 
+test("the daemon applies control.owner and control.group to the bound socket", {skip: process.platform !== "linux" && "requires POSIX chown"}, async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-test-"))
+  const socketPath = path.join(root, "rollbridge.sock")
+  const {uid, username} = os.userInfo()
+  const gid = process.getgid?.() ?? 0
+  const config = normalizeConfig({
+    application: "rollbridge-test",
+    // owner by name (resolved to the current uid); group by numeric id. Both are the current
+    // user's, so a non-root daemon can chown the socket to itself.
+    control: {group: gid, owner: username, 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: () => {}})
+
+  try {
+    await daemon.start()
+
+    const stats = await fs.stat(socketPath)
+
+    assert.equal(stats.uid, uid)
+    assert.equal(stats.gid, gid)
+  } finally {
+    await daemon.shutdown()
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
 test("a control socket held by a non-Rollbridge process reports a generic conflict", async () => {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-test-"))
   const socketPath = path.join(root, "busy.sock")
@@ -499,13 +972,14 @@ test("deploy can ensure the daemon before sending the release command", async ()
 })
 
 /**
- * @param {{includeCompanion?: boolean, includeService?: boolean, includeSingleton?: boolean, proxyHost?: string, singletonCwd?: string, webCommand?: string, webDependsOnService?: boolean, webHealthTimeoutMs?: number}} [options] - Fixture options.
- * @returns {Promise<{config: import("../src/config.js").RollbridgeConfig, root: string, serviceLogPath: string, singletonLogPath: string}>} Fixture data.
+ * @param {{companionReplicas?: number, includeCompanion?: boolean, includeService?: boolean, includeSingleton?: boolean, memoryLimitBytes?: number, nonBlockingDrainWorker?: boolean, persistState?: boolean, proxyHost?: string, singletonCwd?: string, webCommand?: string, webDependsOnService?: boolean, webHealthTimeoutMs?: number}} [options] - Fixture options.
+ * @returns {Promise<{config: import("../src/config.js").RollbridgeConfig, root: string, serviceLogPath: string, singletonLogPath: string, statePath: string}>} Fixture data.
  */
 async function createFixture(options = {}) {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-test-"))
   const serviceLogPath = path.join(root, "service.log")
   const singletonLogPath = path.join(root, "singleton.log")
+  const statePath = path.join(root, "rollbridge.state.json")
   /** @type {Array<Record<string, import("../src/json.js").JsonValue>>} */
   const processes = []
 
@@ -530,6 +1004,36 @@ async function createFixture(options = {}) {
     })
   }
 
+  if (options.companionReplicas) {
+    processes.push({
+      command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify("setInterval(() => {}, 1000)")}`,
+      id: "worker",
+      policy: "companion",
+      replicas: options.companionReplicas
+    })
+  }
+
+  if (options.nonBlockingDrainWorker) {
+    processes.push({
+      command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify("setInterval(() => {}, 1000)")}`,
+      id: "worker",
+      nonBlockingDrain: true,
+      policy: "companion"
+    })
+  }
+
+  if (options.memoryLimitBytes) {
+    processes.push({
+      command: `${JSON.stringify(process.execPath)} ${JSON.stringify(memoryHogPath)}`,
+      env: {
+        ROLLBRIDGE_HOG_BYTES: String(options.memoryLimitBytes * 4)
+      },
+      id: "hog",
+      memory: {checkIntervalMs: 100, limitBytes: options.memoryLimitBytes, warnBytes: 0},
+      policy: "companion"
+    })
+  }
+
   processes.push({
     command: options.webCommand || (options.webDependsOnService
       ? `${JSON.stringify(process.execPath)} ${JSON.stringify(dependentAppPath)}`
@@ -569,10 +1073,11 @@ async function createFixture(options = {}) {
       healthTimeoutMs: 3000,
       host: options.proxyHost || "127.0.0.1",
       port: 0
-    }
+    },
+    ...(options.persistState ? {statePath} : {})
   })
 
-  return {config, root, serviceLogPath, singletonLogPath}
+  return {config, root, serviceLogPath, singletonLogPath, statePath}
 }
 
 /**
@@ -697,10 +1202,11 @@ async function writeConfigFile(config, root) {
 
 /**
  * @param {() => Promise<boolean> | boolean} callback - Probe callback.
+ * @param {number} [timeoutMs] - How long to wait before giving up (default 3000).
  * @returns {Promise<void>} Resolves when callback returns true.
  */
-async function waitFor(callback) {
-  const deadline = Date.now() + 3000
+async function waitFor(callback, timeoutMs = 3000) {
+  const deadline = Date.now() + timeoutMs
 
   while (Date.now() < deadline) {
     if (await callback()) return
@@ -709,3 +1215,14 @@ async function waitFor(callback) {
 
   throw new Error("Timed out waiting for condition")
 }
+
+/**
+ * @param {RollbridgeDaemon} daemon - Daemon.
+ * @param {string} processId - Process id within the active release.
+ * @returns {import("../src/managed-process.js").ManagedProcessStatus | undefined} The process status, if present.
+ */
+function activeProcessStatus(daemon, processId) {
+  const release = daemon.status().releases.find((candidate) => candidate.state === "active")
+
+  return release ? release.processes.find((processStatus) => processStatus.id === processId) : undefined
+}

package/test/state-store.test.js

@@ -0,0 +1,69 @@
+// @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 {clearState, readState, writeState} from "../src/state-store.js"
+
+test("writeState then readState round-trips a snapshot", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-state-"))
+  const statePath = path.join(dir, "state.json")
+
+  try {
+    await writeState(statePath, {activeReleaseId: "v1", releases: [{releaseId: "v1"}]})
+
+    const state = /** @type {{activeReleaseId: string}} */ (await readState(statePath))
+
+    assert.equal(state.activeReleaseId, "v1")
+  } finally {
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})
+
+test("readState returns undefined for a missing or unparseable file", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-state-"))
+  const statePath = path.join(dir, "state.json")
+
+  try {
+    assert.equal(await readState(statePath), undefined)
+
+    await fs.writeFile(statePath, "{not json")
+
+    assert.equal(await readState(statePath), undefined)
+  } finally {
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})
+
+test("concurrent writes leave a complete, uncorrupted snapshot", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-state-"))
+  const statePath = path.join(dir, "state.json")
+
+  try {
+    await Promise.all([writeState(statePath, {n: 1}), writeState(statePath, {n: 2}), writeState(statePath, {n: 3})])
+
+    const state = /** @type {{n: number}} */ (await readState(statePath))
+
+    // A complete snapshot from one of the writers — never a partial/corrupt file or a temp race.
+    assert.ok(state && typeof state.n === "number")
+  } finally {
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})
+
+test("clearState removes the file and ignores a missing one", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-state-"))
+  const statePath = path.join(dir, "state.json")
+
+  try {
+    await writeState(statePath, {ok: true})
+    await clearState(statePath)
+
+    assert.equal(await readState(statePath), undefined)
+    await clearState(statePath)
+  } finally {
+    await fs.rm(dir, {force: true, recursive: true})
+  }
+})