velocious 1.0.605 → 1.0.607

package/src/background-jobs/job-semantics.js

@@ -0,0 +1,145 @@
+// @ts-check
+
+import VelociousError from "../velocious-error.js"
+
+export const DEFAULT_BACKGROUND_JOB_EXECUTION_MODE = "pooled"
+export const DEFAULT_BACKGROUND_JOB_MAX_RETRIES = 10
+export const DEFAULT_BACKGROUND_JOB_QUEUE = "default"
+export const QUEUE_CONCURRENCY_KEY_PREFIX = "queue:"
+/** @type {import("./types.js").BackgroundJobExecutionMode[]} */
+export const BACKGROUND_JOB_EXECUTION_MODES = ["inline", "forked", "pooled", "spawned"]
+
+/**
+ * Normalizes a job queue.
+ * @param {import("./types.js").BackgroundJobOptions} [options] - Job options.
+ * @returns {string} - Queue name.
+ */
+export function normalizeBackgroundJobQueue(options) {
+  const queue = options?.queue
+
+  if (typeof queue === "string" && queue.trim().length > 0) return queue.trim()
+
+  return DEFAULT_BACKGROUND_JOB_QUEUE
+}
+
+/**
+ * Normalizes an explicit execution mode while retaining the Node default.
+ * @param {Omit<import("./types.js").BackgroundJobOptions, "executionMode"> & {executionMode?: string}} options - Job options.
+ * @param {import("./types.js").BackgroundJobExecutionMode} [defaultExecutionMode] - Default mode.
+ * @param {import("./types.js").BackgroundJobExecutionMode[]} [supportedExecutionModes] - Modes accepted by the caller.
+ * @returns {import("./types.js").BackgroundJobExecutionMode} - Execution mode.
+ */
+export function normalizeBackgroundJobExecutionMode(options = {}, defaultExecutionMode = DEFAULT_BACKGROUND_JOB_EXECUTION_MODE, supportedExecutionModes = BACKGROUND_JOB_EXECUTION_MODES) {
+  if ("forked" in options) {
+    throw new Error("The background job `forked` option was removed; pass `executionMode` (\"inline\", \"forked\", \"pooled\", or \"spawned\") instead")
+  }
+
+  const requestedExecutionMode = options.executionMode || defaultExecutionMode
+  /** @type {import("./types.js").BackgroundJobExecutionMode | undefined} */
+  let executionMode
+
+  for (const candidate of BACKGROUND_JOB_EXECUTION_MODES) {
+    if (candidate === requestedExecutionMode) executionMode = candidate
+  }
+
+  if (!executionMode) throw new Error(`Invalid background job executionMode: ${requestedExecutionMode}`)
+
+  if (!supportedExecutionModes.includes(executionMode)) {
+    throw new Error(`Background job executionMode "${executionMode}" is not supported by the local background-jobs adapter`)
+  }
+
+  return executionMode
+}
+
+/**
+ * Validates and normalizes a retry cap.
+ * @param {number | null | undefined} maxRetries - Requested retry cap.
+ * @returns {number} - Retry cap.
+ */
+export function normalizeBackgroundJobMaxRetries(maxRetries) {
+  if (typeof maxRetries === "number" && Number.isFinite(maxRetries) && maxRetries >= 0) {
+    return Math.floor(maxRetries)
+  }
+
+  return DEFAULT_BACKGROUND_JOB_MAX_RETRIES
+}
+
+/**
+ * Validates an enqueue eligibility timestamp.
+ * @param {number | undefined} scheduledAtMs - Requested timestamp.
+ * @param {number} defaultScheduledAtMs - Default timestamp.
+ * @returns {number} - Eligibility timestamp.
+ */
+export function normalizeBackgroundJobScheduledAtMs(scheduledAtMs, defaultScheduledAtMs) {
+  if (scheduledAtMs === undefined) return defaultScheduledAtMs
+  if (Number.isSafeInteger(scheduledAtMs) && scheduledAtMs >= 0) return scheduledAtMs
+
+  throw VelociousError.safe("background job scheduledAtMs must be a non-negative safe integer")
+}
+
+/**
+ * Validates a reschedule delay and resolves it at persistence time.
+ * @param {number} delayMs - Requested delay.
+ * @param {number} nowMs - Persistence timestamp.
+ * @returns {number} - New eligibility timestamp.
+ */
+export function rescheduledBackgroundJobAtMs(delayMs, nowMs) {
+  if (!Number.isSafeInteger(delayMs) || delayMs < 0) {
+    throw VelociousError.safe("background job reschedule delayMs must be a non-negative safe integer")
+  }
+
+  const scheduledAtMs = nowMs + delayMs
+
+  if (!Number.isSafeInteger(scheduledAtMs)) {
+    throw VelociousError.safe("background job reschedule scheduledAtMs must be a safe integer")
+  }
+
+  return scheduledAtMs
+}
+
+/**
+ * Returns the shared failure backoff.
+ * @param {number} retryCount - One-based failed attempt count.
+ * @returns {number} - Backoff in milliseconds.
+ */
+export function retryDelayMs(retryCount) {
+  const scheduleSeconds = [10, 60, 600, 3600]
+
+  if (retryCount <= scheduleSeconds.length) return scheduleSeconds[retryCount - 1] * 1000
+
+  return (retryCount - 3) * 60 * 60 * 1000
+}
+
+/**
+ * Resolves explicit or queue-derived concurrency.
+ * @param {object} args - Resolution arguments.
+ * @param {import("./types.js").BackgroundJobOptions} args.options - Job options.
+ * @param {string} args.queue - Normalized queue.
+ * @param {Record<string, {maxConcurrent?: number, priority?: number}>} args.queues - Queue configuration.
+ * @returns {import("./types.js").ResolvedBackgroundJobConcurrency | null} - Concurrency contract.
+ */
+export function normalizeBackgroundJobConcurrency({options = {}, queue, queues}) {
+  const key = options.concurrencyKey
+  const cap = options.maxConcurrency
+
+  if (key !== undefined || cap !== undefined) {
+    if (typeof key !== "string" || key.length === 0 || !Number.isInteger(cap) || Number(cap) <= 0) {
+      throw new Error("background job concurrencyKey and maxConcurrency must be paired; concurrencyKey must be non-empty and maxConcurrency must be a positive integer")
+    }
+    if (key.startsWith(QUEUE_CONCURRENCY_KEY_PREFIX)) {
+      throw new Error(`background job concurrencyKey must not start with the reserved "${QUEUE_CONCURRENCY_KEY_PREFIX}" prefix, which is reserved for queue-derived concurrency caps`)
+    }
+
+    return {concurrencyKey: key, maxConcurrency: Number(cap), queueDerived: false}
+  }
+
+  const queueCap = queues[queue]?.maxConcurrent
+
+  if (!Number.isInteger(queueCap) || Number(queueCap) <= 0) return null
+
+  return {
+    concurrencyKey: `${QUEUE_CONCURRENCY_KEY_PREFIX}${queue}`,
+    maxConcurrency: Number(queueCap),
+    queueDerived: true
+  }
+}

