rollbridge 0.1.35 → 0.1.36

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

@@ -1,9 +1,9 @@
 ### Fixed
 
 - Select retired-owner commit proof from the guardian-published committed owner
-  snapshot rather than candidate-local process order, and independently require
-  that proof to remain registered while retaining the replacement transaction,
-  authority, and control-path fences.
+  snapshot rather than candidate-local process order, reserve its incumbent-owned
+  registration through commit, then attach it to the committed candidate while
+  retaining the replacement transaction, authority, and control-path 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.35",
+  "version": "0.1.36",
   "description": "Zero-downtime process supervisor and local traffic switcher for deploy-managed apps.",
   "keywords": [
     "deploy",

package/src/daemon.js

@@ -342,6 +342,11 @@ export default class RollbridgeDaemon {
     const transfer = /** @type {PrivateOwnerState} */ (prepared.ownerState)
 
     if (!transfer?.config || !transfer.snapshot) throw new Error("Committed owner published incomplete replacement state")
+    const registeredProcesses = new Map((await this.guardian.inventory()).map(({key, provenance}) => [key, provenance]))
+    const reservedProcessKey = legacyBridge ? undefined : ownerSnapshotProcessKeys(transfer.snapshot, transfer.singletonReleaseIds)
+      .find((key) => registeredProcesses.has(key))
+
+    if (reservedProcessKey) this.guardian.reserveProcessRecovery(reservedProcessKey, /** @type {string} */ (registeredProcesses.get(reservedProcessKey)))
     await this.restoreOwnerState(transfer.snapshot, {config: transfer.config, releaseConfigs: transfer.releaseConfigs, resumeDrains: false, singletonReleaseIds: transfer.singletonReleaseIds, synchronizeLifecycleRoles: false})
     for (const release of this.releases.values()) release.preserveConfigOnRetirement = true
     this.logger("owner replacement candidate prepared", {activeReleaseId: this.activeRelease?.releaseId ?? null, replacementId: prepared.replacementId})
@@ -386,6 +391,7 @@ export default class RollbridgeDaemon {
         if (incumbentControl) {
           const listenerSession = incumbentControl
 
+          if (reservedProcessKey) await this.guardian.recoverReservedProcess(reservedProcessKey)
           incumbentControl.onEvent((event) => this.handleIncumbentListenerEvent(event, listenerSession))
           await incumbentControl.request({
             command: "yield-owner-listeners",
@@ -414,15 +420,20 @@ export default class RollbridgeDaemon {
         snapshot: this.status()
       })
 
+      if (staged.committed && reservedProcessKey) {
+        committedAuthority = true
+        await this.guardian.recoverReservedProcess(reservedProcessKey)
+      }
+
       if (!staged.committed) {
         if (retiredIncumbentControl) {
-          const recoveredProcesses = this.guardian.processes
-          const processKey = ownerSnapshotProcessKeys(transfer.snapshot, transfer.singletonReleaseIds)
-            .find((key) => recoveredProcesses.has(key))
+          const processKey = reservedProcessKey
 
-          if (!processKey) throw new Error("Retired owner replacement requires an exact recovered process from committed owner state")
+          if (!processKey || !this.guardian.processes.has(processKey)) throw new Error("Retired owner replacement requires an exact reserved process from committed owner state")
           try {
             await this.guardian.commitRetiredOwnerReplacement(prepared.replacementId, processKey)
+            committedAuthority = true
+            await this.guardian.recoverReservedProcess(processKey)
           } catch (error) {
             if (!(error instanceof Error) || error.message !== "Guardian commit-retired-owner-replacement requires the committed owner") throw error
             throw new Error(

package/src/guardian-client.js

@@ -21,6 +21,8 @@ export default class GuardianClient {
     this.idleWaiters = /** @type {(() => void)[]} */ ([])
     this.guardianExitPromise = /** @type {Promise<void> | undefined} */ (undefined)
     this.processes = /** @type {Map<string, GuardianProcess>} */ (new Map())
+    this.reservedProcessKey = /** @type {string | undefined} */ (undefined)
+    this.reservedProcessProvenance = /** @type {string | undefined} */ (undefined)
     this.events = /** @type {Map<string, {reject: (error: Error) => void, resolve: (value: Record<string, import("./json.js").JsonValue>) => void}[]>} */ (new Map())
     this.eventHandlers = /** @type {Map<string, ((event: Record<string, import("./json.js").JsonValue>) => void)[]>} */ (new Map())
   }
@@ -111,6 +113,27 @@ export default class GuardianClient {
     return processInstance
   }
 
+  /**
+   * @param {string} key - Exact committed-owner registration reserved until replacement commit.
+   * @param {string} provenance - Guardian-inventoried definition fence.
+   */
+  reserveProcessRecovery(key, provenance) {
+    if (this.reservedProcessKey) throw new Error(`Guardian process recovery ${this.reservedProcessKey} is already reserved`)
+    this.reservedProcessKey = key
+    this.reservedProcessProvenance = provenance
+  }
+
+  /** @param {string} key - Exact reserved registration to attach after authority commits. */
+  async recoverReservedProcess(key) {
+    if (this.reservedProcessKey !== key) throw new Error(`Guardian process recovery ${key} is not reserved`)
+    const processInstance = this.processes.get(key)
+
+    if (!processInstance) throw new Error(`Reserved guardian process ${key} was not reconstructed`)
+    await processInstance.attachReserved()
+    this.reservedProcessKey = undefined
+    this.reservedProcessProvenance = undefined
+  }
+
   /**
    * @param {Record<string, import("./json.js").JsonValue>} command - Command.
    * @returns {Promise<import("./json.js").JsonValue>} Guardian response.
@@ -354,6 +377,16 @@ class GuardianProcess extends ManagedProcess {
 
   /** Reconnects to an already registered guardian process without changing its desired state. */
   async recover() {
+    if (this.client.reservedProcessKey === this.key) {
+      if (this.client.reservedProcessProvenance !== this.provenance) throw new Error(`Guardian provenance mismatch for reserved process ${this.key}`)
+      this.cachedStatus = asProcessStatus(await this.client.request({command: "status", key: this.key}))
+      return
+    }
+    await this.ensureRegistered()
+  }
+
+  /** Attaches a reconstructed process whose incumbent-owned registration was reserved through commit. */
+  async attachReserved() {
     await this.ensureRegistered()
   }
 

package/test/guardian-client.test.js

@@ -224,6 +224,29 @@ test("retired owner replacement commit carries its exact recovered process key",
   await client.commitRetiredOwnerReplacement(replacementId, processKey)
 })
 
+test("reserved process recovery rejects a reconstructed definition with different provenance", async () => {
+  const fixture = await createGuardian()
+  const candidate = new GuardianClient({socketPath: fixture.client.socketPath, token: fixture.token})
+  const processKey = "release:v1:worker"
+
+  try {
+    await fixture.client.process(processKey, definition("worker")).recover()
+    const [registration] = await fixture.client.inventory()
+
+    assert.ok(registration)
+    await candidate.connect()
+    candidate.reserveProcessRecovery(processKey, registration.provenance)
+    await assert.rejects(
+      () => candidate.process(processKey, definition("different-worker")).recover(),
+      /provenance mismatch for reserved process/
+    )
+    assert.deepEqual((await fixture.client.inventory()).map(({key}) => key), [processKey])
+  } finally {
+    candidate.disconnect()
+    await cleanupGuardian(fixture)
+  }
+})
+
 test("retired owner replacement rejects a registered process absent from committed owner state", async () => {
   const fixture = await createGuardian()
   const candidate = new GuardianClient({socketPath: fixture.client.socketPath, token: fixture.token})

package/test/owner-replacement.test.js

@@ -393,16 +393,24 @@ test("cross-version replacement fails closed without dropping a retained WebSock
   }
 })
 
-test("same-authority replacement commits with committed-owner proof after the incumbent control socket is removed", async () => {
+test("cross-version replacement preserves committed-owner proof until commit then recovers every process", async () => {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-owner-replacement-committed-proof-"))
   const socketPath = path.join(root, "rollbridge.sock")
   const statePath = path.join(root, "state.json")
+  const compatibilitySocketPath = path.join(root, "retained-guardian.sock")
   const releasePath = path.join(root, "v1")
   const daemonConfig = normalizeConfig(config({controlPath: socketPath, extraCompanion: false, statePath}))
   const owner = new RollbridgeDaemon({config: daemonConfig, logger: () => {}})
+  const compatibilitySockets = new Set()
   const candidateProcessKey = "release:candidate:worker"
   const committedOwnerProcessKey = "release:v1:worker"
+  const candidateRecoveredKeys = new Set()
+  let compatibilityGuardian
   let committedProcessKey
+  let recoveredKeysAtCommit = /** @type {Set<string> | undefined} */ (undefined)
+  let retainedConnection
+  let retainedConnectionClosed = false
+  let retainedGuardianSocketPath = /** @type {string | undefined} */ (undefined)
   /** @type {RollbridgeDaemon | undefined} */
   let replacement
 
@@ -421,14 +429,66 @@ test("same-authority replacement commits with committed-owner proof after the in
       key: candidateProcessKey,
       provenance: ownerProcess.provenance
     })
-    await Promise.all([...owner.releases.values()].map((release) => release.quiesce()))
+    const running = owner.status()
+    const processState = running.releases[0]?.processes.map(({id, pid, state}) => ({id, pid, state}))
+    const expectedProcessKeys = new Set(running.releases[0]?.processes.map(({id}) => `release:v1:${id}`))
+    const proxyPort = /** @type {{port?: number}} */ (running.proxy).port
+
+    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 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}))
+    const state = JSON.parse(await fs.readFile(statePath, "utf8"))
+    const guardianSocketPath = state.recovery.guardian.socketPath
+
+    if (typeof guardianSocketPath !== "string") throw new Error("Retained guardian state is missing its socket path")
+    retainedGuardianSocketPath = guardianSocketPath
+    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 === "register") candidateRecoveredKeys.add(request.key)
+          if (request.command === "commit-retired-owner-replacement") {
+            committedProcessKey = request.key
+            recoveredKeysAtCommit = new Set(candidateRecoveredKeys)
+            if (candidateRecoveredKeys.has(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`)
 
-    assert.deepEqual(processState?.map(({state}) => state), ["quiesced", "quiesced"])
     assert.equal((await owner.guardian?.replacementStatus())?.ownerClaimed, true)
     await assert.rejects(fs.access(socketPath), {code: "ENOENT"})
 
@@ -455,14 +515,33 @@ test("same-authority replacement commits with committed-owner proof after the in
 
     assert.equal(recovered.activeReleaseId, "v1")
     assert.equal(committedProcessKey, committedOwnerProcessKey)
+    assert.equal(recoveredKeysAtCommit?.has(committedOwnerProcessKey), false)
+    assert.deepEqual(candidateRecoveredKeys, expectedProcessKeys)
+    assert.equal([...replacement.guardian?.processes.keys() || []][0], candidateProcessKey)
+    assert.equal(retainedConnectionClosed, false, "successful compatibility handoff must preserve retained connections")
+    assert.equal(retainedConnection.destroyed, false, "successful compatibility handoff must leave the retained listener serving")
     assert.deepEqual(recovered.releaseReferences, [{releaseId: "v1", releasePath}])
     assert.deepEqual(recoveredReleases[0]?.processes.map(({id, pid, state}) => ({id, pid, state})), processState)
+    for (const {pid} of processState || []) {
+      if (typeof pid !== "number") throw new Error("Retained process is missing its PID")
+      assert.doesNotThrow(() => process.kill(pid, 0))
+    }
   } finally {
+    if (retainedGuardianSocketPath) {
+      const cleanupState = JSON.parse(await fs.readFile(statePath, "utf8"))
+
+      cleanupState.recovery.guardian.socketPath = retainedGuardianSocketPath
+      await fs.writeFile(statePath, `${JSON.stringify(cleanupState)}\n`)
+    }
     const shutdown = replacement?.controlCommandsReady ? replacement.shutdown().catch(() => {}) : owner.shutdown().catch(() => {})
 
+    retainedConnection?.destroy()
+    await owner.closeServer(owner.proxyServer)
     await Promise.all([fs.writeFile(path.join(releasePath, "worker.fifo"), "drained\n").catch(() => {}), shutdown])
     owner.guardian?.disconnect()
     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})
   }