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.
Files changed (87) hide show
  1. package/README.md +1 -1
  2. package/build/background-jobs/adapter.js +13 -1
  3. package/build/background-jobs/local-store.js +10 -16
  4. package/build/background-jobs/main.js +65 -2
  5. package/build/background-jobs/queue-priority-order.js +96 -0
  6. package/build/background-jobs/store.js +138 -29
  7. package/build/background-jobs/types.js +10 -0
  8. package/build/configuration-types.js +9 -0
  9. package/build/configuration.js +7 -1
  10. package/build/database/database-name.js +25 -0
  11. package/build/database/drivers/base.js +26 -0
  12. package/build/database/drivers/mssql/index.js +10 -0
  13. package/build/database/drivers/mysql/index.js +10 -0
  14. package/build/database/drivers/pgsql/index.js +10 -0
  15. package/build/database/drivers/sqlite/base.js +13 -0
  16. package/build/database/query/model-class-query.js +85 -0
  17. package/build/database/record/index.js +33 -0
  18. package/build/src/background-jobs/adapter.d.ts +17 -1
  19. package/build/src/background-jobs/adapter.d.ts.map +1 -1
  20. package/build/src/background-jobs/adapter.js +13 -2
  21. package/build/src/background-jobs/local-store.d.ts +5 -2
  22. package/build/src/background-jobs/local-store.d.ts.map +1 -1
  23. package/build/src/background-jobs/local-store.js +11 -15
  24. package/build/src/background-jobs/main.d.ts +16 -0
  25. package/build/src/background-jobs/main.d.ts.map +1 -1
  26. package/build/src/background-jobs/main.js +58 -3
  27. package/build/src/background-jobs/queue-priority-order.d.ts +55 -0
  28. package/build/src/background-jobs/queue-priority-order.d.ts.map +1 -0
  29. package/build/src/background-jobs/queue-priority-order.js +89 -0
  30. package/build/src/background-jobs/store.d.ts +71 -14
  31. package/build/src/background-jobs/store.d.ts.map +1 -1
  32. package/build/src/background-jobs/store.js +129 -34
  33. package/build/src/background-jobs/types.d.ts +32 -0
  34. package/build/src/background-jobs/types.d.ts.map +1 -1
  35. package/build/src/background-jobs/types.js +11 -1
  36. package/build/src/configuration-types.d.ts +21 -0
  37. package/build/src/configuration-types.d.ts.map +1 -1
  38. package/build/src/configuration-types.js +10 -1
  39. package/build/src/configuration.d.ts.map +1 -1
  40. package/build/src/configuration.js +8 -2
  41. package/build/src/database/database-name.d.ts +9 -0
  42. package/build/src/database/database-name.d.ts.map +1 -0
  43. package/build/src/database/database-name.js +23 -0
  44. package/build/src/database/drivers/base.d.ts +16 -0
  45. package/build/src/database/drivers/base.d.ts.map +1 -1
  46. package/build/src/database/drivers/base.js +24 -1
  47. package/build/src/database/drivers/mssql/index.d.ts +5 -0
  48. package/build/src/database/drivers/mssql/index.d.ts.map +1 -1
  49. package/build/src/database/drivers/mssql/index.js +9 -1
  50. package/build/src/database/drivers/mysql/index.d.ts +5 -0
  51. package/build/src/database/drivers/mysql/index.d.ts.map +1 -1
  52. package/build/src/database/drivers/mysql/index.js +9 -1
  53. package/build/src/database/drivers/pgsql/index.d.ts +5 -0
  54. package/build/src/database/drivers/pgsql/index.d.ts.map +1 -1
  55. package/build/src/database/drivers/pgsql/index.js +9 -1
  56. package/build/src/database/drivers/sqlite/base.d.ts +8 -0
  57. package/build/src/database/drivers/sqlite/base.d.ts.map +1 -1
  58. package/build/src/database/drivers/sqlite/base.js +12 -1
  59. package/build/src/database/query/model-class-query.d.ts +20 -0
  60. package/build/src/database/query/model-class-query.d.ts.map +1 -1
  61. package/build/src/database/query/model-class-query.js +75 -1
  62. package/build/src/database/record/index.d.ts +46 -0
  63. package/build/src/database/record/index.d.ts.map +1 -1
  64. package/build/src/database/record/index.js +30 -1
  65. package/build/src/tenants/default-tenant-database-provisioning.d.ts +14 -0
  66. package/build/src/tenants/default-tenant-database-provisioning.d.ts.map +1 -1
  67. package/build/src/tenants/default-tenant-database-provisioning.js +25 -17
  68. package/build/tenants/default-tenant-database-provisioning.js +26 -20
  69. package/package.json +3 -2
  70. package/scripts/verify-dependency-refs.js +14 -0
  71. package/src/background-jobs/adapter.js +13 -1
  72. package/src/background-jobs/local-store.js +10 -16
  73. package/src/background-jobs/main.js +65 -2
  74. package/src/background-jobs/queue-priority-order.js +96 -0
  75. package/src/background-jobs/store.js +138 -29
  76. package/src/background-jobs/types.js +10 -0
  77. package/src/configuration-types.js +9 -0
  78. package/src/configuration.js +7 -1
  79. package/src/database/database-name.js +25 -0
  80. package/src/database/drivers/base.js +26 -0
  81. package/src/database/drivers/mssql/index.js +10 -0
  82. package/src/database/drivers/mysql/index.js +10 -0
  83. package/src/database/drivers/pgsql/index.js +10 -0
  84. package/src/database/drivers/sqlite/base.js +13 -0
  85. package/src/database/query/model-class-query.js +85 -0
  86. package/src/database/record/index.js +33 -0
  87. 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 the dispatcher picks higher-priority queues first regardless of enqueue