package/src/background-jobs/local-adapter.js

@@ -0,0 +1,161 @@
+// @ts-check
+
+import BackgroundJobsAdapter from "./adapter.js"
+import LocalBackgroundJobsDispatcher from "./local-dispatcher.js"
+import LocalBackgroundJobRegistry from "./local-job-registry.js"
+import LocalBackgroundJobsStore, {localBackgroundJobsClock} from "./local-store.js"
+
+/** Durable local SQLite adapter with an owned in-process dispatcher. */
+export default class LocalBackgroundJobsAdapter extends BackgroundJobsAdapter {
+  /**
+   * Creates a local adapter for one configuration and database.
+   * @param {object} args - Adapter options.
+   * @param {import("../configuration.js").default} args.configuration - Owning configuration.
+   * @param {import("./types.js").LocalBackgroundJobsClock} [args.clock] - Injectable clock.
+   * @param {string} [args.databaseIdentifier] - Local database identifier.
+   */
+  constructor({configuration, clock = localBackgroundJobsClock(), databaseIdentifier}) {
+    super()
+    this.clock = clock
+    this.configuration = configuration
+    this.registry = new LocalBackgroundJobRegistry({jobClasses: configuration.getBackgroundJobClasses()})
+    this.store = new LocalBackgroundJobsStore({
+      clock,
+      configuration,
+      databaseIdentifier,
+      onCommittedEnqueue: () => this.dispatcher.wake()
+    })
+    this.dispatcher = new LocalBackgroundJobsDispatcher({clock, configuration, registry: this.registry, store: this.store})
+  }
+
+  /**
+   * Ensures that local persistence and dispatch are ready.
+   * @returns {Promise<void>} - Resolves when local dispatch is ready.
+   */
+  async ensureReady() { await this.dispatcher.start() }
+
+  /**
+   * Stops local dispatch gracefully.
+   * @returns {Promise<void>} - Resolves after graceful local shutdown.
+   */
+  async close() {
+    await this.dispatcher.stop()
+    this.store.resetReadiness()
+  }
+
+  /**
+   * Reports local dispatcher health.
+   * @returns {Promise<import("./types.js").BackgroundJobsHealth>} - Local adapter health.
+   */
+  async health() { return {ready: this.dispatcher.isReady()} }
+
+  /**
+   * Reconciles configuration-derived queue concurrency caps.
+   * @returns {Promise<void>} - Resolves after queue cap reconciliation.
+   */
+  async reconcileQueueConcurrency() { await this.store.reconcileQueueConcurrency() }
+
+  /**
+   * Enqueues one statically registered local job.
+   * @param {{jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} args - Enqueue request.
+   * @returns {Promise<string>} - Durable local job id.
+   */
+  async enqueue(args) {
+    await this.ensureReady()
+    this.registry.resolve(args.jobName)
+    return await this.store.enqueue(args)
+  }
+
+  /**
+   * Rejects stable-key cancellation, which is outside the local adapter contract.
+   * @param {string} _scheduleKey - Unsupported stable key.
+   * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Never resolves.
+   */
+  async cancelScheduled(_scheduleKey) { throw new Error("cancelScheduled is not supported by the local background-jobs adapter") }
+
+  /**
+   * Rejects stable-key replacement, which is outside the local adapter contract.
+   * @param {{scheduleKey: string, jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} _args - Unsupported request.
+   * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Never resolves.
+   */
+  async replaceScheduled(_args) { throw new Error("replaceScheduled is not supported by the local background-jobs adapter") }
+
+  /**
+   * Finds the next eligible local job.
+   * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Next eligible job.
+   */
+  async nextAvailableJob() { return await this.store.nextAvailableJob() }
+
+  /**
+   * Finds the next future local job.
+   * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Next future job.
+   */
+  async nextScheduledJob() { return await this.store.nextScheduledJob() }
+
+  /**
+   * Finds a local job by id.
+   * @param {string} jobId - Job id.
+   * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Persisted job.
+   */
+  async getJob(jobId) { return await this.store.getJob(jobId) }
+
+  /**
+   * Lists local jobs in insertion order.
+   * @returns {Promise<import("./types.js").BackgroundJobRow[]>} - Local jobs.
+   */
+  async listJobs() { return await this.store.listJobs() }
+
+  /**
+   * Claims one queued local job.
+   * @param {{jobId: string, workerId?: string}} args - Claim request.
+   * @returns {Promise<import("./types.js").BackgroundJobHandoff | null>} - Handoff.
+   */
+  async markHandedOff(args) { return await this.store.markHandedOff(args) }
+
+  /**
+   * Finds active local handoffs owned by one worker.
+   * @param {{workerId: string}} args - Worker identity.
+   * @returns {Promise<Array<{jobId: string, handoffId: string}>>} - Active worker handoffs.
+   */
+  async handedOffJobsForWorker(args) { return await this.store.handedOffJobsForWorker(args) }
+
+  /**
+   * Returns an exact active local handoff to the queue.
+   * @param {{jobId: string, handoffId: string}} args - Handoff release.
+   * @returns {Promise<void>} - Resolves after the fenced release.
+   */
+  async markReturnedToQueue(args) { await this.store.markReturnedToQueue(args) }
+
+  /**
+   * Acknowledges successful local job completion.
+   * @param {{jobId: string, handoffId?: string}} args - Completion report.
+   * @returns {Promise<boolean>} - Whether accepted.
+   */
+  async markCompleted(args) { return await this.store.markCompleted(args) }
+
+  /**
+   * Acknowledges an explicit local reschedule.
+   * @param {{jobId: string, delayMs: number, handoffId?: string}} args - Reschedule report.
+   * @returns {Promise<boolean>} - Whether accepted.
+   */
+  async markRescheduled(args) { return await this.store.markRescheduled(args) }
+
+  /**
+   * Acknowledges a failed local performance.
+   * @param {{jobId: string, error: ReturnType<typeof JSON.parse>, handoffId?: string}} args - Failure report.
+   * @returns {Promise<import("./types.js").BackgroundJobRow | null>} - Transition.
+   */
+  async markFailed(args) { return await this.store.markFailed(args) }
+
+  /**
+   * Coalesces a dispatcher wake.
+   * @returns {void} - No return value.
+   */
+  wake() { this.dispatcher.wake() }
+
+  /**
+   * Waits until current local work has been acknowledged.
+   * @returns {Promise<void>} - Resolves after all current work is acknowledged.
+   */
+  async waitForIdle() { await this.dispatcher.waitForIdle() }
+}