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 +1 -1
- package/src/daemon.js +6 -2
- package/src/guardian-client.js +15 -1
- package/src/managed-process.js +31 -3
- package/src/process-guardian.js +15 -0
- package/src/process-memory.js +25 -0
- package/src/release-group.js +8 -3
- package/test/managed-process.test.js +23 -0
package/package.json
CHANGED
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:
|
|
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, {
|
|
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
|
}
|
package/src/guardian-client.js
CHANGED
|
@@ -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
|
-
|
|
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. */
|
package/src/managed-process.js
CHANGED
|
@@ -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(),
|
package/src/process-guardian.js
CHANGED
|
@@ -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") {
|
package/src/process-memory.js
CHANGED
|
@@ -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).
|
package/src/release-group.js
CHANGED
|
@@ -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")
|
|
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)}`,
|