velocious 1.0.751 → 1.0.752

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "velocious": "build/bin/velocious.js"
4
4
  },
5
5
  "name": "velocious",
6
- "version": "1.0.751",
6
+ "version": "1.0.752",
7
7
  "main": "build/index.js",
8
8
  "types": "build/index.d.ts",
9
9
  "files": [
@@ -7,6 +7,7 @@ import BackgroundJobEnqueueAcknowledgementTimeoutError from "./enqueue-acknowled
7
7
  import BackgroundJobsSocketRequest from "./socket-request.js"
8
8
  import { DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, validateGenerationHandshakeTimeoutMs } from "./generation-handshake-timeout-error.js"
9
9
  import { BACKGROUND_JOB_ACTIVE_STATUSES, BACKGROUND_JOB_EXECUTION_MODES, BACKGROUND_JOB_STATUSES, BACKGROUND_JOB_TERMINAL_STATUSES } from "./job-semantics.js"
10
+ import {readBackgroundJobsEndpoint} from "./endpoint-file.js"
10
11
 
11
12
  const DEFAULT_ENQUEUE_TIMEOUT_MS = 5000
12
13
  const BACKGROUND_JOB_WAKE_OUTCOMES = ["woken", "already_due", "handed_off", "not_found"]
@@ -113,7 +114,10 @@ export default class BackgroundJobsClient {
113
114
  */
114
115
  async _request() {
115
116
  const configuration = await this.configurationPromise
116
- const {host, port} = configuration.getBackgroundJobsConfig()
117
+ const config = configuration.getBackgroundJobsConfig()
118
+ const endpoint = await readBackgroundJobsEndpoint(config.endpointPath)
119
+ const host = endpoint?.host || config.host
120
+ const port = endpoint?.port || config.port
117
121
  const {generationId} = configuration.resolveBackgroundJobsGenerationConfig({
118
122
  generationId: this.explicitGenerationId,
119
123
  sourceName: "BackgroundJobsClient"
@@ -0,0 +1,62 @@
1
+ // @ts-check
2
+
3
+ import {readFile, rename, unlink, writeFile} from "node:fs/promises"
4
+
5
+ /** @typedef {{generationId?: string, host: string, port: number, pid: number}} BackgroundJobsEndpointRecord */
6
+
7
+ /**
8
+ * Checks one endpoint record.
9
+ * @param {unknown} value - Candidate record.
10
+ * @returns {value is BackgroundJobsEndpointRecord} - Whether the record is valid.
11
+ */
12
+ function isEndpointRecord(value) {
13
+ if (value === null || typeof value !== "object") return false
14
+ const candidate = /** @type {Record<string, unknown>} */ (value)
15
+ return typeof candidate.host === "string" && candidate.host.length > 0 && typeof candidate.port === "number" && Number.isInteger(candidate.port) && candidate.port > 0 && typeof candidate.pid === "number" && Number.isInteger(candidate.pid) && candidate.pid > 0
16
+ }
17
+
18
+ /**
19
+ * Reads the current endpoint record.
20
+ * @param {string | undefined} path - Endpoint file path.
21
+ * @returns {Promise<BackgroundJobsEndpointRecord | null>} - Current record or no record.
22
+ */
23
+ export async function readBackgroundJobsEndpoint(path) {
24
+ if (!path) return null
25
+ try {
26
+ const value = JSON.parse(await readFile(path, "utf8"))
27
+ return isEndpointRecord(value) ? value : null
28
+ } catch (error) {
29
+ if (/** @type {{code?: string}} */ (error).code === "ENOENT") return null
30
+ throw error
31
+ }
32
+ }
33
+
34
+ /**
35
+ * Atomically publishes the current endpoint.
36
+ * @param {string | undefined} path - Endpoint file path.
37
+ * @param {BackgroundJobsEndpointRecord} record - Endpoint record.
38
+ * @returns {Promise<void>} - Resolves after publication.
39
+ */
40
+ export async function publishBackgroundJobsEndpoint(path, record) {
41
+ if (!path) return
42
+ const temporaryPath = `${path}.tmp-${process.pid}`
43
+ await writeFile(temporaryPath, `${JSON.stringify(record)}\n`, {encoding: "utf8", mode: 0o600})
44
+ await rename(temporaryPath, path)
45
+ }
46
+
47
+ /**
48
+ * Removes the endpoint only when it still belongs to this main process.
49
+ * @param {string | undefined} path - Endpoint file path.
50
+ * @param {BackgroundJobsEndpointRecord} record - Endpoint ownership record.
51
+ * @returns {Promise<void>} - Resolves after conditional removal.
52
+ */
53
+ export async function removeBackgroundJobsEndpoint(path, record) {
54
+ if (!path) return
55
+ const current = await readBackgroundJobsEndpoint(path)
56
+ if (!current || current.pid !== record.pid || current.port !== record.port || current.host !== record.host || current.generationId !== record.generationId) return
57
+ try {
58
+ await unlink(path)
59
+ } catch (error) {
60
+ if (/** @type {{code?: string}} */ (error).code !== "ENOENT") throw error
61
+ }
62
+ }
@@ -11,6 +11,7 @@ import VelociousError from "../velocious-error.js"
11
11
  import shutdownLifecycle, { runShutdownSteps } from "../utils/shutdown-lifecycle.js"
12
12
  import { parseGenerationWorkerId, validateGenerationId, workerIdBelongsToGeneration } from "./generation-identity.js"
13
13
  import BackgroundJobsLifecycleControlServer from "./lifecycle-control-server.js"
14
+ import {publishBackgroundJobsEndpoint, removeBackgroundJobsEndpoint} from "./endpoint-file.js"
14
15
 
15
16
  /**
16
17
  * WorkerExecutionModeCapability type.
@@ -147,6 +148,7 @@ export default class BackgroundJobsMain {
147
148
  this._stoppedPromise = new Promise((/** @type {(value: void) => void} */ resolve) => { this._resolveStopped = resolve })
148
149
  this.host = host || config.host
149
150
  this.port = typeof port === "number" ? port : config.port
151
+ this.endpointPath = config.endpointPath
150
152
  this.dispatchStrategy = config.dispatchStrategy
151
153
  this.pollIntervalMs = config.pollIntervalMs
152
154
  this.drainStoreOperationTimeoutMs = config.drainStoreOperationTimeoutMs
@@ -332,6 +334,7 @@ export default class BackgroundJobsMain {
332
334
  if (address && typeof address === "object") {
333
335
  this.port = address.port
334
336
  }
337
+ await publishBackgroundJobsEndpoint(this.endpointPath, {generationId: this.generationId, host: this.host, port: this.port, pid: process.pid})
335
338
 
336
339
  this.lifecycleState = this.generationId ? this.initialGenerationState : "active"
337
340
 
@@ -431,6 +434,13 @@ export default class BackgroundJobsMain {
431
434
  * @returns {void} */
432
435
  _closeWorkers() {
433
436
  for (const connection of this.connections) {
437
+ if (this.generationId && this.workers.has(connection)) {
438
+ try {
439
+ connection.send({type: "shutdown", generationId: this.generationId})
440
+ } catch {
441
+ // The peer may already have closed; the endpoint record is the fallback fence.
442
+ }
443
+ }
434
444
  connection.close()
435
445
  }
436
446
  }
@@ -509,6 +519,7 @@ export default class BackgroundJobsMain {
509
519
 
510
520
  const {server} = this
511
521
  this.server = undefined
522
+ await removeBackgroundJobsEndpoint(this.endpointPath, {generationId: this.generationId, host: this.host, port: this.port, pid: process.pid})
512
523
  await new Promise((resolve) => server.close(() => resolve(undefined)))
513
524
  }
514
525
 
@@ -16,6 +16,7 @@ import { createGenerationWorkerId } from "./generation-identity.js"
16
16
  import { isProcessAlive } from "./owner-liveness.js"
17
17
  import BackgroundJobsGenerationHandshakeTimeoutError, { DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, validateGenerationHandshakeTimeoutMs } from "./generation-handshake-timeout-error.js"
18
18
  import { POOLED_RUNNER_INFLIGHT_JOB_ID_LIMIT, boundedPooledRunnerInflightJobIds, isPooledChildProcessFault, isPooledChildShutdownReason, isPooledChildShutdownSignal } from "./pooled-runner-shutdown.js"
19
+ import {readBackgroundJobsEndpoint} from "./endpoint-file.js"
19
20
 
20
21
  /**
21
22
  * Per-forked-child bookkeeping, shared by the wall-clock backstop, the runner's
@@ -279,6 +280,7 @@ export default class BackgroundJobsWorker {
279
280
  this.configuration = undefined
280
281
  this.host = host
281
282
  this.port = port
283
+ this.endpointPath = undefined
282
284
  this.explicitGenerationId = generationId
283
285
  this.workerInstanceId = workerInstanceId || randomUUID()
284
286
  /** @type {string | undefined} */
@@ -483,6 +485,7 @@ export default class BackgroundJobsWorker {
483
485
  : this.workerInstanceId
484
486
  this.host ||= resolvedConfig.host
485
487
  if (typeof this.port !== "number") this.port = resolvedConfig.port
488
+ this.endpointPath = resolvedConfig.endpointPath
486
489
  await this.configuration.initialize({type: "background-jobs-worker"})
487
490
  await this.configuration.connectBeacon({peerType: "background-jobs-worker"})
488
491
 
@@ -857,8 +860,11 @@ export default class BackgroundJobsWorker {
857
860
 
858
861
  const config = configuration.getBackgroundJobsConfig()
859
862
  if (this.generationId) this._generationAccepted = false
860
- const host = this.host || config.host
861
- const port = typeof this.port === "number" ? this.port : config.port
863
+ const endpoint = await readBackgroundJobsEndpoint(this.endpointPath)
864
+ const host = endpoint?.host || this.host || config.host
865
+ const port = endpoint?.port || (typeof this.port === "number" ? this.port : config.port)
866
+ this.host = host
867
+ this.port = port
862
868
  const socket = net.createConnection({host, port})
863
869
  socket.setKeepAlive(true, SOCKET_KEEPALIVE_MS)
864
870
  const jsonSocket = new JsonSocket(socket)
@@ -923,6 +929,14 @@ export default class BackgroundJobsWorker {
923
929
  return
924
930
  }
925
931
 
932
+ if (message?.type === "shutdown") {
933
+ if (this.generationId && message.generationId === this.generationId) {
934
+ this.shouldStop = true
935
+ this._beginGenerationRetirement()
936
+ }
937
+ return
938
+ }
939
+
926
940
  if (message?.type === "job") {
927
941
  await this._handleJob(message.payload)
928
942
  }
@@ -940,7 +954,24 @@ export default class BackgroundJobsWorker {
940
954
  if (this.generationId && !this._generationAccepted) {
941
955
  rejectHandshake(new Error("Background jobs socket closed before generation acknowledgement"))
942
956
  }
957
+ // A retiring main closes its listener as part of the same event that
958
+ // removes its endpoint record. Never reconnect a superseded generation:
959
+ // the reconnect would keep its runner process alive after the main died.
943
960
  if (this.shouldStop) return
961
+ if (this.generationId && this.endpointPath) {
962
+ void readBackgroundJobsEndpoint(this.endpointPath).then((endpoint) => {
963
+ if (this.shouldStop || this.isRetiring) return
964
+ if (!endpoint || endpoint.generationId !== this.generationId || !isProcessAlive(endpoint.pid)) {
965
+ this._beginGenerationRetirement()
966
+ return
967
+ }
968
+ if (connectionAccepted || allowReconnect) this._scheduleReconnect()
969
+ }).catch((error) => {
970
+ this._reportLifecycleError(error instanceof Error ? error : new Error(String(error)))
971
+ this._beginGenerationRetirement()
972
+ })
973
+ return
974
+ }
944
975
  if (connectionAccepted || allowReconnect || !this.generationId) this._scheduleReconnect()
945
976
  })
946
977
 
@@ -196,6 +196,7 @@
196
196
  * @property {string} [generationId] - Opt-in release generation identity. Must match `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` and agree with environment/API/CLI sources.
197
197
  * @property {BackgroundJobsGenerationInitialState} [initialGenerationState] - Generation-aware boot state. Defaults to `"candidate"`; invalid without `generationId`.
198
198
  * @property {string} [lifecycleSocketPath] - Absolute release-local Unix socket used by acknowledged activation and retirement commands.
199
+ * @property {string} [endpointPath] - Shared durable JSON file containing the currently listening main endpoint.
199
200
  * @property {string} [host] - Hostname for the background jobs main process.
200
201
  * @property {number} [port] - Port for the background jobs main process.
201
202
  * @property {string} [databaseIdentifier] - Database identifier used to store background jobs. Browser/Expo local dispatch uses this existing SQLite database and defaults to `"default"`.
@@ -1870,13 +1870,14 @@ export default class VelociousConfiguration {
1870
1870
 
1871
1871
  /**
1872
1872
  * Runs get background jobs config.
1873
- * @returns {Omit<Required<import("./configuration-types.js").BackgroundJobsConfiguration>, "adapter" | "retention" | "generationId" | "lifecycleSocketPath"> & {generationId?: string, lifecycleSocketPath?: string, retention: import("./configuration-types.js").ResolvedBackgroundJobsRetentionConfiguration}} - Background jobs configuration.
1873
+ * @returns {Omit<Required<import("./configuration-types.js").BackgroundJobsConfiguration>, "adapter" | "retention" | "generationId" | "lifecycleSocketPath" | "endpointPath"> & {endpointPath?: string, generationId?: string, lifecycleSocketPath?: string, retention: import("./configuration-types.js").ResolvedBackgroundJobsRetentionConfiguration}} - Background jobs configuration.
1874
1874
  */
1875
1875
  getBackgroundJobsConfig() {
1876
1876
  const processEnvironment = globalThis.process?.env
1877
1877
  const envHost = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_HOST
1878
1878
  const envPortRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_PORT
1879
1879
  const envDatabaseIdentifier = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_DATABASE_IDENTIFIER
1880
+ const envEndpointPath = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_ENDPOINT_PATH
1880
1881
  const envMaxConcurrentForkedRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_FORKED_JOBS
1881
1882
  const envMaxConcurrentRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_INLINE_JOBS
1882
1883
  const envPooledRunnerCountRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_COUNT
@@ -2017,7 +2018,8 @@ export default class VelociousConfiguration {
2017
2018
 
2018
2019
  const jobClasses = this.getBackgroundJobClasses()
2019
2020
 
2020
- return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, pooledRunnerSilenceTimeoutMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, scheduledEnqueueTimeoutMs, queues, queuePriorityAgingUnitMs, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
2021
+ 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}
2021
2023
  }
2022
2024
 
2023
2025
  /**