rollbridge 0.1.76 → 0.1.78

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rollbridge",
3
- "version": "0.1.76",
3
+ "version": "0.1.78",
4
4
  "description": "Zero-downtime process supervisor and local traffic switcher for deploy-managed apps.",
5
5
  "keywords": [
6
6
  "deploy",
package/src/daemon.js CHANGED
@@ -38,7 +38,7 @@ const STATE_PERSIST_INTERVAL_MS = 5000
38
38
  * @typedef {{configDigest: string, format: number, guardian: {pid?: number, socketPath: string, token: string}, reconnectGraceMs: number}} OwnerRecoveryMetadata
39
39
  * @typedef {DaemonStatus & {recovery: OwnerRecoveryMetadata, serviceReleaseIds?: Record<string, string>, singletonReleaseIds?: Record<string, string>}} OwnerRecoverySnapshot
40
40
  * @typedef {{authority: JsonValue, config: import("./config.js").RollbridgeConfig, listenerConnectionSources?: Record<string, Record<string, {http: number, websocket: number}>>, listenerSourceId?: string, recovery?: {command: JsonValue, reconnectGraceMs: number, startupTimeoutMs: number}, releaseConfigs?: Record<string, import("./config.js").RollbridgeConfig>, retiredListenerHandoff?: number, serviceReleaseIds?: Record<string, string>, singletonReleaseIds?: Record<string, string>, snapshot: OwnerRecoverySnapshot}} PrivateOwnerState
41
- * @typedef {{boundaryCrossed: boolean, guardianVersion?: string, incumbentControl?: Awaited<ReturnType<typeof openControlSession>>, incumbentStartTime: string, legacyGuardian: GuardianClient, legacyInventory: {key: string, provenance: string}[], legacyPrepared?: {ownerState: JsonValue, replacementId: string}, legacySnapshot: OwnerRecoverySnapshot, prepared: {ownerState: JsonValue, replacementId: string}, protocol: GuardianHandoffProtocol, recoverySnapshot: OwnerRecoverySnapshot}} LegacyOwnerBridge
41
+ * @typedef {{boundaryCrossed: boolean, guardianVersion?: string, incumbentControl?: Awaited<ReturnType<typeof openControlSession>>, incumbentStartTime: string, legacyGuardian: GuardianClient, legacyInventory: {key: string, provenance: string, status: import("./managed-process.js").ManagedProcessStatus}[], legacyPrepared?: {ownerState: JsonValue, replacementId: string}, legacySnapshot: OwnerRecoverySnapshot, prepared: {ownerState: JsonValue, replacementId: string}, protocol: GuardianHandoffProtocol, recoverySnapshot: OwnerRecoverySnapshot}} LegacyOwnerBridge
42
42
  */
43
43
 
44
44
  export default class RollbridgeDaemon {
@@ -1134,7 +1134,7 @@ export default class RollbridgeDaemon {
1134
1134
  }
1135
1135
  const currentInventory = normalizeLegacyGuardianInventory(await bridge.legacyGuardian.inventory())
1136
1136
 
1137
- if (!isDeepStrictEqual(currentInventory, bridge.legacyInventory)) {
1137
+ if (!isDeepStrictEqual(legacyInventoryIdentity(currentInventory), legacyInventoryIdentity(bridge.legacyInventory))) {
1138
1138
  throw new Error("Legacy guardian process inventory changed before the disruptive boundary")
1139
1139
  }
1140
1140
  const candidateOwnerState = {
@@ -1146,7 +1146,11 @@ export default class RollbridgeDaemon {
1146
1146
  snapshot: this.status()
1147
1147
  }
1148
1148
 
1149
- assertLegacyGuardianInventoryMembership(currentInventory, candidateOwnerState)
1149
+ // A legacy guardian keeps stopped registrations until its owner reconciles them. The
1150
+ // replacement intentionally does not reconstruct stopped releases; prove every live
1151
+ // registration exactly, while allowing only this known, non-running residue through the
1152
+ // disruptive boundary.
1153
+ assertLegacyGuardianInventoryMembership(currentInventory, candidateOwnerState, {allowStopped: true})
1150
1154
  let legacyCommitted
1151
1155
 
1152
1156
  if (bridge.legacyPrepared) {
@@ -2944,8 +2948,9 @@ export default class RollbridgeDaemon {
2944
2948
  */
2945
2949
  async drainAndPrune(release, config = this.config) {
2946
2950
  try {
2947
- await release.drainAndStop(config.proxy.drainTimeoutMs, config)
2948
- this.logger("release drained", {releaseId: release.releaseId})
2951
+ const drained = await release.drainAndStop(config.proxy.drainTimeoutMs, config)
2952
+ if (drained) this.logger("release drained", {releaseId: release.releaseId})
2953
+ else this.logger("release drain remains active", {releaseId: release.releaseId})
2949
2954
  } catch (error) {
2950
2955
  this.logger("release drain failed", {error: error instanceof Error ? error.message : String(error), releaseId: release.releaseId})
2951
2956
  } finally {
@@ -3539,15 +3544,15 @@ function reconstructableOwnerSnapshotProcessKeys(snapshot, singletonReleaseIds =
3539
3544
 
3540
3545
  /**
3541
3546
  * Canonicalizes the authenticated guardian inventory without relying on map insertion order.
3542
- * @param {{key: string, provenance: string}[]} inventory - Guardian inventory response.
3543
- * @returns {{key: string, provenance: string}[]} Exact key/provenance fence.
3547
+ * @param {{key: string, provenance: string, status: import("./managed-process.js").ManagedProcessStatus}[]} inventory - Guardian inventory response.
3548
+ * @returns {{key: string, provenance: string, status: import("./managed-process.js").ManagedProcessStatus}[]} Exact key/provenance/status fence.
3544
3549
  */
3545
3550
  function normalizeLegacyGuardianInventory(inventory) {
3546
3551
  const normalized = inventory.map((entry) => {
3547
3552
  if (!entry || typeof entry.key !== "string" || !entry.key || typeof entry.provenance !== "string" || !entry.provenance) {
3548
3553
  throw new Error("Legacy guardian returned an invalid process inventory")
3549
3554
  }
3550
- return {key: entry.key, provenance: entry.provenance}
3555
+ return {key: entry.key, provenance: entry.provenance, status: entry.status}
3551
3556
  }).sort((left, right) => left.key.localeCompare(right.key))
3552
3557
 
3553
3558
  if (new Set(normalized.map(({key}) => key)).size !== normalized.length) {
@@ -3556,14 +3561,23 @@ function normalizeLegacyGuardianInventory(inventory) {
3556
3561
  return normalized
3557
3562
  }
3558
3563
 
3564
+ /**
3565
+ * @param {{key: string, provenance: string, status: import("./managed-process.js").ManagedProcessStatus}[]} inventory - Canonical guardian inventory.
3566
+ * @returns {{key: string, provenance: string}[]} Stable guardian inventory identity.
3567
+ */
3568
+ function legacyInventoryIdentity(inventory) {
3569
+ return inventory.map(({key, provenance}) => ({key, provenance}))
3570
+ }
3571
+
3559
3572
  /**
3560
3573
  * Requires every and only the process registrations serialized by committed private owner state.
3561
- * @param {{key: string, provenance: string}[]} inventory - Canonical guardian inventory.
3574
+ * @param {{key: string, provenance: string, status: import("./managed-process.js").ManagedProcessStatus}[]} inventory - Canonical guardian inventory.
3562
3575
  * @param {{snapshot: DaemonStatus, singletonReleaseIds?: Record<string, string>}} ownerState - Authenticated owner process snapshot.
3576
+ * @param {{allowStopped?: boolean}} [options] - Whether known stopped registrations may remain during legacy handoff.
3563
3577
  */
3564
- function assertLegacyGuardianInventoryMembership(inventory, ownerState) {
3578
+ export function assertLegacyGuardianInventoryMembership(inventory, ownerState, {allowStopped = false} = {}) {
3565
3579
  if (!ownerState?.snapshot) throw new Error("Legacy guardian owner state is missing its committed process snapshot")
3566
- const inventoryKeys = inventory.map(({key}) => key)
3580
+ const inventoryKeys = inventory.filter(({status}) => !allowStopped || status.state !== "stopped").map(({key}) => key)
3567
3581
  const snapshotKeys = ownerSnapshotProcessKeys(ownerState.snapshot, ownerState.singletonReleaseIds).sort((left, right) => left.localeCompare(right))
3568
3582
 
3569
3583
  if (!isDeepStrictEqual(inventoryKeys, snapshotKeys)) {
@@ -552,9 +552,13 @@ export default class ManagedProcess extends EventEmitter {
552
552
 
553
553
  // 2. Drain: let in-flight work finish, bounded by drainTimeoutMs (0 skips the step). A
554
554
  // drainCommand blocks until drained; otherwise wait for the process to exit on its own.
555
- if (this.processGroupExists(pgid) && drainTimeoutMs > 0) {
556
- if (drainCommand) await this.runHook(drainCommand, drainTimeoutMs, "drain command")
557
- else await this.waitForExit(drainTimeoutMs)
555
+ const drainBudgetMs = retirementDeadline === undefined
556
+ ? drainTimeoutMs
557
+ : Math.max(0, Math.min(drainTimeoutMs, retirementDeadline - Date.now()))
558
+
559
+ if (this.processGroupExists(pgid) && drainBudgetMs > 0) {
560
+ if (drainCommand) await this.runHook(drainCommand, drainBudgetMs, "drain command")
561
+ else await this.waitForExit(drainBudgetMs)
558
562
  }
559
563
 
560
564
  // 3. Stop whatever is still running, then SIGKILL if it outlasts the graceful window.
@@ -886,10 +886,10 @@ export default class ReleaseGroup extends EventEmitter {
886
886
  * Starts draining and stops once existing connections close or timeout.
887
887
  * @param {number} timeoutMs - Drain timeout.
888
888
  * @param {import("./config.js").RollbridgeConfig} [config] - Refreshed config governing retirement.
889
- * @returns {Promise<void>} Resolves when stopped.
889
+ * @returns {Promise<boolean | undefined>} True when every supervised process retired; false when a live process remains; undefined when owner handoff paused the drain.
890
890
  */
891
891
  async drainAndStop(timeoutMs, config = this.config) {
892
- if (this.state === "stopped") return
892
+ if (this.state === "stopped") return this.processesAreRetired()
893
893
 
894
894
  if (this.state !== "draining") await this.beginRetirement(config)
895
895
 
@@ -957,6 +957,12 @@ export default class ReleaseGroup extends EventEmitter {
957
957
  // it does not end silently with the process still holding the release.
958
958
  if (retirementBaselineSample) await this.escalateWedgedGeneration({previousSample: retirementBaselineSample, reason: "release retirement"})
959
959
 
960
+ // A bounded retirement may return while a non-blocking process is still draining, but that
961
+ // is not a completed release drain. Keep the generation in the retirement path so a later
962
+ // deployment can observe or escalate it; a live process must never disappear behind a
963
+ // "release drained" record.
964
+ if (!this.processesAreRetired()) return false
965
+
960
966
  this.state = "stopped"
961
967
  this.stoppedAt = new Date().toISOString()
962
968
  this.releasePortReservations()
@@ -964,6 +970,16 @@ export default class ReleaseGroup extends EventEmitter {
964
970
  // The bracket pair is deliberately kept: a generation that stopped with a live process
965
971
  // group stays observable, and the deploy path needs the older observation to prove the
966
972
  // residue is still flat rather than starting a fresh window from zero.
973
+ return true
974
+ }
975
+
976
+ /** @returns {boolean} Whether every supervised process has exited and left no process group behind. */
977
+ processesAreRetired() {
978
+ return [...this.processes.values()].every((processInstance) => {
979
+ const {heldProcessGroup, pid, state} = processInstance.status()
980
+
981
+ return heldProcessGroup === undefined && pid === undefined && (state === "stopped" || state === "failed")
982
+ })
967
983
  }
968
984
 
969
985
  /**
@@ -743,11 +743,12 @@ test("guardian recovery becomes ready before replaying a gated generation hook",
743
743
  process.kill(recoveredDaemonPid, "SIGTERM")
744
744
  await fs.writeFile(retirementGatePath, "release retirement\n")
745
745
  await waitForProcessExit(recoveredDaemonPid, 5000)
746
- await waitForProcessExit(guardianPid, 5000)
747
- // The old generation is quiesced only after traffic switched to the candidate, so its quiet
748
- // hook runs first; the candidate's own quiet hook can only run at shutdown. This is the order
749
- // the same file asserts at lines 177 and 313.
750
- expect(await lifecycleEvents(fixture.lifecycleLogPath)).toEqual(["activate:v1", "activate:v2", "retire:v1", "retire:v2"])
746
+ // An owner-recovery SIGTERM deliberately leaves the durable guardian alive so it can
747
+ // re-establish ownership and preserve the active generation for the replacement daemon.
748
+ expect(isProcessRunning(guardianPid)).toBe(true)
749
+ // The old generation is quiesced only after traffic switched to the candidate. The candidate
750
+ // remains active under the replacement owner, so its quiet hook must not run during recovery.
751
+ await waitForLifecycleEvents(fixture.lifecycleLogPath, ["activate:v1", "activate:v2", "retire:v1"])
751
752
  } finally {
752
753
  await fs.writeFile(retirementGatePath, "release retirement\n").catch(() => undefined)
753
754
  await sendControlCommand({command: {command: "shutdown"}, path: fixture.socketPath}).catch(() => undefined)
@@ -10,13 +10,48 @@ import {describe, expect, test} from "@velocious/testing"
10
10
  import {fileURLToPath} from "node:url"
11
11
  import {normalizeConfig} from "../src/config.js"
12
12
  import {openControlSession, sendControlCommand} from "../src/control-client.js"
13
- import RollbridgeDaemon, {isLegacyGuardianPrepareDiagnostic, ownerConfigDigest, ownerReplacementTransitionAuthorityMatches} from "../src/daemon.js"
13
+ import RollbridgeDaemon, {assertLegacyGuardianInventoryMembership, isLegacyGuardianPrepareDiagnostic, ownerConfigDigest, ownerReplacementTransitionAuthorityMatches} from "../src/daemon.js"
14
14
  import GuardianClient from "../src/guardian-client.js"
15
15
  import {findAvailablePort} from "../src/port-allocator.js"
16
16
  import {isProcessRunning, waitForProcessExit} from "./support/process.js"
17
17
 
18
18
  describe("owner-replacement", () => {
19
19
 
20
+ test("legacy owner proof ignores only stopped registrations omitted by replacement reconstruction", () => {
21
+ const ownerState = /** @type {Parameters<typeof assertLegacyGuardianInventoryMembership>[1]} */ (/** @type {import("../src/json.js").JsonValue} */ ({
22
+ snapshot: {
23
+ activeReleaseId: "active",
24
+ releases: [
25
+ {releaseId: "stopped", processes: [{id: "web"}], state: "stopped"},
26
+ {releaseId: "active", processes: [{id: "web"}], state: "active"}
27
+ ],
28
+ services: [],
29
+ singletons: []
30
+ }
31
+ }))
32
+ const inventory = /** @type {Parameters<typeof assertLegacyGuardianInventoryMembership>[0]} */ (/** @type {import("../src/json.js").JsonValue} */ ([
33
+ {key: "release:active:web", provenance: "active-provenance", status: {state: "running"}},
34
+ {key: "release:stopped:web", provenance: "stopped-provenance", status: {state: "stopped"}}
35
+ ]))
36
+ const unexpectedStopped = /** @type {Parameters<typeof assertLegacyGuardianInventoryMembership>[0]} */ (/** @type {import("../src/json.js").JsonValue} */ ([
37
+ {key: "release:unexpected:web", provenance: "unexpected-provenance", status: {state: "stopped"}},
38
+ inventory[0]
39
+ ]))
40
+ const unexpectedLive = /** @type {Parameters<typeof assertLegacyGuardianInventoryMembership>[0]} */ (/** @type {import("../src/json.js").JsonValue} */ ([
41
+ {key: "release:unexpected:web", provenance: "unexpected-provenance", status: {state: "running"}},
42
+ inventory[1]
43
+ ]))
44
+
45
+ expect(() => assertLegacyGuardianInventoryMembership(inventory, ownerState)).not.toThrow()
46
+ expect(() => assertLegacyGuardianInventoryMembership(unexpectedStopped, ownerState, {allowStopped: true})).toThrow(/inventory does not match/)
47
+ expect(() => assertLegacyGuardianInventoryMembership(inventory, {
48
+ snapshot: {...ownerState.snapshot, releases: [ownerState.snapshot.releases[1]]}
49
+ }, {allowStopped: true})).not.toThrow()
50
+ expect(() => assertLegacyGuardianInventoryMembership(unexpectedLive, {
51
+ snapshot: {...ownerState.snapshot, releases: [ownerState.snapshot.releases[1]]}
52
+ }, {allowStopped: true})).toThrow(/inventory does not match/)
53
+ })
54
+
20
55
  const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
21
56
  const binPath = path.join(repoRoot, "bin", "rollbridge")
22
57
  const dummyAppPath = path.join(repoRoot, "test", "fixtures", "dummy-app.js")
@@ -200,9 +200,10 @@ test("a wedged non-blocking process cannot block release retirement", async () =
200
200
  stop: async () => { handoffStopped = true }
201
201
  })))
202
202
 
203
- await release.drainAndStop(0, {...release.config, proxy: {...release.config.proxy, nonBlockingDrainTimeoutMs: 20}})
203
+ const drained = await release.drainAndStop(0, {...release.config, proxy: {...release.config.proxy, nonBlockingDrainTimeoutMs: 20}})
204
204
 
205
- expect(release.state).toBe("stopped")
205
+ expect(drained).toBe(false)
206
+ expect(release.state).toBe("draining")
206
207
  expect(handoffStopped).toBe(true)
207
208
  expect(logs).toMatchObject([{message: "release non-blocking process still draining", data: {pid: 4242, processId: "worker"}}])
208
209
  })
@@ -534,14 +535,16 @@ test("the retirement transition brackets its own wait and reports a residue it c
534
535
  stop: async () => {}
535
536
  })))
536
537
 
537
- await release.drainAndStop(0, {
538
+ const drained = await release.drainAndStop(0, {
538
539
  ...release.config,
539
540
  proxy: {...release.config.proxy, nonBlockingDrainTimeoutMs: 20},
540
541
  releaseRetention: {...release.config.releaseRetention, escalateWedgedGenerations: true}
541
542
  })
542
543
 
543
- // The transition still completes: the escalation is its last act, never a wait of its own.
544
- expect(release.state).toBe("stopped")
544
+ // The transition keeps the live process supervised: the escalation is its last act, never a
545
+ // wait of its own, and no false "release drained" claim can be emitted.
546
+ expect(drained).toBe(false)
547
+ expect(release.state).toBe("draining")
545
548
  expect(escalations).toEqual([])
546
549
  expect(release.drainPriorSample).toBeDefined()
547
550
  expect(release.drainNewestSample).toBeDefined()
@@ -2298,11 +2298,11 @@ test("rollback refuses to restore a drained generation that still holds live pro
2298
2298
  await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
2299
2299
  await daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"})
2300
2300
 
2301
- // The retirement budget expires, Rollbridge records the generation as drained, and the
2301
+ // The retirement budget expires, Rollbridge keeps the generation in the drain path, and the
2302
2302
  // worker stays alive with its in-flight work — the shape a restore must not re-deploy.
2303
2303
  // The tracked process (the shell wrapper) is already gone, so the only honest record of
2304
2304
  // the leak is the process group that outlived it.
2305
- await waitFor(() => statusRelease(daemon, "v1").state === "stopped")
2305
+ await waitFor(() => statusRelease(daemon, "v1").state === "draining")
2306
2306
  await retirementRecordSettled(daemon, "v1", "worker")
2307
2307
 
2308
2308
  const worker = statusRelease(daemon, "v1").processes.find((processStatus) => processStatus.id === "worker")
@@ -2314,7 +2314,7 @@ test("rollback refuses to restore a drained generation that still holds live pro
2314
2314
  expect(worker.pid).toBeUndefined()
2315
2315
  expect(worker.retirementTimedOut).toBe(true)
2316
2316
  expect(worker.state).toBe("stopped")
2317
- await expect(daemon.rollback({releaseId: "v1"})).rejects.toThrow(/recorded as drained while 1 process of that generation still hold live work \(worker: process group \d+ with \d+ live member\(s\) still alive after the tracked process exited\)\. Restoring it would re-register those processes under a new provenance and fail with a guardian provenance mismatch\. The guardian's active release is "v2"/)
2317
+ await expect(daemon.rollback({releaseId: "v1"})).rejects.toThrow(/Deploy refused before activation: release "v1" is retained in state stopped while 1 process of that generation still hold live work \(worker: process group \d+ with \d+ live member\(s\) still alive after the tracked process exited\)\. Activating that release id again would re-register those processes under a new provenance and abort with a guardian provenance mismatch\. The guardian's active release is "v2"/)
2318
2318
  expect(daemon.status().activeReleaseId).toBe("v2")
2319
2319
  expect(await fetchText(daemon, "/release")).toBe("v2")
2320
2320
  } finally {
@@ -2375,10 +2375,10 @@ test("a restore deploy naming a drained generation that outlived its tracked pro
2375
2375
  await daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})
2376
2376
  await daemon.deploy({releaseId: "v2", releasePath: fixture.root, revision: "v2"})
2377
2377
 
2378
- // v1 is recorded as drained while its worker keeps its in-flight work in the group its
2378
+ // v1 remains in the drain path while its worker keeps its in-flight work in the group its
2379
2379
  // shell wrapper led. The 2026-10-25 carve-out that lets a dead generation's process key be
2380
2380
  // re-registered does not apply here: the group is alive, so the key is still held.
2381
- await waitFor(() => statusRelease(daemon, "v1").state === "stopped")
2381
+ await waitFor(() => statusRelease(daemon, "v1").state === "draining")
2382
2382
  await retirementRecordSettled(daemon, "v1", "worker")
2383
2383
 
2384
2384
  const worker = statusRelease(daemon, "v1").processes.find((processStatus) => processStatus.id === "worker")
@@ -2387,7 +2387,7 @@ test("a restore deploy naming a drained generation that outlived its tracked pro
2387
2387
  throw new Error(`the drained generation should still hold the worker's process group, got ${JSON.stringify(worker && {pid: worker.pid, retirementTimedOut: worker.retirementTimedOut, state: worker.state})}`)
2388
2388
  }
2389
2389
 
2390
- await expect(daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})).rejects.toThrow(/Deploy refused before activation: release "v1" is retained in state stopped while 1 process of that generation still hold live work \(worker: process group \d+ with \d+ live member\(s\) still alive after the tracked process exited\)\. Activating that release id again would re-register those processes under a new provenance and abort with a guardian provenance mismatch\. The guardian's active release is "v2"/)
2390
+ await expect(daemon.deploy({releaseId: "v1", releasePath: fixture.root, revision: "v1"})).rejects.toThrow(/Deploy refused before activation: release "v1" is retained in state draining while 1 process of that generation still hold live work \(worker: process group \d+ with \d+ live member\(s\) still alive after the tracked process exited\)\. Activating that release id again would re-register those processes under a new provenance and abort with a guardian provenance mismatch\. The guardian's active release is "v2"/)
2391
2391
  expect(daemon.status().activeReleaseId).toBe("v2")
2392
2392
  expect(daemon.status().releases.filter((release) => release.releaseId === "v1").length).toBe(1)
2393
2393
  expect(await fetchText(daemon, "/release")).toBe("v2")