velocious 1.0.751 → 1.0.753
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/build/background-jobs/client.js +5 -1
- package/build/background-jobs/endpoint-file.js +62 -0
- package/build/background-jobs/endpoint-unavailable-error.js +21 -0
- package/build/background-jobs/main.js +11 -0
- package/build/background-jobs/socket-request.js +7 -0
- package/build/background-jobs/worker.js +33 -2
- package/build/configuration-types.js +1 -0
- package/build/configuration.js +4 -2
- package/build/src/background-jobs/client.d.ts.map +1 -1
- package/build/src/background-jobs/client.js +6 -2
- package/build/src/background-jobs/endpoint-file.d.ts +27 -0
- package/build/src/background-jobs/endpoint-file.d.ts.map +1 -0
- package/build/src/background-jobs/endpoint-file.js +66 -0
- package/build/src/background-jobs/endpoint-unavailable-error.d.ts +20 -0
- package/build/src/background-jobs/endpoint-unavailable-error.d.ts.map +1 -0
- package/build/src/background-jobs/endpoint-unavailable-error.js +20 -0
- package/build/src/background-jobs/main.d.ts +1 -0
- package/build/src/background-jobs/main.d.ts.map +1 -1
- package/build/src/background-jobs/main.js +13 -1
- package/build/src/background-jobs/socket-request.d.ts.map +1 -1
- package/build/src/background-jobs/socket-request.js +7 -1
- package/build/src/background-jobs/worker.d.ts +1 -0
- package/build/src/background-jobs/worker.d.ts.map +1 -1
- package/build/src/background-jobs/worker.js +35 -3
- package/build/src/configuration-types.d.ts +5 -0
- package/build/src/configuration-types.d.ts.map +1 -1
- package/build/src/configuration-types.js +2 -1
- package/build/src/configuration.d.ts +3 -2
- package/build/src/configuration.d.ts.map +1 -1
- package/build/src/configuration.js +5 -3
- package/package.json +1 -1
- package/src/background-jobs/client.js +5 -1
- package/src/background-jobs/endpoint-file.js +62 -0
- package/src/background-jobs/endpoint-unavailable-error.js +21 -0
- package/src/background-jobs/main.js +11 -0
- package/src/background-jobs/socket-request.js +7 -0
- package/src/background-jobs/worker.js +33 -2
- package/src/configuration-types.js +1 -0
- package/src/configuration.js +4 -2
package/package.json
CHANGED
|
@@ -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
|
|
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
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
|
|
3
|
+
export const BACKGROUND_JOBS_ENDPOINT_UNAVAILABLE_ERROR_CODE = "BACKGROUND_JOBS_ENDPOINT_UNAVAILABLE"
|
|
4
|
+
|
|
5
|
+
/** Actionable failure when a background-jobs client cannot connect to the selected endpoint. */
|
|
6
|
+
export default class BackgroundJobsEndpointUnavailableError extends Error {
|
|
7
|
+
/**
|
|
8
|
+
* Creates an endpoint-unavailable error with the selected endpoint and peer role.
|
|
9
|
+
* @param {object} args - Error context.
|
|
10
|
+
* @param {string} args.endpoint - Main endpoint.
|
|
11
|
+
* @param {"client" | "reporter"} args.role - Initiating peer role.
|
|
12
|
+
* @param {Error} args.cause - Underlying connection error.
|
|
13
|
+
*/
|
|
14
|
+
constructor({endpoint, role, cause}) {
|
|
15
|
+
super(`Background jobs ${role} endpoint unavailable at ${endpoint}: ${cause.message}`, {cause})
|
|
16
|
+
this.name = "BackgroundJobsEndpointUnavailableError"
|
|
17
|
+
this.code = BACKGROUND_JOBS_ENDPOINT_UNAVAILABLE_ERROR_CODE
|
|
18
|
+
this.endpoint = endpoint
|
|
19
|
+
this.role = role
|
|
20
|
+
}
|
|
21
|
+
}
|
|
@@ -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
|
|
|
@@ -4,6 +4,7 @@ import net from "net"
|
|
|
4
4
|
import JsonSocket from "./json-socket.js"
|
|
5
5
|
import BackgroundJobsGenerationHandshakeTimeoutError, { DEFAULT_GENERATION_HANDSHAKE_TIMEOUT_MS, validateGenerationHandshakeTimeoutMs } from "./generation-handshake-timeout-error.js"
|
|
6
6
|
import BackgroundJobsGenerationRejectedError from "./generation-rejected-error.js"
|
|
7
|
+
import BackgroundJobsEndpointUnavailableError from "./endpoint-unavailable-error.js"
|
|
7
8
|
|
|
8
9
|
export default class BackgroundJobsSocketRequest {
|
|
9
10
|
/**
|
|
@@ -95,6 +96,12 @@ export default class BackgroundJobsSocketRequest {
|
|
|
95
96
|
}
|
|
96
97
|
|
|
97
98
|
jsonSocket.on("error", (error) => {
|
|
99
|
+
if (error && typeof error === "object" && "code" in error && error.code === "ECONNREFUSED") {
|
|
100
|
+
const connectionError = error instanceof Error ? error : new Error(String(error))
|
|
101
|
+
finish({}, () => reject(new BackgroundJobsEndpointUnavailableError({endpoint: `${this.host}:${this.port}`, role: this.role, cause: connectionError})))
|
|
102
|
+
return
|
|
103
|
+
}
|
|
104
|
+
|
|
98
105
|
finish({}, () => reject(error))
|
|
99
106
|
})
|
|
100
107
|
|
|
@@ -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
|
|
861
|
-
const
|
|
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"`.
|
package/src/configuration.js
CHANGED
|
@@ -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
|
-
|
|
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
|
/**
|