rollbridge 0.1.70 → 0.1.71

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.
Files changed (63) hide show
  1. package/README.md +10 -63
  2. package/TODO.md +0 -13
  3. package/docs/cli.md +3 -128
  4. package/docs/config.md +6 -177
  5. package/docs/troubleshooting.md +6 -97
  6. package/docs/velocious.md +1 -1
  7. package/docs/workers.md +0 -11
  8. package/examples/tensorbuzz.com.js +2 -3
  9. package/package.json +1 -1
  10. package/src/cli.js +2 -68
  11. package/src/config.js +8 -347
  12. package/src/daemon.js +65 -387
  13. package/src/doctor.js +0 -74
  14. package/src/guardian-client.js +8 -67
  15. package/src/health.js +8 -99
  16. package/src/managed-process.js +16 -197
  17. package/src/process-guardian.js +22 -212
  18. package/src/process-memory.js +2 -62
  19. package/src/release-group.js +37 -435
  20. package/tensorbuzz.yml +1 -20
  21. package/test/completion.test.js +2 -5
  22. package/test/config-validation.test.js +5 -135
  23. package/test/guardian-client.test.js +5 -119
  24. package/test/health.test.js +1 -74
  25. package/test/managed-process.test.js +1 -260
  26. package/test/owner-recovery.test.js +21 -125
  27. package/test/owner-replacement.test.js +14 -175
  28. package/test/process-memory.test.js +1 -47
  29. package/test/release-group.test.js +2 -408
  30. package/test/rollbridge.test.js +72 -737
  31. package/test/shutdown-completion.test.js +0 -52
  32. package/test/support/process.js +1 -3
  33. package/changelog.d/20261025-guardian-re-register-dead-generation.md +0 -13
  34. package/changelog.d/20261026-stale-committed-generation-transition-recovery.md +0 -1
  35. package/changelog.d/20261104-compose-service-units.md +0 -21
  36. package/changelog.d/20261105-owner-mutation-lease-diagnostics.md +0 -20
  37. package/changelog.d/20261106-release-dependency-boot-budgets.md +0 -32
  38. package/changelog.d/20261109-path-filtered-builds.md +0 -11
  39. package/changelog.d/20261110-default-boot-budget-above-measured-startup.md +0 -26
  40. package/changelog.d/20261111-contention-sensitive-daemon-specs.md +0 -27
  41. package/changelog.d/20261113-bounded-nonblocking-retirement.md +0 -5
  42. package/changelog.d/20261115-bound-draining-release-groups.md +0 -62
  43. package/changelog.d/20261115-restore-deploy-refuses-held-generation.md +0 -27
  44. package/changelog.d/20261115-wedged-generation-escalation.md +0 -44
  45. package/changelog.d/20261116-bounded-explicit-stop-retirement.md +0 -30
  46. package/changelog.d/20261116-config-json-canonical-shape.md +0 -11
  47. package/changelog.d/20261116-drain-specs-gate-the-retirement-record.md +0 -29
  48. package/changelog.d/20261116-guardian-version-handoff.md +0 -37
  49. package/changelog.d/20261116-reclaim-dead-owner-mutation.md +0 -7
  50. package/changelog.d/20261117-activate-before-incumbent-retirement.md +0 -1
  51. package/changelog.d/20261117-activation-path-drain-deadline.md +0 -35
  52. package/changelog.d/20261117-stop-companion-after-retired-dependency.md +0 -7
  53. package/docs/compose-services.md +0 -222
  54. package/src/compose-unit.js +0 -725
  55. package/src/drain-policy.js +0 -252
  56. package/src/process-order.js +0 -26
  57. package/test/compose-config.test.js +0 -160
  58. package/test/compose-docker.test.js +0 -297
  59. package/test/compose-unit.test.js +0 -415
  60. package/test/drain-policy.test.js +0 -328
  61. package/test/fixtures/deferred-boot-app.js +0 -106
  62. package/test/fixtures/gated-app.js +0 -50
  63. package/test/tensorbuzz-config.test.js +0 -228
package/src/doctor.js CHANGED
@@ -5,7 +5,6 @@ import fs from "node:fs/promises"
5
5
  import net from "node:net"
6
6
  import path from "node:path"
7
7
  import {inspectControlSocket} from "./daemon.js"
8
- import {composeGlobalArgs, runComposeCommand} from "./compose-unit.js"
9
8
  import {liveProcesses, readState} from "./state-store.js"
10
9
  import {processTemplateContext, renderObject, renderTemplate} from "./template.js"
11
10
 
