velocious 1.0.728 → 1.0.730
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/README.md +1 -1
- package/build/background-jobs/adapter.js +13 -1
- package/build/background-jobs/local-store.js +10 -16
- package/build/background-jobs/main.js +65 -2
- package/build/background-jobs/queue-priority-order.js +96 -0
- package/build/background-jobs/store.js +138 -29
- package/build/background-jobs/types.js +10 -0
- package/build/configuration-types.js +9 -0
- package/build/configuration.js +7 -1
- package/build/database/database-name.js +25 -0
- package/build/database/drivers/base.js +26 -0
- package/build/database/drivers/mssql/index.js +10 -0
- package/build/database/drivers/mysql/index.js +10 -0
- package/build/database/drivers/pgsql/index.js +10 -0
- package/build/database/drivers/sqlite/base.js +13 -0
- package/build/database/query/model-class-query.js +85 -0
- package/build/database/record/index.js +33 -0
- package/build/src/background-jobs/adapter.d.ts +17 -1
- package/build/src/background-jobs/adapter.d.ts.map +1 -1
- package/build/src/background-jobs/adapter.js +13 -2
- package/build/src/background-jobs/local-store.d.ts +5 -2
- package/build/src/background-jobs/local-store.d.ts.map +1 -1
- package/build/src/background-jobs/local-store.js +11 -15
- package/build/src/background-jobs/main.d.ts +16 -0
- package/build/src/background-jobs/main.d.ts.map +1 -1
- package/build/src/background-jobs/main.js +58 -3
- package/build/src/background-jobs/queue-priority-order.d.ts +55 -0
- package/build/src/background-jobs/queue-priority-order.d.ts.map +1 -0
- package/build/src/background-jobs/queue-priority-order.js +89 -0
- package/build/src/background-jobs/store.d.ts +71 -14
- package/build/src/background-jobs/store.d.ts.map +1 -1
- package/build/src/background-jobs/store.js +129 -34
- package/build/src/background-jobs/types.d.ts +32 -0
- package/build/src/background-jobs/types.d.ts.map +1 -1
- package/build/src/background-jobs/types.js +11 -1
- package/build/src/configuration-types.d.ts +21 -0
- package/build/src/configuration-types.d.ts.map +1 -1
- package/build/src/configuration-types.js +10 -1
- package/build/src/configuration.d.ts.map +1 -1
- package/build/src/configuration.js +8 -2
- package/build/src/database/database-name.d.ts +9 -0
- package/build/src/database/database-name.d.ts.map +1 -0
- package/build/src/database/database-name.js +23 -0
- package/build/src/database/drivers/base.d.ts +16 -0
- package/build/src/database/drivers/base.d.ts.map +1 -1
- package/build/src/database/drivers/base.js +24 -1
- package/build/src/database/drivers/mssql/index.d.ts +5 -0
- package/build/src/database/drivers/mssql/index.d.ts.map +1 -1
- package/build/src/database/drivers/mssql/index.js +9 -1
- package/build/src/database/drivers/mysql/index.d.ts +5 -0
- package/build/src/database/drivers/mysql/index.d.ts.map +1 -1
- package/build/src/database/drivers/mysql/index.js +9 -1
- package/build/src/database/drivers/pgsql/index.d.ts +5 -0
- package/build/src/database/drivers/pgsql/index.d.ts.map +1 -1
- package/build/src/database/drivers/pgsql/index.js +9 -1
- package/build/src/database/drivers/sqlite/base.d.ts +8 -0
- package/build/src/database/drivers/sqlite/base.d.ts.map +1 -1
- package/build/src/database/drivers/sqlite/base.js +12 -1
- package/build/src/database/query/model-class-query.d.ts +20 -0
- package/build/src/database/query/model-class-query.d.ts.map +1 -1
- package/build/src/database/query/model-class-query.js +75 -1
- package/build/src/database/record/index.d.ts +46 -0
- package/build/src/database/record/index.d.ts.map +1 -1
- package/build/src/database/record/index.js +30 -1
- package/build/src/tenants/default-tenant-database-provisioning.d.ts +14 -0
- package/build/src/tenants/default-tenant-database-provisioning.d.ts.map +1 -1
- package/build/src/tenants/default-tenant-database-provisioning.js +25 -17
- package/build/tenants/default-tenant-database-provisioning.js +26 -20
- package/package.json +3 -2
- package/scripts/verify-dependency-refs.js +14 -0
- package/src/background-jobs/adapter.js +13 -1
- package/src/background-jobs/local-store.js +10 -16
- package/src/background-jobs/main.js +65 -2
- package/src/background-jobs/queue-priority-order.js +96 -0
- package/src/background-jobs/store.js +138 -29
- package/src/background-jobs/types.js +10 -0
- package/src/configuration-types.js +9 -0
- package/src/configuration.js +7 -1
- package/src/database/database-name.js +25 -0
- package/src/database/drivers/base.js +26 -0
- package/src/database/drivers/mssql/index.js +10 -0
- package/src/database/drivers/mysql/index.js +10 -0
- package/src/database/drivers/pgsql/index.js +10 -0
- package/src/database/drivers/sqlite/base.js +13 -0
- package/src/database/query/model-class-query.js +85 -0
- package/src/database/record/index.js +33 -0
- package/src/tenants/default-tenant-database-provisioning.js +26 -20
|
@@ -27,6 +27,7 @@ import {
|
|
|
27
27
|
rescheduledBackgroundJobAtMs,
|
|
28
28
|
retryDelayMs
|
|
29
29
|
} from "./job-semantics.js"
|
|
30
|
+
import {buildQueuePriorityOrderSql} from "./queue-priority-order.js"
|
|
30
31
|
import {
|
|
31
32
|
MAIL_DELIVERY_OPERATIONS_TABLE,
|
|
32
33
|
mailDeliveryOperationForJob,
|
|
@@ -87,6 +88,21 @@ import {
|
|
|
87
88
|
* @property {number | null} maxConcurrency - Current concurrency cap for queued work.
|
|
88
89
|
*/
|
|
89
90
|
|
|
91
|
+
/**
|
|
92
|
+
* Aggregated queued backlog for one lane, read straight off the jobs table.
|
|
93
|
+
* @typedef {object} BackgroundJobQueueBacklogRow
|
|
94
|
+
* @property {number | string} backlog_depth - Eligible queued rows in the lane.
|
|
95
|
+
* @property {number | string | null} oldest_scheduled_at_ms - Oldest eligible queued row.
|
|
96
|
+
* @property {string} queue - Lane name.
|
|
97
|
+
*/
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* Aggregated claims for one lane inside the observation window.
|
|
101
|
+
* @typedef {object} BackgroundJobQueueClaimRow
|
|
102
|
+
* @property {number | string} claim_count - Rows the dispatcher handed off in the window.
|
|
103
|
+
* @property {string} queue - Lane name.
|
|
104
|
+
*/
|
|
105
|
+
|
|
90
106
|
const MIGRATIONS_TABLE = "velocious_internal_migrations"
|
|
91
107
|
const MIGRATION_SCOPE = "background_jobs"
|
|
92
108
|
const MIGRATION_VERSION = "20250215000000"
|
|
@@ -104,6 +120,22 @@ const JOBS_INDEX_REPAIR_MIGRATION_VERSION = "20260903120000"
|
|
|
104
120
|
const LEGACY_POOLED_HANDOFF_ID_PREFIX = "velocious-pooled:"
|
|
105
121
|
const LEGACY_POOLED_QUEUED_HANDOFF_ID = `${LEGACY_POOLED_HANDOFF_ID_PREFIX}queued`
|
|
106
122
|
const JOBS_TABLE = "background_jobs"
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Adds parent-side pooled-runner termination provenance to the durable error.
|
|
126
|
+
* @param {ReturnType<typeof JSON.parse>} error - Reported failure.
|
|
127
|
+
* @param {import("./types.js").PooledRunnerFailure} [runnerFailure] - Pooled-child failure provenance.
|
|
128
|
+
* @returns {ReturnType<typeof JSON.parse>} - Error with durable provenance.
|
|
129
|
+
*/
|
|
130
|
+
function errorWithPooledRunnerProvenance(error, runnerFailure) {
|
|
131
|
+
if (!runnerFailure?.shutdownReason) return error
|
|
132
|
+
|
|
133
|
+
const message = normalizeBackgroundJobError(error)
|
|
134
|
+
const shutdownSignal = runnerFailure.shutdownSignal || "none"
|
|
135
|
+
|
|
136
|
+
return `${message}; pooledRunnerShutdownReason=${runnerFailure.shutdownReason} pooledRunnerShutdownSignal=${shutdownSignal}`
|
|
137
|
+
}
|
|
138
|
+
|
|
107
139
|
const JOBS_INDEX_COLUMN_NAMES = [
|
|
108
140
|
"job_name",
|
|
109
141
|
"queue",
|
|
@@ -144,6 +176,16 @@ const JOB_TIMEOUT_VALIDATION_MESSAGE = `background job timeoutMs must be a finit
|
|
|
144
176
|
const BACKGROUND_JOB_PRIORITY_VALIDATION_MESSAGE = "background job priority must be a non-negative integer"
|
|
145
177
|
const ORPHANED_AFTER_MS = 2 * 60 * 60 * 1000
|
|
146
178
|
|
|
179
|
+
/**
|
|
180
|
+
* How long a lane's oldest eligible queued row may wait before the lane counts as starved.
|
|
181
|
+
* Normal dispatch claims an eligible job within one cycle, so a five-minute wait with no
|
|
182
|
+
* claim in the observation window is not ordinary queue depth — it is the lane not being
|
|
183
|
+
* reached, which is what {@link BackgroundJobsStore#readQueueDispatchDiagnostics} names.
|
|
184
|
+
*/
|
|
185
|
+
export const QUEUE_LANE_STARVATION_THRESHOLD_MS = 5 * 60 * 1000
|
|
186
|
+
/** Window over which a lane's claims are counted for the starvation diagnostic. */
|
|
187
|
+
export const QUEUE_CLAIM_OBSERVATION_WINDOW_MS = 10 * 60 * 1000
|
|
188
|
+
|
|
147
189
|
/**
|
|
148
190
|
* Priority a job is demoted to when it is re-queued after a failed attempt.
|
|
149
191
|
* A retry has already consumed capacity and time, so it must never overtake
|
|
@@ -1174,7 +1216,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
|
|
|
1174
1216
|
if (executionMode) query = this._whereExecutionMode({db, executionMode, query})
|
|
1175
1217
|
|
|
1176
1218
|
if (scheduledAtOperator === "<=") {
|
|
1177
|
-
const priorityOrder = this._queuePriorityOrderSql(db)
|
|
1219
|
+
const priorityOrder = this._queuePriorityOrderSql(db, now)
|
|
1178
1220
|
|
|
1179
1221
|
if (priorityOrder) query = query.order(`${priorityOrder} DESC`)
|
|
1180
1222
|
|
|
@@ -1200,36 +1242,102 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
|
|
|
1200
1242
|
|
|
1201
1243
|
/**
|
|
1202
1244
|
* Builds a raw SQL ORDER BY expression ranking queued jobs by their queue's
|
|
1203
|
-
* configured priority (`backgroundJobs.queues[queue].priority`, default `0`)
|
|
1204
|
-
* so
|
|
1205
|
-
*
|
|
1206
|
-
*
|
|
1207
|
-
*
|
|
1208
|
-
*
|
|
1209
|
-
*
|
|
1210
|
-
*
|
|
1245
|
+
* configured priority (`backgroundJobs.queues[queue].priority`, default `0`) plus the
|
|
1246
|
+
* row's own eligible wait, so a lane cannot be starved by a higher-priority lane that
|
|
1247
|
+
* stays non-empty without ever reaching its own cap. See
|
|
1248
|
+
* {@link buildQueuePriorityOrderSql} for the ranking contract. Only applied to the
|
|
1249
|
+
* dispatch path (`scheduledAtOperator === "<="`); the future-scheduled lookup must stay
|
|
1250
|
+
* strictly time-ordered. Composes with the concurrency EXISTS filter: a higher-priority
|
|
1251
|
+
* queue already at its cap is filtered out, so dispatch falls through to the next eligible
|
|
1252
|
+
* lower-priority job. Returns null when no queue configures a non-zero priority so the
|
|
1253
|
+
* plain FIFO ordering is left untouched (and no needless filesort is introduced).
|
|
1211
1254
|
* @param {import("../database/drivers/base.js").default} db - Database connection.
|
|
1212
|
-
* @
|
|
1255
|
+
* @param {number} nowMs - Dispatch instant.
|
|
1256
|
+
* @returns {string | null} - Raw SQL rank expression, or null when no queue is prioritized.
|
|
1213
1257
|
*/
|
|
1214
|
-
_queuePriorityOrderSql(db) {
|
|
1215
|
-
|
|
1216
|
-
|
|
1217
|
-
const prioritized = []
|
|
1258
|
+
_queuePriorityOrderSql(db, nowMs) {
|
|
1259
|
+
return buildQueuePriorityOrderSql({configuration: this.configuration, db, nowMs})
|
|
1260
|
+
}
|
|
1218
1261
|
|
|
1219
|
-
|
|
1220
|
-
|
|
1262
|
+
/**
|
|
1263
|
+
* Reads the per-lane dispatch boundary for every queue holding eligible queued work:
|
|
1264
|
+
* backlog depth, the oldest eligible row, and how many jobs that lane actually claimed
|
|
1265
|
+
* inside the observation window. A lane whose oldest eligible row has waited past
|
|
1266
|
+
* `starvationThresholdMs` while claiming nothing in the window is starved, and this is the
|
|
1267
|
+
* named diagnostic for that state instead of a backlog that only grows.
|
|
1268
|
+
*
|
|
1269
|
+
* The backlog uses the dispatcher's own eligibility gate, so a lane that is legitimately
|
|
1270
|
+
* sitting at its `maxConcurrent` cap is not reported as starved.
|
|
1271
|
+
* @param {object} [args] - Options.
|
|
1272
|
+
* @param {number} [args.nowMs] - Observation instant. Defaults to the store clock.
|
|
1273
|
+
* @param {number} [args.starvationThresholdMs] - How long the oldest eligible row may wait before the lane counts as starved.
|
|
1274
|
+
* @param {number} [args.windowMs] - Window in which lane claims are counted. Default 10 minutes.
|
|
1275
|
+
* @returns {Promise<import("./types.js").BackgroundJobLaneDiagnostics[]>} - Per-lane diagnostics, oldest backlog first.
|
|
1276
|
+
*/
|
|
1277
|
+
async readQueueDispatchDiagnostics({nowMs = this.clock.now(), starvationThresholdMs = QUEUE_LANE_STARVATION_THRESHOLD_MS, windowMs = QUEUE_CLAIM_OBSERVATION_WINDOW_MS} = {}) {
|
|
1278
|
+
await this.ensureReady()
|
|
1279
|
+
|
|
1280
|
+
const rows = await this._withDb(async (db) => {
|
|
1281
|
+
const jobsTable = db.quoteTable(JOBS_TABLE)
|
|
1282
|
+
const concurrencyTable = db.quoteTable(CONCURRENCY_TABLE)
|
|
1283
|
+
const queueExpression = `COALESCE(${jobsTable}.${db.quoteColumn("queue")}, ${db.quote(DEFAULT_BACKGROUND_JOB_QUEUE)})`
|
|
1284
|
+
const eligible = `(${jobsTable}.${db.quoteColumn("concurrency_key")} IS NULL OR EXISTS (` +
|
|
1285
|
+
`SELECT 1 FROM ${concurrencyTable} WHERE ` +
|
|
1286
|
+
`${concurrencyTable}.${db.quoteColumn("concurrency_key")} = ${jobsTable}.${db.quoteColumn("concurrency_key")} AND ` +
|
|
1287
|
+
`${concurrencyTable}.${db.quoteColumn("active_count")} < ${concurrencyTable}.${db.quoteColumn("max_concurrency")}))`
|
|
1288
|
+
const backlogRows = await db.query(`
|
|
1289
|
+
SELECT ${queueExpression} AS queue, COUNT(*) AS backlog_depth, MIN(${jobsTable}.${db.quoteColumn("scheduled_at_ms")}) AS oldest_scheduled_at_ms
|
|
1290
|
+
FROM ${jobsTable}
|
|
1291
|
+
WHERE ${jobsTable}.${db.quoteColumn("status")} = ${db.quote("queued")}
|
|
1292
|
+
AND ${jobsTable}.${db.quoteColumn("scheduled_at_ms")} <= ${db.quote(nowMs)}
|
|
1293
|
+
AND ${eligible}
|
|
1294
|
+
GROUP BY ${queueExpression}
|
|
1295
|
+
`)
|
|
1296
|
+
const claimRows = await db.query(`
|
|
1297
|
+
SELECT ${queueExpression} AS queue, COUNT(*) AS claim_count
|
|
1298
|
+
FROM ${jobsTable}
|
|
1299
|
+
WHERE ${jobsTable}.${db.quoteColumn("handed_off_at_ms")} >= ${db.quote(nowMs - windowMs)}
|
|
1300
|
+
GROUP BY ${queueExpression}
|
|
1301
|
+
`)
|
|
1302
|
+
|
|
1303
|
+
return {backlogRows, claimRows}
|
|
1304
|
+
})
|
|
1305
|
+
|
|
1306
|
+
const lanesByQueue = new Map()
|
|
1307
|
+
|
|
1308
|
+
for (const rawRow of rows.backlogRows) {
|
|
1309
|
+
const row = /** @type {BackgroundJobQueueBacklogRow} */ (rawRow)
|
|
1310
|
+
const queue = String(row.queue)
|
|
1221
1311
|
|
|
1222
|
-
|
|
1312
|
+
lanesByQueue.set(queue, {
|
|
1313
|
+
backlogDepth: this._validatedConcurrencyCount(row.backlog_depth, queue),
|
|
1314
|
+
claimsCount: 0,
|
|
1315
|
+
oldestScheduledAtMs: row.oldest_scheduled_at_ms === null || row.oldest_scheduled_at_ms === undefined
|
|
1316
|
+
? null
|
|
1317
|
+
: Number(row.oldest_scheduled_at_ms),
|
|
1318
|
+
queue,
|
|
1319
|
+
starved: false
|
|
1320
|
+
})
|
|
1223
1321
|
}
|
|
1224
1322
|
|
|
1225
|
-
|
|
1323
|
+
for (const rawRow of rows.claimRows) {
|
|
1324
|
+
const row = /** @type {BackgroundJobQueueClaimRow} */ (rawRow)
|
|
1325
|
+
const queue = String(row.queue)
|
|
1326
|
+
const lane = lanesByQueue.get(queue) || {backlogDepth: 0, claimsCount: 0, oldestScheduledAtMs: null, queue, starved: false}
|
|
1226
1327
|
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1328
|
+
lane.claimsCount = this._validatedConcurrencyCount(row.claim_count, queue)
|
|
1329
|
+
lanesByQueue.set(queue, lane)
|
|
1330
|
+
}
|
|
1331
|
+
|
|
1332
|
+
/** @type {import("./types.js").BackgroundJobLaneDiagnostics[]} */
|
|
1333
|
+
const diagnostics = []
|
|
1334
|
+
|
|
1335
|
+
for (const lane of lanesByQueue.values()) {
|
|
1336
|
+
lane.starved = lane.claimsCount === 0 && lane.oldestScheduledAtMs !== null && nowMs - lane.oldestScheduledAtMs >= starvationThresholdMs
|
|
1337
|
+
diagnostics.push(lane)
|
|
1338
|
+
}
|
|
1231
1339
|
|
|
1232
|
-
return
|
|
1340
|
+
return diagnostics.sort((left, right) => (left.oldestScheduledAtMs ?? Number.MAX_SAFE_INTEGER) - (right.oldestScheduledAtMs ?? Number.MAX_SAFE_INTEGER))
|
|
1233
1341
|
}
|
|
1234
1342
|
|
|
1235
1343
|
/**
|
|
@@ -1773,9 +1881,10 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
|
|
|
1773
1881
|
* @param {string} [args.handoffId] - Handoff lease id.
|
|
1774
1882
|
* @param {string} [args.workerId] - Worker id.
|
|
1775
1883
|
* @param {number} [args.handedOffAtMs] - Handed off timestamp.
|
|
1884
|
+
* @param {import("./types.js").PooledRunnerFailure} [args.runnerFailure] - Pooled-child process failure provenance.
|
|
1776
1885
|
* @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Updated job row when the report was accepted.
|
|
1777
1886
|
*/
|
|
1778
|
-
async markFailed({jobId, error, handoffId, workerId, handedOffAtMs}) {
|
|
1887
|
+
async markFailed({jobId, error, handoffId, workerId, handedOffAtMs, runnerFailure}) {
|
|
1779
1888
|
await this.ensureReady()
|
|
1780
1889
|
|
|
1781
1890
|
return await this._serializedCountMutation(async (db) => {
|
|
@@ -1784,7 +1893,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
|
|
|
1784
1893
|
if (!job) return null
|
|
1785
1894
|
if (!this._shouldAcceptReport({job, handoffId, workerId, handedOffAtMs})) return null
|
|
1786
1895
|
|
|
1787
|
-
const updatedJob = await this._applyFailure({db, job, error, markOrphaned: false})
|
|
1896
|
+
const updatedJob = await this._applyFailure({db, job, error: errorWithPooledRunnerProvenance(error, runnerFailure), markOrphaned: false})
|
|
1788
1897
|
|
|
1789
1898
|
if (updatedJob) await this._recordStatusTransition(db, job.status, updatedJob.status)
|
|
1790
1899
|
return updatedJob
|
|
@@ -3997,16 +4106,16 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
|
|
|
3997
4106
|
}
|
|
3998
4107
|
|
|
3999
4108
|
/**
|
|
4000
|
-
* Validates a database count before it participates in reconciliation.
|
|
4109
|
+
* Validates a database count before it participates in a diagnostic or reconciliation.
|
|
4001
4110
|
* @param {number | string} value - Raw count.
|
|
4002
|
-
* @param {string}
|
|
4111
|
+
* @param {string} counterName - Counter identity used in the failure message.
|
|
4003
4112
|
* @returns {number} - Safe non-negative count.
|
|
4004
4113
|
*/
|
|
4005
|
-
_validatedConcurrencyCount(value,
|
|
4114
|
+
_validatedConcurrencyCount(value, counterName) {
|
|
4006
4115
|
const count = this._normalizeNumber(value)
|
|
4007
4116
|
|
|
4008
4117
|
if (count === null || !Number.isSafeInteger(count) || count < 0) {
|
|
4009
|
-
throw new Error(`Invalid reconciled background job concurrency count for ${
|
|
4118
|
+
throw new Error(`Invalid reconciled background job concurrency count for ${counterName}: ${count}`)
|
|
4010
4119
|
}
|
|
4011
4120
|
|
|
4012
4121
|
return count
|
|
@@ -121,6 +121,16 @@
|
|
|
121
121
|
* @property {BackgroundJobConcurrencyRepair[]} repairs - Bounded deterministic sample of applied repairs.
|
|
122
122
|
* @property {number} repairsTruncatedCount - Applied repairs omitted from the sample.
|
|
123
123
|
*/
|
|
124
|
+
/**
|
|
125
|
+
* One queue lane's dispatch boundary: how deep its eligible backlog is, how long its oldest
|
|
126
|
+
* eligible row has waited, and how many jobs the dispatcher actually claimed from it.
|
|
127
|
+
* @typedef {object} BackgroundJobLaneDiagnostics
|
|
128
|
+
* @property {number} backlogDepth - Eligible queued rows in the lane.
|
|
129
|
+
* @property {number} claimsCount - Rows handed off by the dispatcher inside the observation window.
|
|
130
|
+
* @property {number | null} oldestScheduledAtMs - Oldest eligible queued row, null when the lane is empty.
|
|
131
|
+
* @property {string} queue - Lane name.
|
|
132
|
+
* @property {boolean} starved - Backlog past the starvation threshold with zero claims in the window.
|
|
133
|
+
*/
|
|
124
134
|
/**
|
|
125
135
|
* @typedef {object} PreparedLocalBackgroundJob
|
|
126
136
|
* @property {string} argsDigest - Fixed-width digest of the serialized arguments.
|
|
@@ -241,6 +241,15 @@
|
|
|
241
241
|
* Priorities may be any number, including negative to sink a queue below the
|
|
242
242
|
* default. Jobs within the same priority keep FIFO (`scheduled_at`, then
|
|
243
243
|
* `created_at`) order. Default: `{}` (no queue caps, all queues priority `0`).
|
|
244
|
+
* @property {number | null} [queuePriorityAgingUnitMs] - How many milliseconds of eligible
|
|
245
|
+
* waiting cancel one unit of `queues[name].priority` in the dispatch claim. Strict queue
|
|
246
|
+
* priority alone starves a lane that sits below a queue which stays non-empty without
|
|
247
|
+
* ever reaching its own `maxConcurrent` cap: the claim takes one job per cycle, so the
|
|
248
|
+
* lower lane is never selected. Aging adds each row's own eligible wait to its queue rank,
|
|
249
|
+
* capped at the full configured priority span, so the wait eventually cancels every gap
|
|
250
|
+
* and no lane can be starved for longer than `(highest priority - lowest priority) × unitMs`.
|
|
251
|
+
* Fresh work keeps its configured order exactly. Default: `60000` (one priority unit per
|
|
252
|
+
* minute of eligible waiting). `null` opts out and restores strict queue-priority ordering.
|
|
244
253
|
* @property {number | null} [scheduledEnqueueTimeoutMs] - Bounds one scheduled enqueue attempt in the main process. A durable enqueue that never settles (wedged DB connection, contended advisory lock) would otherwise keep its schedule key permanently in flight, so every later tick skipped itself and shutdown could never drain. On timeout the attempt is reported as `background-jobs-scheduled-enqueue-stall` and the key clears for the next tick. Default: 20 minutes — deliberately 5 minutes above `advisoryLockAcquireTimeoutMs` so the precise lock error surfaces first. `null` opts out.
|
|
245
254
|
* @property {BackgroundJobsDispatchStrategy} [dispatchStrategy] - How the main process
|
|
246
255
|
* detects new work. Defaults to `"beacon"` (event-driven). Set to `"polling"`
|
package/src/configuration.js
CHANGED
|
@@ -26,6 +26,7 @@ import UUID from "pure-uuid"
|
|
|
26
26
|
import translate from "gettext-universal/build/src/translate.js"
|
|
27
27
|
import Ability from "./authorization/ability.js"
|
|
28
28
|
import BackgroundJobsAdapter from "./background-jobs/adapter.js"
|
|
29
|
+
import {normalizeQueuePriorityAgingUnitMs} from "./background-jobs/queue-priority-order.js"
|
|
29
30
|
import {DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS} from "./background-jobs/scheduled-enqueue-bound.js"
|
|
30
31
|
import DatabaseOperation from "./database/operation.js"
|
|
31
32
|
import { initializeAuditedModelRelationships } from "./database/record/auditing.js"
|
|
@@ -1953,6 +1954,11 @@ export default class VelociousConfiguration {
|
|
|
1953
1954
|
)
|
|
1954
1955
|
: DEFAULT_SCHEDULED_ENQUEUE_TIMEOUT_MS
|
|
1955
1956
|
const queues = configured.queues && typeof configured.queues === "object" ? configured.queues : {}
|
|
1957
|
+
// `null` opts out of queue-priority aging and restores the strict configured priority
|
|
1958
|
+
// order. A present but non-positive or non-finite value is a mistake, not an opt-out, so
|
|
1959
|
+
// it falls back to the framework default instead of silently re-opening the starvation
|
|
1960
|
+
// path the aging term exists to close.
|
|
1961
|
+
const queuePriorityAgingUnitMs = normalizeQueuePriorityAgingUnitMs(configured.queuePriorityAgingUnitMs)
|
|
1956
1962
|
// An explicit config value wins over the env var — including `null`/`0`,
|
|
1957
1963
|
// which disable the backstop even when the environment sets a default.
|
|
1958
1964
|
// Only fall through to the env var when config omits `jobTimeoutMs` entirely.
|
|
@@ -1977,7 +1983,7 @@ export default class VelociousConfiguration {
|
|
|
1977
1983
|
|
|
1978
1984
|
const jobClasses = this.getBackgroundJobClasses()
|
|
1979
1985
|
|
|
1980
|
-
return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, pooledRunnerSilenceTimeoutMs, runnerMaxOldSpaceSizeMb, runnerMallocArenaMax, dispatchStrategy, pollIntervalMs, drainStoreOperationTimeoutMs, scheduledEnqueueTimeoutMs, queues, jobClasses, jobTimeoutMs, retention, generationId, initialGenerationState, lifecycleSocketPath}
|
|
1986
|
+
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}
|
|
1981
1987
|
}
|
|
1982
1988
|
|
|
1983
1989
|
/**
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Database names that may be interpolated into CREATE/DROP DATABASE DDL:
|
|
5
|
+
* plain lowercase identifiers only. Anything else (quotes, semicolons,
|
|
6
|
+
* wildcards, dots) is rejected before a statement is built, so every
|
|
7
|
+
* database-level helper operates on one explicitly named database and a
|
|
8
|
+
* name can never smuggle a pattern sweep or statement injection.
|
|
9
|
+
*/
|
|
10
|
+
const SAFE_DATABASE_NAME = /^[a-z0-9_]+$/
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Validates a database name against the strict allowlist before it is
|
|
14
|
+
* interpolated into DDL.
|
|
15
|
+
* @param {string | null | undefined} databaseName - Candidate database name.
|
|
16
|
+
* @param {string} operation - Operation name used in the rejection message.
|
|
17
|
+
* @returns {string} - The validated database name.
|
|
18
|
+
*/
|
|
19
|
+
export function safeDatabaseName(databaseName, operation) {
|
|
20
|
+
if (!databaseName || !SAFE_DATABASE_NAME.test(databaseName)) {
|
|
21
|
+
throw new Error(`Unsafe database name for ${operation}: ${databaseName}`)
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
return databaseName
|
|
25
|
+
}
|
|
@@ -1537,6 +1537,32 @@ export default class VelociousDatabaseDriversBase {
|
|
|
1537
1537
|
return false
|
|
1538
1538
|
}
|
|
1539
1539
|
|
|
1540
|
+
/**
|
|
1541
|
+
* Lists the database names visible from this connection, so callers never
|
|
1542
|
+
* issue `SHOW DATABASES`-style raw SQL through the driver. The listing is
|
|
1543
|
+
* read-only and never filters by name pattern — callers decide what to do
|
|
1544
|
+
* with the exact names.
|
|
1545
|
+
* @abstract
|
|
1546
|
+
* @returns {Promise<string[]>} - Resolves with the database names.
|
|
1547
|
+
*/
|
|
1548
|
+
listDatabases() {
|
|
1549
|
+
throw new Error(`'listDatabases' not implemented for ${this.constructor.name}`)
|
|
1550
|
+
}
|
|
1551
|
+
|
|
1552
|
+
/**
|
|
1553
|
+
* Whether one exact database name exists in this connection's listing.
|
|
1554
|
+
* Exact comparison only — never a name-pattern sweep.
|
|
1555
|
+
* @param {string} databaseName - Exact database name to look for.
|
|
1556
|
+
* @returns {Promise<boolean>} - Resolves with whether the database exists.
|
|
1557
|
+
*/
|
|
1558
|
+
async databaseExists(databaseName) {
|
|
1559
|
+
if (!databaseName) throw new Error("databaseExists requires an exact database name")
|
|
1560
|
+
|
|
1561
|
+
const databases = await this.listDatabases()
|
|
1562
|
+
|
|
1563
|
+
return databases.some((name) => name == databaseName)
|
|
1564
|
+
}
|
|
1565
|
+
|
|
1540
1566
|
/**
|
|
1541
1567
|
* Runs a callback inside a database transaction (or a savepoint when already inside one).
|
|
1542
1568
|
* The outermost transaction retries the whole callback on a deadlock / lock-wait-timeout,
|
|
@@ -516,6 +516,16 @@ export default class VelociousDatabaseDriversMssql extends Base{
|
|
|
516
516
|
return tables
|
|
517
517
|
}
|
|
518
518
|
|
|
519
|
+
/**
|
|
520
|
+
* Lists database names visible to this server connection from `sys.databases`.
|
|
521
|
+
* @returns {Promise<string[]>} - Resolves with the database names.
|
|
522
|
+
*/
|
|
523
|
+
async listDatabases() {
|
|
524
|
+
const result = await this.query("SELECT [name] FROM [sys].[databases] ORDER BY [name]")
|
|
525
|
+
|
|
526
|
+
return result.map((row) => String(row.name))
|
|
527
|
+
}
|
|
528
|
+
|
|
519
529
|
/**
|
|
520
530
|
* Reads column metadata for many tables in one query. The per-table read of the
|
|
521
531
|
* same three-way `INFORMATION_SCHEMA` join is one of the slowest things a boot
|
|
@@ -790,6 +790,16 @@ export default class VelociousDatabaseDriversMysql extends Base{
|
|
|
790
790
|
return tables
|
|
791
791
|
}
|
|
792
792
|
|
|
793
|
+
/**
|
|
794
|
+
* Lists database names visible to this server connection (`SHOW DATABASES`).
|
|
795
|
+
* @returns {Promise<string[]>} - Resolves with the database names.
|
|
796
|
+
*/
|
|
797
|
+
async listDatabases() {
|
|
798
|
+
const result = await this.query("SHOW DATABASES")
|
|
799
|
+
|
|
800
|
+
return result.map((row) => String(Object.values(row)[0]))
|
|
801
|
+
}
|
|
802
|
+
|
|
793
803
|
/**
|
|
794
804
|
* Reads column metadata for many tables in one query. `SHOW FULL COLUMNS` only
|
|
795
805
|
* describes a single table, but `information_schema.COLUMNS` carries the same
|
|
@@ -346,6 +346,16 @@ export default class VelociousDatabaseDriversPgsql extends Base{
|
|
|
346
346
|
return tables
|
|
347
347
|
}
|
|
348
348
|
|
|
349
|
+
/**
|
|
350
|
+
* Lists database names on this server connection from `pg_database`.
|
|
351
|
+
* @returns {Promise<string[]>} - Resolves with the database names.
|
|
352
|
+
*/
|
|
353
|
+
async listDatabases() {
|
|
354
|
+
const result = await this.query("SELECT datname FROM pg_database ORDER BY datname")
|
|
355
|
+
|
|
356
|
+
return result.map((row) => String(row.datname))
|
|
357
|
+
}
|
|
358
|
+
|
|
349
359
|
/**
|
|
350
360
|
* Reads column metadata for many tables in one query instead of one catalog
|
|
351
361
|
* join per table.
|
|
@@ -144,6 +144,19 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
|
|
|
144
144
|
return tables
|
|
145
145
|
}
|
|
146
146
|
|
|
147
|
+
/**
|
|
148
|
+
* SQLite has no server-side database catalog: the driver's own file is the
|
|
149
|
+
* only database it can list. `PRAGMA database_list` reports the attached
|
|
150
|
+
* schemas, so the listing stays driver-native instead of a raw-SQL caller
|
|
151
|
+
* convention.
|
|
152
|
+
* @returns {Promise<string[]>} - Resolves with the attached database names.
|
|
153
|
+
*/
|
|
154
|
+
async listDatabases() {
|
|
155
|
+
const result = await this.query("PRAGMA database_list")
|
|
156
|
+
|
|
157
|
+
return result.map((row) => String(row.name))
|
|
158
|
+
}
|
|
159
|
+
|
|
147
160
|
/**
|
|
148
161
|
* Deletes every eligible table through the platform driver's native SQLite
|
|
149
162
|
* script path so the whole cleanup is submitted as one request.
|
|
@@ -869,6 +869,91 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
|
|
|
869
869
|
await driver.query(sql, {logName: this.queryLogName("Update All"), signal: this._signal})
|
|
870
870
|
}
|
|
871
871
|
|
|
872
|
+
/**
|
|
873
|
+
* Executes a bulk DELETE of all rows matching the query's WHERE clause in one
|
|
874
|
+
* statement. Unlike `destroyAll()`, which loads records and destroys them one
|
|
875
|
+
* by one, this bypasses model lifecycle callbacks and validations — the
|
|
876
|
+
* cleanup-teardown shape where a fixed handful of statements must purge a
|
|
877
|
+
* scope regardless of row count.
|
|
878
|
+
* @returns {Promise<number>} - Affected row count.
|
|
879
|
+
*/
|
|
880
|
+
async deleteAll() {
|
|
881
|
+
const driver = this.driver
|
|
882
|
+
const tableName = this.getModelClass().tableName()
|
|
883
|
+
const joinsSql = new JoinsParser({pretty: false, query: this}).toSql()
|
|
884
|
+
const whereSql = new WhereParser({pretty: false, query: this}).toSql()
|
|
885
|
+
let sql
|
|
886
|
+
|
|
887
|
+
if (joinsSql.length > 0) {
|
|
888
|
+
// Subquery form for cross-driver compatibility (same rule as updateAll):
|
|
889
|
+
// drivers like SQLite cannot DELETE with JOINs.
|
|
890
|
+
const primaryKey = scalarModelPrimaryKey(this.getModelClass().primaryKey(), `${this.getModelClass().name}.deleteAll() with joins`)
|
|
891
|
+
const pk = driver.quoteColumn(primaryKey)
|
|
892
|
+
const qt = driver.quoteTable(tableName)
|
|
893
|
+
|
|
894
|
+
sql = `DELETE FROM ${qt} WHERE ${pk} IN (SELECT ${qt}.${pk} FROM ${qt}${joinsSql}${whereSql})`
|
|
895
|
+
} else {
|
|
896
|
+
sql = `DELETE FROM ${driver.quoteTable(tableName)}${whereSql}`
|
|
897
|
+
}
|
|
898
|
+
|
|
899
|
+
return await driver.affectedRows(sql, {logName: this.queryLogName("Delete All"), signal: this._signal})
|
|
900
|
+
}
|
|
901
|
+
|
|
902
|
+
/**
|
|
903
|
+
* Bulk-unlinks the rows matching this query: sets the given belongsTo
|
|
904
|
+
* relationship's foreign key column to NULL in one statement. The column is
|
|
905
|
+
* resolved through the relationship definition (never a caller-supplied
|
|
906
|
+
* column name), and the live schema must allow NULL for that column — a
|
|
907
|
+
* non-nullable FK fails loudly instead of issuing a doomed UPDATE. Lifecycle
|
|
908
|
+
* callbacks do not run (same contract as `updateAll`).
|
|
909
|
+
* @param {string} relationshipName - Declared belongsTo relationship to unlink.
|
|
910
|
+
* @returns {Promise<number>} - Affected row count.
|
|
911
|
+
*/
|
|
912
|
+
async unlinkAll(relationshipName) {
|
|
913
|
+
const modelClass = this.getModelClass()
|
|
914
|
+
const relationship = modelClass.getRelationshipByName(relationshipName)
|
|
915
|
+
|
|
916
|
+
if (relationship.getType() != "belongsTo") {
|
|
917
|
+
throw new Error(`${modelClass.name}#${relationshipName} is a ${relationship.getType()} relationship — unlinkAll requires a belongsTo relationship`)
|
|
918
|
+
}
|
|
919
|
+
|
|
920
|
+
if (relationship.getPolymorphic()) {
|
|
921
|
+
// A polymorphic FK value is only meaningful together with its type column,
|
|
922
|
+
// which the framework cannot infer from the relationship alone. Fail closed
|
|
923
|
+
// instead of unlinking same-id rows of other target types; use
|
|
924
|
+
// `where({subjectId, subjectType}).updateAll({subjectId: null})` for that shape.
|
|
925
|
+
throw new Error(`${modelClass.name}#${relationshipName} is polymorphic — unlinkAll requires a non-polymorphic belongsTo relationship`)
|
|
926
|
+
}
|
|
927
|
+
|
|
928
|
+
const driver = this.driver
|
|
929
|
+
const tableName = modelClass.tableName()
|
|
930
|
+
const foreignKeyColumn = relationship.getForeignKey()
|
|
931
|
+
const column = modelClass.getColumnsHash()[foreignKeyColumn]
|
|
932
|
+
|
|
933
|
+
if (!column) throw new Error(`Couldn't unlink ${modelClass.name}#${relationshipName}: column ${foreignKeyColumn} was not found on ${tableName}`)
|
|
934
|
+
|
|
935
|
+
if (!column.getNull()) {
|
|
936
|
+
throw new Error(`Couldn't unlink ${modelClass.name}#${relationshipName}: column ${foreignKeyColumn} is NOT NULL — destroy the dependent rows instead of unlinking them`)
|
|
937
|
+
}
|
|
938
|
+
|
|
939
|
+
const joinsSql = new JoinsParser({pretty: false, query: this}).toSql()
|
|
940
|
+
const whereSql = new WhereParser({pretty: false, query: this}).toSql()
|
|
941
|
+
const setSql = `${driver.quoteColumn(foreignKeyColumn)} = NULL`
|
|
942
|
+
let sql
|
|
943
|
+
|
|
944
|
+
if (joinsSql.length > 0) {
|
|
945
|
+
const primaryKey = scalarModelPrimaryKey(modelClass.primaryKey(), `${modelClass.name}.unlinkAll() with joins`)
|
|
946
|
+
const pk = driver.quoteColumn(primaryKey)
|
|
947
|
+
const qt = driver.quoteTable(tableName)
|
|
948
|
+
|
|
949
|
+
sql = `UPDATE ${qt} SET ${setSql} WHERE ${pk} IN (SELECT ${qt}.${pk} FROM ${qt}${joinsSql}${whereSql})`
|
|
950
|
+
} else {
|
|
951
|
+
sql = `UPDATE ${driver.quoteTable(tableName)} SET ${setSql}${whereSql}`
|
|
952
|
+
}
|
|
953
|
+
|
|
954
|
+
return await driver.affectedRows(sql, {logName: this.queryLogName("Unlink All"), signal: this._signal})
|
|
955
|
+
}
|
|
956
|
+
|
|
872
957
|
/**
|
|
873
958
|
* Runs find.
|
|
874
959
|
* @param {import("../../utils/model-primary-key.js").ModelPrimaryKeyValue} recordId - Record id.
|
|
@@ -3494,6 +3494,39 @@ class VelociousDatabaseRecord {
|
|
|
3494
3494
|
return await this._newQuery().destroyAll()
|
|
3495
3495
|
}
|
|
3496
3496
|
|
|
3497
|
+
/**
|
|
3498
|
+
* Bulk-deletes all rows of this model matching the given where hash in one
|
|
3499
|
+
* SQL statement. Unlike `destroyAll()`, no records are loaded and no
|
|
3500
|
+
* lifecycle callbacks or validations run — the cleanup/teardown shape where
|
|
3501
|
+
* a purge must cost one statement per table regardless of row count.
|
|
3502
|
+
* @template {typeof VelociousDatabaseRecord} MC
|
|
3503
|
+
* @this {MC}
|
|
3504
|
+
* @param {import("../query/index.js").WhereArgumentType} where - Where conditions (same resolution as `where(...)`).
|
|
3505
|
+
* @returns {Promise<number>} - Affected row count.
|
|
3506
|
+
*/
|
|
3507
|
+
static async deleteWhere(where) {
|
|
3508
|
+
await this.ensureInitialized()
|
|
3509
|
+
|
|
3510
|
+
return await this._newQuery().where(where).deleteAll()
|
|
3511
|
+
}
|
|
3512
|
+
|
|
3513
|
+
/**
|
|
3514
|
+
* Bulk-unlinks rows of this model in one SQL statement: sets the given
|
|
3515
|
+
* belongsTo relationship's foreign key to NULL for every row matching the
|
|
3516
|
+
* where hash. The column comes from the relationship definition and the live
|
|
3517
|
+
* schema must allow NULL. No lifecycle callbacks run.
|
|
3518
|
+
* @template {typeof VelociousDatabaseRecord} MC
|
|
3519
|
+
* @this {MC}
|
|
3520
|
+
* @param {string} relationshipName - Declared belongsTo relationship to unlink.
|
|
3521
|
+
* @param {import("../query/index.js").WhereArgumentType} where - Where conditions (same resolution as `where(...)`).
|
|
3522
|
+
* @returns {Promise<number>} - Affected row count.
|
|
3523
|
+
*/
|
|
3524
|
+
static async unlinkWhere(relationshipName, where) {
|
|
3525
|
+
await this.ensureInitialized()
|
|
3526
|
+
|
|
3527
|
+
return await this._newQuery().where(where).unlinkAll(relationshipName)
|
|
3528
|
+
}
|
|
3529
|
+
|
|
3497
3530
|
/**
|
|
3498
3531
|
* Runs pluck.
|
|
3499
3532
|
* @template {typeof VelociousDatabaseRecord} MC
|