rollbridge 0.1.72 → 0.1.73

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.72",
3
+ "version": "0.1.73",
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
@@ -23,7 +23,7 @@ const STATE_PERSIST_INTERVAL_MS = 5000
23
23
  * @typedef {{releaseId?: string, releasePath: string, revision?: string}} DeployArgs
24
24
  * @typedef {{attestation?: string, releaseId: string, releasePath: string, revision: string}} BootstrapIdentity
25
25
  * @typedef {{id: string, process: import("./managed-process.js").ManagedProcessStatus}} ProcessStatus
26
- * @typedef {{disruptive: true, mode: "legacy-first-upgrade", reason: string}} OwnerTransition
26
+ * @typedef {{disruptive: boolean, mode: "guardian-version-handoff" | "legacy-first-upgrade", reason: string}} OwnerTransition
27
27
  * @typedef {"candidate_ready" | "retiring_previous" | "previous_retired" | "activating_candidate" | "restoring_previous" | "retiring_failed_candidate" | "degraded_active" | "committed_pending" | "committed" | "restoring_committed"} GenerationTransitionPhase
28
28
  * @typedef {{activationError?: string, activationLifecycle?: boolean, candidateReleaseId: string, candidateReleasePath: string, candidateRevision: string, compensationError?: string, configDigest: string, degradedIncumbent?: boolean, error?: string, journalRevision?: number, phase: GenerationTransitionPhase, previousReleaseId: string | null, startedAt: string, updatedAt: string}} GenerationTransition
29
29
  * @typedef {{activeReleaseId: string | null, application: string, bootstrap: BootstrapIdentity | undefined, control: import("./config.js").ControlConfig, daemonPid: number, daemonRuntime: import("./daemon-runtime.js").DaemonRuntimeIdentity | undefined, generationTransition?: GenerationTransition, ownerRecovery: {configDigest: string, ready: boolean} | undefined, ownerTransition?: OwnerTransition, orphans: {id: string, pid: number, releaseId: string | null}[], proxy: {host: string, port: number | undefined, upstreamHost: string}, releaseReferences: {releaseId: string, releasePath: string}[], releases: import("./release-group.js").ReleaseStatus[], services: ProcessStatus[], singletons: ProcessStatus[]}} DaemonStatus
@@ -406,7 +406,11 @@ export default class RollbridgeDaemon {
406
406
  shouldStart: () => !this.stopping
407
407
  })
408
408
 
409
- await release.restore(releaseStatus, {synchronizeLifecycleRole: synchronizeLifecycleRoles})
409
+ await release.restore(releaseStatus, {
410
+ adoptCommittedGeneration: releaseStatus.releaseId === snapshot.activeReleaseId && snapshot.generationTransition?.phase === "committed" && snapshot.ownerTransition?.mode === "guardian-version-handoff",
411
+ configDigest: ownerConfigDigest(config),
412
+ synchronizeLifecycleRole: synchronizeLifecycleRoles
413
+ })
410
414
  this.releases.set(release.releaseId, release)
411
415
  if (release.releaseId === snapshot.activeReleaseId) this.activeRelease = release
412
416
  }
@@ -462,13 +462,27 @@ class GuardianProcess extends ManagedProcess {
462
462
  }
463
463
 
464
464
  /** Reconnects to an already registered guardian process without changing its desired state. */