@@ -26,13 +25,6 @@ export async function runEnvironmentChecks(config) {
26
25
  const socketInspection = await inspectControlSocketSafely(config.control.path)
27
26
 
28
27
  checks.push(controlSocketCheck(config, socketInspection))
29
- if (!("error" in socketInspection) && socketInspection.guardian) {
30
- const {guardian} = socketInspection
31
- const lease = guardian.ownerMutation
32
- const leaseDetail = lease ? `, owner mutation ${String(lease.operation || "unnamed operation")} held by pid ${String(lease.pid || "unknown")}` : ", no active owner-mutation lease"
33
-
34
- checks.push({detail: `guardian Rollbridge ${guardian.version || "unknown"}${leaseDetail}`, name: "guardian diagnostics", ok: guardian.version !== null})
35
- }
36
28
  checks.push(await controlSocketDirectoryCheck(config))
37
29
  checks.push(await proxyPortCheck(config, socketInspection))
38
30
 
@@ -44,75 +36,9 @@ export async function runEnvironmentChecks(config) {
44
36
  checks.push(await orphanCheck(config.statePath, daemonRunning))
45
37
  }
46
38
 
47
- if (config.compose !== undefined) checks.push(...await runComposeChecks(config))
48
-
49
- return checks
50
- }
51
-
52
- /**
53
- * Pre-flights every declared Compose unit: the Docker Compose CLI, the unit's Compose file, and
54
- * the service it names inside that file.
55
- * @param {import("./config.js").RollbridgeConfig} config - Normalized config.
56
- * @returns {Promise<DoctorCheck[]>} One check per probed aspect.
57
- */
58
- async function runComposeChecks(config) {
59
- /** @type {DoctorCheck[]} */
60
- const checks = []
61
- const version = await runComposeCommand({args: ["docker", "compose", "version"], timeoutMs: 15000})
62
-
63
- if (version.code !== 0) {
64
- return [{detail: `docker compose is not usable: ${version.stderr.trim() || `exit ${version.code}`}`, name: "docker compose", ok: false}]
65
- }
66
-
67
- checks.push({detail: version.stdout.trim() || "available", name: "docker compose", ok: true})
68
-
69
- for (const unit of config.compose ?? []) {
70
- const composeFile = path.resolve(unit.projectDirectory, unit.composeFile)
71
-
72
- if (!await fileExists(composeFile)) {
73
- checks.push({detail: `${composeFile} is missing; unit "${unit.id}" cannot be rolled`, name: `compose unit ${unit.id}`, ok: false})
74
- continue
75
- }
76
-
77
- if (unit.envFile !== undefined && !await fileExists(path.resolve(unit.projectDirectory, unit.envFile))) {
78
- checks.push({detail: `${path.resolve(unit.projectDirectory, unit.envFile)} is missing; unit "${unit.id}" cannot be rolled`, name: `compose unit ${unit.id}`, ok: false})
79
- continue
80
- }
81
-
82
- const services = await runComposeCommand({args: [...composeGlobalArgs(unit), "config", "--services"], cwd: unit.projectDirectory, timeoutMs: 30000})
83
-
84
- if (services.code !== 0) {
85
- checks.push({detail: `could not read ${composeFile}: ${services.stderr.trim() || `exit ${services.code}`}`, name: `compose unit ${unit.id}`, ok: false})
86
- continue
87
- }
88
-
89
- const listed = services.stdout.split("\n").map((line) => line.trim()).filter(Boolean)
90
-
91
- if (!listed.includes(unit.service)) {
92
- checks.push({detail: `service "${unit.service}" is not declared in ${composeFile}; found ${listed.join(", ") || "no services"}`, name: `compose unit ${unit.id}`, ok: false})
93
- continue
94
- }
95
-
96
- checks.push({detail: `${unit.service} in ${composeFile}, target image ${unit.image}`, name: `compose unit ${unit.id}`, ok: true})
97
- }
98
-
99
39
  return checks
100
40
  }
101
41
 
