velocious 1.0.517 → 1.0.519

package/README.md

@@ -440,7 +440,7 @@ This creates `src/frontend-models/user.js` (and one file per configured resource
 - Attribute methods like `user.name()` and `user.setName(...)`
 - Relationship helpers (when `relationships` are configured), for example `task.project()`, `await task.projectOrLoad()`, `await project.tasks().toArray()`, `await project.tasks().load()`, and `project.tasks().build({...})`
 - Preload relationships onto records you already have with `await record.preload(Model.preload({...}).select({...}))` (or `Preloader.preload(records, ...)` for arrays), including `selectsExtra(...)` and a `{force: true}` reload option — see [docs/frontend-models.md](docs/frontend-models.md#preloading-onto-loaded-records)
-- Attachment helpers (when `attachments` are configured), for example `await task.descriptionFile().attach(file)`, `await task.descriptionFile().download()`, and `await task.update({descriptionFile: file})`
+- Attachment helpers (when `attachments` are configured), for example `await task.descriptionFile().attach(file)`, `await task.descriptionFile().download()`, `await task.files().purgeAll()`, and `await task.update({descriptionFile: file})`
 
 React components can subscribe to lifecycle broadcasts without manual cleanup code:
 
@@ -501,6 +501,14 @@ await task.update({
 })
 ```
 
+Purge a record's attachments — both the stored files and their rows — for example before destroying the owner record:
+
+```js
+const purgedCount = await task.files().purgeAll()
+```
+
+`purgeAll()` deletes each attachment's backing storage and then its row, and removes only the attachments that existed when the purge started (a concurrent `attach()` for the same record/name is left intact). It throws without deleting anything if a storage driver has no `delete` operation, so a driver configured without deletion can never silently leak storage. It is a no-op for unpersisted records and returns the number of attachments purged.
+
 Configure attachment storage drivers in `Configuration`:
 
 ```js

package/build/background-jobs/job.js

@@ -13,6 +13,15 @@ import BackgroundJobsClient from "./client.js"
  * @template {Array<?>} [TArgs=[]]
  */
 export default class VelociousJob {
+  /**
+   * Queue this job class runs on. Subclasses set e.g. `static queue = "builds"`
+   * to route onto a queue with its own cluster-wide concurrency cap (configured
+   * via `backgroundJobs.queues`). The `{queue}` enqueue option overrides it.
+   * Left undefined, jobs run on the `"default"` queue.
+   * @type {string | undefined}
+   */
+  static queue = undefined
+
   /**
    * Runs job name.
    * @returns {string} - Job name.
@@ -21,6 +30,22 @@ export default class VelociousJob {
     return this.name
   }
 
+  /**
+   * Folds this job class's static `queue` into the enqueue options unless the
+   * caller already specified one.
+   * @param {import("./types.js").BackgroundJobOptions | undefined} options - Job options.
+   * @returns {import("./types.js").BackgroundJobOptions} - Options including the resolved queue.
+   */
+  static _withQueue(options) {
+    const merged = options ? {...options} : {}
+
+    if (merged.queue === undefined && typeof this.queue === "string" && this.queue.length > 0) {
+      merged.queue = this.queue
+    }
+
+    return merged
+  }
+
   /**
    * Runs perform later.
    * @param {...?} args - Job args.
@@ -33,7 +58,7 @@ export default class VelociousJob {
     return await client.enqueue({
       jobName: this.jobName(),
       args: jobArgs,
-      options: jobOptions
+      options: this._withQueue(jobOptions)
     })
   }
 
@@ -50,7 +75,7 @@ export default class VelociousJob {
     return await client.enqueue({
       jobName: this.jobName(),
       args,
-      options
+      options: this._withQueue(options)
     })
   }
 

package/build/background-jobs/main.js

@@ -54,6 +54,7 @@ export default class BackgroundJobsMain {
     this.port = typeof port === "number" ? port : config.port
     this.dispatchStrategy = config.dispatchStrategy
     this.pollIntervalMs = config.pollIntervalMs
+    this.retention = config.retention
     this.store = new BackgroundJobsStore({configuration, databaseIdentifier: config.databaseIdentifier})
     this.logger = new Logger(this)
     /**
@@ -88,6 +89,10 @@ export default class BackgroundJobsMain {
      * Narrows the runtime value to the documented type.
      * @type {ReturnType<typeof setTimeout> | undefined} */
     this._orphanTimer = undefined
+    /**
+     * Narrows the runtime value to the documented type.
+     * @type {ReturnType<typeof setTimeout> | undefined} */
+    this._retentionTimer = undefined
     /**
      * Narrows the runtime value to the documented type.
      * @type {BackgroundJobsScheduler | undefined} */
@@ -139,6 +144,10 @@ export default class BackgroundJobsMain {
         void this._sweepOrphans()
       }, 60000)
 
+      this._retentionTimer = setInterval(() => {
+        void this._sweepRetention()
+      }, this.retention.sweepIntervalMs)
+
       this.scheduler = new BackgroundJobsScheduler({
         configuration: this.configuration,
         enqueueJob: async ({args, jobClass, options}) => {
@@ -197,10 +206,12 @@ export default class BackgroundJobsMain {
     if (this._scheduledTimer) clearTimeout(this._scheduledTimer)
     if (this._errorRetryTimer) clearTimeout(this._errorRetryTimer)
     if (this._orphanTimer) clearInterval(this._orphanTimer)
+    if (this._retentionTimer) clearInterval(this._retentionTimer)
     this._pollTimer = undefined
     this._scheduledTimer = undefined
     this._errorRetryTimer = undefined
     this._orphanTimer = undefined
+    this._retentionTimer = undefined
   }
 
   /**
@@ -1085,4 +1096,24 @@ export default class BackgroundJobsMain {
       this.logger.error(() => ["Failed to mark orphaned jobs:", error])
     }
   }
+
+  /**
+   * Deletes terminal job rows past their retention window so the jobs table
+   * does not grow unbounded. Runs on its own interval; failures are logged and
+   * retried on the next tick.
+   * @returns {Promise<void>} - Resolves after one retention sweep.
+   */
+  async _sweepRetention() {
+    try {
+      const deleted = await this.store.pruneTerminalJobs({
+        completedTtlMs: this.retention.completedTtlMs,
+        failedTtlMs: this.retention.failedTtlMs,
+        batchSize: this.retention.batchSize
+      })
+
+      if (deleted > 0) this.logger.warn(() => ["Pruned terminal background jobs", deleted])
+    } catch (error) {
+      this.logger.error(() => ["Failed to prune terminal jobs:", error])
+    }
+  }
 }

package/build/background-jobs/store.js

@@ -19,6 +19,10 @@ const ORPHANED_AFTER_MS = 2 * 60 * 60 * 1000
  * @type {import("./types.js").BackgroundJobExecutionMode[]} */
 const EXECUTION_MODES = ["inline", "forked", "spawned"]
 const DEFAULT_EXECUTION_MODE = "forked"
+const DEFAULT_QUEUE = "default"
+// Queue-derived durable concurrency keys are namespaced so they can't collide
+// with explicit caller-supplied concurrencyKeys.
+const QUEUE_CONCURRENCY_KEY_PREFIX = "queue:"
 
 /**
  * Columns the dashboard is allowed to sort job listings by, mapped to their
@@ -95,10 +99,17 @@ export default class BackgroundJobsStore {
     const executionMode = this._normalizeExecutionMode(options)
     const maxRetries = this._normalizeMaxRetries(options?.maxRetries)
     const argsJson = JSON.stringify(args || [])
-    const concurrency = this._normalizeConcurrencyOptions(options)
+    const queue = this._normalizeQueue(options)
+    const concurrency = this._resolveConcurrency(options, queue)
 
     await this._withDb(async (db) => {
-      if (concurrency) await this._ensureConcurrencyKey(db, concurrency)
+      if (concurrency) {
+        if (concurrency.queueDerived) {
+          await this._ensureQueueConcurrencyKey(db, concurrency)
+        } else {
+          await this._ensureConcurrencyKey(db, concurrency)
+        }
+      }
       await db.insert({
         tableName: JOBS_TABLE,
         data: {
@@ -107,6 +118,7 @@ export default class BackgroundJobsStore {
           args_json: argsJson,
           forked: executionMode !== "inline",
           execution_mode: executionMode,
+          queue,
           max_retries: maxRetries,
           attempts: 0,
           status: "queued",
@@ -464,11 +476,25 @@ export default class BackgroundJobsStore {
       for (const row of rows) {
         const job = this._normalizeJobRow(row)
 
+        // Fence the reclaim on the exact handoff this sweep selected, using its
+        // `handed_off_at_ms` rather than its `handoff_id`. Two reasons:
+        //   1. Null-safe. Some rows have a null `handoff_id` (handed off by an
+        //      older velocious before handoff-id fencing). `{handoff_id: null}`
+        //      renders as `handoff_id = NULL`, which matches nothing, so those
+        //      rows would be stranded in `handed_off` forever.
+        //   2. Race-safe. If the row is returned to the queue and re-handed-off
+        //      between the SELECT above and this update, it gets a fresh
+        //      `handed_off_at_ms` (always "now"), so this stale cutoff-era
+        //      timestamp no longer matches and we won't fail/orphan — or
+        //      wrongly release the concurrency reservation of — that new lease.
+        // `handed_off_at_ms` is always set on a handed-off row (and the SELECT
+        // required it `<= cutoff`), so it is a reliable null-safe lease pin.
         const orphanedJob = await this._applyFailure({
           db,
           job,
           error: "Job orphaned after timeout",
-          markOrphaned: true
+          markOrphaned: true,
+          conditions: {id: job.id, status: "handed_off", handed_off_at_ms: job.handedOffAtMs}
         })
 
         if (orphanedJob) orphanedCount += 1
@@ -478,6 +504,78 @@ export default class BackgroundJobsStore {
     })
   }
 
+  /**
+   * Deletes terminal job rows past their retention window so the jobs table
+   * does not grow unbounded (completed rows in particular accumulate forever
+   * otherwise). Batched by id — SELECT a page of ids, then
+   * `DELETE ... WHERE id IN (...)` — rather than `DELETE ... LIMIT`, which not
+   * every driver supports; each batch runs on its own connection so the sweep
+   * yields between batches instead of holding one long transaction.
+   * @param {object} [args] - Options.
+   * @param {number | null} [args.completedTtlMs] - Delete `completed` jobs whose `completed_at_ms` is older than this many ms. Falsy or `<= 0` disables completed pruning.
+   * @param {number | null} [args.failedTtlMs] - Delete terminal `failed`/`orphaned` jobs older than this many ms (by `failed_at_ms`/`orphaned_at_ms`). Falsy or `<= 0` disables.
+   * @param {number} [args.batchSize] - Max rows deleted per batch. Default `1000`.
+   * @returns {Promise<number>} - Total rows deleted.
+   */
+  async pruneTerminalJobs({completedTtlMs = null, failedTtlMs = null, batchSize = 1000} = {}) {
+    await this.ensureReady()
+
+    const now = Date.now()
+    const size = batchSize > 0 ? batchSize : 1000
+    let deleted = 0
+
+    if (completedTtlMs && completedTtlMs > 0) {
+      deleted += await this._pruneStatusBatches({status: "completed", column: "completed_at_ms", cutoff: now - completedTtlMs, batchSize: size})
+    }
+
+    if (failedTtlMs && failedTtlMs > 0) {
+      deleted += await this._pruneStatusBatches({status: "failed", column: "failed_at_ms", cutoff: now - failedTtlMs, batchSize: size})
+      deleted += await this._pruneStatusBatches({status: "orphaned", column: "orphaned_at_ms", cutoff: now - failedTtlMs, batchSize: size})
+    }
+
+    return deleted
+  }
+
+  /**
+   * Deletes rows of one terminal status older than a cutoff, batch by batch,
+   * until a page returns fewer than `batchSize` rows.
+   * @param {object} args - Options.
+   * @param {string} args.status - Terminal status to prune.
+   * @param {string} args.column - Timestamp column compared against the cutoff.
+   * @param {number} args.cutoff - Delete rows whose column value is `<= cutoff`.
+   * @param {number} args.batchSize - Max rows per batch.
+   * @returns {Promise<number>} - Rows deleted for this status.
+   */
+  async _pruneStatusBatches({status, column, cutoff, batchSize}) {
+    let deleted = 0
+
+    for (;;) {
+      const removed = await this._withDb(async (db) => {
+        const rows = await db
+          .newQuery()
+          .from(JOBS_TABLE)
+          .select("id")
+          .where({status})
+          .where(`${db.quoteColumn(column)} <= ${db.quote(cutoff)}`)
+          .limit(batchSize)
+          .results()
+
+        if (rows.length === 0) return 0
+
+        const ids = rows.map((/** @type {Record<string, ?>} */ row) => db.quote(String(row.id))).join(", ")
+
+        await db.query(`DELETE FROM ${db.quoteTable(JOBS_TABLE)} WHERE ${db.quoteColumn("id")} IN (${ids})`)
+
+        return rows.length
+      })
+
+      deleted += removed
+      if (removed < batchSize) break
+    }
+
+    return deleted
+  }
+
   /**
    * Runs clear all.
    * @returns {Promise<void>} - Resolves when cleared.
@@ -621,6 +719,7 @@ export default class BackgroundJobsStore {
     table.text("args_json", {null: false})
     table.boolean("forked", {null: false})
     table.string("execution_mode", {null: false})
+    table.string("queue", {null: true, index: true})
     table.integer("max_retries", {null: false})
     table.integer("attempts", {null: false})
     table.string("status", {null: false, index: true})
@@ -723,6 +822,43 @@ export default class BackgroundJobsStore {
     } finally {
       await db.releaseAdvisoryLock(lockName)
     }
+
+    await this._ensureQueueColumn(db)
+  }
+
+  /**
+   * Idempotently adds the `queue` column to an existing jobs table. Existing
+   * rows read back as the default queue (see {@link _normalizeJobRow}), so no
+   * data backfill is required.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} - Resolves when ensured.
+   */
+  async _ensureQueueColumn(db) {
+    const table = await db.getTableByNameOrFail(JOBS_TABLE)
+
+    if (await table.getColumnByName("queue")) return
+
+    const lockName = `${MIGRATION_SCOPE}:queue_column`
+    const acquired = await db.acquireAdvisoryLock(lockName)
+
+    if (!acquired) throw new Error("Failed to acquire background jobs queue schema lock")
+
+    try {
+      db.clearSchemaCache()
+      const lockedTable = await db.getTableByNameOrFail(JOBS_TABLE)
+
+      if (!(await lockedTable.getColumnByName("queue"))) {
+        const tableData = new TableData(JOBS_TABLE)
+
+        tableData.string("queue", {null: true, index: true})
+
+        for (const sql of await db.alterTableSQLs(tableData)) await db.query(sql)
+
+        db.clearSchemaCache()
+      }
+    } finally {
+      await db.releaseAdvisoryLock(lockName)
+    }
   }
 
   /**
@@ -819,9 +955,10 @@ export default class BackgroundJobsStore {
    * @param {import("./types.js").BackgroundJobRow} args.job - Job row.
    * @param {?} args.error - Error.
    * @param {boolean} args.markOrphaned - Whether marking orphaned.
+   * @param {Record<string, ?>} [args.conditions] - Update fencing conditions. Defaults to the active-handoff lease match; the time-based orphan sweep overrides this with an id/status match so it can reclaim rows whose `handoff_id` is null (e.g. handed off by an older velocious before handoff-id fencing existed).
    * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Updated job row when the lease transition won.
    */
-  async _applyFailure({db, job, error, markOrphaned}) {
+  async _applyFailure({db, job, error, markOrphaned, conditions}) {
     const now = Date.now()
     const nextAttempt = (job.attempts || 0) + 1
     const maxRetries = this._normalizeMaxRetries(job.maxRetries)
@@ -840,7 +977,7 @@ export default class BackgroundJobsStore {
     const affectedRows = await this._updateAffectedRows(db, {
       tableName: JOBS_TABLE,
       data: update,
-      conditions: this._activeHandoffConditions(job)
+      conditions: conditions ?? this._activeHandoffConditions(job)
     })
 
     if (affectedRows !== 1) return null
@@ -934,6 +1071,7 @@ export default class BackgroundJobsStore {
       args: this._parseArgs(row.args_json),
       executionMode,
       forked: executionMode !== "inline",
+      queue: row.queue ? String(row.queue) : DEFAULT_QUEUE,
       status: row.status ? String(row.status) : "queued",
       attempts: this._normalizeNumber(row.attempts),
       maxRetries: this._normalizeNumber(row.max_retries),
@@ -966,6 +1104,89 @@ export default class BackgroundJobsStore {
     return {concurrencyKey: key, maxConcurrency: Number(cap)}
   }
 
+  /**
+   * Normalizes a job's queue name, defaulting to "default".
+   * @param {import("./types.js").BackgroundJobOptions | undefined} options - Job options.
+   * @returns {string} - Queue name.
+   */
+  _normalizeQueue(options) {
+    const queue = options?.queue
+
+    if (typeof queue === "string" && queue.trim().length > 0) return queue.trim()
+
+    return DEFAULT_QUEUE
+  }
+
+  /**
+   * Resolves a job's durable concurrency. An explicit concurrencyKey/maxConcurrency
+   * pair always wins. Otherwise, when the job's queue has a configured cap
+   * (`backgroundJobs.queues[queue].maxConcurrent`), derive a queue-scoped
+   * concurrency key so the queue cap is enforced cluster-wide through the
+   * existing durable concurrency mechanism.
+   * @param {import("./types.js").BackgroundJobOptions | undefined} options - Job options.
+   * @param {string} queue - Normalized queue name.
+   * @returns {{concurrencyKey: string, maxConcurrency: number, queueDerived: boolean} | null} - Resolved concurrency.
+   */
+  _resolveConcurrency(options, queue) {
+    const explicit = this._normalizeConcurrencyOptions(options)
+
+    if (explicit) return {...explicit, queueDerived: false}
+
+    const cap = this._queueMaxConcurrency(queue)
+
+    if (cap === null) return null
+
+    return {concurrencyKey: `${QUEUE_CONCURRENCY_KEY_PREFIX}${queue}`, maxConcurrency: cap, queueDerived: true}
+  }
+
+  /**
+   * Reads the configured max concurrency for a queue from the background-jobs config.
+   * @param {string} queue - Queue name.
+   * @returns {number | null} - Positive integer cap, or null when the queue has no configured cap.
+   */
+  _queueMaxConcurrency(queue) {
+    const queues = this.configuration.getBackgroundJobsConfig().queues
+    const cap = queues?.[queue]?.maxConcurrent
+
+    if (Number.isInteger(cap) && Number(cap) > 0) return Number(cap)
+
+    return null
+  }
+
+  /**
+   * Like {@link _ensureConcurrencyKey}, but for queue-derived keys the configured
+   * queue cap is the source of truth: if it changed, update the stored cap
+   * instead of throwing on conflict (config-driven caps must be tunable).
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {{concurrencyKey: string, maxConcurrency: number}} concurrency - Concurrency configuration.
+   * @returns {Promise<void>} - Resolves when ensured.
+   */
+  async _ensureQueueConcurrencyKey(db, {concurrencyKey, maxConcurrency}) {
+    const rows = await db.newQuery().from(CONCURRENCY_TABLE).where({concurrency_key: concurrencyKey}).limit(1).results()
+
+    if (!rows[0]) {
+      try {
+        await db.insert({tableName: CONCURRENCY_TABLE, data: {active_count: 0, concurrency_key: concurrencyKey, max_concurrency: maxConcurrency}})
+
+        return
+      } catch (error) {
+        const racedRows = await db.newQuery().from(CONCURRENCY_TABLE).where({concurrency_key: concurrencyKey}).limit(1).results()
+
+        if (!racedRows[0]) throw error
+
+        rows[0] = racedRows[0]
+      }
+    }
+
+    const configured = /** @type {{max_concurrency?: number | string}} */ (rows[0])
+
+    if (this._normalizeNumber(configured.max_concurrency) !== maxConcurrency) {
+      const table = db.quoteTable(CONCURRENCY_TABLE)
+
+      await db.query(`UPDATE ${table} SET ${db.quoteColumn("max_concurrency")} = ${Number(maxConcurrency)} WHERE ${db.quoteColumn("concurrency_key")} = ${db.quote(concurrencyKey)}`)
+    }
+  }
+
   /**
    * Ensures the concurrency state table exists.
    * @param {import("../database/drivers/base.js").default} db - Database connection.

package/build/background-jobs/types.js

@@ -13,7 +13,8 @@
  * @property {BackgroundJobExecutionMode} [executionMode] - How the job should run. Defaults to `"forked"`.
  * @property {boolean} [forked] - Compatibility alias: `false` maps to `"inline"` and `true` maps to `"forked"`.
  * @property {number} [maxRetries] - Max retries for a failed job before it is marked failed.
- * @property {string} [concurrencyKey] - Opaque non-empty key used to share a concurrency cap.
+ * @property {string} [queue] - Queue name. Defaults to `"default"`. When the queue has a configured cap in `backgroundJobs.queues`, that cap is enforced cluster-wide.
+ * @property {string} [concurrencyKey] - Opaque non-empty key used to share a concurrency cap. Overrides any queue-derived cap.
  * @property {number} [maxConcurrency] - Positive integer cap; must be paired with `concurrencyKey`.
  */
 /**
@@ -33,6 +34,7 @@
  * @property {Array<?>} args - Serialized job arguments.
  * @property {BackgroundJobExecutionMode} executionMode - How the job should run.
  * @property {boolean} forked - Compatibility flag; true for non-inline execution.
+ * @property {string} queue - Queue name (defaults to `"default"`).
  * @property {string} status - Current job status.
  * @property {number | null} attempts - Failure attempts count.
  * @property {number | null} maxRetries - Max retry attempts.

package/build/configuration-types.js

@@ -161,12 +161,41 @@
  *   long-running jobs and for using more cores. Default: `4`.
  * @property {number} [maxConcurrentForkedJobs] - How many out-of-process
  *   `"forked"` or `"spawned"` jobs a single `background-jobs-worker` is
- *   allowed to keep in flight. Default: `4`.
+ *   allowed to keep in flight. Default: `4`. This is a per-worker safety cap;
+ *   for workload-shaped limits use per-queue caps (`queues`) instead, which are
+ *   enforced cluster-wide and are immune to duplicate worker processes.
+ * @property {Record<string, {maxConcurrent?: number}>} [queues] - Per-queue
+ *   concurrency caps, Sidekiq-style. A job declares its queue (static `queue` on
+ *   the job class, or the `queue` enqueue option; defaults to `"default"`), and
+ *   `queues[name].maxConcurrent` bounds how many jobs from that queue may be
+ *   in flight across the whole cluster (enforced via durable per-key
+ *   concurrency, so it holds regardless of how many worker processes run).
+ *   Size each queue to its workload: I/O-bound queues (e.g. build runners
+ *   waiting on remote Docker servers) can run far above the core count, while
+ *   CPU-bound queues should stay near it. Default: `{}` (no queue caps).
  * @property {BackgroundJobsDispatchStrategy} [dispatchStrategy] - How the main process
  *   detects new work. Defaults to `"beacon"` (event-driven). Set to `"polling"`
  *   to restore the legacy fixed-interval poll.
  * @property {number} [pollIntervalMs] - Poll interval in milliseconds. Only used
  *   when `dispatchStrategy === "polling"`. Default: `1000`.
+ * @property {BackgroundJobsRetentionConfiguration} [retention] - Retention/pruning
+ *   of terminal job rows. Without pruning the jobs table grows unbounded
+ *   (completed rows accumulate forever), which bloats storage and indexes and
+ *   eventually slows dispatch. The main process sweeps terminal rows past their
+ *   window on an interval.
+ */
+
+/**
+ * @typedef {object} BackgroundJobsRetentionConfiguration
+ * @property {number | null} [completedTtlMs] - Delete `completed` jobs whose
+ *   `completed_at_ms` is older than this many ms. `null` or `<= 0` disables
+ *   completed pruning. Default: `604800000` (7 days).
+ * @property {number | null} [failedTtlMs] - Delete terminal `failed`/`orphaned`
+ *   jobs older than this many ms. `null` or `<= 0` disables (keeps them for
+ *   debugging). Default: `2592000000` (30 days).
+ * @property {number} [batchSize] - Rows deleted per batch. Default: `1000`.
+ * @property {number} [sweepIntervalMs] - How often the main process runs the
+ *   retention sweep. Default: `3600000` (1 hour).
  */
 
 /**

package/build/configuration.js

@@ -1291,8 +1291,24 @@ export default class VelociousConfiguration {
     const pollIntervalMs = typeof configured.pollIntervalMs === "number" && configured.pollIntervalMs >= 1
       ? configured.pollIntervalMs
       : (typeof envPollInterval === "number" && Number.isFinite(envPollInterval) && envPollInterval >= 1 ? envPollInterval : 1000)
-
-    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, dispatchStrategy, pollIntervalMs}
+    const queues = configured.queues && typeof configured.queues === "object" ? configured.queues : {}
+    const configuredRetention = configured.retention && typeof configured.retention === "object" ? configured.retention : {}
+    const retention = {
+      completedTtlMs: typeof configuredRetention.completedTtlMs === "number" || configuredRetention.completedTtlMs === null
+        ? configuredRetention.completedTtlMs
+        : 7 * 24 * 60 * 60 * 1000,
+      failedTtlMs: typeof configuredRetention.failedTtlMs === "number" || configuredRetention.failedTtlMs === null
+        ? configuredRetention.failedTtlMs
+        : 30 * 24 * 60 * 60 * 1000,
+      batchSize: typeof configuredRetention.batchSize === "number" && configuredRetention.batchSize > 0
+        ? configuredRetention.batchSize
+        : 1000,
+      sweepIntervalMs: typeof configuredRetention.sweepIntervalMs === "number" && configuredRetention.sweepIntervalMs > 0
+        ? configuredRetention.sweepIntervalMs
+        : 60 * 60 * 1000
+    }
+
+    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, dispatchStrategy, pollIntervalMs, queues, retention}
   }
 
   /**

package/build/database/record/attachments/handle.js

@@ -217,4 +217,22 @@ export default class RecordAttachmentHandle {
 
     return await store.attachmentRowUrl({model: this.model, name: this.name, row})
   }
+
+  /**
+   * Purges every attachment under this (record, name): deletes the backing
+   * storage for each and removes the attachment rows. A no-op for unpersisted
+   * records. Only the attachments present when the purge starts are removed, so a
+   * concurrent attach for the same (record, name) is left intact. Throws (without
+   * deleting any rows) if a storage driver cannot delete its object, so a driver
+   * configured without a `delete` operation can never leak storage. Callers use
+   * this to clean up attachments before destroying the owner record.
+   * @returns {Promise<number>} - Number of attachments purged.
+   */
+  async purgeAll() {
+    if (!this.model.isPersisted()) return 0
+
+    const store = recordAttachmentsStoreForModel(this.model)
+
+    return await store.purgeAll({model: this.model, name: this.name})
+  }
 }

package/build/database/record/attachments/store.js

@@ -391,6 +391,51 @@ export default class RecordAttachmentsStore {
     })
   }
 
+  /**
+   * Purges every attachment stored under (model, name): deletes each row's
+   * backing storage and then removes the attachment rows. Used to clean up an
+   * owner record's attachments before/when the owner is destroyed.
+   * @param {object} args - Options.
+   * @param {import("../index.js").default} args.model - Model instance.
+   * @param {string} args.name - Attachment name.
+   * @returns {Promise<number>} - Number of attachments purged.
+   */
+  async purgeAll({model, name}) {
+    await this.ensureReady()
+
+    return await this._withDb(async (db) => {
+      const recordType = model.getModelClass().getModelName()
+      const recordId = String(model.id())
+      /** @type {Array<Record<string, ?>>} */
+      const rows = await db
+        .newQuery()
+        .from(ATTACHMENTS_TABLE)
+        .where({name, record_id: recordId, record_type: recordType})
+        .results()
+
+      // Refuse to purge when any row's driver cannot delete its backing storage:
+      // removing the row while the object stays behind would leak storage and
+      // discard the metadata needed to retry cleanup. Fail loudly instead.
+      for (const row of rows) {
+        const attachmentDriver = await this.resolveAttachmentDriver({model, name, row})
+
+        if (typeof attachmentDriver.delete !== "function") {
+          throw new Error(`Cannot purge attachment ${row.id} for ${recordType}#${recordId} (${name}): its storage driver does not support deletion.`)
+        }
+      }
+
+      for (const row of rows) {
+        await this.deleteAttachmentRowStorage({model, name, row})
+        // Delete only the snapshotted row by id, so an attachment inserted for the
+        // same (record, name) after the snapshot is not removed with its storage
+        // still present (which would leave it as unreachable storage).
+        await db.delete({conditions: {id: row.id}, tableName: ATTACHMENTS_TABLE})
+      }
+
+      return rows.length
+    })
+  }
+
   /**
    * Runs attachment driver by name.
    * @param {string} driverName - Driver name.

package/build/http-server/client/index.js

@@ -400,7 +400,7 @@ export default class VeoliciousHttpServerClient {
         const stats = await fs.stat(filePath)
         contentLength = stats.size
       } else {
-        contentLength = bodyIsString ? new TextEncoder().encode(body).length : body.byteLength
+        contentLength = bodyIsString ? Buffer.byteLength(body, "utf8") : body.byteLength
       }
 
       response.setHeader("Content-Length", contentLength)