465
- async recover() {
465
+ /** @param {{adopt?: {configDigest: string, pid: number, processStartTime: string}}} [options] - Optional identity-fenced adoption. */
466
+ async recover({adopt} = {}) {
466
467
  if (this.client.reservedProcessKey === this.key) {
467
468
  if (this.client.reservedProcessProvenance !== this.provenance) throw new Error(`Guardian provenance mismatch for reserved process ${this.key}`)
468
469
  this.cachedStatus = asProcessStatus(await this.client.request({command: "status", key: this.key}))
470
+ if (adopt) await this.adopt(adopt, adopt.configDigest)
469
471
  return
470
472
  }
471
473
  await this.ensureRegistered()
474
+ if (adopt) await this.adopt(adopt, adopt.configDigest)
475
+ }
476
+
477
+ /** Re-adopts a live committed process after a guardian/version handoff. */
478
+ /**
479
+ * @param {{pid: number, processStartTime: string}} identity - Exact process identity.
480
+ * @param {string} [configDigest] - Committed owner config digest.
481
+ */
482
+ async adopt(identity, configDigest) {
483
+ if (!configDigest) throw new Error("Guardian process adoption requires the committed owner config digest")
484
+ await this.ensureRegistered()
485
+ this.cachedStatus = asProcessStatus(await this.client.request({command: "adopt", key: this.key, pid: identity.pid, processStartTime: identity.processStartTime, configDigest}))
472
486
  }
473
487
 
474
488
  /** Attaches a reconstructed process whose incumbent-owned registration was reserved through commit. */
@@ -2,7 +2,7 @@
2
2
 
3
3
  import {EventEmitter} from "node:events"
4
4
  import {spawn} from "node:child_process"
5
- import {processGroupHasLiveMembers, processGroupMembers} from "./process-memory.js"
5
+ import {processGroupHasLiveMembers, processGroupMembers, processStartTime} from "./process-memory.js"
6
6
 
7
7
  const DEFAULT_ACTIVATION_HOOK_TIMEOUT_MS = 30000
8
8
  const MAX_BUFFERED_OUTPUT_CHARACTERS = 64 * 1024
@@ -16,7 +16,7 @@ const MAX_BUFFERED_OUTPUT_CHARACTERS = 64 * 1024
16
16
  * @typedef {{at: string, line: string, stream: "stdout" | "stderr"}} ManagedProcessLog
17
17
  * @typedef {import("./config.js").StopTimeoutMs} StopTimeoutMs
18
18
  * @typedef {{command: string, cwd: string | undefined, env: Record<string, string | undefined>, lifecycle: import("./config.js").LifecycleConfig, logger: (message: string, data?: Record<string, import("./json.js").JsonValue>) => void, memory: import("./config.js").MemoryConfig | undefined, outputLines: number, restart: import("./config.js").RestartConfig, restartDelayMs: number, shouldRestart: () => boolean, stopSignal: string, stopTimeoutMs: StopTimeoutMs}} ManagedProcessDefinition
19
- * @typedef {{children: import("./process-memory.js").ProcessGroupMember[], command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, id: string, lastMemoryRestartAt: string | undefined, lastStartReason: ManagedProcessStartReason | undefined, lifecycleRole?: LifecycleRole, logs: ManagedProcessLog[], memoryRestarts: number, pid: number | undefined, restarts: number, rssBytes: number | undefined, startedAt: string | undefined, state: ManagedProcessState, uptimeMs: number | undefined}} ManagedProcessStatus
19
+ * @typedef {{children: import("./process-memory.js").ProcessGroupMember[], command: string, cwd: string | undefined, exitCode: number | null | undefined, exitSignal: ProcessExitSignal | undefined, id: string, lastMemoryRestartAt: string | undefined, lastStartReason: ManagedProcessStartReason | undefined, lifecycleRole?: LifecycleRole, logs: ManagedProcessLog[], memoryRestarts: number, pid: number | undefined, processStartTime?: string, restarts: number, rssBytes: number | undefined, startedAt: string | undefined, state: ManagedProcessState, uptimeMs: number | undefined}} ManagedProcessStatus
20
20
  */
21
21
 
22
22
  export default class ManagedProcess extends EventEmitter {
@@ -78,6 +78,7 @@ export default class ManagedProcess extends EventEmitter {
78
78
  this.child = undefined
79
79
  this.exitPromise = undefined
80
80
  this.pid = undefined
81
+ this.processStartTime = undefined
81
82
  this.exitCode = undefined
82
83
  this.exitSignal = undefined
83
84
  }
@@ -126,6 +127,7 @@ export default class ManagedProcess extends EventEmitter {
126
127
  child.once("spawn", () => {
127
128
  void (async () => {
128
129
  this.startedAtMs = Date.now()
130
+ this.processStartTime = child.pid ? processStartTime(child.pid) : undefined
129
131
  this.lastStartReason = reason
130
132
  const lifecycleRestore = this.restoreLifecycleRole()
131
133
  const lifecycleRestoreBarrier = lifecycleRestore.then(() => undefined, () => undefined)
@@ -161,6 +163,7 @@ export default class ManagedProcess extends EventEmitter {
161
163
  if (this.child === child) {
162
164
  this.child = undefined
163
165
  this.pid = undefined
166
+ this.processStartTime = undefined
164
167
  this.exitPromise = undefined
165
168
  }
166
169
  reject(error)
@@ -174,6 +177,29 @@ export default class ManagedProcess extends EventEmitter {
174
177
  })
175
178
  }
176
179
 
180
+ /**
181
+ * Re-adopts an already-live process after a guardian/version handoff.
182
+ * @param {{pid: number, processStartTime: string}} identity - Exact process identity.
183
+ * @param {string} [_configDigest] - Owner digest accepted by guardian-backed implementations.
184
+ * @returns {Promise<void>}
185
+ */
186
+ async adopt({pid, processStartTime: expectedStartTime}, _configDigest) {
187
+ if (!Number.isInteger(pid) || pid <= 0 || !/^\d+$/.test(expectedStartTime)) throw new Error(`Process ${this.id} adoption identity is invalid`)
188
+ const actualStartTime = processStartTime(pid)
189
+
190
+ if (actualStartTime !== expectedStartTime) throw new Error(`Process ${this.id} adoption rejected: PID ${pid} start time does not match the committed identity`)
191
+ if (this.child) throw new Error(`Process ${this.id} adoption rejected while the process is already supervised`)
192
+
193
+ this.pid = pid
194
+ this.processStartTime = actualStartTime
195
+ this.state = "running"
196
+ this.intentionalStop = false
197
+ this.intentionalStopSignal = undefined
198
+ this.exitCode = undefined
199
+ this.exitSignal = undefined
200
+ this.lastStartReason = "deploy"
201
+ }
202
+
177
203
  /**
178
204
  * Updates the command template used for future restarts without touching the currently running child.
179
205
  * @param {ManagedProcessDefinition} definition - Replacement process definition.
@@ -245,6 +271,7 @@ export default class ManagedProcess extends EventEmitter {
245
271
  this.exitSignal = signal ?? this.intentionalStopSignal
246
272
  this.child = undefined
247
273
  this.pid = undefined
274
+ this.processStartTime = undefined
248
275
  this.exitPromise = undefined
249
276
  this.rssBytes = undefined
250
277
  this.children = []
@@ -484,7 +511,7 @@ export default class ManagedProcess extends EventEmitter {
484
511
  this.restartTimer = undefined
485
512
  }
486
513
  if (this.lifecycleRestoreBarrier) await this.lifecycleRestoreBarrier
487
- if (!this.child?.pid) {
514
+ if (!this.child?.pid && !this.pid) {
488
515
  this.state = "stopped"
489
516
  if (this.hasRestorableLifecycle()) this.lifecycleRole = "retired"
490
517
  return
@@ -824,6 +851,7 @@ export default class ManagedProcess extends EventEmitter {
824
851
  logs: this.logs.slice(-this.outputLines),
825
852
  memoryRestarts: this.memoryRestarts,
826
853
  pid: this.pid,
854
+ processStartTime: this.processStartTime,
827
855
  restarts: this.restarts,
828
856
  rssBytes: this.rssBytes,
829
857
  startedAt: this.startedAtMs === undefined ? undefined : new Date(this.startedAtMs).toISOString(),
@@ -34,6 +34,9 @@ const OWNER_RESTART_RETRY_MS = 1000
34
34
  * @property {string} [mutationId] - Owner mutation lease id.
35
35
  * @property {string} [operation] - Owner mutation diagnostic name.
36
36
  * @property {number} [ownerPid] - Exact claimant process PID.
37
+ * @property {string} [configDigest] - Exact committed owner configuration digest.
38
+ * @property {number} [pid] - Exact live process PID to re-adopt.
39
+ * @property {string} [processStartTime] - Exact `/proc` process start-time counter.
37
40
  * @property {import("./json.js").JsonValue} [recoverySnapshot] - Public bridge recovery snapshot.
38
41
  * @property {string} [statePath] - Exact public recovery state path.
39
42
  * @property {import("./json.js").JsonValue} [authority] - Expected current authority.
@@ -657,6 +660,18 @@ async function execute(request, socket) {
657
660
  if (request.command === "start") {
658
661
  record.desired = true
659
662
  await record.process.start(request.reason, request.lifecycleRole)
663
+ } else if (request.command === "adopt") {
664
+ requireOwner(socket, request.command)
665
+ const requestedPid = request.pid
666
+ const requestedStartTime = request.processStartTime
667
+ const committedConfigDigest = ownerState && typeof ownerState === "object" && !Array.isArray(ownerState)
668
+ ? /** @type {{authority?: {configDigest?: string}}} */ (ownerState).authority?.configDigest
669
+ : undefined
670
+ if (!request.configDigest || !committedConfigDigest || !isDeepStrictEqual(request.configDigest, committedConfigDigest)) throw new Error("Guardian process adoption authority does not match the committed owner")
671
+ if (!Number.isInteger(requestedPid) || !requestedStartTime) throw new Error("Guardian process adoption requires an exact PID and process start time")
672
+ if (typeof record.process.adopt !== "function") throw new Error("Guardian process adoption is not supported by this process implementation")
673
+ record.desired = true
674
+ await record.process.adopt({pid: /** @type {number} */ (requestedPid), processStartTime: requestedStartTime}, request.configDigest)
660
675
  } else if (request.command === "activate") {
661
676
  await record.process.activateStrict()
662
677
  } else if (request.command === "reactivate" || request.command === "reactivate-with-command") {
@@ -70,6 +70,31 @@ export function processGroupHasLiveMembers(pgid, procPath = "/proc") {
70
70
  return false
71
71
  }
72
72
 
73
+ /**
74
+ * Returns Linux's monotonic process start-time counter for a PID.
75
+ * @param {number} pid - Process id.
76
+ * @param {string} [procPath] - Procfs root (overridable for deterministic tests).
77
+ * @returns {string | undefined} Kernel start-time ticks, or undefined when unavailable.
78
+ */
79
+ export function processStartTime(pid, procPath = "/proc") {
80
+ let stat
81
+
82
+ try {
83
+ stat = fs.readFileSync(`${procPath}/${pid}/stat`, "utf8")
84
+ } catch {
85
+ return undefined
86
+ }
87
+
88
+ const commEnd = stat.lastIndexOf(")")
89
+
90
+ if (commEnd < 0) return undefined
91
+
92
+ const fields = stat.slice(commEnd + 2).split(" ")
93
+ const startTime = fields[19]
94
+
95
+ return /^\d+$/.test(startTime || "") ? startTime : undefined
96
+ }
97
+
73
98
  /**
74
99
  * Measures the total resident memory (RSS) of a managed process group.
75
100
  * @param {number} pgid - Process-group id (the detached spawn's pid).
@@ -151,9 +151,9 @@ export default class ReleaseGroup extends EventEmitter {
151
151
  /**
152
152
  * Reconstructs this release around processes still owned by the durable guardian.
153
153
  * @param {ReleaseStatus} snapshot - Persisted release snapshot.
154
- * @param {{synchronizeLifecycleRole?: boolean}} [options] - Guardian role synchronization options.
154
+ * @param {{adoptCommittedGeneration?: boolean, configDigest?: string, synchronizeLifecycleRole?: boolean}} [options] - Guardian role synchronization options.
155
155
  */
156
- async restore(snapshot, {synchronizeLifecycleRole = true} = {}) {
156
+ async restore(snapshot, {adoptCommittedGeneration = false, configDigest, synchronizeLifecycleRole = true} = {}) {
157
157
  if (!snapshot || snapshot.releaseId !== this.releaseId || snapshot.releasePath !== this.releasePath || snapshot.revision !== this.revision) {
158
158
  throw new Error(`Persisted release identity mismatch for ${this.releaseId}`)
159
159
  }
@@ -214,7 +214,12 @@ export default class ReleaseGroup extends EventEmitter {
214
214
  this.processes.set(processStatus.id, processInstance)
215
215
  if (processConfig.policy === "service" && processConfig.deployStrategy === "handoff") this.handoffServiceIds.add(processStatus.id)
216
216
  if (processConfig.nonBlockingDrain) this.nonBlockingDrainIds.add(processStatus.id)
217
- if ("recover" in processInstance && typeof processInstance.recover === "function") await processInstance.recover()
217
+ if ("recover" in processInstance && typeof processInstance.recover === "function") {
218
+ const adopt = adoptCommittedGeneration && processStatus.state === "stopped" && processStatus.pid && processStatus.processStartTime && configDigest
219
+ ? {pid: processStatus.pid, processStartTime: processStatus.processStartTime, configDigest}
220
+ : undefined
221
+ await processInstance.recover(adopt ? {adopt} : undefined)
222
+ }
218
223
  }
219
224
  if (synchronizeLifecycleRole) await this.synchronizeLifecycleRoles()
220
225
  }
@@ -1,11 +1,13 @@
1
1
  // @ts-check
2
2
 
3
3
  import fs from "node:fs"
4
+ import {spawn} from "node:child_process"
4
5
  import os from "node:os"
5
6
  import path from "node:path"
6
7
  import {describe, expect, test} from "@velocious/testing"
7
8
  import {fileURLToPath} from "node:url"
8
9
  import ManagedProcess from "../src/managed-process.js"
10
+ import {processStartTime} from "../src/process-memory.js"
9
11
 
10
12
  describe("managed-process", () => {
11
13
 
@@ -111,6 +113,27 @@ test("reports zeroed restart and uptime fields before the process starts", () =>
111
113
  expect(status.state).toBe("stopped")
112
114
  })
113
115
 
116
+ test("re-adopts a live process whose supervisor status was stopped without spawning a duplicate", async () => {
117
+ const live = spawn(process.execPath, ["-e", "setTimeout(() => {}, 30000)"], {detached: true, stdio: "ignore"})
118
+ await new Promise((resolve, reject) => {
119
+ live.once("error", reject)
120
+ live.once("spawn", resolve)
121
+ })
122
+ if (!live.pid) throw new Error("Missing live process PID")
123
+ const startTime = processStartTime(live.pid)
124
+ if (!startTime) throw new Error("Missing live process start time")
125
+ const managed = buildProcess(10)
126
+
127
+ try {
128
+ expect(managed.status().state).toBe("stopped")
129
+ await managed.adopt({pid: live.pid, processStartTime: startTime}, "committed-config-digest")
130
+
131
+ expect(managed.status()).toMatchObject({pid: live.pid, processStartTime: startTime, state: "running"})
132
+ } finally {
133
+ await managed.stop()
134
+ }
135
+ })
136
+
114
137
  test("counts automatic restarts and reports startedAt and uptime while running", async () => {
115
138
  const managed = new ManagedProcess({
116
139
  command: `${JSON.stringify(process.execPath)} ${JSON.stringify(crasherPath)}`,