102
- /**
103
- * @param {string} filePath - Path to probe.
104
- * @returns {Promise<boolean>} True when the path exists.
105
- */
106
- async function fileExists(filePath) {
107
- try {
108
- await fs.access(filePath)
109
-
110
- return true
111
- } catch {
112
- return false
113
- }
114
- }
115
-
116
42
  /**
117
43
  * @param {string} statePath - Configured state file path.
118
44
  * @returns {Promise<DoctorCheck>} Whether the state file's directory is writable.
@@ -2,34 +2,17 @@
2
2
 
3
3
  import crypto from "node:crypto"
4
4
  import {spawn} from "node:child_process"
5
- import fs from "node:fs/promises"
6
5
  import net from "node:net"
7
- import path from "node:path"
8
6
  import {fileURLToPath} from "node:url"
9
7
  import ManagedProcess from "./managed-process.js"
10
8
 
11
9
  const guardianPath = fileURLToPath(new URL("./process-guardian.js", import.meta.url))
12
- const MAX_UNIX_SOCKET_PATH_BYTES = 107
13
-
14
- /**
15
- * Linux reserves one byte of sockaddr_un.sun_path for its terminator. Keep
16
- * long task/workspace prefixes out of the pathname while retaining a stable,
17
- * collision-resistant name for the configured path.
18
- * @param {string} socketPath - Configured Unix socket pathname.
19
- * @returns {string} Path that can be passed to net.createConnection/listen.
20
- */
21
- export function usableSocketPath(socketPath) {
22
- if (Buffer.byteLength(socketPath) <= MAX_UNIX_SOCKET_PATH_BYTES) return socketPath
23
-
24
- const digest = crypto.createHash("sha256").update(socketPath).digest("hex").slice(0, 32)
25
- return path.join("/tmp", `rollbridge-${digest}.sock`)
26
- }
27
10
 
