velocious 1.0.598 → 1.0.600

package/build/background-jobs/platform-job.js

@@ -0,0 +1,156 @@
+// @ts-check
+
+import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
+import {cancelScheduledBackgroundJob, enqueueBackgroundJob, replaceScheduledBackgroundJob} from "./runtime.js"
+
+/**
+ * Base class for background jobs.
+ *
+ * `TArgs` is the tuple of arguments the subclass's `perform` accepts, so a job that
+ * needs arguments declares them as required and typed — for example
+ * `class RunBuildJob extends VelociousJob<[string]>` with `async perform(buildId)`.
+ * The default empty tuple keeps argument-less jobs (`extends VelociousJob`,
+ * `async perform()`) working unchanged.
+ * @template {Array<ReturnType<typeof JSON.parse>>} [TArgs=[]]
+ */
+export default class VelociousJob {
+  /**
+   * Database identifiers checked out while this job performs. Set an explicit
+   * list to avoid holding unrelated configured database connections, or `[]`
+   * when the job establishes any connections it needs itself. Left undefined,
+   * jobs retain the existing behavior of checking out every active database.
+   * @type {string[] | undefined}
+   */
+  static databaseIdentifiers = undefined
+
+  /**
+   * 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
+
+  /**
+   * Optional process title shown for the runner while this job executes.
+   * Velocious sets `process.title` to this for the duration of the job — so
+   * `ps`/`top`/`htop` identify what a runner is doing — and restores the
+   * runner's base title when the job finishes. Left undefined, the runner falls
+   * back to `velocious job-runner: <JobName>`. Set e.g.
+   * `static processTitle = "velocious media transcoder"` to give a job a
+   * custom, human-readable title.
+   * @type {string | undefined}
+   */
+  static processTitle = undefined
+
+  /**
+   * Stops this performance and reschedules the same logical job row. This is
+   * normal control flow: it does not count as a failure or consume a retry.
+   * @param {number} delayMs - Non-negative safe-integer delay in milliseconds.
+   * @returns {never} - This method never returns.
+   */
+  rescheduleIn(delayMs) {
+    if (!Number.isSafeInteger(delayMs) || delayMs < 0) {
+      throw new TypeError("background job reschedule delayMs must be a non-negative safe integer")
+    }
+
+    throw new BackgroundJobRescheduleSignal(delayMs)
+  }
+
+  /**
+   * Runs job name.
+   * @returns {string} - Job name.
+   */
+  static jobName() {
+    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 {...ReturnType<typeof JSON.parse>} args - Job args.
+   * @returns {Promise<string>} - Job id.
+   */
+  static async performLater(...args) {
+    const {jobArgs, jobOptions} = this._splitArgsAndOptions(args)
+    return await enqueueBackgroundJob({JobClass: this, jobArgs, jobOptions})
+  }
+
+  /**
+   * Runs perform later with options.
+   * @param {object} args - Options.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
+   * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
+   * @returns {Promise<string>} - Job id.
+   */
+  static async performLaterWithOptions({args, options}) {
+    return await enqueueBackgroundJob({JobClass: this, jobArgs: args, jobOptions: options})
+  }
+
+  /**
+   * Atomically replaces this job class's queued owner for a stable schedule key.
+   * @param {object} args - Options.
+   * @param {string} args.scheduleKey - Stable logical schedule key.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
+   * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
+   * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+   */
+  static async replaceScheduled({scheduleKey, args, options}) {
+    return await replaceScheduledBackgroundJob({JobClass: this, scheduleKey, jobArgs: args, jobOptions: options})
+  }
+
+  /**
+   * Cancels or detaches the current owner of a stable schedule key.
+   * @param {string} scheduleKey - Stable logical schedule key.
+   * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
+   */
+  static async cancelScheduled(scheduleKey) {
+    return await cancelScheduledBackgroundJob(scheduleKey)
+  }
+
+  /**
+   * Runs split args and options.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Job args.
+   * @returns {{jobArgs: Array<ReturnType<typeof JSON.parse>>, jobOptions: import("./types.js").BackgroundJobOptions}} - Split args and options.
+   */
+  static _splitArgsAndOptions(args) {
+    if (args.length === 0) {
+      return {jobArgs: [], jobOptions: {}}
+    }
+
+    const lastArg = args[args.length - 1]
+    const isOptionsArg = lastArg && typeof lastArg === "object" && !Array.isArray(lastArg) && "jobOptions" in lastArg
+
+    if (isOptionsArg) {
+      const {jobOptions} = /** @type {{jobOptions: import("./types.js").BackgroundJobOptions}} */ (lastArg)
+      return {jobArgs: args.slice(0, -1), jobOptions: jobOptions || {}}
+    }
+
+    return {jobArgs: args, jobOptions: {}}
+  }
+
+  /**
+   * Override in subclasses.
+   * @param {TArgs} _args - Job args (the tuple this job class was parameterized with).
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async perform(..._args) {
+    throw new Error("perform not implemented")
+  }
+}

package/build/background-jobs/runtime.js

@@ -0,0 +1,156 @@
+// @ts-check
+
+import {currentConfiguration} from "../current-configuration.js"
+import performBackgroundJob from "./perform-job.js"
+import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
+
+let inlinePerformanceSequence = 0
+
+/**
+ * Rejects options whose semantics require durable queue state.
+ * @param {import("./types.js").BackgroundJobOptions | undefined} options - Requested options.
+ * @returns {void}
+ */
+function validateInlineOptions(options) {
+  const optionNames = Object.keys(options || {})
+
+  if (optionNames.length > 0) {
+    throw new Error(`Background job option ${optionNames[0]} is not supported in inline mode`)
+  }
+}
+
+/**
+ * Builds an ephemeral inline performance id.
+ * @returns {string} - Performance id.
+ */
+function inlineJobId() {
+  inlinePerformanceSequence++
+  return `inline-${Date.now()}-${inlinePerformanceSequence}`
+}
+
+/**
+ * Enqueues durably in background mode or performs immediately in inline mode.
+ * @param {object} args - Enqueue request.
+ * @param {typeof import("./platform-job.js").default} args.JobClass - Job class.
+ * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+ * @param {import("./types.js").BackgroundJobOptions | undefined} args.jobOptions - Job options.
+ * @returns {Promise<string>} - Durable job id or ephemeral inline performance id.
+ */
+export async function enqueueBackgroundJob({JobClass, jobArgs, jobOptions}) {
+  const configuration = currentConfiguration()
+
+  return await enqueueBackgroundJobForConfiguration({configuration, JobClass, jobArgs, jobOptions})
+}
+
+/**
+ * Enqueues using an explicitly resolved configuration.
+ * @param {object} args - Enqueue request.
+ * @param {import("../configuration.js").default} args.configuration - Configuration.
+ * @param {typeof import("./platform-job.js").default} args.JobClass - Job class.
+ * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+ * @param {import("./types.js").BackgroundJobOptions | undefined} args.jobOptions - Job options.
+ * @returns {Promise<string>} - Durable job id or ephemeral inline performance id.
+ */
+export async function enqueueBackgroundJobForConfiguration({configuration, JobClass, jobArgs, jobOptions}) {
+
+  if (configuration.getBackgroundJobsConfig().mode === "inline") {
+    validateInlineOptions(jobOptions)
+    configuration.setCurrent()
+    await configuration.initialize({type: "background-jobs-inline"})
+
+    try {
+      await performBackgroundJob({
+        configuration,
+        JobClass,
+        jobArgs,
+        name: `Background job inline mode: ${JobClass.jobName()}`
+      })
+    } catch (error) {
+      if (error instanceof BackgroundJobRescheduleSignal) {
+        throw new Error("rescheduleIn is not supported in inline mode", {cause: error})
+      }
+
+      throw error
+    }
+
+    return inlineJobId()
+  }
+
+  const client = configuration.getEnvironmentHandler().backgroundJobsClient({configuration})
+
+  return await client.enqueue({
+    jobName: JobClass.jobName(),
+    args: jobArgs,
+    options: JobClass._withQueue(jobOptions)
+  })
+}
+
+/**
+ * Replaces a stable durable schedule in background mode.
+ * @param {object} args - Replacement request.
+ * @param {typeof import("./platform-job.js").default} args.JobClass - Job class.
+ * @param {string} args.scheduleKey - Stable schedule key.
+ * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+ * @param {import("./types.js").BackgroundJobOptions | undefined} args.jobOptions - Job options.
+ * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+ */
+export async function replaceScheduledBackgroundJob({JobClass, scheduleKey, jobArgs, jobOptions}) {
+  const configuration = currentConfiguration()
+
+  return await replaceScheduledBackgroundJobForConfiguration({configuration, JobClass, scheduleKey, jobArgs, jobOptions})
+}
+
+/**
+ * Replaces a stable schedule using an explicitly resolved configuration.
+ * @param {object} args - Replacement request.
+ * @param {import("../configuration.js").default} args.configuration - Configuration.
+ * @param {typeof import("./platform-job.js").default} args.JobClass - Job class.
+ * @param {string} args.scheduleKey - Stable schedule key.
+ * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+ * @param {import("./types.js").BackgroundJobOptions | undefined} args.jobOptions - Job options.
+ * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+ */
+export async function replaceScheduledBackgroundJobForConfiguration({configuration, JobClass, scheduleKey, jobArgs, jobOptions}) {
+
+  if (configuration.getBackgroundJobsConfig().mode === "inline") {
+    throw new Error("replaceScheduled is not supported in inline mode")
+  }
+
+  const client = configuration.getEnvironmentHandler().backgroundJobsClient({configuration})
+
+  return await client.replaceScheduled({
+    scheduleKey,
+    jobName: JobClass.jobName(),
+    args: jobArgs,
+    options: JobClass._withQueue(jobOptions)
+  })
+}
+
+/**
+ * Cancels a stable durable schedule in background mode.
+ * @param {string} scheduleKey - Stable schedule key.
+ * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
+ */
+export async function cancelScheduledBackgroundJob(scheduleKey) {
+  const configuration = currentConfiguration()
+
+  return await cancelScheduledBackgroundJobForConfiguration({configuration, scheduleKey})
+}
+
+/**
+ * Cancels a stable schedule using an explicitly resolved configuration.
+ * @param {object} args - Cancellation request.
+ * @param {import("../configuration.js").default} args.configuration - Configuration.
+ * @param {string} args.scheduleKey - Stable logical schedule key.
+ * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
+ */
+export async function cancelScheduledBackgroundJobForConfiguration({configuration, scheduleKey}) {
+
+  if (configuration.getBackgroundJobsConfig().mode === "inline") {
+    throw new Error("cancelScheduled is not supported in inline mode")
+  }
+
+  const client = configuration.getEnvironmentHandler().backgroundJobsClient({configuration})
+
+  return await client.cancelScheduled({scheduleKey})
+}

package/build/background-jobs/sql-adapter.js

@@ -0,0 +1,20 @@
+// @ts-check
+
+import BackgroundJobsStore from "./store.js"
+
+/** Built-in SQL adapter preserving the existing durable store implementation. */
+export default class SqlBackgroundJobsAdapter extends BackgroundJobsStore {
+  /**
+   * Ensures the built-in SQL schema during migration.
+   * @param {{dbs: Record<string, import("../database/drivers/base.js").default>}} args - Migrated databases.
+   * @returns {Promise<void>} - Resolves when the SQL schema is present.
+   */
+  async ensureFrameworkSchema({dbs}) {
+    const databaseIdentifier = this.getDatabaseIdentifier() || "default"
+    const frameworkDb = dbs[databaseIdentifier]
+
+    if (!frameworkDb) return
+
+    await this.ensureSchema(frameworkDb)
+  }
+}

package/build/background-jobs/store.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import {createHash, randomUUID} from "crypto"
+import BackgroundJobsAdapter from "./adapter.js"
 import Logger from "../logger.js"
 import TableData from "../database/table-data/index.js"
 import VelociousError from "../velocious-error.js"
@@ -100,7 +101,7 @@ const schemaApplyChains = new Map()
 /** @type {Map<string, Promise<void>>} */
 const transactionMutationChains = new Map()
 
-export default class BackgroundJobsStore {
+export default class BackgroundJobsStore extends BackgroundJobsAdapter {
   /**
    * Runs constructor.
    * @param {object} args - Options.
@@ -108,6 +109,7 @@ export default class BackgroundJobsStore {
    * @param {string} [args.databaseIdentifier] - Database identifier.
    */
   constructor({configuration, databaseIdentifier}) {
+    super()
     this.configuration = configuration
     this.databaseIdentifier = databaseIdentifier
     this.logger = new Logger(this)

package/build/background-jobs/types.js

@@ -3,6 +3,16 @@
 /**
  * @typedef {"inline" | "forked" | "pooled" | "spawned"} BackgroundJobExecutionMode
  */
+/**
+ * @typedef {object} BackgroundJobsHealth
+ * @property {boolean} ready - Whether the adapter can accept and process work.
+ */
+/**
+ * @typedef {object} BackgroundJobsProducer
+ * @property {(args: {jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: BackgroundJobOptions}) => Promise<string>} enqueue - Enqueues a job.
+ * @property {(args: {scheduleKey: string, jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: BackgroundJobOptions}) => Promise<BackgroundJobReplacementResult>} replaceScheduled - Replaces a stable schedule.
+ * @property {(args: {scheduleKey: string}) => Promise<BackgroundJobCancellationResult>} cancelScheduled - Cancels a stable schedule.
+ */
 /**
  * @typedef {object} BackgroundJobHandoff
  * @property {string} handoffId - Unique handoff lease id.

package/build/background-jobs/web/controller.js

@@ -99,11 +99,14 @@ export default class VelociousBackgroundJobsWebController extends Controller {
    */
   async health() {
     await this._respond(async () => {
+      const health = await this.getConfiguration().backgroundJobsHealth()
+
       await this.render({json: {
         capabilities: {backgroundJobCountDeltas: 1},
-        ok: true,
+        ok: health.ready,
+        ready: health.ready,
         service: "velocious-background-jobs"
-      }})
+      }, status: health.ready ? 200 : 503})
     })
   }
 

package/build/background-jobs/worker.js

@@ -10,6 +10,7 @@ import {randomUUID} from "crypto"
 import {fileURLToPath} from "node:url"
 import shutdownLifecycle from "../utils/shutdown-lifecycle.js"
 import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
+import performBackgroundJob from "./perform-job.js"
 
 /**
  * Per-forked-child timeout bookkeeping.
@@ -958,14 +959,11 @@ export default class BackgroundJobsWorker {
     const registry = new BackgroundJobRegistry({configuration})
     await registry.load()
     const JobClass = registry.getJobByName(payload.jobName)
-    const jobInstance = new JobClass()
-    /**
-     * Perform.
-     * @type {(...args: Array<ReturnType<typeof JSON.parse>>) => Promise<void>} */
-    const perform = jobInstance.perform
-
-    await configuration.withConnections({databaseIdentifiers: JobClass.databaseIdentifiers, name: `Background job worker inline: ${payload.jobName}`}, async () => {
-      await perform.apply(jobInstance, payload.args || [])
+    await performBackgroundJob({
+      configuration,
+      JobClass,
+      jobArgs: payload.args || [],
+      name: `Background job worker inline: ${payload.jobName}`
     })
   }
 

package/build/configuration-types.js

@@ -156,8 +156,13 @@
  *   `background_jobs` table (see `pollIntervalMs`).
  */
 
+/** @typedef {"background" | "inline"} BackgroundJobsMode */
+/** @typedef {(args: {configuration: import("./configuration.js").default}) => import("./background-jobs/adapter.js").default} BackgroundJobsAdapterFactory */
+
 /**
  * @typedef {object} BackgroundJobsConfiguration
+ * @property {import("./background-jobs/adapter.js").default | BackgroundJobsAdapterFactory} [adapter] - Adapter instance or synchronous factory. A factory creates one adapter per configuration lifecycle; the framework closes adapters it resolves.
+ * @property {BackgroundJobsMode} [mode] - `"background"` uses the configured adapter/transport and durable queue semantics; `"inline"` performs immediately without durable queue state. Defaults to `"background"`.
  * @property {string} [host] - Hostname for the background jobs main process.
  * @property {number} [port] - Port for the background jobs main process.
  * @property {string} [databaseIdentifier] - Database identifier used to store background jobs.