rollbridge 0.1.19 → 0.1.21

package/README.md

@@ -412,6 +412,15 @@ rollbridge daemon --config /srv/ticket-server/rollbridge.js \
   --boot-attestation sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
 ```
 
+External supervisors that need to replace a foreground owner without waiting
+for its workers to drain add `--takeover-owner`. The candidate starts and
+health-checks the exact release first. Only then does it retire the accepted
+owner's proxy/control listeners; the retired daemon keeps its already-accepted
+workers until their ordinary drain completes while the attested replacement
+binds the stable listeners. Candidate bootstrap failure leaves the accepted
+owner untouched. This is opt-in; ordinary daemon bootstrap and `shutdown` keep
+their existing behavior.
+
 The four bootstrap inputs are all-or-nothing and use absolute config/release
 paths. Rollbridge binds its proxy, activates the release through the normal
 deploy path, then exposes the control socket and stays foreground. A failed

package/docs/cli.md

@@ -23,7 +23,7 @@ process-policy details.
 ## `daemon`
 
 ```
-rollbridge daemon [--config <path>]
+rollbridge daemon [--config <path>] [--takeover-owner]
                   [--release-path <path> --release-id <id> --revision <sha>
                    [--boot-attestation <sha256:digest>]]
 ```
@@ -64,6 +64,13 @@ identity. Rollbridge does not calculate or interpret the digest.
 With no release options, daemon behavior is unchanged: it starts listener-only
 and waits for control-socket deployments.
 
+`--takeover-owner` requires the complete bootstrap tuple. It bootstraps and
+health-checks the replacement before sending the current daemon the private
+retirement command. Retirement stops stable listeners and new work promptly,
+but does not wait for owned workers' normal drain before the replacement binds
+the proxy and control socket. A bootstrap failure occurs before retirement, so
+the previously accepted owner remains available.
+
 ## `ensure-daemon`
 
 ```

package/package.json

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

package/src/cli.js

