velocious 1.0.605 → 1.0.607

package/src/background-jobs/main.js

@@ -222,7 +222,11 @@ export default class BackgroundJobsMain {
             options: jobClass._withQueue(options)
           })
           this._notifyEnqueued()
-          await this._drain()
+          // Persistence is the scheduler enqueue boundary. Dispatch remains
+          // coalesced, but a slow active drain must not make the recurring
+          // scheduler treat this job key as still being enqueued and suppress
+          // later timer occurrences.
+          void this._drain()
         }
       })
       await this.scheduler.start()
@@ -284,6 +288,7 @@ export default class BackgroundJobsMain {
           this._disconnectBeaconHandlers()
           try {
             await this.scheduler?.stop()
+            if (this._drainPromise) await this._drainPromise
           } finally {
             try {
               await this._drainWorkerHandoffAdoptions()

package/src/background-jobs/store.js

@@ -9,6 +9,19 @@ import BackgroundJobRecord from "./job-record.js"
 import normalizeBackgroundJobError from "./normalize-error.js"
 import {coordinateSharedTransactionConnection} from "../testing/shared-transaction-connection-coordinator.js"
 import stableJsonStringify from "../utils/stable-json.js"
+import {
+  BACKGROUND_JOB_EXECUTION_MODES,
+  DEFAULT_BACKGROUND_JOB_EXECUTION_MODE,
+  DEFAULT_BACKGROUND_JOB_QUEUE,
+  QUEUE_CONCURRENCY_KEY_PREFIX,
+  normalizeBackgroundJobConcurrency,
+  normalizeBackgroundJobExecutionMode,
+  normalizeBackgroundJobMaxRetries,
+  normalizeBackgroundJobQueue,
+  normalizeBackgroundJobScheduledAtMs,
+  rescheduledBackgroundJobAtMs,
+  retryDelayMs
+} from "./job-semantics.js"
 import {
   MAIL_DELIVERY_OPERATIONS_TABLE,
   mailDeliveryOperationForJob,
@@ -52,22 +65,7 @@ const COUNTS_REVISION_KEY = "counts"
 export const BACKGROUND_JOB_COUNTS_CHANNEL = "velocious-background-job-counts"
 export const BACKGROUND_JOB_COUNT_BUCKETS = ["all", "queued", "handed_off", "completed", "failed", "orphaned"]
 const COUNTED_JOB_STATUSES = BACKGROUND_JOB_COUNT_BUCKETS.slice(1)
-const DEFAULT_MAX_RETRIES = 10
 const ORPHANED_AFTER_MS = 2 * 60 * 60 * 1000
-/**
- * Execution modes.
- * @type {import("./types.js").BackgroundJobExecutionMode[]} */
-const EXECUTION_MODES = ["inline", "forked", "pooled", "spawned"]
-/**
- * Execution mode for a new enqueue that names neither `executionMode` nor the
- * legacy `forked` flag. Pooled routes the job to a warm, reused local runner
- * process — the same isolation as forked without paying a fresh process per job.
- * @type {import("./types.js").BackgroundJobExecutionMode} */
-const DEFAULT_EXECUTION_MODE = "pooled"
-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
@@ -783,7 +781,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
       .map(([queue, priority]) => `WHEN ${db.quote(queue)} THEN ${priority}`)
       .join(" ")
 
-    return `CASE COALESCE(${queueColumn}, ${db.quote(DEFAULT_QUEUE)}) ${whens} ELSE 0 END`
+    return `CASE COALESCE(${queueColumn}, ${db.quote(DEFAULT_BACKGROUND_JOB_QUEUE)}) ${whens} ELSE 0 END`
   }
 
   /**
@@ -1302,13 +1300,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {number} - Delay in milliseconds.
    */
   getRetryDelayMs(retryCount) {
-    const scheduleSeconds = [10, 60, 600, 3600]
-
-    if (retryCount <= scheduleSeconds.length) {
-      return scheduleSeconds[retryCount - 1] * 1000
-    }
-
-    return (retryCount - 3) * 60 * 60 * 1000
+    return retryDelayMs(retryCount)
   }
 
   /**
@@ -1382,11 +1374,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {number} - Normalized max retries.
    */
   _normalizeMaxRetries(maxRetries) {
-    if (typeof maxRetries === "number" && Number.isFinite(maxRetries) && maxRetries >= 0) {
-      return Math.floor(maxRetries)
-    }
-
-    return DEFAULT_MAX_RETRIES
+    return normalizeBackgroundJobMaxRetries(maxRetries)
   }
 
   /**
@@ -1396,10 +1384,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {number} - Dispatch timestamp.
    */
   _normalizeScheduledAtMs(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")
+    return normalizeBackgroundJobScheduledAtMs(scheduledAtMs, defaultScheduledAtMs)
   }
 
   /**
@@ -1408,14 +1393,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {number} - Future eligibility timestamp.
    */
   _rescheduledAtMs(delayMs) {
-    this._validateRescheduleDelayMs(delayMs)
-
-    const scheduledAtMs = Date.now() + delayMs
-    if (!Number.isSafeInteger(scheduledAtMs)) {
-      throw VelociousError.safe("background job reschedule scheduledAtMs must be a safe integer")
-    }
-
-    return scheduledAtMs
+    return rescheduledBackgroundJobAtMs(delayMs, Date.now())
   }
 
   /**
@@ -1424,9 +1402,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {void}
    */
   _validateRescheduleDelayMs(delayMs) {
-    if (!Number.isSafeInteger(delayMs) || delayMs < 0) {
-      throw VelociousError.safe("background job reschedule delayMs must be a non-negative safe integer")
-    }
+    rescheduledBackgroundJobAtMs(delayMs, 0)
   }
 
   /**
@@ -2083,14 +2059,14 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     // `execution_mode` is the single source of truth for a job's runtime and is
     // written on every enqueue; the drop-forked migration backfills any pre-existing
     // rows before the legacy `forked` column is removed.
-    const executionMode = row.execution_mode ? this._normalizeExecutionModeName(String(row.execution_mode)) : DEFAULT_EXECUTION_MODE
+    const executionMode = row.execution_mode ? this._normalizeExecutionModeName(String(row.execution_mode)) : DEFAULT_BACKGROUND_JOB_EXECUTION_MODE
 
     return {
       id: String(row.id),
       jobName: String(row.job_name),
       args: this._parseArgs(row.args_json),
       executionMode,
-      queue: row.queue ? String(row.queue) : DEFAULT_QUEUE,
+      queue: row.queue ? String(row.queue) : DEFAULT_BACKGROUND_JOB_QUEUE,
       scheduleKey: row.schedule_key ? String(row.schedule_key) : null,
       status: row.status ? String(row.status) : "queued",
       attempts: this._normalizeNumber(row.attempts),
@@ -2109,35 +2085,13 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
     }
   }
 
-  /**
-   * Validates concurrency options.
-   * @param {import("./types.js").BackgroundJobOptions | undefined} options - Job options.
-   * @returns {{concurrencyKey: string, maxConcurrency: number} | null} - Normalized configuration.
-   */
-  _normalizeConcurrencyOptions(options) {
-    const key = options?.concurrencyKey
-    const cap = options?.maxConcurrency
-    if (key === undefined && cap === undefined) return null
-    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)}
-  }
-
   /**
    * 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
+    return normalizeBackgroundJobQueue(options)
   }
 
   /**
@@ -2151,15 +2105,11 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @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}
+    return normalizeBackgroundJobConcurrency({
+      options: options || {},
+      queue,
+      queues: this.configuration.getBackgroundJobsConfig().queues
+    })
   }
 
   /**
@@ -2667,21 +2617,7 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {import("./types.js").BackgroundJobExecutionMode} - Normalized execution mode.
    */
   _normalizeExecutionMode(options) {
-    const executionMode = options?.executionMode
-
-    if (executionMode) {
-      return this._normalizeExecutionModeName(executionMode)
-    }
-
-    // The `forked` option alias was removed. Reject it loudly instead of silently
-    // defaulting to pooled, which would turn an explicitly inline (`forked: false`)
-    // or one-shot forked (`forked: true`) job into a pooled child-runner job — a
-    // silent semantic change for any not-yet-migrated caller.
-    if (options && "forked" in options) {
-      throw new Error("The background job `forked` option was removed; pass `executionMode` (\"inline\", \"forked\", \"pooled\", or \"spawned\") instead")
-    }
-
-    return DEFAULT_EXECUTION_MODE
+    return normalizeBackgroundJobExecutionMode(options || {}, DEFAULT_BACKGROUND_JOB_EXECUTION_MODE)
   }
 
   /**
@@ -2690,11 +2626,11 @@ export default class BackgroundJobsStore extends BackgroundJobsAdapter {
    * @returns {import("./types.js").BackgroundJobExecutionMode} - Normalized execution mode.
    */
   _normalizeExecutionModeName(executionMode) {
-    for (const mode of EXECUTION_MODES) {
-      if (mode === executionMode) return mode
-    }
-
-    throw new Error(`Invalid background job executionMode: ${executionMode}`)
+    return normalizeBackgroundJobExecutionMode(
+      {executionMode: /** @type {import("./types.js").BackgroundJobExecutionMode} */ (executionMode)},
+      DEFAULT_BACKGROUND_JOB_EXECUTION_MODE,
+      BACKGROUND_JOB_EXECUTION_MODES
+    )
   }
 
   /**

package/src/background-jobs/types.js

@@ -3,6 +3,31 @@
 /**
  * @typedef {"inline" | "forked" | "pooled" | "spawned"} BackgroundJobExecutionMode
  */
+/**
+ * @typedef {object} LocalBackgroundJobsClock
+ * @property {() => number} now - Current epoch milliseconds.
+ * @property {(callback: () => void, delayMs: number) => ReturnType<typeof setTimeout> | number} setTimeout - Arms a timer.
+ * @property {(timerId: ReturnType<typeof setTimeout> | number) => void} clearTimeout - Clears a timer.
+ */
+/**
+ * @typedef {object} ResolvedBackgroundJobConcurrency
+ * @property {string} concurrencyKey - Durable cap identity.
+ * @property {number} maxConcurrency - Positive cap.
+ * @property {boolean} queueDerived - Whether queue configuration owns the cap.
+ */
+/**
+ * @typedef {object} PreparedLocalBackgroundJob
+ * @property {string} argsDigest - Fixed-width digest of the serialized arguments.
+ * @property {string} argsJson - Serialized arguments.
+ * @property {ResolvedBackgroundJobConcurrency | null} concurrency - Resolved concurrency.
+ * @property {number} createdAtMs - Creation timestamp.
+ * @property {"inline"} executionMode - Local in-process execution mode.
+ * @property {string} jobId - Durable id.
+ * @property {string} jobName - Registered name.
+ * @property {number} maxRetries - Retry cap.
+ * @property {string} queue - Queue name.
+ * @property {number} scheduledAtMs - Eligibility timestamp.
+ */
 /**
  * @typedef {object} BackgroundJobsHealth
  * @property {boolean} ready - Whether the adapter can accept and process work.
@@ -20,7 +45,7 @@
  */
 /**
  * @typedef {object} BackgroundJobOptions
- * @property {BackgroundJobExecutionMode} [executionMode] - How the job should run. Defaults to `"pooled"` (a warm, reused local runner process). `"forked"` runs the job in a fresh `child_process.fork()` child, `"spawned"` in a detached CLI runner, and `"inline"` inside the worker process. Omit to use the default `"pooled"` mode.
+ * @property {BackgroundJobExecutionMode} [executionMode] - How the job should run. Node defaults to `"pooled"` (a warm, reused local runner process). Browser/Expo local dispatch defaults to and only accepts `"inline"`. `"forked"` runs a Node job in a fresh `child_process.fork()` child, and `"spawned"` in a detached CLI runner.
  * @property {number} [maxRetries] - Max retries for a failed job before it is marked failed.
  * @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.

package/src/configuration-types.js

@@ -158,14 +158,16 @@
 
 /** @typedef {"background" | "inline"} BackgroundJobsMode */
 /** @typedef {(args: {configuration: import("./configuration.js").default}) => import("./background-jobs/adapter.js").default} BackgroundJobsAdapterFactory */
+/** @typedef {typeof import("./background-jobs/platform-job.js").default} BackgroundJobClass */
 
 /**
  * @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 {BackgroundJobClass[]} [jobClasses] - Static portable job classes available to Browser/Expo local dispatch. Defaults to `[]`; Node keeps its filesystem registry.
  * @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.
+ * @property {string} [databaseIdentifier] - Database identifier used to store background jobs. Browser/Expo local dispatch uses this existing SQLite database and defaults to `"default"`.
  * @property {number} [maxConcurrentInlineJobs] - How many `forked: false` jobs a single
  *   `background-jobs-worker` process is allowed to run in parallel. Concurrency
  *   is at the JS event-loop level: every concurrent job shares the worker's

package/src/configuration.js

@@ -1543,7 +1543,22 @@ export default class VelociousConfiguration {
         : 60 * 60 * 1000
     }
 
-    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, dispatchStrategy, pollIntervalMs, queues, jobTimeoutMs, retention}
+    const jobClasses = this.getBackgroundJobClasses()
+
+    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, dispatchStrategy, pollIntervalMs, queues, jobClasses, jobTimeoutMs, retention}
+  }
+
+  /**
+   * Returns statically registered portable background jobs.
+   * @returns {import("./configuration-types.js").BackgroundJobClass[]} - Configured job classes.
+   */
+  getBackgroundJobClasses() {
+    const jobClasses = this._backgroundJobs?.jobClasses
+
+    if (jobClasses === undefined) return []
+    if (!Array.isArray(jobClasses)) throw new TypeError("backgroundJobs.jobClasses must be an array")
+
+    return [...jobClasses]
   }
 
   /**

package/src/database/drivers/sqlite/index.js

@@ -255,6 +255,35 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
     await fs.writeFile(ownerPath, payload)
   }
 
+  /**
+   * Publishes a fully initialized lock directory with one atomic rename.
+   * A losing candidate is removed in the same call, so concurrent acquisition
+   * cannot observe or delete another process's half-written owner metadata.
+   * @param {string} lockPath - Stable advisory-lock path.
+   * @returns {Promise<boolean>} - Whether this candidate became the lock owner.
+   */
+  async _publishAdvisoryLockDirectory(lockPath) {
+    const candidatePath = await fs.mkdtemp(`${lockPath}.pending-`)
+    let published = false
+
+    try {
+      await this._writeAdvisoryLockMetadata(candidatePath)
+
+      try {
+        await fs.rename(candidatePath, lockPath)
+        published = true
+        return true
+      } catch (error) {
+        const code = /** @type {Error & {code?: string}} */ (error)?.code
+
+        if (code === "EEXIST" || code === "ENOTEMPTY") return false
+        throw error
+      }
+    } finally {
+      if (!published) await fs.rm(candidatePath, {force: true, recursive: true})
+    }
+  }
+
   /**
    * Runs acquire advisory lock file.
    * @param {string} name - Lock name.
@@ -272,28 +301,21 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
     // mkdir succeeds, the deadline elapses, or an unexpected error is
     // re-thrown.
     while (true) {
-      try {
-        await fs.mkdir(lockPath)
-        await this._writeAdvisoryLockMetadata(lockPath)
+      if (await this._publishAdvisoryLockDirectory(lockPath)) return true
 
-        return true
-      } catch (error) {
-        if (/** @type {Error & {code?: string}} */ (error)?.code !== "EEXIST") throw error
-
-        if (await this._isAdvisoryLockStale(lockPath)) {
-          await fs.rm(lockPath, {recursive: true, force: true})
-          continue
-        }
+      if (await this._isAdvisoryLockStale(lockPath)) {
+        await fs.rm(lockPath, {recursive: true, force: true})
+        continue
+      }
 
