velocious 1.0.754 → 1.0.756

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 (38) hide show
  1. package/build/background-jobs/worker.js +50 -10
  2. package/build/configuration-types.js +9 -1
  3. package/build/configuration.js +36 -2
  4. package/build/database/advisory-lock-lock-server-local-client.js +28 -1
  5. package/build/environment-handlers/base.js +2 -0
  6. package/build/environment-handlers/node/advisory-lock-lock-server-local-server.js +260 -23
  7. package/build/environment-handlers/node/cli/commands/background-jobs-worker.js +4 -27
  8. package/build/environment-handlers/node.js +7 -4
  9. package/build/src/background-jobs/worker.d.ts +30 -2
  10. package/build/src/background-jobs/worker.d.ts.map +1 -1
  11. package/build/src/background-jobs/worker.js +50 -11
  12. package/build/src/configuration-types.d.ts +22 -2
  13. package/build/src/configuration-types.d.ts.map +1 -1
  14. package/build/src/configuration-types.js +10 -2
  15. package/build/src/configuration.d.ts +2 -1
  16. package/build/src/configuration.d.ts.map +1 -1
  17. package/build/src/configuration.js +35 -3
  18. package/build/src/database/advisory-lock-lock-server-local-client.d.ts +10 -1
  19. package/build/src/database/advisory-lock-lock-server-local-client.d.ts.map +1 -1
  20. package/build/src/database/advisory-lock-lock-server-local-client.js +25 -2
  21. package/build/src/environment-handlers/base.d.ts +7 -0
  22. package/build/src/environment-handlers/base.d.ts.map +1 -1
  23. package/build/src/environment-handlers/base.js +3 -1
  24. package/build/src/environment-handlers/node/advisory-lock-lock-server-local-server.js +239 -28
  25. package/build/src/environment-handlers/node/cli/commands/background-jobs-worker.d.ts.map +1 -1
  26. package/build/src/environment-handlers/node/cli/commands/background-jobs-worker.js +5 -24
  27. package/build/src/environment-handlers/node.d.ts +5 -3
  28. package/build/src/environment-handlers/node.d.ts.map +1 -1
  29. package/build/src/environment-handlers/node.js +8 -5
  30. package/package.json +1 -1
  31. package/src/background-jobs/worker.js +50 -10
  32. package/src/configuration-types.js +9 -1
  33. package/src/configuration.js +36 -2
  34. package/src/database/advisory-lock-lock-server-local-client.js +28 -1
  35. package/src/environment-handlers/base.js +2 -0
  36. package/src/environment-handlers/node/advisory-lock-lock-server-local-server.js +260 -23
  37. package/src/environment-handlers/node/cli/commands/background-jobs-worker.js +4 -27
  38. package/src/environment-handlers/node.js +7 -4
