rollbridge 0.1.33 → 0.1.35

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

@@ -1,5 +1,9 @@
 ### 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.
+- 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.
+- 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.33",
+  "version": "0.1.35",
   "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,10 +416,20 @@ export default class RollbridgeDaemon {
 
       if (!staged.committed) {
         if (retiredIncumbentControl) {
-          const processKey = this.guardian.processes.keys().next().value
+          const recoveredProcesses = this.guardian.processes
+          const processKey = ownerSnapshotProcessKeys(transfer.snapshot, transfer.singletonReleaseIds)
+            .find((key) => recoveredProcesses.has(key))
 
-          if (!processKey) throw new Error("Retired owner replacement requires an exact recovered guardian process registration")
-          await this.guardian.commitRetiredOwnerReplacement(prepared.replacementId, processKey)
+          if (!processKey) throw new Error("Retired owner replacement requires an exact recovered process from committed owner state")
+          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")
@@ -428,7 +442,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)
@@ -475,6 +491,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", {
@@ -523,7 +546,7 @@ export default class RollbridgeDaemon {
    */
   async prepareLegacyOwnerReplacement({error, persisted, persistedAuthority}) {
     const diagnostic = error instanceof Error ? error.message : String(error)
-    const legacyProcessKey = legacyGuardianKeys(persisted)[0]
+    const legacyProcessKey = ownerSnapshotProcessKeys(persisted, persisted.singletonReleaseIds)[0]
 
     if (!isLegacyGuardianPrepareDiagnostic(diagnostic)) throw error
     if (!legacyProcessKey) throw new Error("Legacy disruptive owner replacement requires an exact guardian-owned process registration in durable state", {cause: error})
@@ -1975,18 +1998,21 @@ export function isLegacyGuardianPrepareDiagnostic(diagnostic) {
 }
 
 /**
- * @param {OwnerRecoverySnapshot} snapshot - Durable pre-split snapshot.
+ * @param {OwnerRecoverySnapshot} snapshot - Durable committed owner snapshot.
+ * @param {Record<string, string>} [singletonReleaseIds] - Exact singleton owner releases.
  * @returns {string[]} Exact guardian registration keys present in the snapshot.
  */
-function legacyGuardianKeys(snapshot) {
+function ownerSnapshotProcessKeys(snapshot, singletonReleaseIds = {}) {
   const keys = []
 
   for (const release of snapshot.releases) {
     for (const processStatus of release.processes) keys.push(`release:${release.releaseId}:${processStatus.id}`)
   }
   for (const service of snapshot.services) keys.push(`service:${service.id}`)
-  if (snapshot.activeReleaseId) {
-    for (const singleton of snapshot.singletons) keys.push(`singleton:${snapshot.activeReleaseId}:${singleton.id}`)
+  for (const singleton of snapshot.singletons) {
+    const releaseId = singletonReleaseIds[singleton.id] || snapshot.activeReleaseId
+
+    if (releaseId) keys.push(`singleton:${releaseId}:${singleton.id}`)
   }
   return keys
 }

package/src/process-guardian.js

@@ -68,7 +68,7 @@ let ownerState = bootstrap.ownerState
 let ownerRevision = ownerState === undefined ? 0 : 1
 /** @type {number | undefined} */
 let replacementRevision
-const legacyKeys = legacyGuardian ? legacyOwnerKeys(ownerState) : new Set()
+const legacyKeys = legacyGuardian ? committedOwnerProcessKeys(ownerState) : new Set()
 /** @type {net.Socket | undefined} */
 let ownerMutationClient
 /** @type {string | undefined} */
@@ -301,6 +301,9 @@ async function execute(request, socket) {
   if (request.command === "commit-retired-owner-replacement") {
     requireReplacement(socket, request)
     requireProcess(request)
+    if (!committedOwnerProcessKeys(ownerState).has(/** @type {string} */ (request.key))) {
+      throw new Error(`Guardian process ${request.key} does not belong to the committed owner`)
+    }
     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)
@@ -622,11 +625,11 @@ function errorMessage(error) {
 }
 
 /**
- * Derives only exact process keys present in a committed pre-split durable snapshot.
- * @param {import("./json.js").JsonValue | undefined} state - Seeded owner state.
- * @returns {Set<string>} Exact legacy registrations eligible for recovery.
+ * Derives only exact process keys serialized by committed private owner state.
+ * @param {import("./json.js").JsonValue | undefined} state - Committed owner state.
+ * @returns {Set<string>} Exact committed registrations eligible as owner proof.
  */
-function legacyOwnerKeys(state) {
+function committedOwnerProcessKeys(state) {
   const keys = new Set()
 
   if (!state || typeof state !== "object" || Array.isArray(state) || !("snapshot" in state)) return keys
@@ -646,9 +649,18 @@ function legacyOwnerKeys(state) {
       if (service && typeof service === "object" && !Array.isArray(service) && typeof service.id === "string") keys.add(`service:${service.id}`)
     }
   }
-  if (typeof snapshot.activeReleaseId === "string" && Array.isArray(snapshot.singletons)) {
+  const singletonReleaseIds = "singletonReleaseIds" in state && state.singletonReleaseIds && typeof state.singletonReleaseIds === "object" && !Array.isArray(state.singletonReleaseIds)
+    ? state.singletonReleaseIds
+    : {}
+
+  if (Array.isArray(snapshot.singletons)) {
     for (const singleton of snapshot.singletons) {
-      if (singleton && typeof singleton === "object" && !Array.isArray(singleton) && typeof singleton.id === "string") keys.add(`singleton:${snapshot.activeReleaseId}:${singleton.id}`)
+      if (!singleton || typeof singleton !== "object" || Array.isArray(singleton) || typeof singleton.id !== "string") continue
+      const releaseId = singleton.id in singletonReleaseIds && typeof singletonReleaseIds[singleton.id] === "string"
+        ? singletonReleaseIds[singleton.id]
+        : snapshot.activeReleaseId
+
+      if (typeof releaseId === "string") keys.add(`singleton:${releaseId}:${singleton.id}`)
     }
   }
   return keys

package/test/guardian-client.test.js

@@ -224,6 +224,42 @@ test("retired owner replacement commit carries its exact recovered process key",
   await client.commitRetiredOwnerReplacement(replacementId, processKey)
 })
 
+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})
+  const committedProcessKey = "release:v1:worker"
+  const candidateProcessKey = "release:candidate:worker"
+  const authority = {configDigest: "owner", runtime: null}
+  const snapshot = {
+    activeReleaseId: "v1",
+    control: {path: path.join(fixture.root, "rollbridge.sock")},
+    releases: [{processes: [{id: "worker"}], releaseId: "v1"}],
+    services: [],
+    singletons: []
+  }
+  const candidateSnapshot = {
+    ...snapshot,
+    releases: [...snapshot.releases, {processes: [{id: "worker"}], releaseId: "candidate"}]
+  }
+
+  try {
+    await fixture.client.process(committedProcessKey, definition("worker")).recover()
+    await fixture.client.process(candidateProcessKey, definition("candidate-worker")).recover()
+    await fixture.client.publishOwnerState({authority, snapshot})
+    await candidate.connect()
+    const prepared = await candidate.prepareOwnerReplacement(authority, authority)
+
+    await candidate.stageOwnerReplacement(prepared.replacementId, {authority, snapshot: candidateSnapshot})
+    await assert.rejects(
+      () => candidate.commitRetiredOwnerReplacement(prepared.replacementId, candidateProcessKey),
+      /process .* does not belong to the committed owner/
+    )
+  } finally {
+    candidate.disconnect()
+    await cleanupGuardian(fixture)
+  }
+})
+
 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})
@@ -232,7 +268,13 @@ test("retired owner replacement requires unchanged authority and the exact contr
   const processKey = "release:v1:worker"
   const authority = {configDigest: "incumbent", runtime: null}
   const nextAuthority = {configDigest: "candidate", runtime: null}
-  const snapshot = {activeReleaseId: "v1", control: {path: controlPath}}
+  const snapshot = {
+    activeReleaseId: "v1",
+    control: {path: controlPath},
+    releases: [{processes: [{id: "worker"}], releaseId: "v1"}],
+    services: [],
+    singletons: []
+  }
 
   try {
     await fixture.client.process(processKey, definition("worker")).recover()
@@ -260,6 +302,10 @@ test("retired owner replacement requires unchanged authority and the exact contr
       () => contender.request({command: "commit-retired-owner-replacement", key: processKey, replacementId: ready.replacementId}),
       /not the prepared candidate/
     )
+    await assert.rejects(
+      () => candidate.commitRetiredOwnerReplacement("stale-replacement", processKey),
+      /not the prepared candidate/
+    )
     await assert.rejects(
       () => candidate.commitRetiredOwnerReplacement(ready.replacementId, "release:v1:wrong"),
       /process .* is not registered/

package/test/owner-replacement.test.js

@@ -249,13 +249,161 @@ 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 compatibilitySockets = new Set()
+  let compatibilityGuardian
+  let committedProcessKey
+  let retainedGuardianSocketPath = /** @type {string | undefined} */ (undefined)
+  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 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
+
+    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"
+
+    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 === "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(transactionStatus.committedReplacementId, null)
+    assert.equal(transactionStatus.ownerClaimed, true)
+    assert.equal(transactionStatus.retirementPending, false)
+  } finally {
+    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)
+    if (retainedGuardianSocketPath) {
+      const cleanupState = JSON.parse(await fs.readFile(statePath, "utf8"))
+
+      cleanupState.recovery.guardian.socketPath = retainedGuardianSocketPath
+      await fs.writeFile(statePath, `${JSON.stringify(cleanupState)}\n`)
+    }
+    await stopGuardian(statePath)
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
+test("same-authority replacement commits with committed-owner proof after the incumbent control socket is removed", 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 releasePath = path.join(root, "v1")
   const daemonConfig = normalizeConfig(config({controlPath: socketPath, extraCompanion: false, statePath}))
   const owner = new RollbridgeDaemon({config: daemonConfig, logger: () => {}})
+  const candidateProcessKey = "release:candidate:worker"
+  const committedOwnerProcessKey = "release:v1:worker"
+  let committedProcessKey
+  /** @type {RollbridgeDaemon | undefined} */
   let replacement
 
   try {
@@ -263,6 +411,16 @@ test("same-authority replacement commits after a retired incumbent already remov
     await makeFifo(path.join(releasePath, "worker.fifo"))
     await owner.start()
     await owner.deploy({releaseId: "v1", releasePath, revision: "v1"})
+    const ownerProcess = owner.guardian?.processes.values().next().value
+
+    assert.ok(owner.guardian)
+    assert.ok(ownerProcess)
+    await owner.guardian.request({
+      command: "register",
+      definition: ownerProcess.definition,
+      key: candidateProcessKey,
+      provenance: ownerProcess.provenance
+    })
     await Promise.all([...owner.releases.values()].map((release) => release.quiesce()))
     await owner.closeServer(owner.controlServer)
     await owner.removeControlSocket()
@@ -274,12 +432,29 @@ test("same-authority replacement commits after a retired incumbent already remov
     assert.equal((await owner.guardian?.replacementStatus())?.ownerClaimed, true)
     await assert.rejects(fs.access(socketPath), {code: "ENOENT"})
 
-    replacement = new RollbridgeDaemon({config: daemonConfig, logger: () => {}})
+    replacement = new RollbridgeDaemon({
+      config: daemonConfig,
+      logger: (message) => {
+        if (message !== "owner replacement candidate prepared" || !replacement?.guardian) return
+        const guardian = replacement.guardian
+        const recoveredProcess = guardian.processes.values().next().value
+
+        if (!recoveredProcess) throw new Error("Replacement did not reconstruct a guardian process")
+        guardian.processes = new Map([[candidateProcessKey, recoveredProcess], ...guardian.processes])
+        const commitRetiredOwnerReplacement = guardian.commitRetiredOwnerReplacement.bind(guardian)
+
+        guardian.commitRetiredOwnerReplacement = async (replacementId, processKey) => {
+          committedProcessKey = processKey
+          await commitRetiredOwnerReplacement(replacementId, processKey)
+        }
+      }
+    })
     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.equal(recovered.activeReleaseId, "v1")
+    assert.equal(committedProcessKey, committedOwnerProcessKey)
     assert.deepEqual(recovered.releaseReferences, [{releaseId: "v1", releasePath}])
     assert.deepEqual(recoveredReleases[0]?.processes.map(({id, pid, state}) => ({id, pid, state})), processState)
   } finally {