rollbridge 0.1.69 → 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 (62) hide show
  1. package/README.md +1 -53
  2. package/TODO.md +0 -12
  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 +69 -370
  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 +21 -211
  18. package/src/process-memory.js +2 -62
  19. package/src/release-group.js +37 -427
  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 +4 -118
  24. package/test/health.test.js +1 -74
  25. package/test/managed-process.test.js +1 -260
  26. package/test/owner-recovery.test.js +28 -132
  27. package/test/owner-replacement.test.js +11 -172
  28. package/test/process-memory.test.js +1 -47
  29. package/test/release-group.test.js +2 -408
  30. package/test/rollbridge.test.js +82 -766
  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-activation-path-drain-deadline.md +0 -35
  51. package/changelog.d/20261117-stop-companion-after-retired-dependency.md +0 -7
  52. package/docs/compose-services.md +0 -222
  53. package/src/compose-unit.js +0 -725
  54. package/src/drain-policy.js +0 -252
  55. package/src/process-order.js +0 -26
  56. package/test/compose-config.test.js +0 -160
  57. package/test/compose-docker.test.js +0 -297
  58. package/test/compose-unit.test.js +0 -415
  59. package/test/drain-policy.test.js +0 -328
  60. package/test/fixtures/deferred-boot-app.js +0 -106
  61. package/test/fixtures/gated-app.js +0 -50
  62. package/test/tensorbuzz-config.test.js +0 -228
package/docs/velocious.md CHANGED
@@ -32,7 +32,7 @@ export default {
32
32
  host: "127.0.0.1",
33
33
  port: 4500,
34
34
  healthPath: "/ping",
35
- healthTimeoutMs: 120000,
35
+ healthTimeoutMs: 30000,
36
36
  drainTimeoutMs: 60000,
37
37
  forceStopTimeoutMs: 10000
38
38
  },