@@ -36,6 +36,7 @@ export async function runCli(argv) {
     .option("--release-id <id>", "Bootstrap release id (requires --config, --release-path, and --revision)")
     .option("--revision <sha>", "Bootstrap revision (requires --config, --release-path, and --release-id)")
     .option("--boot-attestation <digest>", "Opaque bootstrap ownership attestation (requires the complete bootstrap release tuple)")
+    .option("--takeover-owner", "Boot and health-check before retiring the current external owner")
     .action(async (options) => {
       const bootstrap = await validateDaemonBootstrapOptions(options)
       const configPath = await resolveConfigPath(options.config)
@@ -43,7 +44,9 @@ export async function runCli(argv) {
       const runtime = await loadDaemonRuntimeIdentity(process.env.ROLLBRIDGE_DAEMON_RUNTIME_MANIFEST)
       const daemon = new RollbridgeDaemon({bootstrap, config, configPath, runtime})
 
-      await daemon.start({exposeControl: !bootstrap})
+      if (options.takeoverOwner && (!bootstrap || !bootstrap.attestation)) throw new Error("Daemon --takeover-owner requires the complete bootstrap release tuple and --boot-attestation.")
+
+      if (!options.takeoverOwner) await daemon.start({exposeControl: !bootstrap})
 
       const shutdown = async () => {
         await daemon.shutdown()
@@ -56,10 +59,15 @@ export async function runCli(argv) {
       if (bootstrap) {
         try {
           await daemon.deploy(bootstrap)
-          await daemon.exposeControl()
+          if (options.takeoverOwner) {
+            await sendControlCommand({command: {attestation: bootstrap.attestation, command: "retire-owner"}, path: config.control.path})
+            await daemon.start({reportOrphans: false})
+          } else {
+            await daemon.exposeControl()
+          }
         } catch {
           daemon.logger("bootstrap activation failed", {releaseId: bootstrap.releaseId, status: "error"})
-          await daemon.shutdown()
+          if (!options.takeoverOwner) await daemon.shutdown()
           process.exitCode = 1
           return
         }

package/src/daemon.js

@@ -61,8 +61,10 @@ export default class RollbridgeDaemon {
     this.stopping = false
     this.statePath = config.statePath
     this.persistTimer = /** @type {ReturnType<typeof setInterval> | undefined} */ (undefined)
+    this.persistenceEnabled = false
     this.pendingWrite = /** @type {Promise<void> | undefined} */ (undefined)
     this.shutdownPromise = /** @type {Promise<void> | undefined} */ (undefined)
+    this.retirementPromise = /** @type {Promise<void> | undefined} */ (undefined)
     this.controlClosePromise = /** @type {Promise<void> | undefined} */ (undefined)
     this.startingReleases = /** @type {Set<ReleaseGroup>} */ (new Set())
     // Still-alive managed processes left by a previous daemon (from statePath), captured at
@@ -74,11 +76,11 @@ export default class RollbridgeDaemon {
 
   /**
    * Starts daemon listeners.
-   * @param {{exposeControl?: boolean}} [options] - Whether to expose the control socket immediately.
+   * @param {{exposeControl?: boolean, reportOrphans?: boolean}} [options] - Listener startup options.
    * @returns {Promise<void>} Resolves when the requested listeners are ready.
    */
-  async start({exposeControl = true} = {}) {
-    await this.reportOrphans()
+  async start({exposeControl = true, reportOrphans = true} = {}) {
+    if (reportOrphans) await this.reportOrphans()
     await this.startProxy()
     if (exposeControl) await this.exposeControl()
   }
@@ -358,6 +360,13 @@ export default class RollbridgeDaemon {
       return {message: "shutdown"}
     }
 
+    if (commandName === "retire-owner") {
+      const attestation = requiredString(data.attestation, "attestation")
+      if (!/^sha256:[a-f0-9]{64}$/.test(attestation)) throw new Error("Owner retirement attestation must use the canonical sha256:<64 lowercase hex> format")
+      await this.retireOwner({attestation, completionSocket: controlSocket})
+      return {message: "owner retired"}
+    }
+
     throw new Error(`Unknown command: ${String(commandName)}`)
   }
 
@@ -732,6 +741,7 @@ export default class RollbridgeDaemon {
   startStatePersistence() {
     if (!this.statePath) return
 
+    this.persistenceEnabled = true
     this.persistState()
     this.persistTimer = setInterval(() => this.persistState(), STATE_PERSIST_INTERVAL_MS)
     this.persistTimer.unref?.()
@@ -743,7 +753,7 @@ export default class RollbridgeDaemon {
    * @returns {void}
    */
   persistState() {
-    if (!this.statePath || this.stopping) return
+    if (!this.statePath || !this.persistenceEnabled || this.stopping) return
 
     const statePath = this.statePath
     const status = /** @type {Record<string, JsonValue>} */ (secretSafeStateValue(this.status()))
@@ -797,6 +807,50 @@ export default class RollbridgeDaemon {
     if (waitForControlConnections && this.controlClosePromise) await this.controlClosePromise
   }
 
+  /**
+   * Relinquishes stable listeners promptly while retaining draining children under
+   * this daemon until their normal stop contract completes.
+   * @param {{attestation: string, completionSocket?: net.Socket}} options - Attested handoff request.
+   * @returns {Promise<void>} Resolves once a replacement can exclusively bind listeners.
+   */
+  async retireOwner({attestation, completionSocket}) {
+    if (this.retirementPromise) return await this.retirementPromise
+    this.retirementPromise = this.performOwnerRetirement(attestation, completionSocket)
+    return await this.retirementPromise
+  }
+
+  /**
+   * @param {string} attestation - Replacement boot attestation.
+   * @param {net.Socket | undefined} completionSocket - Requesting handoff connection.
+   * @returns {Promise<void>} Resolves after quiesce and listener release.
+   */
+  async performOwnerRetirement(attestation, completionSocket) {
+    this.stopping = true
+    if (this.persistTimer) {
+      clearInterval(this.persistTimer)
+      this.persistTimer = undefined
+    }
+    this.persistenceEnabled = false
+    if (this.pendingWrite) await this.pendingWrite
+    this.controlClosePromise = this.closeServer(this.controlServer)
+    for (const socket of this.controlSockets) if (socket !== completionSocket) socket.destroy()
+    await Promise.all([
+      ...[...this.services.values()].map((processInstance) => processInstance.quiesce()),
+      ...[...this.singletons.values()].map((processInstance) => processInstance.quiesce()),
+      ...[...this.startingReleases].map((release) => release.quiesce()),
+      ...[...this.releases.values()].map((release) => release.quiesce())
+    ])
+    await this.removeControlSocket()
+    void this.closeServer(this.proxyServer)
+    void Promise.allSettled([
+      ...[...this.services.values()].map((processInstance) => processInstance.stop()),
+      ...[...this.singletons.values()].map((processInstance) => processInstance.stop()),
+      ...[...this.startingReleases].map((release) => release.stop()),
+      ...[...this.releases.values()].map((release) => release.stop())
+    ])
+    this.logger("external owner retired", {attestation, status: "draining"})
+  }
+
   /**
    * @param {net.Socket | undefined} completionSocket - Requester retained for the final response.
    * @returns {Promise<void>} Retires listeners and cleans up every daemon-owned resource.
@@ -925,7 +979,7 @@ function isShutdownControlLine(line) {
   try {
     const command = JSON.parse(line)
 
-    return Boolean(command && typeof command === "object" && command.command === "shutdown")
+    return Boolean(command && typeof command === "object" && ["retire-owner", "shutdown"].includes(command.command))
   } catch {
     return false
   }

package/src/managed-process.js

@@ -62,6 +62,7 @@ export default class ManagedProcess extends EventEmitter {
     this.memoryWarned = false
     this.startedAtMs = /** @type {number | undefined} */ (undefined)
     this.intentionalStop = false
+    this.quiescePromise = /** @type {Promise<void> | undefined} */ (undefined)
     this.restartTimer = undefined
     this.child = undefined
     this.exitPromise = undefined
@@ -78,6 +79,7 @@ export default class ManagedProcess extends EventEmitter {
     if (this.child) return
 
     this.intentionalStop = false
+    this.quiescePromise = undefined
     this.exitCode = undefined
     this.exitSignal = undefined
     this.state = "starting"
@@ -338,36 +340,22 @@ export default class ManagedProcess extends EventEmitter {
    * @returns {Promise<void>} Resolves when stopped.
    */
   async stop(options = {}) {
-    this.intentionalStop = true
-    this.clearMemoryMonitor()
-
-    if (this.restartTimer) {
-      clearTimeout(this.restartTimer)
-      this.restartTimer = undefined
-    }
-
-    const child = this.child
+    const pgid = this.child?.pid ?? this.pid
+    const exitPromise = this.exitPromise
+    await this.quiesce()
 
-    if (!child || !child.pid) {
+    if (!pgid) {
       this.state = "stopped"
       return
     }
 
-    const pgid = child.pid
-    const exitPromise = this.exitPromise
-
-    this.state = "stopping"
-
-    const {drainCommand, drainTimeoutMs, quietCommand, stopCommand} = this.lifecycle
+    const {drainCommand, drainTimeoutMs, stopCommand} = this.lifecycle
 
     const hookTimeoutMs = this.hookTimeoutMs()
 
-    // 1. Quiesce: tell the process to stop accepting new work.
-    if (quietCommand) await this.runHook(quietCommand, hookTimeoutMs, "quiet command")
-
     // 2. Drain: let in-flight work finish, bounded by drainTimeoutMs (0 skips the step). A
     //    drainCommand blocks until drained; otherwise wait for the process to exit on its own.
-    if (this.child && drainTimeoutMs > 0) {
+    if (this.processGroupExists(pgid) && drainTimeoutMs > 0) {
       if (drainCommand) await this.runHook(drainCommand, drainTimeoutMs, "drain command")
       else await this.waitForExit(drainTimeoutMs)
     }
@@ -391,6 +379,26 @@ export default class ManagedProcess extends EventEmitter {
     this.state = "stopped"
   }
 
+  /** @returns {Promise<void>} Stops restarts and waits until the process has stopped accepting new work. */
+  async quiesce() {
+    if (this.quiescePromise) return await this.quiescePromise
+    this.quiescePromise = (async () => {
+      this.intentionalStop = true
+      this.clearMemoryMonitor()
+      if (this.restartTimer) {
+        clearTimeout(this.restartTimer)
+        this.restartTimer = undefined
+      }
+      if (!this.child?.pid) {
+        this.state = "stopped"
+        return
+      }
+      this.state = "stopping"
+      if (this.lifecycle.quietCommand) await this.runHook(this.lifecycle.quietCommand, this.hookTimeoutMs(), "quiet command")
+    })()
+    return await this.quiescePromise
+  }
+
   /** @returns {number} Timeout used for lifecycle hooks. */
   hookTimeoutMs() {
     if (this.stopTimeoutMs === "indefinite") return 30000

package/src/release-group.js

@@ -403,6 +403,11 @@ export default class ReleaseGroup extends EventEmitter {
     this.stoppedAt = new Date().toISOString()
   }
 
+  /** @returns {Promise<void>} Quiesces every release process without waiting for its drain. */
+  async quiesce() {
+    await Promise.all([...this.processes.values()].map((processInstance) => processInstance.quiesce()))
+  }
+
   /** @returns {ReleaseStatus} Status payload. */
   status() {
     return {

package/test/daemon-bootstrap.test.js

@@ -85,6 +85,38 @@ test("daemon bootstrap activates the exact release through the foreground daemon
   }
 })
 
+test("failed takeover bootstrap preserves the previously accepted owner", async () => {
+  const fixture = await createFixture()
+  const accepted = spawnDaemon(fixture, {attestation: firstAttestation, releaseId: "accepted", revision: "accepted123"})
+
+  try {
+    await waitForLog(accepted, "control socket listening")
+    const badConfig = JSON.parse((await fs.readFile(fixture.configPath, "utf8")).replace(/^module\.exports = /, ""))
+    badConfig.processes[0].health.path = "/never-ready"
+    badConfig.processes[0].health.timeoutMs = 100
+    await fs.writeFile(fixture.configPath, `module.exports = ${JSON.stringify(badConfig, null, 2)}\n`)
+
+    const result = await runDaemon([
+      "--config", fixture.configPath,
+      "--release-path", fixture.root,
+      "--release-id", "candidate",
+      "--revision", "candidate123",
+      "--boot-attestation", secondAttestation,
+      "--takeover-owner"
+    ])
+
+    assert.notEqual(result.code, 0)
+    const status = await sendControlCommand({command: {command: "status"}, path: fixture.socketPath})
+    assert.equal(status.activeReleaseId, "accepted")
+    assert.ok(status.bootstrap && typeof status.bootstrap === "object" && !Array.isArray(status.bootstrap))
+    assert.equal(status.bootstrap.attestation, firstAttestation)
+  } finally {
+    accepted.kill("SIGTERM")
+    if (accepted.exitCode === null) await once(accepted, "exit")
+    await fs.rm(fixture.root, {force: true, recursive: true})
+  }
+})
+
 test("daemon bootstrap does not expose control deploys until activation completes", async () => {
   const fixture = await createFixture({healthGate: true, healthTimeoutMs: 60000})
   const started = waitForFile(fixture.startedPath)

package/test/rollbridge.test.js

@@ -855,6 +855,14 @@ test("a process over its memory limit is restarted with reason memory", {skip: p
     assert.equal(hog.lastStartReason, "memory")
     assert.equal(typeof hog.lastMemoryRestartAt, "string")
 
+    // Keep the replacement alive long enough to observe its next monitor sample. The fixture
+    // remains over the configured limit after every launch, otherwise it can restart again and
+    // clear rssBytes/children before this polling loop observes them on slower CI runners.
+    const hogProcess = daemon.activeRelease?.processes.get("hog")
+
+    assert.ok(hogProcess?.memory)
+    hogProcess.memory.limitBytes = Number.MAX_SAFE_INTEGER
+
     // rssBytes is sampled on the monitor's interval; wait for a measurement of the running process.
     await waitFor(() => {
       const rssBytes = activeProcessStatus(daemon, "hog")?.rssBytes

package/test/shutdown-completion.test.js

@@ -115,6 +115,43 @@ test("shutdown response waits for endpoint and owned-process cleanup before imme
   }
 })
 
+test("external-owner retirement releases listeners before a long-draining companion exits", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-owner-retirement-"))
+  const socketPath = path.join(root, "rollbridge.sock")
+  const gatePath = path.join(root, "retire.fifo")
+  const stoppingPath = path.join(root, "stopping")
+  const gate = spawn("mkfifo", [gatePath])
+  assert.equal((await once(gate, "exit"))[0], 0)
+  const config = buildConfig(socketPath, {companion: {
+    command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify("setInterval(() => {}, 1000)")}`,
+    id: "worker",
+    lifecycle: {drainCommand: `read released < ${JSON.stringify(gatePath)}`, drainTimeoutMs: 60000, quietCommand: `printf stopping > ${JSON.stringify(stoppingPath)}`},
+    policy: "companion"
+  }})
+  const daemon = new RollbridgeDaemon({config, logger: () => {}})
+  let replacement
+
+  try {
+    await daemon.start()
+    await daemon.deploy({releaseId: "old", releasePath: root, revision: "old"})
+    const retirement = sendControlCommand({command: {attestation: `sha256:${"a".repeat(64)}`, command: "retire-owner"}, path: socketPath})
+    const response = await retirement
+    assert.deepEqual(response, {message: "owner retired", status: "success"})
+    assert.equal(await fs.readFile(stoppingPath, "utf8"), "stopping", "old worker must stop accepting work before listener takeover")
+
+    replacement = new RollbridgeDaemon({config, logger: () => {}})
+    await replacement.start({reportOrphans: false})
+    assert.equal((await sendControlCommand({command: {command: "status"}, path: socketPath})).application, "shutdown-target")
+    assert.deepEqual(replacement.status().orphans, [], "intentional retired companions are not replacement orphans")
+    assert.equal(daemon.status().releases[0].processes[0].state, "stopping")
+  } finally {
+    await fs.writeFile(gatePath, "done\n").catch(() => {})
+    if (replacement) await replacement.shutdown()
+    await daemon.shutdown()
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
 test("control socket unlink failure is reported only after owned cleanup completes", async () => {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-shutdown-unlink-failure-"))
   const socketPath = path.join(root, "control.sock")