@@ -261,6 +261,7 @@ export default class BackgroundJobsWorker {
261
261
  * @param {number} [args.generationHandshakeTimeoutMs] - Maximum time to wait for generation acknowledgement (default: 4000).
262
262
  * @param {number} [args.reconnectDelayMs] - Delay before reconnecting an established worker connection (default: 1000).
263
263
  * @param {number} [args.jobTimeoutMs] - Override the wall-clock timeout for forked and pooled jobs from `configuration.getBackgroundJobsConfig()`. `0` disables it.
264
+ * @param {number | null} [args.workerShutdownTimeoutMs] - Override the wall-clock cap on one whole shutdown drain from `configuration.getBackgroundJobsConfig().workerShutdownTimeoutMs`. `null` drains without a bound.
264
265
  * @param {number} [args.pooledRunnerSilenceTimeoutMs] - Override the per-child IPC-silence bound for pooled children with in-flight jobs from `configuration.getBackgroundJobsConfig()` (default 120000ms). `0` disables the watchdog.
265
266
  * @param {boolean} [args.closeDatabaseConnectionsOnStop] - Whether stop owns closing the configuration's database pools (default true).
266
267
  * @param {() => void | Promise<void>} [args.onStopped] - Lifecycle hook invoked after the worker finishes stopping.
@@ -269,7 +270,7 @@ export default class BackgroundJobsWorker {
269
270
  * @param {(observation: import("./types.js").PooledChildMemoryObservation) => void | Promise<void>} [args.onPooledRunnerMemoryObservation] - Explicit pooled-child memory observation hook. Every validated observation (periodic while a child has in-flight jobs, plus on demand) is forwarded here, in addition to the worker's compact stderr log line, so an application can route memory diagnostics (e.g. to a bug reporter) without parsing logs.
270
271
  * @param {(payload: import("./types.js").BackgroundJobPayload) => void} [args.onJobAccepted] - Explicit job-acceptance observation hook. Fires the moment the worker accepts a dispatched job payload, before execution mode routing, so an observer can wait for the pickup event instead of polling in-flight sets.
271
272
  */
272
- constructor({configuration, host, port, generationId, workerInstanceId, maxConcurrentForkedJobs, maxConcurrentInlineJobs, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, forkedChildSigkillGraceMs, heartbeatIntervalMs, generationHandshakeTimeoutMs = DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, reconnectDelayMs = 1000, jobTimeoutMs, pooledRunnerSilenceTimeoutMs, closeDatabaseConnectionsOnStop = true, onStopped, onGenerationAccepted, onRetireMessage, onPooledRunnerMemoryObservation, onJobAccepted} = {}) {
273
+ constructor({configuration, host, port, generationId, workerInstanceId, maxConcurrentForkedJobs, maxConcurrentInlineJobs, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, forkedChildSigkillGraceMs, heartbeatIntervalMs, generationHandshakeTimeoutMs = DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, reconnectDelayMs = 1000, jobTimeoutMs, workerShutdownTimeoutMs, pooledRunnerSilenceTimeoutMs, closeDatabaseConnectionsOnStop = true, onStopped, onGenerationAccepted, onRetireMessage, onPooledRunnerMemoryObservation, onJobAccepted} = {}) {
273
274
  /**
274
275
  * Narrows the runtime value to the documented type.
275
276
  * @type {Promise<import("../configuration.js").default>} */
@@ -347,6 +348,20 @@ export default class BackgroundJobsWorker {
347
348
  * @type {number | undefined}
348
349
  */
349
350
  this.jobTimeoutMsOverride = typeof jobTimeoutMs === "number" ? jobTimeoutMs : undefined
351
+ /**
352
+ * Wall-clock cap on one whole shutdown drain, in ms, or `null` to drain
353
+ * without a bound. Constructor override wins; otherwise it is read from
354
+ * `configuration.getBackgroundJobsConfig().workerShutdownTimeoutMs` in
355
+ * `start()`. It bounds the generation-retirement drain as well as a SIGTERM
356
+ * stop, because a retired worker is the process that a deploy cannot wait on
357
+ * and must not have to wait on forever.
358
+ * @type {number | null | undefined}
359
+ */
360
+ this.workerShutdownTimeoutMsOverride = workerShutdownTimeoutMs === undefined
361
+ ? undefined
362
+ : (typeof workerShutdownTimeoutMs === "number" && Number.isInteger(workerShutdownTimeoutMs) && workerShutdownTimeoutMs > 0 ? workerShutdownTimeoutMs : null)
363
+ /** @type {number | null} */
364
+ this.workerShutdownTimeoutMs = this.workerShutdownTimeoutMsOverride ?? null
350
365
  this.shouldStop = false
351
366
  this.isRetiring = false
352
367
  /** @type {Promise<void> | undefined} */
@@ -509,6 +524,7 @@ export default class BackgroundJobsWorker {
509
524
  if (typeof this.pooledRunnerSilenceTimeoutMsOverride !== "number" && typeof poolConfig.pooledRunnerSilenceTimeoutMs === "number") this.pooledRunnerSilenceTimeoutMs = poolConfig.pooledRunnerSilenceTimeoutMs
510
525
  if (typeof this.runnerMaxOldSpaceSizeMbOverride !== "number" && typeof poolConfig.runnerMaxOldSpaceSizeMb === "number") this.runnerMaxOldSpaceSizeMb = poolConfig.runnerMaxOldSpaceSizeMb
511
526
  if (typeof this.runnerMallocArenaMaxOverride !== "number" && typeof poolConfig.runnerMallocArenaMax === "number") this.runnerMallocArenaMax = poolConfig.runnerMallocArenaMax
527
+ if (this.workerShutdownTimeoutMsOverride === undefined) this.workerShutdownTimeoutMs = poolConfig.workerShutdownTimeoutMs ?? null
512
528
 
513
529
  this.statusReporter = new BackgroundJobsStatusReporter({
514
530
  configuration: this.configuration,
@@ -586,10 +602,11 @@ export default class BackgroundJobsWorker {
586
602
  /**
587
603
  * Runs the worker shutdown lifecycle once.
588
604
  * @param {object} [args] - Options.
589
- * @param {number} [args.timeoutMs] - Max wait for in-flight jobs (per phase) in ms.
605
+ * @param {number} [args.timeoutMs] - Max wait for in-flight jobs (per phase) in ms. Defaults to the configured `workerShutdownTimeoutMs`.
590
606
  * @returns {Promise<void>} - Resolves when stopped.
591
607
  */
592
608
  async _stop({timeoutMs} = {}) {
609
+ const drainTimeoutMs = typeof timeoutMs === "number" ? timeoutMs : (this.workerShutdownTimeoutMs ?? undefined)
593
610
  this.shouldStop = true
594
611
  this.isRetiring = true
595
612
  this._stopHeartbeat()
@@ -611,14 +628,14 @@ export default class BackgroundJobsWorker {
611
628
  }
612
629
  }
613
630
 
614
- await this._drainInflight(this.inflightInlineJobs, timeoutMs, {phase: "inline-jobs"})
615
- await this._drainInflight(this.inflightPooledJobs, timeoutMs, {phase: "pooled-jobs"})
631
+ await this._drainInflight(this.inflightInlineJobs, drainTimeoutMs, {phase: "inline-jobs"})
632
+ await this._drainInflight(this.inflightPooledJobs, drainTimeoutMs, {phase: "pooled-jobs"})
616
633
  this._releaseProcessJobHoldersWithGoneChildren()
617
- await this._drainInflight(this.inflightProcessJobs, timeoutMs, {phase: "process-jobs", describeHolders: () => this._describeProcessJobHolders()})
634
+ await this._drainInflight(this.inflightProcessJobs, drainTimeoutMs, {phase: "process-jobs", describeHolders: () => this._describeProcessJobHolders()})
618
635
  await this._terminateProcessChildren()
619
636
  // Give in-flight result reports (now decoupled from job slots) a bounded
620
637
  // chance to land before the socket closes.
621
- await this._drainInflight(this.inflightReports, timeoutMs)
638
+ await this._drainInflight(this.inflightReports, drainTimeoutMs)
622
639
 
623
640
  if (this.jsonSocket) this.jsonSocket.close()
624
641
  if (!this.configuration) return
@@ -646,6 +663,12 @@ export default class BackgroundJobsWorker {
646
663
  /**
647
664
  * Drains accepted generation work while retaining the exact connection and
648
665
  * heartbeat, then performs the final terminating stop.
666
+ *
667
+ * The drain is bounded by the worker's own configured cap, as one deadline
668
+ * shared across every phase rather than one per phase: this is the path a
669
+ * deploy retires a generation through, and the supervisor's retirement budget
670
+ * is deliberately only slightly longer than the cap, so four separate windows
671
+ * would overrun it and hand the wedge straight back to the release.
649
672
  * @returns {Promise<void>} - Resolves after the worker has fully closed.
650
673
  */
651
674
  async _stopAfterGenerationDrain() {
@@ -657,11 +680,15 @@ export default class BackgroundJobsWorker {
657
680
  }
658
681
  }
659
682
 
660
- await this._drainInflight(this.inflightInlineJobs)
661
- await this._drainInflight(this.inflightPooledJobs)
683
+ const deadlineMs = typeof this.workerShutdownTimeoutMs === "number"
684
+ ? Date.now() + this.workerShutdownTimeoutMs
685
+ : undefined
686
+
687
+ await this._drainInflight(this.inflightInlineJobs, this._remainingDrainMs(deadlineMs), {phase: "inline-jobs"})
688
+ await this._drainInflight(this.inflightPooledJobs, this._remainingDrainMs(deadlineMs), {phase: "pooled-jobs"})
662
689
  this._releaseProcessJobHoldersWithGoneChildren()
663
- await this._drainInflight(this.inflightProcessJobs)
664
- await this._drainInflight(this.inflightReports)
690
+ await this._drainInflight(this.inflightProcessJobs, this._remainingDrainMs(deadlineMs), {phase: "process-jobs", describeHolders: () => this._describeProcessJobHolders()})
691
+ await this._drainInflight(this.inflightReports, this._remainingDrainMs(deadlineMs), {phase: "reports"})
665
692
 
666
693
  this.shouldStop = true
667
694
  this._stopHeartbeat()
@@ -682,6 +709,19 @@ export default class BackgroundJobsWorker {
682
709
  })
683
710
  }
684
711
 
712
+ /**
713
+ * Time left inside one shared drain deadline, or `undefined` for an unbounded
714
+ * drain. A deadline that has already passed yields `0`, which lets each later
715
+ * phase report what it is still holding instead of silently waiting.
716
+ * @param {number | undefined} deadlineMs - Absolute deadline, or undefined when unbounded.
717
+ * @returns {number | undefined} - Remaining milliseconds, or undefined for no bound.
718
+ */
719
+ _remainingDrainMs(deadlineMs) {
720
+ if (typeof deadlineMs !== "number") return undefined
721
+
722
+ return Math.max(0, deadlineMs - Date.now())
723
+ }
724
+
685
725
  /**
686
726
  * Closes application resources before framework resources when this worker owns them.
687
727
  * @returns {Promise<void>} - Resolves after every owned close succeeds.
@@ -274,6 +274,14 @@
274
274
  * tuning: set it well above the longest legitimate forked job (build runners,
275
275
  * long imports) so only genuinely-stuck runners are killed. Omit, `null`, or
276
276
  * `<= 0` to disable (default), which preserves the prior unbounded behavior.
277
+ * @property {number | null} [workerShutdownTimeoutMs] - Wall-clock cap, in ms, on
278
+ * one worker's whole shutdown drain, read from `VELOCIOUS_BACKGROUND_JOBS_WORKER_SHUTDOWN_TIMEOUT_MS`
279
+ * when the config omits it. It bounds the generation-retirement drain too, not
280
+ * only a SIGTERM stop: after the cap, whatever is still held is named in a
281
+ * `worker-shutdown-drain-timeout` event and the runner children are terminated
282
+ * (SIGTERM, then SIGKILL), so a retired generation closes itself instead of
283
+ * pinning its release. Omit, `null`, `0`, or the literal `"indefinite"` to drain
284
+ * without a bound (default), which keeps a live multi-hour job protected.
277
285
  * @property {BackgroundJobsRetentionConfiguration} [retention] - Retention/pruning
278
286
  * of terminal job rows. Without pruning the jobs table grows unbounded
279
287
  * (completed rows accumulate forever), which bloats storage and indexes and
@@ -908,7 +916,7 @@
908
916
  * behavior; the file backend is disabled by default and only selectable by
909
917
  * explicit configuration.
910
918
  * @typedef {object} AdvisoryLocksConfiguration
911
- * @property {{file?: {directory?: string, enabled?: boolean, leaseMs?: number, renewIntervalMs?: number}, lockServer?: {authToken?: string, connectTimeoutMs?: number, enabled?: boolean, host?: string, leaseMs?: number, mode?: "embedded" | "external" | "local", port?: number, reprobeCooldownMs?: number, socketPath?: string, url?: string}}} [backends] - Backend enablement. `file.enabled` defaults to false; enabling it is the deployment's explicit single-host declaration. `lockServer` defaults to enabled when a host/port/url or the `VELOCIOUS_LOCK_SERVER_HOST`/`_PORT` env pair is configured.
919
+ * @property {{file?: {directory?: string, enabled?: boolean, leaseMs?: number, renewIntervalMs?: number}, lockServer?: {authToken?: string, connectTimeoutMs?: number, enabled?: boolean, host?: string, leaseMs?: number, mode?: "embedded" | "external" | "local", port?: number, reprobeCooldownMs?: number, socketPath?: string, spawnEngine?: boolean, url?: string}}} [backends] - Backend enablement. `file.enabled` defaults to false; enabling it is the deployment's explicit single-host declaration. `lockServer` defaults to enabled when a host/port/url or the `VELOCIOUS_LOCK_SERVER_HOST`/`_PORT` env pair is configured. `lockServer.spawnEngine` is `local`-only and defaults to true; false means a supervisor owns the engine and this process never spawns one.
912
920
  * @property {import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]} [policy] - Per-lock-name minimum/allowed/preferred tier rules (design §5).
913
921
  */
914
922
 
@@ -140,6 +140,29 @@ function resolveBeaconUnreachableReportMs(value) {
140
140
  return 30_000
141
141
  }
142
142
 
143
+ /**
144
+ * Resolves the background-jobs worker's own drain cap from a raw configured value.
145
+ * `null` means "drain without a bound and never reap a live runner", which is what a
146
+ * multi-hour build needs; a positive integer is a deadline after which a runner still
147
+ * in flight is terminated instead of orphaned. The literal strings `indefinite` and
148
+ * `0` are the documented opt-out spellings — the production Rollbridge config writes
149
+ * `indefinite` — so they must not be parsed as numbers.
150
+ * @param {unknown} value - Configured value or raw environment value.
151
+ * @returns {number | null} - Milliseconds, or null for an unbounded drain.
152
+ */
153
+ function resolveWorkerShutdownTimeoutMs(value) {
154
+ if (value === null || value === undefined) return null
155
+
156
+ const normalized = typeof value === "string" ? value.trim().toLowerCase() : value
157
+
158
+ if (normalized === "" || normalized === "indefinite" || normalized === "0" || normalized === 0) return null
159
+ if (typeof normalized !== "string" && typeof normalized !== "number") return null
160
+
161
+ const parsed = Number(normalized)
162
+
163
+ return Number.isInteger(parsed) && parsed > 0 ? parsed : null
164
+ }
165
+
143
166
  const DEFAULT_WEBSOCKET_INBOUND_MAX_PENDING_BYTES = 16 * 1024 * 1024
144
167
  const DEFAULT_WEBSOCKET_INBOUND_MAX_PENDING_MESSAGES = 256
145
168
  const DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_BYTES = 16 * 1024 * 1024
@@ -1891,6 +1914,7 @@ export default class VelociousConfiguration {
1891
1914
  const envDispatchStrategy = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_DISPATCH_STRATEGY
1892
1915
  const envPollIntervalRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POLL_INTERVAL_MS
1893
1916
  const envJobTimeoutRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS
1917
+ const envWorkerShutdownTimeoutRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_WORKER_SHUTDOWN_TIMEOUT_MS
1894
1918
  const envPort = envPortRaw ? Number(envPortRaw) : undefined
1895
1919
  const envMaxConcurrentForked = envMaxConcurrentForkedRaw ? Number(envMaxConcurrentForkedRaw) : undefined
1896
1920
  const envMaxConcurrent = envMaxConcurrentRaw ? Number(envMaxConcurrentRaw) : undefined
@@ -1987,6 +2011,13 @@ export default class VelociousConfiguration {
1987
2011
  const jobTimeoutMs = "jobTimeoutMs" in configured
1988
2012
  ? (typeof configured.jobTimeoutMs === "number" && configured.jobTimeoutMs > 0 ? configured.jobTimeoutMs : null)
1989
2013
  : (typeof envJobTimeout === "number" && Number.isFinite(envJobTimeout) && envJobTimeout > 0 ? envJobTimeout : null)
2014
+ // The worker's own drain cap, read here so every shutdown path shares one
2015
+ // bound. `jobTimeoutMs` bounds one job; this bounds the whole retirement
2016
+ // drain, and it is the only thing that can end a drain whose remaining
2017
+ // work can no longer report its outcome.
2018
+ const workerShutdownTimeoutMs = "workerShutdownTimeoutMs" in configured
2019
+ ? resolveWorkerShutdownTimeoutMs(configured.workerShutdownTimeoutMs)
2020
+ : resolveWorkerShutdownTimeoutMs(envWorkerShutdownTimeoutRaw)
1990
2021
  const configuredRetention = configured.retention && typeof configured.retention === "object" ? configured.retention : {}
1991
2022
  const retention = {
1992
2023
  completedTtlMs: typeof configuredRetention.completedTtlMs === "number" || configuredRetention.completedTtlMs === null
@@ -2019,7 +2050,7 @@ export default class VelociousConfiguration {
2019
2050
  const jobClasses = this.getBackgroundJobClasses()
2020
2051
 
2021
2052
  const endpointPath = typeof configured.endpointPath === "string" ? configured.endpointPath : envEndpointPath
2022
- return {host, port, endpointPath, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, pooledRunnerSilenceTimeoutMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, scheduledEnqueueTimeoutMs, queues, queuePriorityAgingUnitMs, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
2053
+ return {host, port, endpointPath, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, pooledRunnerSilenceTimeoutMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, scheduledEnqueueTimeoutMs, queues, queuePriorityAgingUnitMs, jobClasses, jobTimeoutMs, workerShutdownTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
2023
2054
  }
2024
2055
 
2025
2056
  /**
@@ -4302,7 +4333,7 @@ export default class VelociousConfiguration {
4302
4333
  * Full backward compatibility: an app that configures nothing gets today's
4303
4334
  * driver-native-only behavior — the file backend is **disabled by default**
4304
4335
  * and only ever selectable by explicit configuration.
4305
- * @returns {{backends: {file: {directory?: string, enabled: boolean, leaseMs: number, renewIntervalMs: number}, lockServer: {authToken: string, connectTimeoutMs: number, enabled: boolean, leaseMs: number, mode: "embedded" | "external" | "local", reprobeCooldownMs: number, socketPath: string, url: string}}, policy: import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]}} - Advisory-lock configuration with defaults applied.
4336
+ * @returns {{backends: {file: {directory?: string, enabled: boolean, leaseMs: number, renewIntervalMs: number}, lockServer: {authToken: string, connectTimeoutMs: number, enabled: boolean, leaseMs: number, mode: "embedded" | "external" | "local", reprobeCooldownMs: number, socketPath: string, spawnEngine: boolean, url: string}}, policy: import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]}} - Advisory-lock configuration with defaults applied.
4306
4337
  */
4307
4338
  getAdvisoryLockConfig() {
4308
4339
  const configured = this._advisoryLocks || {}
@@ -4348,6 +4379,8 @@ export default class VelociousConfiguration {
4348
4379
  leaseMs: typeof lockServerConfigured.leaseMs === "number" ? lockServerConfigured.leaseMs : 30_000,
4349
4380
  mode: lockServerMode,
4350
4381
  reprobeCooldownMs: typeof lockServerConfigured.reprobeCooldownMs === "number" ? lockServerConfigured.reprobeCooldownMs : 5000,
4382
+ // `local` mode spawns its engine on demand. Set false when a supervisor (a Rollbridge service, for example) owns the engine, so no client can put a second unsupervised authority on the same socket path.
4383
+ spawnEngine: typeof lockServerConfigured.spawnEngine === "boolean" ? lockServerConfigured.spawnEngine : true,
4351
4384
  socketPath: typeof lockServerConfigured.socketPath === "string" ? lockServerConfigured.socketPath : "",
4352
4385
  url: lockServerUrl
4353
4386
  }
@@ -4447,6 +4480,7 @@ export default class VelociousConfiguration {
4447
4480
  },
4448
4481
  reprobeCooldownMs: config.backends.lockServer.reprobeCooldownMs,
4449
4482
  socketPath: config.backends.lockServer.socketPath,
4483
+ spawnEngine: config.backends.lockServer.spawnEngine,
4450
4484
  url: config.backends.lockServer.url
4451
4485
  })
4452
4486
 
@@ -21,6 +21,12 @@ import {fileURLToPath} from "node:url"
21
21
  * acquisition after the cooldown reconnects — respawning the engine child when
22
22
  * the socket file is gone. The cooldown IS the restart backoff; there is no
23
23
  * separate respawn loop.
24
+ *
25
+ * With `spawnEngine: false` the engine belongs to a supervisor (a Rollbridge
26
+ * service, for example) and this client never spawns one, so exactly one
27
+ * process on the host can own the socket. A missing engine then surfaces as an
28
+ * outage, and the engine server's takeover path replaces a retiring authority
29
+ * without a window where nothing is listening.
24
30
  */
25
31
  export default class AdvisoryLockLockServerLocalClient {
26
32
  /**
@@ -30,13 +36,15 @@ export default class AdvisoryLockLockServerLocalClient {
30
36
  * @param {string} [args.authToken] - Shared secret forwarded in the hello params.
31
37
  * @param {number} [args.connectTimeoutMs] - Bounded wait for the socket/engine child to become ready.
32
38
  * @param {number} [args.leaseMs] - Lease duration the engine child should use.
39
+ * @param {boolean} [args.spawnEngine] - When false the engine is owned by a supervisor and this client never spawns one: a missing engine is reported as an outage instead of being replaced by an unsupervised child that would fight the supervisor for the socket.
33
40
  * @param {string} args.socketPath - Unix socket path of the local engine.
34
41
  */
35
- constructor({authToken = "", connectTimeoutMs = 3000, leaseMs = 30_000, socketPath}) {
42
+ constructor({authToken = "", connectTimeoutMs = 3000, leaseMs = 30_000, socketPath, spawnEngine = true}) {
36
43
  this.authToken = authToken
37
44
  this.connectTimeoutMs = connectTimeoutMs
38
45
  this.leaseMs = leaseMs
39
46
  this.socketPath = socketPath
47
+ this.spawnEngine = spawnEngine !== false
40
48
  this.connectionId = `client-${process.pid}-${Math.random().toString(36).slice(2, 10)}`
41
49
  /** @type {net.Socket | null} */
42
50
  this.socket = null
@@ -64,6 +72,13 @@ export default class AdvisoryLockLockServerLocalClient {
64
72
  } catch (error) {
65
73
  if (!this.socketMissingError(error)) throw error
66
74
 
75
+ if (!this.spawnEngine) {
76
+ // The engine is a supervised process: spawning a child here would put a
77
+ // second, unsupervised authority on the same socket path. Report the
78
+ // outage and let the supervisor's own restart heal it.
79
+ throw new Error(`No supervised local lock server is listening at ${this.socketPath}`, {cause: error})
80
+ }
81
+
67
82
  // No engine is listening (missing socket, or a stale socket file left by
68
83
  // a crashed engine): spawn the engine child and poll until it is live.
69
84
  this.spawnEngineChild()
@@ -222,6 +237,18 @@ export default class AdvisoryLockLockServerLocalClient {
222
237
  try {
223
238
  const parsed = /** @type {Record<string, unknown>} */ (JSON.parse(line))
224
239
 
240
+ if (parsed.type === "server-retiring") {
241
+ // The engine is handing the host over to its successor: drop this
242
+ // transport now so the next acquisition reconnects to the successor
243
+ // instead of staying bound to an engine that is on its way out.
244
+ const socket = this.socket
245
+
246
+ this.handleTransportDeath(new Error("Local lock server is retiring"))
247
+ socket?.destroy()
248
+
249
+ continue
250
+ }
251
+
225
252
  this.onMessage?.(parsed)
226
253
  } catch {
227
254
  // A malformed engine line is not a lock answer: the adapter's
@@ -39,6 +39,7 @@ import {validateTimeZone} from "../time-zone.js"
39
39
  * @property {(error: Error) => void} [onError] - Async error reporter.
40
40
  * @property {number} [reprobeCooldownMs] - How long an unavailable server is not re-probed.
41
41
  * @property {string} [socketPath] - Unix socket path for `local` mode (defaults to a short path under os.tmpdir()).
42
+ * @property {boolean} [spawnEngine] - `local` mode only: false when a supervisor owns the engine, so this process never spawns a rival authority on the socket path.
42
43
  * @property {string} url - Lock-server endpoint (websocket URL for external mode; informational for embedded/local modes).
43
44
  */
44
45
 
@@ -85,6 +86,7 @@ export default class VelociousEnvironmentHandlerBase {
85
86
  * @param {(error: Error) => void} [args.onError] - Async error reporter.
86
87
  * @param {number} [args.reprobeCooldownMs] - Unavailability cache window.
87
88
  * @param {string} [args.socketPath] - Unix socket path for `local` mode.
89
+ * @param {boolean} [args.spawnEngine] - `local` mode only: false when a supervisor owns the engine.
88
90
  * @param {string} args.url - Lock-server endpoint.
89
91
  * @returns {Promise<import("../database/advisory-lock-lock-server-backend.js").default>} - Resolves with the created backend in capable handlers.
90
92
  */