rollbridge 0.1.29 → 0.1.31

package/package.json

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

package/src/daemon.js

@@ -300,6 +300,7 @@ export default class RollbridgeDaemon {
     let stagingControlPath
     let finalControlPublished = false
     let listenersYielded = false
+    let retiredIncumbentControl = false
     let retainIncumbentControl = false
     let incumbentControl = legacyBridge?.incumbentControl
 
@@ -325,22 +326,31 @@ export default class RollbridgeDaemon {
       if (legacyBridge) {
         await this.crossLegacyDisruptiveBoundary(legacyBridge)
       } else if (preparedStatus.ownerClaimed) {
-        incumbentControl = await openControlSession(transfer.snapshot.control.path)
-        const listenerSession = incumbentControl
-
-        incumbentControl.onEvent((event) => this.handleIncumbentListenerEvent(event, listenerSession))
-        await incumbentControl.request({
-          command: "yield-owner-listeners",
-          control: transfer.snapshot.control.path === this.config.control.path,
-          proxy: true,
-          replacementId: prepared.replacementId
-        })
-        listenersYielded = true
+        try {
+          incumbentControl = await openControlSession(transfer.snapshot.control.path)
+        } catch (error) {
+          if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") throw error
+          retiredIncumbentControl = true
+        }
+        if (incumbentControl) {
+          const listenerSession = incumbentControl
+
+          incumbentControl.onEvent((event) => this.handleIncumbentListenerEvent(event, listenerSession))
+          await incumbentControl.request({
+            command: "yield-owner-listeners",
+            control: transfer.snapshot.control.path === this.config.control.path,
+            proxy: true,
+            replacementId: prepared.replacementId
+          })
+          listenersYielded = true
+        }
       }
       if (sharedFixedProxy) await this.startProxy()
-      await fs.rename(stagingControlPath, this.config.control.path)
-      finalControlPublished = true
-      this.boundControlPath = this.config.control.path
+      if (!retiredIncumbentControl) {
+        await fs.rename(stagingControlPath, this.config.control.path)
+        finalControlPublished = true
+        this.boundControlPath = this.config.control.path
+      }
       const committed = this.guardian.waitForEvent("replacement-committed")
       const staged = await this.guardian.stageOwnerReplacement(prepared.replacementId, {
         authority: this.ownerAuthority(),
@@ -350,18 +360,27 @@ export default class RollbridgeDaemon {
       })
 
       if (!staged.committed) {
-        try {
-          if (!incumbentControl) throw new Error("Owner replacement incumbent control session is unavailable")
-          await incumbentControl.request({command: "commit-owner-replacement", replacementId: prepared.replacementId})
-        } catch (error) {
-          const status = await this.guardian.replacementStatus()
-
-          if (status.committedReplacementId !== prepared.replacementId || !status.ownerClaimed) throw error
-          this.logger("owner replacement commit response lost; guardian commit confirmed", {replacementId: prepared.replacementId})
+        if (retiredIncumbentControl) {
+          await this.guardian.commitRetiredOwnerReplacement(prepared.replacementId)
+        } else {
+          try {
+            if (!incumbentControl) throw new Error("Owner replacement incumbent control session is unavailable")
+            await incumbentControl.request({command: "commit-owner-replacement", replacementId: prepared.replacementId})
+          } catch (error) {
+            const status = await this.guardian.replacementStatus()
+
+            if (status.committedReplacementId !== prepared.replacementId || !status.ownerClaimed) throw error
+            this.logger("owner replacement commit response lost; guardian commit confirmed", {replacementId: prepared.replacementId})
+          }
         }
       }
       await committed
       committedAuthority = true
+      if (retiredIncumbentControl) {
+        await fs.rename(stagingControlPath, this.config.control.path)
+        finalControlPublished = true
+        this.boundControlPath = this.config.control.path
+      }
       if (!legacyBridge && incumbentControl && [...this.releases.values()].some((release) => release.hasTransferredConnections())) {
         this.incumbentListenerControl = incumbentControl
         retainIncumbentControl = true
@@ -1437,11 +1456,11 @@ export default class RollbridgeDaemon {
   /**
    * Persists a state snapshot (status plus recent events) to statePath, atomically and
    * fire-and-forget unless the caller awaits the returned write. A failed write is logged.
-   * @param {{throwOnError?: boolean}} [options] - Whether a write failure rejects the returned promise.
+   * @param {{allowStopping?: boolean, throwOnError?: boolean}} [options] - Write behavior.
    * @returns {Promise<void> | undefined} The queued write, or undefined when persistence is disabled.
    */
-  persistState({throwOnError = false} = {}) {
-    if (!this.statePath || !this.persistenceEnabled || this.stopping) return
+  persistState({allowStopping = false, throwOnError = false} = {}) {
+    if (!this.statePath || !this.persistenceEnabled || (this.stopping && !allowStopping)) return
 
     const statePath = this.statePath
     const status = /** @type {Record<string, JsonValue>} */ (secretSafeStateValue(this.status()))
@@ -1533,25 +1552,35 @@ export default class RollbridgeDaemon {
       clearInterval(this.persistTimer)
       this.persistTimer = undefined
     }
-    this.persistenceEnabled = false
     if (this.pendingWrite) await this.pendingWrite
     this.stateCleanupEnabled = false
     this.controlClosePromise = this.closeServer(this.controlServer)
     for (const socket of this.controlSockets) if (socket !== completionSocket) socket.destroy()
+    if (this.activeRelease) {
+      await this.activeRelease.beginRetirement(this.activeRelease.config)
+      this.activeRelease = undefined
+    }
     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.persistState({allowStopping: true, throwOnError: true})
+    this.persistenceEnabled = false
     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())
-    ])
+    if (this.guardian) {
+      await this.guardian.retireOwner()
+      this.guardian.disconnect()
+    } else {
+      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"})
   }
 

package/src/guardian-client.js

@@ -156,6 +156,11 @@ export default class GuardianClient {
     await this.request({authority, command: "claim-owner", graceMs})
   }
 
+  /** Starts graceful process retirement and relinquishes committed owner authority. */
+  async retireOwner() {
+    await this.request({command: "retire-owner"})
+  }
+
   /** @param {import("./json.js").JsonValue} ownerState - Private transferable owner state. */
   async publishOwnerState(ownerState) {
     await this.request({command: "publish-owner-state", ownerState})
@@ -189,6 +194,11 @@ 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 - Committed transaction awaiting incumbent retirement. */
   async finalizeOwnerReplacement(replacementId) {
     await this.request({command: "finalize-owner-replacement", replacementId})

package/src/process-guardian.js

@@ -200,6 +200,19 @@ async function execute(request, socket) {
     })
   }
 
+  if (request.command === "retire-owner") {
+    requireOwner(socket, request.command)
+    if (replacementClient) throw new Error("Committed owner cannot retire while an owner replacement is prepared")
+    for (const entry of processes.values()) entry.desired = false
+    void Promise.allSettled([...processes.values()].map((entry) => entry.process.stop()))
+    ownerClient = undefined
+    ownerMutationClient = undefined
+    ownerMutationId = undefined
+    ownerRevision += 1
+    grantNextOwner()
+    return {retired: true}
+  }
+
   if (request.command === "abandon-legacy-upgrade") {
     if (!legacyGuardian) throw new Error("Guardian is not a legacy upgrade coordinator")
     if (ownerClient || committedReplacementId) throw new Error("Committed guardian authority cannot abandon its legacy backend")
@@ -284,6 +297,23 @@ async function execute(request, socket) {
     return {aborted: true}
   }
 
+  if (request.command === "commit-retired-owner-replacement") {
+    requireReplacement(socket, 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)
+
+    try {
+      await fs.lstat(controlPath)
+      throw new Error(`Retired owner control socket ${controlPath} still exists`)
+    } catch (error) {
+      if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") throw error
+    }
+    commitReplacement()
+    finalizeReplacementRetirement()
+    return {committed: true}
+  }
+
   if (request.command === "commit-owner-replacement") {
     requireOwner(socket, request.command)
     if (!replacementClient || request.replacementId !== replacementId || !replacementOwnerState) throw new Error("Owner replacement transaction is not the prepared ready candidate")
@@ -497,6 +527,21 @@ function ownerAuthority(state) {
   return state.authority
 }
 
+/**
+ * @param {import("./json.js").JsonValue | undefined} state - Committed transferable state.
+ * @returns {string} Exact incumbent public control path.
+ */
+function ownerControlPath(state) {
+  if (!state || typeof state !== "object" || Array.isArray(state) || !("snapshot" in state)) throw new Error("Guardian owner state is missing its committed snapshot")
+  const snapshot = state.snapshot
+
+  if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot) || !("control" in snapshot)) throw new Error("Guardian owner snapshot is missing its control identity")
+  const control = snapshot.control
+
+  if (!control || typeof control !== "object" || Array.isArray(control) || !("path" in control) || typeof control.path !== "string") throw new Error("Guardian owner snapshot has an invalid control identity")
+  return control.path
+}
+
 /**
  * Stops accepting connections and closes every authority channel except the response caller.
  * @param {net.Socket} caller - Shutdown requester retained until it receives the response.

package/test/guardian-client.test.js

@@ -171,6 +171,37 @@ test("replacement staging rejects owner state published after prepare", async ()
   }
 })
 
+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 controlPath = path.join(fixture.root, "rollbridge.sock")
+  const authority = {configDigest: "incumbent", runtime: null}
+  const nextAuthority = {configDigest: "candidate", runtime: null}
+  const snapshot = {activeReleaseId: "v1", control: {path: controlPath}}
+
+  try {
+    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 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 candidate.abortOwnerReplacement(occupied.replacementId)
+    await fixture.client.shutdown()
+    await fixture.client.guardianExit()
+  } finally {
+    candidate.disconnect()
+    await cleanupGuardian(fixture)
+  }
+})
+
 test("first upgrade migrates a real pre-split guardian without replacing its owned process", async () => {
   const fixture = await createLegacyGuardian()
   const processDefinition = definition("legacy-worker")

package/test/owner-recovery.test.js

@@ -9,6 +9,7 @@ import os from "node:os"
 import path from "node:path"
 import test from "node:test"
 import {fileURLToPath} from "node:url"
+import {normalizeConfig} from "../src/config.js"
 import {sendControlCommand} from "../src/control-client.js"
 import RollbridgeDaemon from "../src/daemon.js"
 import GuardianClient from "../src/guardian-client.js"
@@ -21,6 +22,79 @@ const serviceAppPath = path.join(currentDir, "fixtures", "service-app.js")
 /** @typedef {import("../src/daemon.js").DaemonStatus} DaemonStatus */
 /** @typedef {DaemonStatus & {recovery: {configDigest: string}}} RecoveryState */
 
+test("external owner retirement releases guardian authority without losing its generation", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-owner-retirement-recovery-"))
+  const socketPath = path.join(root, "rollbridge.sock")
+  const statePath = path.join(root, "rollbridge.state.json")
+  const v1Path = path.join(root, "v1")
+  const v2Path = path.join(root, "v2")
+  const config = normalizeConfig({
+    application: "owner-retirement-recovery-test",
+    control: {path: socketPath},
+    ownerRecovery: {reconnectGraceMs: 50},
+    processes: [
+      {
+        command: `${JSON.stringify(process.execPath)} -e ${JSON.stringify("setInterval(() => {}, 1000)")}`,
+        id: "worker",
+        lifecycle: {drainCommand: "printf started > \"$ROLLBRIDGE_RELEASE_PATH/drain-started\"; while [ ! -f \"$ROLLBRIDGE_RELEASE_PATH/drained\" ]; do sleep 0.01; done", drainTimeoutMs: 3000},
+        nonBlockingDrain: true,
+        policy: "companion"
+      },
+      {
+        command: `${JSON.stringify(process.execPath)} ${JSON.stringify(dummyAppPath)}`,
+        health: {intervalMs: 25, path: "/ping", timeoutMs: 3000},
+        id: "web",
+        policy: "proxied",
+        port: {from: 0, to: 0}
+      }
+    ],
+    proxy: {forceStopTimeoutMs: 500, healthPath: "/ping", healthTimeoutMs: 3000, host: "127.0.0.1", port: 0},
+    statePath
+  })
+  const retired = new RollbridgeDaemon({config, logger: () => {}})
+  let replacement
+
+  try {
+    await Promise.all([fs.mkdir(v1Path), fs.mkdir(v2Path)])
+    await retired.start()
+    await retired.deploy({releaseId: "v1", releasePath: v1Path, revision: "v1"})
+    const before = retired.status()
+    const v1WorkerPid = releaseProcessPid(before, "v1", "worker")
+
+    replacement = new RollbridgeDaemon({config, logger: () => {}})
+    await replacement.deploy({releaseId: "v2", releasePath: v2Path, revision: "v2"})
+    const v2WorkerPid = releaseProcessPid(replacement.status(), "v2", "worker")
+
+    await retired.retireOwner({attestation: `sha256:${"a".repeat(64)}`})
+    await replacement.start({reportOrphans: false})
+    const recovered = replacement.status()
+    const v1 = recovered.releases.find(({releaseId}) => releaseId === "v1")
+    const v2 = recovered.releases.find(({releaseId}) => releaseId === "v2")
+
+    assert.equal(recovered.activeReleaseId, "v2", "the prestarted candidate must remain active")
+    assert.deepEqual(recovered.releaseReferences.sort((a, b) => a.releaseId.localeCompare(b.releaseId)), [
+      {releaseId: "v1", releasePath: v1Path},
+      {releaseId: "v2", releasePath: v2Path}
+    ])
+    assert.equal(v1?.state, "draining")
+    assert.equal(v1?.processes.find(({id}) => id === "worker")?.pid, v1WorkerPid)
+    assert.equal(v1?.processes.find(({id}) => id === "worker")?.state, "quiesced")
+    assert.equal(v2?.state, "active")
+    assert.equal(v2?.processes.find(({id}) => id === "worker")?.pid, v2WorkerPid)
+    assert.equal(v2?.processes.find(({id}) => id === "worker")?.state, "running")
+    await waitForFile(path.join(v1Path, "drain-started"), 1000)
+    await fs.writeFile(path.join(v1Path, "drained"), "done\n")
+    await waitForProcessExit(v1WorkerPid, 1000)
+    assert.equal(isAlive(v2WorkerPid), true, "the active candidate worker must remain usable while the old generation drains")
+  } finally {
+    await Promise.all([v1Path, v2Path].map((releasePath) => fs.writeFile(path.join(releasePath, "drained"), "done\n").catch(() => {})))
+    await replacement?.shutdown().catch(() => {})
+    retired.guardian?.disconnect()
+    await stopFixtureGuardian(statePath)
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
 test("replacement owner reconstructs one active and two draining generations after abrupt daemon exit", async () => {
   const fixture = await createFixture()
   let owner = spawnDaemon(fixture.configPath)
@@ -687,16 +761,19 @@ async function waitForState(statePath, predicate) {
 
 /**
  * @param {string} filePath - File whose creation is the transaction-boundary signal.
+ * @param {number} [timeoutMs] - Optional bounded wait.
  * @returns {Promise<void>} Resolves when the file exists.
  */
-async function waitForFile(filePath) {
+async function waitForFile(filePath, timeoutMs) {
   try {
     await fs.access(filePath)
     return
   } catch (error) {
     if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") throw error
   }
-  const watcher = fs.watch(path.dirname(filePath))
+  const controller = timeoutMs === undefined ? undefined : new AbortController()
+  const timer = timeoutMs === undefined ? undefined : setTimeout(() => controller?.abort(), timeoutMs)
+  const watcher = fs.watch(path.dirname(filePath), {signal: controller?.signal})
 
   try {
     for await (const change of watcher) {
@@ -708,11 +785,26 @@ async function waitForFile(filePath) {
         if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") throw error
       }
     }
+  } catch (error) {
+    if (error && typeof error === "object" && "name" in error && error.name === "AbortError") throw new Error(`Timed out waiting for ${filePath}`, {cause: error})
+    throw error
   } finally {
+    clearTimeout(timer)
     await watcher.return?.()
   }
 }
 
+/**
+ * @param {number} pid - Exact fixture process.
+ * @param {number} timeoutMs - Bounded exit wait.
+ */
+async function waitForProcessExit(pid, timeoutMs) {
+  const deadline = Date.now() + timeoutMs
+
+  while (isAlive(pid) && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 10))
+  assert.equal(isAlive(pid), false, `process ${pid} did not exit within ${timeoutMs}ms`)
+}
+
 /**
  * Opens a live WebSocket through the fixture proxy.
  * @param {number} port - Proxy port.

package/test/owner-replacement.test.js

@@ -9,8 +9,9 @@ import os from "node:os"
 import path from "node:path"
 import test from "node:test"
 import {fileURLToPath} from "node:url"
+import {normalizeConfig} from "../src/config.js"
 import {sendControlCommand} from "../src/control-client.js"
-import {isLegacyGuardianPrepareDiagnostic} from "../src/daemon.js"
+import RollbridgeDaemon, {isLegacyGuardianPrepareDiagnostic} from "../src/daemon.js"
 import GuardianClient from "../src/guardian-client.js"
 import {findAvailablePort} from "../src/port-allocator.js"
 
@@ -248,6 +249,50 @@ 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 () => {
+  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 releasePath = path.join(root, "v1")
+  const daemonConfig = normalizeConfig(config({controlPath: socketPath, extraCompanion: false, statePath}))
+  const owner = new RollbridgeDaemon({config: daemonConfig, logger: () => {}})
+  let replacement
+
+  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"})
+
+    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.equal(recovered.activeReleaseId, "v1")
+    assert.deepEqual(recovered.releaseReferences, [{releaseId: "v1", releasePath}])
+    assert.deepEqual(recoveredReleases[0]?.processes.map(({id, pid, state}) => ({id, pid, state})), processState)
+  } 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()
+    replacement?.guardian?.disconnect()
+    await stopGuardian(statePath)
+    await fs.rm(root, {force: true, recursive: true})
+  }
+})
+
 test("replacement refuses to overwrite an unrelated live final control socket and preserves the owner", async () => {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "rollbridge-owner-replacement-fence-"))
   const oldSocketPath = path.join(root, "old.sock")