velocious 1.0.606 → 1.0.608

package/README.md

@@ -34,7 +34,7 @@
 * Cross-process broadcast bus for `broadcastToChannel` via `velocious beacon`, including background job runner processes (see [docs/beacon.md](docs/beacon.md))
 * Configurable HTTP server worker handlers plus backpressured, descriptor-only file responses with completion callbacks (see [docs/http-server.md](docs/http-server.md))
 * Default-on buffered HTTP response compression with Brotli/gzip content negotiation, global and per-response opt-outs, and HEAD-correct representation headers (see [docs/http-server.md](docs/http-server.md#response-compression))
-* Background jobs with failure events for production reporting and authorized database-scoped dashboard count snapshots/deltas (see [docs/background-jobs.md](docs/background-jobs.md) and [docs/background-jobs-dashboard.md](docs/background-jobs-dashboard.md))
+* Background jobs with Node SQL/TCP workers plus a Browser/Expo local SQLite store and in-process dispatcher, failure events, and authorized database-scoped dashboard count snapshots/deltas (see [docs/background-jobs.md](docs/background-jobs.md), [docs/local-background-jobs.md](docs/local-background-jobs.md), and [docs/background-jobs-dashboard.md](docs/background-jobs-dashboard.md))
 * Durable one-off background-job scheduling with exact epoch timestamps (see [docs/scheduled-background-job-enqueue.md](docs/scheduled-background-job-enqueue.md))
 * Rails-style request and database query logging (see [docs/logging.md](docs/logging.md))
 * EJS-backed mailers with delivery, queueing, and payload rendering support (see [docs/mailers.md](docs/mailers.md))
@@ -178,6 +178,17 @@ npx velocious test --include-tag fast,api
 npx velocious test --exclude-tag slow
 ```
 
+`*.browser-spec.js` files remain eligible for both the Node database matrix and
+the browser runner. Add the reserved `browser-only` tag only when a suite requires
+the real browser environment; the Node runner discovers the file but does not
+execute its tagged tests.
+
+```js
+describe("Browser integration", {tags: ["browser-only"]}, () => {
+  it("uses browser runtime behavior", async () => {})
+})
+```
+
 Target a test by line number or description.
 
 ```bash
@@ -2331,6 +2342,38 @@ synchronous factory. See [runtime modes and adapters](docs/background-jobs.md#ru
 for the contract, lifecycle, Node TCP/wake behavior, the explicit
 `platform-job.js` browser/Expo entry, and SQL-only compatibility boundaries.
 
+Browser and Expo configurations have a built-in local SQLite adapter in
+`"background"` mode. Register portable classes statically; no main process,
+worker, socket, or child process is started:
+
+```js
+import VelociousJob from "velocious/build/src/background-jobs/platform-job.js"
+
+class UploadPendingChangesJob extends VelociousJob {
+  async perform(projectId) {
+    await uploadPendingChanges(projectId)
+  }
+}
+
+export default new Configuration({
+  backgroundJobs: {
+    databaseIdentifier: "default",
+    jobClasses: [UploadPendingChangesJob],
+    maxConcurrentInlineJobs: 4,
+    queues: {uploads: {maxConcurrent: 2, priority: 10}}
+  }
+})
+```
+
+Local enqueue participates in an existing application transaction and wakes the
+dispatcher only after commit. It supports queue caps/priorities, explicit
+concurrency, queued deduplication, one-off scheduling, retries/backoff,
+`rescheduleIn`, fenced acknowledgements, graceful close/reopen, interrupted-job
+recovery, and the existing SQL.js persistence backends. It supports one active
+configuration-owned adapter per app/database; OS background execution and
+multi-tab leadership are outside this backend. See
+[local background jobs](docs/local-background-jobs.md).
+
 Or via env vars:
 
 ```
@@ -2362,7 +2405,7 @@ concurrency and per-job connection scopes are unchanged.
 
 `maxConcurrentForkedJobs` (default: `4`) caps how many out-of-process `executionMode: "forked"` or `executionMode: "spawned"` jobs one worker may keep in flight. Forked jobs use `child_process.fork()` with an attached IPC channel. After the main process acknowledges their durable status report, forked and spawned one-shot runners exit without waiting for graceful Beacon/database teardown; the OS closes their process-owned resources. A missing or rejected status acknowledgement makes the runner exit as failed instead of reporting clean success. Spawned jobs use the legacy `background-jobs-runner` CLI process via `child_process.spawn()` and are only for callers that intentionally want that spawned behavior.
 
-`jobTimeoutMs` (or `VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS`, milliseconds; default: disabled) is a wall-clock backstop for `"forked"` and `"pooled"` jobs. A job still running after the timeout is terminated (`SIGTERM`, then `SIGKILL` after the reaping grace) and reported `failed`, so a genuinely-hung job can't pin a worker's capacity — and its whole-app boot and DB connections — indefinitely (notably a retired-release worker draining after a deploy). For a **pooled** job the whole child running it is killed, so its concurrent in-flight siblings on that child are also reported `failed` and requeued — a hung JS job can't be cancelled any other way — before a replacement child is spawned. It's a coarse safety net, not per-job tuning: it applies to every forked and pooled job, so set it well above the longest legitimate job. Omit it, or set `null`/`<= 0`, to disable. `"inline"` jobs are not covered — they share the worker's process and can't be killed without killing the worker. See [docs/background-jobs.md](docs/background-jobs.md#job-timeout-hung-runner-backstop).
+`jobTimeoutMs` (or `VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS`, milliseconds; default: disabled) is a wall-clock backstop for `"forked"` and `"pooled"` jobs. A job still running after the timeout is terminated (`SIGTERM`, then `SIGKILL` after the reaping grace) and reported `failed`, so a genuinely-hung job can't pin a worker's capacity — and its whole-app boot and DB connections — indefinitely (notably a retired-release worker draining after a deploy). For a **pooled** job the whole child running it is killed, so its concurrent in-flight siblings on that child are also reported `failed` and requeued — a hung JS job can't be cancelled any other way — before a replacement child is spawned. Set `options.timeoutMs` to a positive integer no greater than `2_147_483_647` for a per-job wall-clock timeout that overrides the worker default; a non-positive finite value disables the backstop for that job. Invalid types, non-finite values, fractions, and larger values are rejected before persistence. Omit it to retain the worker-level fallback. `"inline"` jobs are not covered — they share the worker's process and can't be killed without killing the worker. See [docs/background-jobs.md](docs/background-jobs.md#job-timeout-hung-runner-backstop).
 
 ### Dispatch strategy
 

package/build/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/build/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() }
+}