rollbridge 0.1.32 → 0.1.34

package/changelog.d/20260830-guardian-retired-replacement-process-key.md

@@ -0,0 +1,8 @@
+### Fixed
+
+- Carry an exact recovered guardian process key when a ready replacement commits
+  after the incumbent control listener has already retired, while retaining the
+  replacement transaction, authority, and registered-process fences.
+- Fail closed when an older retained guardian cannot commit that replacement
+  atomically after the incumbent control socket disappears, preserving the
+  incumbent owner, retained connections, and guardian-managed release processes.

package/package.json

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

package/src/daemon.js

@@ -353,6 +353,7 @@ export default class RollbridgeDaemon {
     let retiredIncumbentControl = false
     let retainIncumbentControl = false
     let incumbentControl = legacyBridge?.incumbentControl
+    let committed = /** @type {Promise<Error | undefined> | undefined} */ (undefined)
 
     try {
       if (this.config.control.path !== transfer.snapshot.control.path) {
@@ -401,7 +402,10 @@ export default class RollbridgeDaemon {
         finalControlPublished = true
         this.boundControlPath = this.config.control.path
       }
-      const committed = this.guardian.waitForEvent("replacement-committed")
+      committed = this.guardian.waitForEvent("replacement-committed").then(
+        () => undefined,
+        (error) => error instanceof Error ? error : new Error(String(error))
+      )
       const staged = await this.guardian.stageOwnerReplacement(prepared.replacementId, {
         authority: this.ownerAuthority(),
         config: this.config,
@@ -412,7 +416,18 @@ export default class RollbridgeDaemon {
 
       if (!staged.committed) {
         if (retiredIncumbentControl) {
-          await this.guardian.commitRetiredOwnerReplacement(prepared.replacementId)
+          const processKey = this.guardian.processes.keys().next().value
+
+          if (!processKey) throw new Error("Retired owner replacement requires an exact recovered guardian process registration")
+          try {
+            await this.guardian.commitRetiredOwnerReplacement(prepared.replacementId, processKey)
+          } catch (error) {
+            if (!(error instanceof Error) || error.message !== "Guardian commit-retired-owner-replacement requires the committed owner") throw error
+            throw new Error(
+              "Cannot safely complete atomic owner replacement through the older retained guardian while the incumbent control socket is absent; incumbent owner and connections were preserved",
+              {cause: error}
+            )
+          }
         } else {
           try {
             if (!incumbentControl) throw new Error("Owner replacement incumbent control session is unavailable")
@@ -425,7 +440,9 @@ export default class RollbridgeDaemon {
           }
         }
       }
-      await committed
+      const commitmentError = await committed
+
+      if (commitmentError) throw commitmentError
       committedAuthority = true
       if (retiredIncumbentControl) {
         await fs.rename(stagingControlPath, this.config.control.path)
@@ -472,6 +489,13 @@ export default class RollbridgeDaemon {
       } else {
         this.guardian.disconnect()
       }
+      if (committed) {
+        const commitmentError = await committed
+
+        if (commitmentError && commitmentError !== error && commitmentError.message !== "Process guardian connection closed") {
+          abortError = commitmentError
+        }
+      }
       incumbentControl?.close()
       if (legacyBridge?.boundaryCrossed) {
         this.logger("legacy disruptive owner replacement failed after incumbent exit", {

package/src/guardian-client.js

@@ -194,9 +194,12 @@ export default class GuardianClient {
     await this.request({command: "commit-owner-replacement", replacementId})
   }
 
-  /** @param {string} replacementId - Same-authority transaction whose incumbent listener is absent. */
-  async commitRetiredOwnerReplacement(replacementId) {
-    await this.request({command: "commit-retired-owner-replacement", replacementId})
+  /**
+   * @param {string} replacementId - Same-authority transaction whose incumbent listener is absent.
+   * @param {string} key - Exact recovered guardian process proving candidate reconstruction.
+   */
+  async commitRetiredOwnerReplacement(replacementId, key) {
+    await this.request({command: "commit-retired-owner-replacement", key, replacementId})
   }
 
   /** @param {string} replacementId - Committed transaction awaiting incumbent retirement. */

package/src/process-guardian.js

@@ -300,6 +300,7 @@ async function execute(request, socket) {
 
   if (request.command === "commit-retired-owner-replacement") {
     requireReplacement(socket, request)
+    requireProcess(request)
     if (!replacementOwnerState) throw new Error("Retired owner replacement transaction is not staged")
     if (!isDeepStrictEqual(ownerAuthority(ownerState), replacementAuthority)) throw new Error("Retired owner replacement requires unchanged owner authority")
     const controlPath = ownerControlPath(ownerState)
@@ -408,10 +409,7 @@ async function execute(request, socket) {
     return managedProcess.status()
   }
 
-  if (!request.key) throw new Error(`Guardian ${request.command} requires a process key`)
-  const record = processes.get(request.key)
-
-  if (!record) throw new Error(`Guardian process ${request.key} is not registered`)
+  const record = requireProcess(request)
 
   if (request.command !== "status") requireOwner(socket, request.command)
 
@@ -530,6 +528,18 @@ function requireReplacement(socket, request) {
   if (replacementClient !== socket || request.replacementId !== replacementId) throw new Error("Owner replacement transaction is not the prepared candidate")
 }
 
+/**
+ * @param {GuardianRequest} request - Keyed guardian request.
+ * @returns {{desired: boolean, process: ManagedProcess, provenance: string}} Exact registered process.
+ */
+function requireProcess(request) {
+  if (!request.key) throw new Error(`Guardian ${request.command} requires a process key`)
+  const record = processes.get(request.key)
+
+  if (!record) throw new Error(`Guardian process ${request.key} is not registered`)
+  return record
+}
+
 /**
  * @param {import("./json.js").JsonValue} state - Transfer state.
  * @returns {import("./json.js").JsonValue} Embedded authority fence.

package/test/guardian-client.test.js

@@ -210,32 +210,68 @@ test("replacement staging rejects owner state published after prepare", async ()
   }
 })
 
+test("retired owner replacement commit carries its exact recovered process key", async () => {
+  const client = new GuardianClient({socketPath: "/unused", token: "authenticated-capability"})
+  const replacementId = "prepared-replacement"
+  const processKey = "release:v1:worker"
+
+  client.request = async (request) => {
+    if (!request.key) throw new Error(`Guardian ${request.command} requires a process key`)
+    assert.deepEqual(request, {command: "commit-retired-owner-replacement", key: processKey, replacementId})
+    return {committed: true}
+  }
+
+  await client.commitRetiredOwnerReplacement(replacementId, processKey)
+})
+
 test("retired owner replacement requires unchanged authority and the exact control path absent", async () => {
   const fixture = await createGuardian()
   const candidate = new GuardianClient({socketPath: fixture.client.socketPath, token: fixture.token})
+  const contender = new GuardianClient({socketPath: fixture.client.socketPath, token: fixture.token})
   const controlPath = path.join(fixture.root, "rollbridge.sock")
+  const processKey = "release:v1:worker"
   const authority = {configDigest: "incumbent", runtime: null}
   const nextAuthority = {configDigest: "candidate", runtime: null}
   const snapshot = {activeReleaseId: "v1", control: {path: controlPath}}
 
   try {
+    await fixture.client.process(processKey, definition("worker")).recover()
     await fixture.client.publishOwnerState({authority, snapshot})
     await candidate.connect()
     const changed = await candidate.prepareOwnerReplacement(authority, nextAuthority)
 
     await candidate.stageOwnerReplacement(changed.replacementId, {authority: nextAuthority, snapshot})
-    await assert.rejects(() => candidate.commitRetiredOwnerReplacement(changed.replacementId), /unchanged owner authority/)
+    await assert.rejects(() => candidate.commitRetiredOwnerReplacement(changed.replacementId, processKey), /unchanged owner authority/)
     await candidate.abortOwnerReplacement(changed.replacementId)
 
     const occupied = await candidate.prepareOwnerReplacement(authority, authority)
 
     await candidate.stageOwnerReplacement(occupied.replacementId, {authority, snapshot})
     await fs.writeFile(controlPath, "occupied\n")
-    await assert.rejects(() => candidate.commitRetiredOwnerReplacement(occupied.replacementId), /control socket .* still exists/)
+    await assert.rejects(() => candidate.commitRetiredOwnerReplacement(occupied.replacementId, processKey), /control socket .* still exists/)
     await candidate.abortOwnerReplacement(occupied.replacementId)
-    await fixture.client.shutdown()
+
+    await fs.rm(controlPath)
+    const ready = await candidate.prepareOwnerReplacement(authority, authority)
+
+    await candidate.stageOwnerReplacement(ready.replacementId, {authority, snapshot})
+    await contender.connect()
+    await assert.rejects(
+      () => contender.request({command: "commit-retired-owner-replacement", key: processKey, replacementId: ready.replacementId}),
+      /not the prepared candidate/
+    )
+    await assert.rejects(
+      () => candidate.commitRetiredOwnerReplacement(ready.replacementId, "release:v1:wrong"),
+      /process .* is not registered/
+    )
+    const committed = candidate.waitForEvent("replacement-committed")
+
+    await candidate.commitRetiredOwnerReplacement(ready.replacementId, processKey)
+    await committed
+    await candidate.shutdown()
     await fixture.client.guardianExit()
   } finally {
+    contender.disconnect()
     candidate.disconnect()
     await cleanupGuardian(fixture)
   }

package/test/owner-replacement.test.js

@@ -249,45 +249,135 @@ test("ensure-daemon atomically replaces incompatible config, socket, and package
   }
 })
 
-test("same-authority replacement commits after a retired incumbent already removed its control socket", async () => {
+test("cross-version replacement fails closed without dropping a retained WebSocket after the public socket is removed", async () => {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-owner-replacement-retired-control-"))
   const socketPath = path.join(root, "rollbridge.sock")
   const statePath = path.join(root, "state.json")
+  const compatibilitySocketPath = path.join(root, "retained-guardian.sock")
+  const configPath = path.join(root, "rollbridge.cjs")
   const releasePath = path.join(root, "v1")
-  const daemonConfig = normalizeConfig(config({controlPath: socketPath, extraCompanion: false, statePath}))
-  const owner = new RollbridgeDaemon({config: daemonConfig, logger: () => {}})
-  let replacement
+  const compatibilitySockets = new Set()
+  let compatibilityGuardian
+  let committedProcessKey
+  let owner = /** @type {import("node:child_process").ChildProcess | undefined} */ (undefined)
+  let replacement = /** @type {RollbridgeDaemon | undefined} */ (undefined)
+  let retainedConnection
+  let retainedConnectionClosed = false
+  let transactionAudit
 
   try {
     await fs.mkdir(releasePath)
     await makeFifo(path.join(releasePath, "worker.fifo"))
-    await owner.start()
-    await owner.deploy({releaseId: "v1", releasePath, revision: "v1"})
-    await Promise.all([...owner.releases.values()].map((release) => release.quiesce()))
-    await owner.closeServer(owner.controlServer)
-    await owner.removeControlSocket()
-    await owner.closeServer(owner.proxyServer)
-    const retired = owner.status()
-    const processState = retired.releases[0]?.processes.map(({id, pid, state}) => ({id, pid, state}))
-
-    assert.deepEqual(processState?.map(({state}) => state), ["quiesced", "quiesced"])
-    assert.equal((await owner.guardian?.replacementStatus())?.ownerClaimed, true)
-    await assert.rejects(fs.access(socketPath), {code: "ENOENT"})
+    await writeConfig(configPath, config({controlPath: socketPath, extraCompanion: false, statePath}))
+    owner = spawn(process.execPath, [binPath, "daemon", "--config", configPath], {stdio: ["ignore", "pipe", "pipe"]})
+    await waitForLog(owner, "control socket listening")
+    await sendControlCommand({command: {command: "deploy", releaseId: "v1", releasePath, revision: "v1"}, path: socketPath})
+    const retired = await sendControlCommand({command: {command: "status"}, path: socketPath})
+    const retiredReleases = /** @type {{processes: {id: string, pid?: number, state: string}[]}[]} */ (retired.releases)
+    const processState = retiredReleases[0]?.processes.map(({id, pid, state}) => ({id, pid, state}))
+    const proxyPort = /** @type {{port?: number}} */ (retired.proxy).port
 
-    replacement = new RollbridgeDaemon({config: daemonConfig, logger: () => {}})
-    await replacement.replaceIncompatibleOwner()
-    const recovered = await sendControlCommand({command: {command: "status"}, path: socketPath})
-    const recoveredReleases = /** @type {{processes: {id: string, pid?: number, state: string}[]}[]} */ (recovered.releases)
+    assert.deepEqual(processState?.map(({state}) => state), ["running", "running"])
+    if (typeof proxyPort !== "number") throw new Error("Retained owner proxy is missing its port")
+    retainedConnection = await openWebSocket(proxyPort)
+    retainedConnection.once("close", () => { retainedConnectionClosed = true })
+    await fs.rm(socketPath)
+    await assert.rejects(fs.access(socketPath), {code: "ENOENT"})
+    const state = JSON.parse(await fs.readFile(statePath, "utf8"))
+    const guardianSocketPath = state.recovery.guardian.socketPath
+    const expectedProcessKey = "release:v1:worker"
+
+    compatibilityGuardian = net.createServer((candidateSocket) => {
+      const guardianSocket = net.createConnection(guardianSocketPath)
+      let buffer = ""
+
+      compatibilitySockets.add(candidateSocket)
+      compatibilitySockets.add(guardianSocket)
+      candidateSocket.setEncoding("utf8")
+      candidateSocket.once("close", () => {
+        compatibilitySockets.delete(candidateSocket)
+        guardianSocket.destroy()
+      })
+      guardianSocket.once("close", () => {
+        compatibilitySockets.delete(guardianSocket)
+        candidateSocket.destroy()
+      })
+      guardianSocket.on("data", (chunk) => candidateSocket.write(chunk))
+      candidateSocket.on("data", (chunk) => {
+        buffer += chunk
+        let newline = buffer.indexOf("\n")
+
+        while (newline >= 0) {
+          const line = buffer.slice(0, newline)
+          const request = JSON.parse(line)
+
+          buffer = buffer.slice(newline + 1)
+          if (request.command === "commit-retired-owner-replacement") {
+            if (request.key !== expectedProcessKey) {
+              candidateSocket.write(`${JSON.stringify({error: `Guardian ${request.command} requires a process key`, id: request.id})}\n`)
+            } else {
+              committedProcessKey = request.key
+              candidateSocket.write(`${JSON.stringify({error: `Guardian ${request.command} requires the committed owner`, id: request.id})}\n`)
+            }
+            newline = buffer.indexOf("\n")
+            continue
+          }
+          guardianSocket.write(`${line}\n`)
+          newline = buffer.indexOf("\n")
+        }
+      })
+    })
+    await listenUnix(compatibilityGuardian, compatibilitySocketPath)
+    state.recovery.guardian.socketPath = compatibilitySocketPath
+    await fs.writeFile(statePath, `${JSON.stringify(state)}\n`)
+
+    const incumbentPid = owner.pid
+
+    assert.ok(incumbentPid)
+    const candidate = new RollbridgeDaemon({
+      config: normalizeConfig(config({controlPath: socketPath, extraCompanion: false, statePath})),
+      configPath,
+      legacyIncumbentPid: incumbentPid,
+      logger: () => {}
+    })
+    replacement = candidate
+    await assert.rejects(
+      () => candidate.replaceIncompatibleOwner(),
+      /cannot safely complete atomic owner replacement through the older retained guardian while the incumbent control socket is absent; incumbent owner and connections were preserved/i
+    )
+    assert.equal(committedProcessKey, expectedProcessKey)
+    assert.equal(owner.exitCode, null)
+    assert.equal(owner.signalCode, null)
+    assert.doesNotThrow(() => process.kill(incumbentPid, 0))
+    assert.equal(retainedConnectionClosed, false, "failed compatibility handoff must leave retained connections serving")
+    assert.equal(retainedConnection.destroyed, false, "failed compatibility handoff must preserve the incumbent listener")
+    for (const {pid} of processState || []) {
+      if (typeof pid !== "number") throw new Error("Retained process is missing its PID")
+      assert.doesNotThrow(() => process.kill(pid, 0))
+    }
+    transactionAudit = new GuardianClient(state.recovery.guardian)
+    await transactionAudit.connect()
+    const transactionStatus = /** @type {{committedReplacementId: string | null, ownerClaimed: boolean, retirementPending?: boolean}} */ (await transactionAudit.replacementStatus())
 
-    assert.equal(recovered.activeReleaseId, "v1")
-    assert.deepEqual(recovered.releaseReferences, [{releaseId: "v1", releasePath}])
-    assert.deepEqual(recoveredReleases[0]?.processes.map(({id, pid, state}) => ({id, pid, state})), processState)
+    assert.equal(transactionStatus.committedReplacementId, null)
+    assert.equal(transactionStatus.ownerClaimed, true)
+    assert.equal(transactionStatus.retirementPending, false)
   } finally {
-    const shutdown = replacement?.controlCommandsReady ? replacement.shutdown().catch(() => {}) : owner.shutdown().catch(() => {})
-
-    await Promise.all([fs.writeFile(path.join(releasePath, "worker.fifo"), "drained\n").catch(() => {}), shutdown])
-    owner.guardian?.disconnect()
+    if (replacement?.controlCommandsReady) {
+      await Promise.all([
+        fs.writeFile(path.join(releasePath, "worker.fifo"), "drained\n").catch(() => {}),
+        replacement.shutdown().catch(() => {})
+      ])
+    }
+    transactionAudit?.disconnect()
+    retainedConnection?.destroy()
+    if (owner && owner.exitCode === null && owner.signalCode === null) {
+      owner.kill("SIGKILL")
+      await once(owner, "exit")
+    }
     replacement?.guardian?.disconnect()
+    for (const socket of compatibilitySockets) socket.destroy()
+    if (compatibilityGuardian?.listening) await closeServer(compatibilityGuardian)
     await stopGuardian(statePath)
     await fs.rm(root, {force: true, recursive: true})
   }