package/docs/workers.md CHANGED
@@ -26,7 +26,6 @@ fixed port such as `7330`.
26
26
  {
27
27
  id: "background-jobs-worker",
28
28
  policy: "companion",
29
- dependsOn: ["background-jobs-main"],
30
29
  env: {VELOCIOUS_BACKGROUND_JOBS_PORT: "{{ports.background-jobs-main}}"},
31
30
  command: "npx velocious background-jobs-worker",
32
31
  replicas: 4,
@@ -107,15 +106,5 @@ Returned work may then run in the active generation. Normal retirement does not
107
106
  simulate a disconnect and does not make a new jobs-main adopt the old worker's
108
107
  handoffs.
109
108
 
110
- The supervisor's answer to a drain that cannot finish is separate from these
111
- timeouts. `releaseRetention.escalateWedgedGenerations` (off by default) lets the
112
- generation supervisor terminate a process group it has proven wedged and holding
113
- nothing — no live connection, every retirement budget expired, no runner child
114
- remaining, CPU flat across a full sample window — at the end of a retirement
115
- transition or at the next deploy. It never waits for a drain and never kills a
116
- process that still holds a live runner; a wedge it may not terminate is reported
117
- with its pids instead. See
118
- [`docs/config.md`](config.md#the-wedged-generation-escalation).
119
-
120
109
  See [`docs/velocious.md`](velocious.md) for the complete topology and
121
110
  [`docs/config.md`](config.md#processesdeploystrategy) for handoff-service fields.
@@ -20,7 +20,7 @@ export default {
20
20
  host: "127.0.0.1",
21
21
  port: 4500,
22
22
  healthPath: "/ping",
23
- healthTimeoutMs: 120000,
23
+ healthTimeoutMs: 30000,
24
24
  drainTimeoutMs: 60000,
25
25
  forceStopTimeoutMs: 10000
26
26
  },
@@ -60,7 +60,6 @@ export default {
60
60
  {
61
61
  id: "background-jobs-worker",
62
62
  policy: "companion",
63
- dependsOn: ["background-jobs-main"],
64
63
  cwd: "{{releasePath}}/backend",
65
64
  env: {
66
65
  NODE_ENV: "production",
@@ -68,7 +67,7 @@ export default {
68
67
  VELOCIOUS_BEACON_PORT: "{{ports.beacon}}",
69
68
  VELOCIOUS_BACKGROUND_JOBS_PORT: "{{ports.background-jobs-main}}"
70
69
  },
71
- command: "wait-for-it 127.0.0.1:{{ports.beacon}} --strict -- npx velocious background-jobs-worker",
70
+ command: "wait-for-it 127.0.0.1:{{ports.beacon}} --strict -- wait-for-it 127.0.0.1:{{ports.background-jobs-main}} --strict -- npx velocious background-jobs-worker",
72
71
  lifecycle: {
73
72
  quietCommand: "appctl jobs-worker-retire --pid $ROLLBRIDGE_PID",
74
73
  reactivateCommand: "appctl jobs-worker-reactivate --pid $ROLLBRIDGE_PID"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rollbridge",
3
- "version": "0.1.69",
3
+ "version": "0.1.71",
4
4
  "description": "Zero-downtime process supervisor and local traffic switcher for deploy-managed apps.",
5
5
  "keywords": [
6
6
  "deploy",
package/src/cli.js CHANGED
@@ -10,7 +10,6 @@ import RollbridgeDaemon, {ownerConfigDigest} from "./daemon.js"
10
10
  import {loadDaemonRuntimeIdentity, prepareDaemonRuntime} from "./daemon-runtime.js"
11
11
  import {loadConfig, parseConfigFile, resolveConfigPath, validateConfig} from "./config.js"
12
12
  import {runEnvironmentChecks, runReleaseChecks} from "./doctor.js"
13
- import {composeUnitStatus, rollComposeUnit, rollbackComposeUnit} from "./compose-unit.js"
14
13
  import {predeployCleanup} from "./predeploy-cleanup.js"
15
14
  import {recoverOrphans} from "./recover.js"
16
15
  import {sendControlCommand} from "./control-client.js"
@@ -248,49 +247,6 @@ export async function runCli(argv) {
248
247
  console.log(JSON.stringify(response, null, 2))
249
248
  })
250
249
 
251
- program
252
- .command("compose-roll")
253
- .description("Drain-first roll of one Docker Compose service: quiesce it, wait for in-flight work, recreate it with the target image, gate on activation, and roll back on failure.")
254
- .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
255
- .requiredOption("--unit <id>", "Compose unit id declared in the config")
256
- .option("--image <reference>", "Target image reference (defaults to the unit's configured image)")
257
- .action(async (options) => {
258
- const configPath = await resolveConfigPath(options.config)
259
- const config = await loadConfig(configPath)
260
- const result = await rollComposeUnit({config, image: options.image, unit: requireComposeUnit(config, options.unit, configPath)})
261
-
262
- console.log(JSON.stringify(result, null, 2))
263
- if (result.status === "failed") process.exitCode = 1
264
- })
265
-
266
- program
267
- .command("compose-rollback")
268
- .description("Roll one Compose unit back to its retained previous image through the same drain-first path.")
269
- .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
270
- .requiredOption("--unit <id>", "Compose unit id declared in the config")
271
- .option("--image <reference>", "Earlier image reference (defaults to the retained previous one)")
272
- .action(async (options) => {
273
- const configPath = await resolveConfigPath(options.config)
274
- const config = await loadConfig(configPath)
275
- const result = await rollbackComposeUnit({config, image: options.image, unit: requireComposeUnit(config, options.unit, configPath)})
276
-
277
- console.log(JSON.stringify(result, null, 2))
278
- if (result.status === "failed") process.exitCode = 1
279
- })
280
-
281
- program
282
- .command("compose-status")
283
- .description("Report a Compose unit's retained image generations and its live container state.")
284
- .option("-c, --config <path>", "Config file path (defaults to rollbridge.js)")
285
- .requiredOption("--unit <id>", "Compose unit id declared in the config")
286
- .action(async (options) => {
287
- const configPath = await resolveConfigPath(options.config)
288
- const config = await loadConfig(configPath)
289
- const status = await composeUnitStatus({config, unit: requireComposeUnit(config, options.unit, configPath)})
290
-
291
- console.log(JSON.stringify(status, null, 2))
292
- })
293
-
294
250
  program
295
251
  .command("ensure-daemon")
296
252
  .description("Start the daemon if the control socket is not already accepting commands.")
@@ -411,7 +367,7 @@ export async function runCli(argv) {
411
367
  const valid = issues.length === 0
412
368
 
413
369
  if (options.json) {
414
- const summary = valid ? {application: config.application, composeUnits: config.compose?.length ?? 0, processes: config.processes.length, proxy: {host: config.proxy.host, port: config.proxy.port}} : null
370
+ const summary = valid ? {application: config.application, processes: config.processes.length, proxy: {host: config.proxy.host, port: config.proxy.port}} : null
415
371
 
416
372
  console.log(JSON.stringify({config: summary, issues, path: configPath, valid}, null, 2))
417
373
  if (!valid) process.exitCode = 1
@@ -420,10 +376,8 @@ export async function runCli(argv) {
420
376
 
421
377
  if (valid) {
422
378
  const processCount = config.processes.length
423
- const composeCount = config.compose?.length ?? 0
424
- const composeSummary = composeCount > 0 ? `, ${composeCount} Compose unit${composeCount === 1 ? "" : "s"}` : ""
425
379
 
426
- console.log(`${configPath} is valid: ${processCount} ${processCount === 1 ? "process" : "processes"}${composeSummary}, proxy on ${config.proxy.host}:${config.proxy.port}.`)
380
+ console.log(`${configPath} is valid: ${processCount} ${processCount === 1 ? "process" : "processes"}, proxy on ${config.proxy.host}:${config.proxy.port}.`)
427
381
  return
428
382
  }
429
383
 
@@ -605,26 +559,6 @@ export async function runCli(argv) {
605
559
  await program.parseAsync(argv)
606
560
  }
607
561
 
608
- /**
609
- * Resolves a Compose unit by id, naming the configured units when the id is unknown.
610
- * @param {import("./config.js").RollbridgeConfig} config - Loaded config.
611
- * @param {string} unitId - Requested Compose unit id.
612
- * @param {string} configPath - Config path shown in the error.
613
- * @returns {import("./config.js").ComposeUnitConfig} The configured unit.
614
- */
615
- function requireComposeUnit(config, unitId, configPath) {
616
- const units = config.compose ?? []
617
- const unit = units.find((candidate) => candidate.id === unitId)
618
-
619
- if (unit) return unit
620
-
621
- if (units.length === 0) {
622
- throw new Error(`${configPath} declares no compose units. Add a compose: [{id: "${unitId}", ...}] entry to roll it drain-first.`)
623
- }
624
-
625
- throw new Error(`No compose unit "${unitId}" in ${configPath}. Configured units: ${units.map((candidate) => candidate.id).join(", ")}.`)
626
- }
627
-
628
562
  /**
629
563
  * @param {import("./predeploy-cleanup.js").PredeployCleanupResult} result - Cleanup result.
630
564
  * @returns {string} Human-readable summary.
package/src/config.js CHANGED
@@ -6,7 +6,6 @@ import {createRequire} from "node:module"
6
6
  import os from "node:os"
7
7
  import path from "node:path"
8
8
  import {pathToFileURL} from "node:url"
9
- import {processStartOrder} from "./process-order.js"
10
9
 
11
10
  /**
12
11
  * @typedef {import("./json.js").JsonValue} JsonValue
@@ -18,52 +17,19 @@ import {processStartOrder} from "./process-order.js"
18
17
  * @typedef {{activateCommand?: string, activateTimeoutMs?: number, drainCommand?: string, drainTimeoutMs: number, quietCommand?: string, reactivateCommand?: string, stopCommand?: string}} LifecycleConfig
19
18
  * @typedef {number | "indefinite"} StopTimeoutMs
20
19
  * @typedef {"persistent" | "handoff"} ServiceDeployStrategy
21
- * @typedef {{cwd?: string, dependencyTimeoutMs: number, dependsOn: string[], deployStrategy: ServiceDeployStrategy, env: Record<string, string>, gracefulStopMs: StopTimeoutMs, health?: HealthConfig, id: string, lifecycle: LifecycleConfig, memory?: MemoryConfig, nonBlockingDrain: boolean, outputLines: number, policy: ProcessPolicy, port?: PortRange, replicas: number, restart: RestartConfig, restartDelayMs: number, stopSignal: string, command: string}} ProcessConfig
20
+ * @typedef {{cwd?: string, deployStrategy: ServiceDeployStrategy, env: Record<string, string>, gracefulStopMs: StopTimeoutMs, health?: HealthConfig, id: string, lifecycle: LifecycleConfig, memory?: MemoryConfig, nonBlockingDrain: boolean, outputLines: number, policy: ProcessPolicy, port?: PortRange, replicas: number, restart: RestartConfig, restartDelayMs: number, stopSignal: string, command: string}} ProcessConfig
22
21
  * @typedef {{group?: number | string, mode?: number, owner?: number | string, path: string}} ControlConfig
23
- * @typedef {{drainTimeoutMs: number, forceStopTimeoutMs: number, healthPath: string, healthTimeoutMs: number, host: string, nonBlockingDrainTimeoutMs: number, port: number, upstreamHost: string}} ProxyConfig
22
+ * @typedef {{drainTimeoutMs: number, forceStopTimeoutMs: number, healthPath: string, healthTimeoutMs: number, host: string, port: number, upstreamHost: string}} ProxyConfig
24
23
  * @typedef {{includes: string[], name: string}} LegacyTakeoverProcessConfig
25
24
  * @typedef {{forceStopTimeoutMs: number, processes: LegacyTakeoverProcessConfig[], screens: string[]}} LegacyTakeoverConfig
26
- * @typedef {{escalateWedgedGenerations: boolean, keep: number, maxAgeMs: number, maxConcurrentDrainingReleaseGroups: number}} ReleaseRetentionConfig
25
+ * @typedef {{keep: number, maxAgeMs: number}} ReleaseRetentionConfig
27
26
  * @typedef {{reconnectGraceMs: number}} OwnerRecoveryConfig
28
- * @typedef {{command: string | undefined, timeoutMs: number}} ComposeDrainConfig
29
- * @typedef {{command: string | undefined, intervalMs: number, timeoutMs: number}} ComposeInFlightConfig
30
- * @typedef {{healthcheck: boolean, intervalMs: number, readyCommand: string | undefined, readyUrl: string | undefined, startDelayMs: number, timeoutMs: number}} ComposeActivationConfig
31
- * @typedef {{enabled: boolean}} ComposeRollbackConfig
32
- * @typedef {{activation: ComposeActivationConfig, composeFile: string, drain: ComposeDrainConfig, envFile: string | undefined, id: string, image: string, inFlight: ComposeInFlightConfig, projectName: string | undefined, projectDirectory: string, recreateTimeoutMs: number, rollback: ComposeRollbackConfig, service: string, stopGracePeriodMs: number}} ComposeUnitConfig
33
- * @typedef {{application: string, compose?: ComposeUnitConfig[], composeStatePath?: string, control: ControlConfig, legacyTakeover?: LegacyTakeoverConfig, ownerRecovery?: OwnerRecoveryConfig, processes: ProcessConfig[], proxy: ProxyConfig, releaseRetention: ReleaseRetentionConfig, statePath?: string}} RollbridgeConfig
27
+ * @typedef {{application: string, control: ControlConfig, legacyTakeover?: LegacyTakeoverConfig, ownerRecovery?: OwnerRecoveryConfig, processes: ProcessConfig[], proxy: ProxyConfig, releaseRetention: ReleaseRetentionConfig, statePath?: string}} RollbridgeConfig
34
28
  * @typedef {{fix: string, message: string}} ConfigIssue
35
29
  */
36
30
 
37
31
  const PROCESS_POLICIES = new Set(["proxied", "companion", "singleton", "service"])
38
32
  const DEFAULT_CONFIG_FILENAMES = ["rollbridge.js"]
39
- // Budget for one process waiting for a dependency's port, separate from the health budget.
40
- // Measured on TensorBuzz production (server3, 2026-11-06): the candidate's
41
- // background-jobs-main took 11817ms (14:33:39.175 start -> 14:33:50.992 listening) before
42
- // the web process could reach its own boot, and the production command chain already waited
43
- // 30000ms per hop. 30000ms keeps that dependency budget, so the health deadline measures
44
- // only the app boot.
45
- const DEFAULT_DEPENDENCY_TIMEOUT_MS = 30000
46
- // Budget for one process to answer its health path for the first time, measured from its
47
- // launch. Measured on TensorBuzz production (server3, 2026-11-06): the 30000ms release
48
- // health deadline killed two candidate web processes mid-boot. Release 20261106142602
49
- // started web at 14:33:39.205, was still printing attachment storage root migration lines
50
- // at 14:34:08.842, and got SIGTERM at 14:34:09.492 without ever logging a listening line,
51
- // so the app's own boot alone exceeded 30000ms; release 20261106144454 was killed 15373ms
52
- // after its web process started, before reaching those lines. 120000ms is the budget the
53
- // same app has been published on since (config/rollbridge.production.js, merged
54
- // 2026-11-06) and is made the default so a slow boot is not a trap every project has to
55
- // know to configure. A candidate that never becomes healthy still fails the deploy at the
56
- // deadline while the incumbent keeps serving; the budget only moves when the gate reports.
57
- const DEFAULT_HEALTH_TIMEOUT_MS = 120000
58
- // Bound on how many release groups may drain at once before a new handoff is refused.
59
- // Measured on TensorBuzz production (2026-11-14/15, shared/log/rollbridge.log): 16 releases
60
- // drained in 18-114 minutes with a median of ~37 minutes, while deploys arrived every
61
- // 3-7 minutes (7 traffic switches in 61 minutes on 2026-11-14). A bound of 1 — the value a
62
- // consumer gate effectively had — is unsatisfiable at that cadence, so every deploy adds one
63
- // more draining generation. 37 / 3 = 12 is the backlog the measured drain median produces at
64
- // the fastest measured cadence, so this default admits normal operation and refuses only
65
- // growth beyond it. 0 disables the bound.
66
- const DEFAULT_MAX_CONCURRENT_DRAINING_RELEASE_GROUPS = 12
67
33
  const commonJsRequire = createRequire(import.meta.url)
68
34
 
69
35
  /**
@@ -106,7 +72,6 @@ export async function loadConfig(configPath) {
106
72
 
107
73
  config.control.path = path.resolve(configDirectory, config.control.path)
108
74
  if (config.statePath) config.statePath = path.resolve(configDirectory, config.statePath)
109
- if (config.composeStatePath) config.composeStatePath = path.resolve(configDirectory, config.composeStatePath)
110
75
  return config
111
76
  }
112
77
 
@@ -160,32 +125,6 @@ export function normalizeConfig(rawConfig, configPath = process.cwd()) {
160
125
  return config
161
126
  }
162
127
 
163
- /**
164
- * Drops every undefined-valued property so a normalized config is identical to its own JSON form.
165
- *
166
- * Owner replacement hands the candidate daemon its release configs through the guardian's JSON
167
- * socket, and JSON serialization drops undefined-valued keys. The inherited config then compares
168
- * unequal to a freshly loaded one under `isDeepStrictEqual` even when the config file never
169
- * changed, and the live-reload fence aborts the next deploy. Measured in production on 2026-11-16
170
- * (tensorbuzz/production): after a failed activation was compensated inside a replacement daemon,
171
- * the following deploy failed with "Config changes to control cannot be applied live" while both
172
- * config files were byte-identical and hashed to the same `ownerConfigDigest` — that digest is
173
- * JSON-based, so the daemon held two contradictory notions of the same config and only the
174
- * JSON-shaped one survived the handoff.
175
- * @param {JsonValue} value - Normalized config value.
176
- * @returns {JsonValue} The same value with every undefined-valued property removed.
177
- */
178
- function withoutUndefinedProperties(value) {
179
- if (Array.isArray(value)) return value.map(withoutUndefinedProperties)
180
- if (isPlainObject(value)) {
181
- return Object.fromEntries(Object.entries(value)
182
- .filter(([, entryValue]) => entryValue !== undefined)
183
- .map(([key, entryValue]) => [key, withoutUndefinedProperties(entryValue)]))
184
- }
185
-
186
- return value
187
- }
188
-
189
128
  /**
190
129
  * Validates a raw config object and collects every issue instead of throwing on the first one.
191
130
  * @param {JsonValue} rawConfig - Parsed config.
@@ -219,32 +158,13 @@ export function validateConfig(rawConfig, configPath = process.cwd()) {
219
158
  const ownerRecoverySource = source.ownerRecovery === undefined || source.ownerRecovery === null ? undefined : objectAt(source.ownerRecovery, "ownerRecovery", issues)
220
159
  const reconnectGraceMs = ownerRecoverySource ? normalizeNumber(ownerRecoverySource.reconnectGraceMs, "ownerRecovery.reconnectGraceMs", issues, {default: 30000}) : 30000
221
160
  const ownerRecovery = ownerRecoverySource ? {reconnectGraceMs: nonNegativeOrDefault(reconnectGraceMs, "ownerRecovery.reconnectGraceMs", issues, 30000, true)} : undefined
222
- const compose = normalizeComposeUnits(source.compose, issues)
223
- const composeStatePath = compose.length === 0 && source.composeStatePath === undefined && source.composeStatePath !== null
224
- ? undefined
225
- : normalizeString(source.composeStatePath, "composeStatePath", issues, {default: path.resolve(path.dirname(configPath), `rollbridge-${application}.compose.state.json`)})
226
161
 
227
162
  if (ownerRecovery && !statePath) issues.push({fix: "Configure statePath when ownerRecovery is enabled.", message: "ownerRecovery requires statePath"})
228
163
 
229
164
  validateProcessSet(processes, issues)
230
165
  validateActivationLifecycle(processes, ownerRecovery, statePath, issues)
231
- validateComposeUnits(compose, processes, issues)
232
166
 
233
- return {
234
- config: /** @type {RollbridgeConfig} */ (withoutUndefinedProperties(/** @type {JsonValue} */ ({
235
- application,
236
- ...(compose.length > 0 ? {compose} : {}),
237
- ...(composeStatePath ? {composeStatePath} : {}),
238
- control,
239
- legacyTakeover,
240
- ownerRecovery,
241
- processes,
242
- proxy,
243
- releaseRetention,
244
- statePath
245
- }))),
246
- issues
247
- }
167
+ return {config: {application, control, legacyTakeover, ownerRecovery, processes, proxy, releaseRetention, statePath}, issues}
248
168
  }
249
169
 
250
170
  /**
@@ -259,9 +179,8 @@ function normalizeProxy(source, issues) {
259
179
  drainTimeoutMs: normalizeNumber(source.drainTimeoutMs, "proxy.drainTimeoutMs", issues, {default: 60000}),
260
180
  forceStopTimeoutMs: normalizeNumber(source.forceStopTimeoutMs, "proxy.forceStopTimeoutMs", issues, {default: 10000}),
261
181
  healthPath: normalizeString(source.healthPath, "proxy.healthPath", issues, {default: "/ping"}),
262
- healthTimeoutMs: normalizeNumber(source.healthTimeoutMs, "proxy.healthTimeoutMs", issues, {default: DEFAULT_HEALTH_TIMEOUT_MS}),
182
+ healthTimeoutMs: normalizeNumber(source.healthTimeoutMs, "proxy.healthTimeoutMs", issues, {default: 30000}),
263
183
  host,
264
- nonBlockingDrainTimeoutMs: normalizeNumber(source.nonBlockingDrainTimeoutMs, "proxy.nonBlockingDrainTimeoutMs", issues, {default: 60000}),
265
184
  port: normalizeNumber(source.port, "proxy.port", issues, {default: 8182}),
266
185
  upstreamHost: normalizeString(source.upstreamHost, "proxy.upstreamHost", issues, {default: defaultUpstreamHost(host)})
267
186
  }
@@ -288,7 +207,7 @@ function normalizeProcess(value, index, proxy, issues) {
288
207
  if (!isPlainObject(value)) {
289
208
  issues.push({fix: `Define processes[${index}] as a mapping with id, policy, and command.`, message: `processes[${index}] must be an object`})
290
209
 
291
- return {command: "", cwd: undefined, dependencyTimeoutMs: DEFAULT_DEPENDENCY_TIMEOUT_MS, dependsOn: [], deployStrategy: "persistent", env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", lifecycle: {drainTimeoutMs: 0}, memory: undefined, nonBlockingDrain: false, outputLines: 50, policy: "companion", port: undefined, replicas: 1, restart: defaultRestartConfig(), restartDelayMs: 1000, stopSignal: "SIGTERM"}
210
+ return {command: "", cwd: undefined, deployStrategy: "persistent", env: {}, gracefulStopMs: proxy.forceStopTimeoutMs, health: undefined, id: "", lifecycle: {drainTimeoutMs: 0}, memory: undefined, nonBlockingDrain: false, outputLines: 50, policy: "companion", port: undefined, replicas: 1, restart: defaultRestartConfig(), restartDelayMs: 1000, stopSignal: "SIGTERM"}
292
211
  }
293
212
 
294
213
  const source = value
@@ -296,8 +215,6 @@ function normalizeProcess(value, index, proxy, issues) {
296
215
  return {
297
216
  command: normalizeString(source.command, `processes[${index}].command`, issues),
298
217
  cwd: source.cwd === undefined ? undefined : normalizeString(source.cwd, `processes[${index}].cwd`, issues),
299
- dependencyTimeoutMs: normalizeDependencyTimeoutMs(source.dependencyTimeoutMs, `processes[${index}].dependencyTimeoutMs`, issues),
300
- dependsOn: normalizeDependsOn(source.dependsOn, `processes[${index}].dependsOn`, issues),
301
218
  deployStrategy: normalizeDeployStrategy(source.deployStrategy, `processes[${index}].deployStrategy`, issues),
302
219
  env: normalizeEnv(source.env, `processes[${index}].env`, issues),
303
220
  gracefulStopMs: normalizeStopTimeout(source.gracefulStopMs, `processes[${index}].gracefulStopMs`, proxy.forceStopTimeoutMs, issues),
@@ -601,180 +518,6 @@ function normalizeLegacyTakeoverProcess(value, index, issues) {
601
518
  }]
602
519
  }
603
520
 
604
- /**
605
- * @param {JsonValue} value - Raw Compose unit list.
606
- * @param {ConfigIssue[]} issues - Issue collector.
607
- * @returns {ComposeUnitConfig[]} Normalized Compose units (empty when the key is absent).
608
- */
609
- function normalizeComposeUnits(value, issues) {
610
- if (value === undefined || value === null) return []
611
-
612
- if (!Array.isArray(value)) {
613
- issues.push({fix: "Set compose to a list of Compose service units, or remove the key.", message: "compose must be an array"})
614
-
615
- return []
616
- }
617
-
618
- if (value.length === 0) {
619
- issues.push({fix: "Define at least one compose unit, or remove the compose key.", message: "compose must define at least one unit"})
620
-
621
- return []
622
- }
623
-
624
- return value.map((unitSource, index) => normalizeComposeUnit(unitSource, index, issues))
625
- }
626
-
627
- /**
628
- * @param {JsonValue} value - Raw Compose unit.
629
- * @param {number} index - Unit index.
630
- * @param {ConfigIssue[]} issues - Issue collector.
631
- * @returns {ComposeUnitConfig} Normalized Compose unit.
632
- */
633
- function normalizeComposeUnit(value, index, issues) {
634
- const key = `compose[${index}]`
635
-
636
- if (!isPlainObject(value)) {
637
- issues.push({fix: `Define ${key} as a mapping with id, service, image, and projectDirectory.`, message: `${key} must be an object`})
638
-
639
- return {
640
- activation: {healthcheck: true, intervalMs: 1000, readyCommand: undefined, readyUrl: undefined, startDelayMs: 0, timeoutMs: 60000},
641
- composeFile: "compose.yml",
642
- drain: {command: undefined, timeoutMs: 0},
643
- envFile: undefined,
644
- id: "",
645
- image: "",
646
- inFlight: {command: undefined, intervalMs: 1000, timeoutMs: 0},
647
- projectName: undefined,
648
- projectDirectory: "",
649
- recreateTimeoutMs: 120000,
650
- rollback: {enabled: true},
651
- service: "",
652
- stopGracePeriodMs: 10000
653
- }
654
- }
655
-
656
- const source = value
657
- const stopGracePeriodMs = normalizePositiveNumber(source.stopGracePeriodMs, `${key}.stopGracePeriodMs`, issues, 10000)
658
- const drainSource = source.drain === undefined || source.drain === null ? undefined : objectAt(source.drain, `${key}.drain`, issues, {})
659
- const inFlightSource = source.inFlight === undefined || source.inFlight === null ? undefined : objectAt(source.inFlight, `${key}.inFlight`, issues, {})
660
- const activationSource = source.activation === undefined || source.activation === null ? {} : objectAt(source.activation, `${key}.activation`, issues, {})
661
- const rollbackSource = source.rollback === undefined || source.rollback === null ? undefined : objectAt(source.rollback, `${key}.rollback`, issues, {})
662
-
663
- /** @type {ComposeUnitConfig} */
664
- const unit = {
665
- activation: {
666
- healthcheck: normalizeBoolean(activationSource.healthcheck, `${key}.activation.healthcheck`, issues, true),
667
- intervalMs: normalizePositiveNumber(activationSource.intervalMs, `${key}.activation.intervalMs`, issues, 1000),
668
- readyCommand: activationSource.readyCommand === undefined ? undefined : normalizeString(activationSource.readyCommand, `${key}.activation.readyCommand`, issues, {nonEmpty: true}),
669
- readyUrl: activationSource.readyUrl === undefined ? undefined : normalizeString(activationSource.readyUrl, `${key}.activation.readyUrl`, issues, {nonEmpty: true}),
670
- startDelayMs: normalizeStartDelayMs(activationSource.startDelayMs, `${key}.activation.startDelayMs`, issues),
671
- timeoutMs: normalizePositiveNumber(activationSource.timeoutMs, `${key}.activation.timeoutMs`, issues, 60000)
672
- },
673
- composeFile: normalizeString(source.composeFile, `${key}.composeFile`, issues, {default: "compose.yml"}),
674
- drain: {
675
- command: drainSource?.command === undefined ? undefined : normalizeString(drainSource.command, `${key}.drain.command`, issues, {nonEmpty: true}),
676
- timeoutMs: normalizeNumber(drainSource?.timeoutMs, `${key}.drain.timeoutMs`, issues, {default: 60000})
677
- },
678
- envFile: source.envFile === undefined || source.envFile === null ? undefined : normalizeString(source.envFile, `${key}.envFile`, issues, {nonEmpty: true}),
679
- id: normalizeString(source.id, `${key}.id`, issues),
680
- image: normalizeString(source.image, `${key}.image`, issues),
681
- inFlight: {
682
- command: inFlightSource?.command === undefined ? undefined : normalizeString(inFlightSource.command, `${key}.inFlight.command`, issues, {nonEmpty: true}),
683
- intervalMs: normalizePositiveNumber(inFlightSource?.intervalMs, `${key}.inFlight.intervalMs`, issues, 1000),
684
- timeoutMs: normalizeNumber(inFlightSource?.timeoutMs, `${key}.inFlight.timeoutMs`, issues, {default: 0})
685
- },
686
- projectName: source.projectName === undefined || source.projectName === null ? undefined : normalizeString(source.projectName, `${key}.projectName`, issues, {nonEmpty: true}),
687
- projectDirectory: normalizeString(source.projectDirectory, `${key}.projectDirectory`, issues),
688
- recreateTimeoutMs: normalizePositiveNumber(source.recreateTimeoutMs, `${key}.recreateTimeoutMs`, issues, 120000),
689
- rollback: {enabled: normalizeBoolean(rollbackSource?.enabled, `${key}.rollback.enabled`, issues, true)},
690
- service: normalizeString(source.service, `${key}.service`, issues),
691
- stopGracePeriodMs
692
- }
693
-
694
- if (unit.drain.command !== undefined && unit.drain.timeoutMs <= 0) {
695
- issues.push({fix: `Set ${key}.drain.timeoutMs to a positive number of milliseconds; with 0 the quiescence step is skipped and ${key}.drain.command never runs.`, message: `${key}.drain.command requires a positive ${key}.drain.timeoutMs`})
696
- }
697
-
698
- if (unit.inFlight.command !== undefined && unit.inFlight.timeoutMs <= 0) {
699
- issues.push({fix: `Set ${key}.inFlight.timeoutMs to how long the roll may wait for in-flight work, e.g. 120000; with 0 the gate is skipped and ${key}.inFlight.command never runs.`, message: `${key}.inFlight.command requires a positive ${key}.inFlight.timeoutMs`})
700
- }
701
-
702
- if (unit.image.length > 0 && !isComposeImageReference(unit.image)) {
703
- issues.push({fix: `Set ${key}.image to an image reference pinned to a tag or digest, e.g. "registry.local/socketduct-gateway:1.4.0".`, message: `${key}.image "${unit.image}" is not a valid image reference`})
704
- }
705
-
706
- return unit
707
- }
708
-
709
- /**
710
- * @param {JsonValue} value - Raw positive-number value.
711
- * @param {string} key - Config key.
712
- * @param {ConfigIssue[]} issues - Issue collector.
713
- * @param {number} fallback - Default and fallback value.
714
- * @returns {number} Positive number, or the fallback when invalid.
715
- */
716
- function normalizePositiveNumber(value, key, issues, fallback) {
717
- const number = normalizeNumber(value, key, issues, {default: fallback})
718
-
719
- if (!(number > 0)) {
720
- issues.push({fix: `Set ${key} to a positive number of milliseconds, e.g. ${fallback}.`, message: `${key} must be a positive number`})
721
-
722
- return fallback
723
- }
724
-
725
- return number
726
- }
727
-
728
- /**
729
- * @param {string} image - Image reference.
730
- * @returns {boolean} True when the reference is a usable Docker image name.
731
- */
732
- function isComposeImageReference(image) {
733
- if (/\s/.test(image) || image.startsWith("-")) return false
734
-
735
- const [name, digest] = image.split("@")
736
-
737
- if (name.length === 0) return false
738
- if (digest === undefined) return true
739
-
740
- return /^sha256:[a-f0-9]{64}$/.test(digest)
741
- }
742
-
743
- /**
744
- * Validates cross-unit rules: unique unit ids, no collision with process ids, and the fields a
745
- * drain-first roll needs.
746
- * @param {ComposeUnitConfig[]} compose - Normalized Compose units.
747
- * @param {ProcessConfig[]} processes - Normalized processes.
748
- * @param {ConfigIssue[]} issues - Issue collector.
749
- * @returns {void}
750
- */
751
- function validateComposeUnits(compose, processes, issues) {
752
- if (compose.length === 0) return
753
-
754
- const processIds = new Set(processes.map((processConfig) => processConfig.id))
755
- const seenIds = /** @type {Set<string>} */ (new Set())
756
-
757
- for (const unit of compose) {
758
- if (!unit.id) continue
759
-
760
- if (seenIds.has(unit.id)) {
761
- issues.push({fix: `Give each compose unit a unique id; "${unit.id}" is used more than once.`, message: `Duplicate compose unit id: ${unit.id}`})
762
- }
763
-
764
- seenIds.add(unit.id)
765
-
766
- if (processIds.has(unit.id)) {
767
- issues.push({fix: `Rename compose unit "${unit.id}" or the process with the same id; Rollbridge targets both by id.`, message: `Compose unit id "${unit.id}" collides with a process id`})
768
- }
769
- }
770
-
771
- for (const [index, unit] of compose.entries()) {
772
- if (!unit.service) issues.push({fix: `Set compose[${index}].service to the Compose service name to roll.`, message: `compose[${index}].service is required`})
773
- if (!unit.projectDirectory) issues.push({fix: `Set compose[${index}].projectDirectory to the directory holding the Compose file.`, message: `compose[${index}].projectDirectory is required`})
774
- if (!unit.image) issues.push({fix: `Set compose[${index}].image to the target image reference.`, message: `compose[${index}].image is required`})
775
- }
776
- }
777
-
778
521
  /**
779
522
  * @param {JsonValue} value - Raw stop signal.
780
523
  * @param {string} key - Config key.
@@ -823,34 +566,6 @@ function normalizeDeployStrategy(value, key, issues) {
823
566
  return "persistent"
824
567
  }
825
568
 
826
- /**
827
- * @param {JsonValue} value - Raw dependency list.
828
- * @param {string} key - Config key.
829
- * @param {ConfigIssue[]} issues - Issue collector.
830
- * @returns {string[]} Ids of the processes this process waits for before it starts.
831
- */
832
- function normalizeDependsOn(value, key, issues) {
833
- return normalizeStringList(value, key, issues)
834
- }
835
-
836
- /**
837
- * @param {JsonValue} value - Raw dependency wait budget.
838
- * @param {string} key - Config key.
839
- * @param {ConfigIssue[]} issues - Issue collector.
840
- * @returns {number} Milliseconds this process may spend waiting for its dependency ports.
841
- */
842
- function normalizeDependencyTimeoutMs(value, key, issues) {
843
- const timeoutMs = normalizeNumber(value, key, issues, {default: DEFAULT_DEPENDENCY_TIMEOUT_MS})
844
-
845
- if (timeoutMs < 1) {
846
- issues.push({fix: `Set ${key} to a positive number of milliseconds, e.g. 30000, or omit it for the default.`, message: `${key} must be a positive number`})
847
-
848
- return DEFAULT_DEPENDENCY_TIMEOUT_MS
849
- }
850
-
851
- return timeoutMs
852
- }
853
-
854
569
  /**
855
570
  * @param {JsonValue} value - Raw output retention value.
856
571
  * @param {string} key - Config key.
@@ -911,13 +626,10 @@ function normalizeBoolean(value, key, issues, fallback) {
911
626
  function normalizeReleaseRetention(source, issues) {
912
627
  const keep = normalizeNumber(source.keep, "releaseRetention.keep", issues, {default: 10})
913
628
  const maxAgeMs = normalizeNumber(source.maxAgeMs, "releaseRetention.maxAgeMs", issues, {default: 0})
914
- const maxConcurrentDrainingReleaseGroups = normalizeNumber(source.maxConcurrentDrainingReleaseGroups, "releaseRetention.maxConcurrentDrainingReleaseGroups", issues, {default: DEFAULT_MAX_CONCURRENT_DRAINING_RELEASE_GROUPS})
915
629
 
916
630
  return {
917
- escalateWedgedGenerations: normalizeBoolean(source.escalateWedgedGenerations, "releaseRetention.escalateWedgedGenerations", issues, false),
918
631
  keep: nonNegativeOrDefault(keep, "releaseRetention.keep", issues, 10, true),
919
- maxAgeMs: nonNegativeOrDefault(maxAgeMs, "releaseRetention.maxAgeMs", issues, 0, false),
920
- maxConcurrentDrainingReleaseGroups: nonNegativeOrDefault(maxConcurrentDrainingReleaseGroups, "releaseRetention.maxConcurrentDrainingReleaseGroups", issues, DEFAULT_MAX_CONCURRENT_DRAINING_RELEASE_GROUPS, true)
632
+ maxAgeMs: nonNegativeOrDefault(maxAgeMs, "releaseRetention.maxAgeMs", issues, 0, false)
921
633
  }
922
634
  }
923
635
 
@@ -1038,57 +750,6 @@ function validateProcessSet(processes, issues) {
1038
750
 
1039
751
  issues.push({fix: `Add a port range to the proxied process "${processConfig.id || "(unnamed)"}", e.g. port: {from: 18000, to: 18099}.`, message: `Proxied process ${processConfig.id || "(unnamed)"} must define a port range`})
1040
752
  }
1041
-
1042
- validateProcessDependencies(processes, issues)
1043
- }
1044
-
1045
- /**
1046
- * Validates `dependsOn`: a dependency must name a ported process that Rollbridge starts
1047
- * before the dependent. Waiting is done on the dependency's allocated port, and an edge that
1048
- * points backwards in the start order can never be satisfied, which also rules out cycles.
1049
- * @param {ProcessConfig[]} processes - Normalized processes.
1050
- * @param {ConfigIssue[]} issues - Issue collector.
1051
- * @returns {void}
1052
- */
1053
- function validateProcessDependencies(processes, issues) {
1054
- const declared = new Map(processes.filter((processConfig) => processConfig.id).map((processConfig) => [processConfig.id, processConfig]))
1055
- const startOrder = new Map(processStartOrder(processes, {includePersistentServices: true}).map((processConfig, index) => [processConfig.id, index]))
1056
-
1057
- for (const processConfig of processes) {
1058
- if (!processConfig.id || processConfig.dependsOn.length === 0) continue
1059
-
1060
- const dependentIndex = startOrder.get(processConfig.id)
1061
-
1062
- for (const dependencyId of processConfig.dependsOn) {
1063
- if (dependencyId === processConfig.id) {
1064
- issues.push({fix: `Remove "${processConfig.id}" from its own dependsOn.`, message: `Process "${processConfig.id}" cannot depend on itself`})
1065
- continue
1066
- }
1067
-
1068
- const dependency = declared.get(dependencyId)
1069
-
1070
- if (!dependency) {
1071
- issues.push({fix: `Name a configured process in "${processConfig.id}".dependsOn; "${dependencyId}" is not one of: ${[...declared.keys()].join(", ")}.`, message: `Process "${processConfig.id}" depends on unknown process "${dependencyId}"`})
1072
- continue
1073
- }
1074
-
1075
- if (dependency.policy === "singleton") {
1076
- issues.push({fix: `Remove "${dependencyId}" from "${processConfig.id}".dependsOn; a singleton is not part of a release generation, so Rollbridge cannot gate a release start on it.`, message: `Process "${processConfig.id}" cannot depend on singleton "${dependencyId}"`})
1077
- continue
1078
- }
1079
-
1080
- if (!dependency.port) {
1081
- issues.push({fix: `Give "${dependencyId}" a port, or remove it from "${processConfig.id}".dependsOn; Rollbridge waits for a dependency on its allocated port.`, message: `Process "${dependencyId}" has no port, so "${processConfig.id}" cannot wait for it`})
1082
- continue
1083
- }
1084
-
1085
- const dependencyIndex = startOrder.get(dependencyId)
1086
-
1087
- if (dependencyIndex === undefined || dependentIndex === undefined || dependencyIndex > dependentIndex) {
1088
- issues.push({fix: `Move "${dependencyId}" before "${processConfig.id}" in processes[]; Rollbridge starts persistent services, then handoff services, companions, and the proxied process.`, message: `Process "${processConfig.id}" depends on "${dependencyId}", which Rollbridge starts after it`})
1089
- }
1090
- }
1091
- }
1092
753
  }
1093
754
 
1094
755
  /**