28
11
  export default class GuardianClient {
29
12
  /** @param {{pid?: number, socketPath: string, token: string}} identity - Durable guardian identity. */
30
13
  constructor({pid, socketPath, token}) {
31
14
  this.pid = pid
32
- this.socketPath = usableSocketPath(socketPath)
15
+ this.socketPath = socketPath
33
16
  this.token = token
34
17
  this.socket = /** @type {net.Socket | undefined} */ (undefined)
35
18
  this.buffer = ""
@@ -167,17 +150,14 @@ export default class GuardianClient {
167
150
  return await response
168
151
  }
169
152
 
170
- /**
171
- * Stops the guardian after every owned process has stopped or reached its retirement budget.
172
- * @param {{retirementTimeoutMs?: number}} [options] - Optional non-blocking retirement budget.
173
- */
174
- async shutdown(options = {}) {
153
+ /** Stops the guardian after every owned process has stopped. */
154
+ async shutdown() {
175
155
  if (this.pending.size > 0) {
176
156
  await new Promise((resolve) => {
177
157
  this.idleWaiters.push(() => { resolve(undefined) })
178
158
  })
179
159
  }
180
- await this.request({command: "shutdown", options})
160
+ await this.request({command: "shutdown"})
181
161
  const socket = this.socket
182
162
 
183
163
  if (!socket || socket.destroyed) throw new Error("Process guardian disconnected before shutdown acknowledgement")
@@ -206,11 +186,9 @@ export default class GuardianClient {
206
186
  await this.request({command: "owner-ready", ownerPid: process.pid})
207
187
  }
208
188
 
209
- /** @returns {Promise<{daemonRecovery: number, generationReactivation?: number, guardianVersion?: string}>} Guardian protocol capabilities. */
189
+ /** @returns {Promise<{daemonRecovery: number, generationReactivation?: number}>} Guardian protocol capabilities. */
210
190
  async capabilities() {
211
- const capabilities = /** @type {{daemonRecovery: number, generationReactivation?: number, guardianVersion?: string}} */ (await this.request({command: "capabilities"}))
212
-
213
- if (!capabilities.guardianVersion) capabilities.guardianVersion = await guardianVersionFromProcess(this.pid)
191
+ const capabilities = /** @type {{daemonRecovery: number, generationReactivation?: number}} */ (await this.request({command: "capabilities"}))
214
192
 
215
193
  this.generationReactivation = capabilities.generationReactivation === 1
216
194
  return capabilities
@@ -345,11 +323,10 @@ export default class GuardianClient {
345
323
  /**
346
324
  * Acquires the committed owner's mutation fence.
347
325
  * @param {string} operation - Control mutation name.
348
- * @param {{mutationTimeoutMs?: number, ownerPid?: number, waitingFor?: string}} [details] - Lease bound, holding PID and what the mutation blocks on.
349
326
  * @returns {Promise<string>} Mutation lease id.
350
327
  */
351
- async beginOwnerMutation(operation, {mutationTimeoutMs, ownerPid, waitingFor} = {}) {
352
- const result = /** @type {{mutationId: string}} */ (await this.request({command: "begin-owner-mutation", mutationTimeoutMs, operation, ownerPid, waitingFor}))
328
+ async beginOwnerMutation(operation) {
329
+ const result = /** @type {{mutationId: string}} */ (await this.request({command: "begin-owner-mutation", operation}))
353
330
 
354
331
  return result.mutationId
355
332
  }
@@ -359,21 +336,6 @@ export default class GuardianClient {
359
336
  await this.request({command: "end-owner-mutation", mutationId})
360
337
  }
361
338
 
362
- /**
363
- * Refines what a held mutation is waiting for, so a later refusal names the real blocker.
364
- * @param {string} mutationId - Mutation lease id.
365
- * @param {string} waitingFor - Current blocker.
366
- * @returns {Promise<void>} Report acknowledged.
367
- */
368
- async reportOwnerMutationWait(mutationId, waitingFor) {
369
- await this.request({command: "report-owner-mutation-wait", mutationId, waitingFor})
370
- }
371
-
372
- /** @returns {Promise<{guardianPid: number, ownerMutation: {elapsedMs: number, leaseMs: number, mutationId: string, operation: string, pid: number | null, startedAt: string, waitingFor: string} | null, version: string}>} Guardian diagnostics. */
373
- async guardianStatus() {
374
- return /** @type {{guardianPid: number, ownerMutation: {elapsedMs: number, leaseMs: number, mutationId: string, operation: string, pid: number | null, startedAt: string, waitingFor: string} | null, version: string}} */ (await this.request({command: "guardian-status"}))
375
- }
376
-
377
339
  /** @returns {Promise<{committedReplacementId: string | null, ownerClaimed: boolean, retirementFailed?: boolean, retirementPending?: boolean, retirementReady?: boolean}>} Transaction status. */
378
340
  async replacementStatus() {
379
341
  return /** @type {{committedReplacementId: string | null, ownerClaimed: boolean, retirementFailed?: boolean, retirementPending?: boolean, retirementReady?: boolean}} */ (await this.request({command: "replacement-status"}))
@@ -477,27 +439,6 @@ export default class GuardianClient {
477
439
  }
478
440
  }
479
441
 
480
- /**
481
- * Reads the package version from a guardian's own executable path. Used when its
482
- * capabilities response predates guardian version reporting, and by owner
483
- * replacement, which must not send a capabilities command before a replacement
484
- * transaction is prepared. An unreadable or non-Rollbridge process remains unknown.
485
- * @param {number | undefined} pid - Existing guardian PID.
486
- * @returns {Promise<string | undefined>} Guardian package version.
487
- */
488
- export async function guardianVersionFromProcess(pid) {
489
- if (!pid) return undefined
490
-
491
- try {
492
- const commandLine = (await fs.readFile(`/proc/${pid}/cmdline`, "utf8")).split("\0").find((argument) => argument.endsWith("/src/process-guardian.js"))
493
- if (!commandLine) return undefined
494
- const metadata = JSON.parse(await fs.readFile(path.resolve(path.dirname(commandLine), "..", "package.json"), "utf8"))
495
- return metadata && typeof metadata.version === "string" ? metadata.version : undefined
496
- } catch {
497
- return undefined
498
- }
499
- }
500
-
501
442
  class GuardianProcess extends ManagedProcess {
502
443
  /** @param {{client: GuardianClient, definition: ConstructorParameters<typeof ManagedProcess>[0], key: string}} args - Remote process args. */
503
444
  constructor({client, definition, key}) {
package/src/health.js CHANGED
@@ -1,126 +1,35 @@
1
1
  // @ts-check
2
2
 
3
- import net from "node:net"
4
-
5
- /**
6
- * @typedef {import("./config.js").HealthConfig} HealthConfig
7
- * @typedef {{attempts: number, deadlineMs: number, elapsedMs: number, processId: string, url: string}} HealthCheckDiagnostics
8
- * @typedef {Error & {healthCheck?: HealthCheckDiagnostics}} HealthCheckError
9
- */
10
-
11
- /**
12
- * @param {number} ms - Milliseconds.
13
- * @returns {Promise<void>} Resolves after the delay.
14
- */
15
- function sleep(ms) {
16
- return new Promise((resolve) => setTimeout(resolve, ms))
17
- }
18
-
19
3
  /**
20
4
  * Waits for a process HTTP health endpoint.
21
- *
22
- * The failure names its own budget: `Health check failed ...: fetch failed` cannot tell a
23
- * slow boot apart from a health deadline that was simply too short.
24
5
  * @param {object} args - Options.
25
6
  * @param {string} args.host - Host.
26
7
  * @param {number} args.port - Port.
27
- * @param {HealthConfig} args.health - Health config.
28
- * @param {string} [args.processId] - Process the probe belongs to, named in the failure.
29
- * @returns {Promise<{elapsedMs: number}>} Time spent reaching the first healthy response.
8
+ * @param {import("./config.js").HealthConfig} args.health - Health config.
9
+ * @returns {Promise<void>} Resolves when healthy.
30
10
  */
31
- export async function waitForHealth({health, host, port, processId = "proxied"}) {
32
- const startedAtMs = Date.now()
33
-
11
+ export async function waitForHealth({health, host, port}) {
34
12
  if (health.startDelayMs > 0) {
35
- await sleep(health.startDelayMs)
13
+ await new Promise((resolve) => setTimeout(resolve, health.startDelayMs))
36
14
  }
37
15
 
38
- const deadlineMs = health.timeoutMs
39
- const deadline = Date.now() + deadlineMs
16
+ const deadline = Date.now() + health.timeoutMs
40
17
  const url = `http://${host}:${port}${health.path}`
41
- let attempts = 0
42
18
  let lastError = "no attempts"
43
19
 
44
20
  while (Date.now() <= deadline) {
45
- attempts += 1
46
-
47
21
  try {
48
22
  const response = await fetch(url)
49
23
 
50
- if (response.ok) return {elapsedMs: Date.now() - startedAtMs}
24
+ if (response.ok) return
51
25
 
52
26
  lastError = `HTTP ${response.status}`
53
27
  } catch (error) {
54
28
  lastError = error instanceof Error ? error.message : String(error)
55
29
  }
56
30
 
57
- await sleep(health.intervalMs)
31
+ await new Promise((resolve) => setTimeout(resolve, health.intervalMs))
58
32
  }
59
33
 
60
- const elapsedMs = Date.now() - startedAtMs
61
- /** @type {HealthCheckError} */
62
- const failure = new Error(`Health check failed for ${url}: ${lastError} (process ${processId}: ${attempts} probes, ${elapsedMs}ms elapsed of the ${deadlineMs}ms health deadline)`)
63
-
64
- failure.healthCheck = {attempts, deadlineMs, elapsedMs, processId, url}
65
-
66
- throw failure
67
- }
68
-
69
- /**
70
- * Waits until a TCP endpoint accepts a connection, on a budget of its own.
71
- *
72
- * This is the dependency leg of a release start: waiting for a process that must bind a
73
- * port before another one can boot. Charged to the health deadline it measures the
74
- * dependency instead of the app, so it is timed here on a separate budget.
75
- * @param {object} args - Options.
76
- * @param {string} args.host - Host to connect to.
77
- * @param {number} args.intervalMs - Delay between connection attempts.
78
- * @param {number} args.port - Port that must accept a connection.
79
- * @param {number} args.timeoutMs - Budget for the wait.
80
- * @returns {Promise<{attempts: number, elapsedMs: number}>} Time and attempts spent waiting.
81
- */
82
- export async function waitForListeningPort({host, intervalMs, port, timeoutMs}) {
83
- const startedAtMs = Date.now()
84
- const deadline = startedAtMs + timeoutMs
85
- let attempts = 0
86
-
87
- while (Date.now() <= deadline) {
88
- attempts += 1
89
-
90
- if (await tryConnect({deadline, host, intervalMs, port})) {
91
- return {attempts, elapsedMs: Date.now() - startedAtMs}
92
- }
93
-
94
- await sleep(Math.max(1, Math.min(intervalMs, deadline - Date.now())))
95
- }
96
-
97
- throw new Error(`Dependency endpoint ${host}:${port} did not accept a connection within ${timeoutMs}ms (${attempts} attempts, ${Date.now() - startedAtMs}ms waited)`)
98
- }
99
-
100
- /**
101
- * @param {object} args - Attempt options.
102
- * @param {number} args.deadline - Absolute deadline that bounds this attempt.
103
- * @param {string} args.host - Host to connect to.
104
- * @param {number} args.intervalMs - Delay between connection attempts.
105
- * @param {number} args.port - Port to connect to.
106
- * @returns {Promise<boolean>} True when the endpoint accepted the connection.
107
- */
108
- function tryConnect({deadline, host, intervalMs, port}) {
109
- return new Promise((resolve) => {
110
- const socket = net.createConnection({host, port})
111
- let settled = false
112
-
113
- /** @param {boolean} connected - Whether the endpoint accepted the connection. */
114
- const finish = (connected) => {
115
- if (settled) return
116
- settled = true
117
- socket.destroy()
118
- resolve(connected)
119
- }
120
-
121
- socket.setTimeout(Math.max(1, Math.min(intervalMs, deadline - Date.now())))
122
- socket.once("connect", () => finish(true))
123
- socket.once("error", () => finish(false))
124
- socket.once("timeout", () => finish(false))
125
- })
34
+ throw new Error(`Health check failed for ${url}: ${lastError}`)
126
35
  }