1205
- * order. Only applied to the dispatch path (`scheduledAtOperator === "<="`);
1206
- * the future-scheduled lookup must stay strictly time-ordered. Composes with
1207
- * the concurrency EXISTS filter: a higher-priority queue already at its cap is
1208
- * filtered out, so dispatch falls through to the next eligible lower-priority
1209
- * job. Returns null when no queue configures a non-zero priority so the plain
1210
- * FIFO ordering is left untouched (and no needless filesort is introduced).
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
- * @returns {string | null} - Raw SQL CASE expression, or null when no queue is prioritized.
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
- const queues = this.configuration.getBackgroundJobsConfig().queues || {}
1216
- /** @type {Array<[string, number]>} */
1217
- const prioritized = []
1258
+ _queuePriorityOrderSql(db, nowMs) {
1259
+ return buildQueuePriorityOrderSql({configuration: this.configuration, db, nowMs})
1260
+ }
1218
1261
 
1219
- for (const [queue, queueConfig] of Object.entries(queues)) {
1220
- const priority = queueConfig?.priority
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
- if (Number.isFinite(priority) && Number(priority) !== 0) prioritized.push([queue, Number(priority)])
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
- if (prioritized.length === 0) return null
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
- const queueColumn = db.quoteColumn("queue")
1228
- const whens = prioritized
1229
- .map(([queue, priority]) => `WHEN ${db.quote(queue)} THEN ${priority}`)
1230
- .join(" ")
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 `CASE COALESCE(${queueColumn}, ${db.quote(DEFAULT_BACKGROUND_JOB_QUEUE)}) ${whens} ELSE 0 END`
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} concurrencyKey - Counter key for diagnostics.
4111
+ * @param {string} counterName - Counter identity used in the failure message.
4003
4112
  * @returns {number} - Safe non-negative count.
4004
4113
  */
4005
- _validatedConcurrencyCount(value, concurrencyKey) {
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 ${concurrencyKey}: ${count}`)
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"`
@@ -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