-        if (deadline !== null) {
-          const remaining = deadline - Date.now()
+      if (deadline !== null) {
+        const remaining = deadline - Date.now()
 
-          if (remaining <= 0) return false
+        if (remaining <= 0) return false
 
-          await wait(Math.min(pollIntervalMs, remaining))
-        } else {
-          await wait(pollIntervalMs)
-        }
+        await wait(Math.min(pollIntervalMs, remaining))
+      } else {
+        await wait(pollIntervalMs)
       }
     }
   }
@@ -308,31 +330,14 @@ export default class VelociousDatabaseDriversSqliteNode extends Base {
 
     const lockPath = this._advisoryLockPath(name)
 
-    try {
-      await fs.mkdir(lockPath)
-      await this._writeAdvisoryLockMetadata(lockPath)
+    if (await this._publishAdvisoryLockDirectory(lockPath)) return true
 
-      return true
-    } catch (error) {
-      if (/** @type {Error & {code?: string}} */ (error)?.code !== "EEXIST") throw error
-
-      if (await this._isAdvisoryLockStale(lockPath)) {
-        await fs.rm(lockPath, {recursive: true, force: true})
-
-        try {
-          await fs.mkdir(lockPath)
-          await this._writeAdvisoryLockMetadata(lockPath)
-
-          return true
-        } catch (retryError) {
-          if (/** @type {Error & {code?: string}} */ (retryError)?.code === "EEXIST") return false
-
-          throw retryError
-        }
-      }
-
-      return false
+    if (await this._isAdvisoryLockStale(lockPath)) {
+      await fs.rm(lockPath, {recursive: true, force: true})
+      return await this._publishAdvisoryLockDirectory(lockPath)
     }
+
+    return false
   }
 
   /**

package/src/environment-handlers/browser.js

@@ -2,6 +2,7 @@ import Base from "./base.js"
 import * as inflection from "inflection"
 import restArgsError from "../utils/rest-args-error.js"
 import Logger from "../logger.js"
+import LocalBackgroundJobsAdapter from "../background-jobs/local-adapter.js"
 
 /**
  * Defines this typedef.
@@ -40,6 +41,15 @@ function isMigrationObject(migration) {
 }
 
 export default class VelociousEnvironmentsHandlerBrowser extends Base {
+  /**
+   * Creates the Browser/Expo local SQLite adapter and in-process dispatcher.
+   * @param {{configuration: import("../configuration.js").default}} args - Adapter options.
+   * @returns {LocalBackgroundJobsAdapter} - Local background-jobs adapter.
+   */
+  createBackgroundJobsAdapter({configuration}) {
+    return new LocalBackgroundJobsAdapter({configuration})
+  }
+
   /**
    * Find commands require context result.
    * @type {CommandsRequireContextType | undefined} */