velocious 1.0.599 → 1.0.601

package/build/configuration.js

@@ -11,11 +11,20 @@
  * @property {string[]} [databaseIdentifiers] - Database identifiers to include in the connection scope.
  * @property {string} [name] - Human-readable name for the checked-out database connections.
  */
+/**
+ * One adapter instance and its serialized ready/close lifecycle.
+ * @typedef {object} BackgroundJobsAdapterGeneration
+ * @property {import("./background-jobs/adapter.js").default} adapter - Adapter owned by this generation.
+ * @property {boolean} closing - Whether close has claimed this generation.
+ * @property {Promise<void> | undefined} readyPromise - Shared readiness attempt.
+ * @property {Promise<void> | undefined} closePromise - Shared close operation.
+ */
 
 import {digg} from "diggerize"
 import gettextConfig from "gettext-universal/build/src/config.js"
 import translate from "gettext-universal/build/src/translate.js"
 import Ability from "./authorization/ability.js"
+import BackgroundJobsAdapter from "./background-jobs/adapter.js"
 import DatabaseOperation from "./database/operation.js"
 import {initializeAuditedModelRelationships} from "./database/record/auditing.js"
 import EventEmitter from "./utils/event-emitter.js"
@@ -204,6 +213,9 @@ export default class VelociousConfiguration {
    * @type {Promise<void> | null} */
   _closeDatabaseConnectionsPromise = null
 
+  /** @type {BackgroundJobsAdapterGeneration | undefined} */
+  _backgroundJobsAdapterGeneration = undefined
+
   /**
    * Dedicated advisory-lock connections currently holding a lock. These are spawned
    * outside the pools' tracked sets (so a hold-timeout lock survives pool checkouts),
@@ -224,7 +236,7 @@ export default class VelociousConfiguration {
    * Runs constructor.
    * @param {import("./configuration-types.js").ConfigurationArgsType} args - Configuration arguments.
    */
-  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients = false, frontendTenantSqlite, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors = false, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
+  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients, frontendTenantSqlite, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
     restArgsError(restArgs)
 
     this._abilityResolver = abilityResolver
@@ -268,11 +280,12 @@ export default class VelociousConfiguration {
     this.debug = debug
     this._debugEndpoint = this._normalizeDebugEndpoint(debugEndpoint)
     this._apiManifest = this._normalizeApiManifest(apiManifest)
-    this._environment = environment || process.env.VELOCIOUS_ENV || process.env.NODE_ENV || "development"
+    this._environment = environment || globalThis.process?.env.VELOCIOUS_ENV || globalThis.process?.env.NODE_ENV || "development"
     this._environmentHandler = environmentHandler
     this._enforceTenantDatabaseScopes = enforceTenantDatabaseScopes
-    this._exposeInternalErrorsToClients = exposeInternalErrorsToClients
-    this._secureFrontendModelErrors = secureFrontendModelErrors
+    this._exposeInternalErrorsToClients = exposeInternalErrorsToClients === undefined
+      ? secureFrontendModelErrors !== true
+      : exposeInternalErrorsToClients
     this._directory = directory
     this._initializeModels = initializeModels
     /** @type {VelociousPackage[]} */
@@ -449,9 +462,10 @@ export default class VelociousConfiguration {
 
   /**
    * Returns whether frontend-model errors expose only explicitly safe messages.
-   * @returns {boolean} Whether frontend-model errors expose only explicitly safe messages.
+   * @deprecated Use `getExposeInternalErrorsToClients()`.
+   * @returns {boolean} Whether frontend-model internal error exposure is disabled.
    */
-  getSecureFrontendModelErrors() { return this._secureFrontendModelErrors === true }
+  getSecureFrontendModelErrors() { return !this.getExposeInternalErrorsToClients() }
 
   /**
    * Runs get debug endpoint.
@@ -1441,22 +1455,23 @@ export default class VelociousConfiguration {
 
   /**
    * Runs get background jobs config.
-   * @returns {Required<import("./configuration-types.js").BackgroundJobsConfiguration> & {retention: import("./configuration-types.js").ResolvedBackgroundJobsRetentionConfiguration}} - Background jobs configuration.
+   * @returns {Omit<Required<import("./configuration-types.js").BackgroundJobsConfiguration>, "adapter" | "retention"> & {retention: import("./configuration-types.js").ResolvedBackgroundJobsRetentionConfiguration}} - Background jobs configuration.
    */
   getBackgroundJobsConfig() {
-    const envHost = process.env.VELOCIOUS_BACKGROUND_JOBS_HOST
-    const envPortRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_PORT
-    const envDatabaseIdentifier = process.env.VELOCIOUS_BACKGROUND_JOBS_DATABASE_IDENTIFIER
-    const envMaxConcurrentForkedRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_FORKED_JOBS
-    const envMaxConcurrentRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_INLINE_JOBS
-    const envPooledRunnerCountRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_COUNT
-    const envPooledRunnerConcurrencyRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_CONCURRENCY
-    const envPooledRunnerMaxJobsRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_JOBS
-    const envPooledRunnerMaxRssBytesRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_RSS_BYTES
-    const envPooledRunnerMaxLifetimeMsRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_LIFETIME_MS
-    const envDispatchStrategy = process.env.VELOCIOUS_BACKGROUND_JOBS_DISPATCH_STRATEGY
-    const envPollIntervalRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_POLL_INTERVAL_MS
-    const envJobTimeoutRaw = process.env.VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS
+    const processEnvironment = globalThis.process?.env
+    const envHost = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_HOST
+    const envPortRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_PORT
+    const envDatabaseIdentifier = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_DATABASE_IDENTIFIER
+    const envMaxConcurrentForkedRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_FORKED_JOBS
+    const envMaxConcurrentRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_MAX_CONCURRENT_INLINE_JOBS
+    const envPooledRunnerCountRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_COUNT
+    const envPooledRunnerConcurrencyRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_CONCURRENCY
+    const envPooledRunnerMaxJobsRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_JOBS
+    const envPooledRunnerMaxRssBytesRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_RSS_BYTES
+    const envPooledRunnerMaxLifetimeMsRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POOLED_RUNNER_MAX_LIFETIME_MS
+    const envDispatchStrategy = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_DISPATCH_STRATEGY
+    const envPollIntervalRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_POLL_INTERVAL_MS
+    const envJobTimeoutRaw = processEnvironment?.VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS
     const envPort = envPortRaw ? Number(envPortRaw) : undefined
     const envMaxConcurrentForked = envMaxConcurrentForkedRaw ? Number(envMaxConcurrentForkedRaw) : undefined
     const envMaxConcurrent = envMaxConcurrentRaw ? Number(envMaxConcurrentRaw) : undefined
@@ -1468,6 +1483,11 @@ export default class VelociousConfiguration {
     const envPollInterval = envPollIntervalRaw ? Number(envPollIntervalRaw) : undefined
     const envJobTimeout = envJobTimeoutRaw ? Number(envJobTimeoutRaw) : undefined
     const configured = this._backgroundJobs || {}
+    const mode = configured.mode === undefined ? "background" : configured.mode
+
+    if (mode !== "background" && mode !== "inline") {
+      throw new TypeError(`backgroundJobs.mode must be "background" or "inline", got: ${String(mode)}`)
+    }
     const host = configured.host || envHost || "127.0.0.1"
     const port = typeof configured.port === "number"
       ? configured.port
@@ -1522,7 +1542,146 @@ export default class VelociousConfiguration {
         : 60 * 60 * 1000
     }
 
-    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, dispatchStrategy, pollIntervalMs, queues, jobTimeoutMs, retention}
+    return {host, port, databaseIdentifier, maxConcurrentForkedJobs, maxConcurrentInlineJobs, mode, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, dispatchStrategy, pollIntervalMs, queues, jobTimeoutMs, retention}
+  }
+
+  /**
+   * Resolves and memoizes one background-jobs adapter for this configuration lifecycle.
+   * @returns {BackgroundJobsAdapter} - Active adapter.
+   */
+  getBackgroundJobsAdapter() {
+    if (this._backgroundJobsAdapterGeneration) return this._backgroundJobsAdapterGeneration.adapter
+
+    const configuredAdapter = this._backgroundJobs?.adapter
+    const adapter = typeof configuredAdapter === "function"
+      ? configuredAdapter({configuration: this})
+      : (configuredAdapter || this.getEnvironmentHandler().createBackgroundJobsAdapter({configuration: this}))
+
+    if (!(adapter instanceof BackgroundJobsAdapter)) {
+      throw new TypeError("backgroundJobs.adapter must be a BackgroundJobsAdapter instance or a synchronous factory returning one")
+    }
+
+    this._backgroundJobsAdapterGeneration = {
+      adapter,
+      closing: false,
+      closePromise: undefined,
+      readyPromise: undefined
+    }
+    return adapter
+  }
+
+  /**
+   * Atomically acquires the exact ready adapter for the active lifecycle.
+   * A close that claims the generation while readiness is pending wins: this
+   * operation waits for that close, creates the next generation, readies it,
+   * and returns only that live instance.
+   * @returns {Promise<BackgroundJobsAdapter>} - Exact ready adapter generation.
+   */
+  async acquireReadyBackgroundJobsAdapter() {
+    while (true) {
+      const databaseClosePromise = this._closeDatabaseConnectionsPromise
+
+      if (databaseClosePromise) {
+        await databaseClosePromise
+        continue
+      }
+
+      this.getBackgroundJobsAdapter()
+      const generation = this._backgroundJobsAdapterGeneration
+
+      if (!generation) throw new Error("Background jobs adapter generation was not created")
+
+      if (generation.closing) {
+        if (generation.closePromise) await generation.closePromise
+        continue
+      }
+
+      const readyPromise = generation.readyPromise || Promise.resolve().then(async () => {
+        await generation.adapter.ensureReady()
+      })
+
+      generation.readyPromise = readyPromise
+
+      try {
+        await readyPromise
+      } catch (error) {
+        if (generation.readyPromise === readyPromise) generation.readyPromise = undefined
+        throw error
+      }
+
+      if (generation.closing) {
+        if (generation.closePromise) await generation.closePromise
+        continue
+      }
+
+      if (this._backgroundJobsAdapterGeneration !== generation) continue
+
+      return generation.adapter
+    }
+  }
+
+  /**
+   * Readies the active adapter once per lifecycle. A failed attempt remains retryable.
+   * @returns {Promise<void>} - Resolves when ready.
+   */
+  async ensureBackgroundJobsAdapterReady() {
+    await this.acquireReadyBackgroundJobsAdapter()
+  }
+
+  /**
+   * Returns health without resolving persistence in non-durable inline mode.
+   * @returns {Promise<import("./background-jobs/types.js").BackgroundJobsHealth>} - Current health.
+   */
+  async backgroundJobsHealth() {
+    if (this.getBackgroundJobsConfig().mode === "inline") return {ready: true}
+
+    const adapter = await this.acquireReadyBackgroundJobsAdapter()
+
+    return await adapter.health()
+  }
+
+  /**
+   * Closes the resolved adapter once and clears lifecycle caches.
+   * @returns {Promise<void>} - Resolves after close.
+   */
+  async closeBackgroundJobsAdapter() {
+    const generation = this._backgroundJobsAdapterGeneration
+
+    if (!generation) return
+    if (generation.closePromise) return await generation.closePromise
+
+    generation.closing = true
+    const closePromise = (async () => {
+      /** @type {Error[]} */
+      const closeErrors = []
+
+      if (generation.readyPromise) {
+        try {
+          await generation.readyPromise
+        } catch (error) {
+          closeErrors.push(error instanceof Error ? error : new Error(String(error)))
+        }
+      }
+
+      try {
+        await generation.adapter.close()
+      } catch (error) {
+        closeErrors.push(error instanceof Error ? error : new Error(String(error)))
+      }
+
+      if (closeErrors.length === 1) throw closeErrors[0]
+      if (closeErrors.length > 1) throw new AggregateError(closeErrors, "Failed to ready and close the background-jobs adapter")
+    })()
+
+    generation.closePromise = closePromise
+
+    try {
+      await closePromise
+    } finally {
+      if (this._backgroundJobsAdapterGeneration === generation) {
+        this._backgroundJobsAdapterGeneration = undefined
+      }
+    }
   }
 
   /**
@@ -1531,6 +1690,10 @@ export default class VelociousConfiguration {
    * @returns {void}
    */
   setBackgroundJobsConfig(backgroundJobs) {
+    if (this._backgroundJobsAdapterGeneration && backgroundJobs.adapter !== undefined) {
+      throw new Error("Cannot replace backgroundJobs.adapter during an active adapter lifecycle; close it first")
+    }
+
     this._backgroundJobs = Object.assign({}, this._backgroundJobs, backgroundJobs)
   }
 
@@ -2099,8 +2262,8 @@ export default class VelociousConfiguration {
     }
 
     const initializeModelsPromise = (async () => {
-      const shouldSkipDummyModelInitialization = process.env.VELOCIOUS_SKIP_DUMMY_MODEL_INITIALIZATION === "1"
-        && process.env.VELOCIOUS_BROWSER_TESTS === "true"
+      const shouldSkipDummyModelInitialization = globalThis.process?.env.VELOCIOUS_SKIP_DUMMY_MODEL_INITIALIZATION === "1"
+        && globalThis.process?.env.VELOCIOUS_BROWSER_TESTS === "true"
         && this.getEnvironment() === "test"
 
       if (!shouldSkipDummyModelInitialization) {
@@ -3425,34 +3588,50 @@ export default class VelociousConfiguration {
     const constructors = new Set()
 
     this._closeDatabaseConnectionsPromise = (async () => {
-      try {
-        // Close dedicated advisory-lock connections first: they are spawned outside the
-        // pools' tracked sets, so `pool.closeAll()` would not reach them and a lock held
-        // by a runner torn down mid-pass would leak until the DB server's `wait_timeout`.
-        // Still close the pools even if this throws, so a stuck lock connection does not
-        // leave the rest of the connections open.
-        await this._closeAdvisoryLockConnections()
-      } finally {
-        for (const pool of Object.values(this.databasePools)) {
-          if (!pool) continue
+      /** @type {Error[]} */
+      const closeErrors = []
 
-          await pool.closeAll()
+      try {
+        await this.closeBackgroundJobsAdapter()
+      } catch (error) {
+        closeErrors.push(error instanceof Error ? error : new Error(String(error)))
+      }
 
-          const PoolClass = /** @type {typeof import("./database/pool/base.js").default} */ (pool.constructor)
-          constructors.add(PoolClass)
-        }
+      try {
+        try {
+          // Close dedicated advisory-lock connections first: they are spawned outside the
+          // pools' tracked sets, so `pool.closeAll()` would not reach them and a lock held
+          // by a runner torn down mid-pass would leak until the DB server's `wait_timeout`.
+          // Still close the pools if this throws, so a stuck lock connection does not
+          // leave the rest of the connections open.
+          await this._closeAdvisoryLockConnections()
+        } finally {
+          for (const pool of Object.values(this.databasePools)) {
+            if (!pool) continue
+
+            await pool.closeAll()
+
+            const PoolClass = /** @type {typeof import("./database/pool/base.js").default} */ (pool.constructor)
+            constructors.add(PoolClass)
+          }
 
-        for (const PoolClass of constructors) {
-          PoolClass.clearGlobalConnections(this)
-        }
+          for (const PoolClass of constructors) {
+            PoolClass.clearGlobalConnections(this)
+          }
 
-        this._frontendTenantSqliteLifecycle.reset()
+          this._frontendTenantSqliteLifecycle.reset()
 
-        // Allow full re-initialization after connections are closed.
-        this._modelInitializationGeneration += 1
-        this._modelsInitialized = false
-        this._isInitialized = false
+          // Allow full re-initialization after connections are closed.
+          this._modelInitializationGeneration += 1
+          this._modelsInitialized = false
+          this._isInitialized = false
+        }
+      } catch (error) {
+        closeErrors.push(error instanceof Error ? error : new Error(String(error)))
       }
+
+      if (closeErrors.length === 1) throw closeErrors[0]
+      if (closeErrors.length > 1) throw new AggregateError(closeErrors, "Failed to close background-jobs and database resources")
     })()
 
     try {

package/build/environment-handlers/base.js

@@ -1,5 +1,6 @@
 // @ts-check
 
+import BackgroundJobsAdapterClient from "../background-jobs/adapter-client.js"
 import {validateTimeZone} from "../time-zone.js"
 
 /**
@@ -575,6 +576,25 @@ export default class VelociousEnvironmentHandlerBase {
     return
   }
 
+  /**
+   * Creates the environment's default persistence adapter.
+   * @abstract
+   * @param {{configuration: import("../configuration.js").default}} _args - Adapter options.
+   * @returns {import("../background-jobs/adapter.js").default} - Default adapter.
+   */
+  createBackgroundJobsAdapter(_args) {
+    throw new Error("This environment requires an explicit backgroundJobs.adapter")
+  }
+
+  /**
+   * Creates the platform-neutral producer path for an explicit adapter.
+   * @param {{configuration: import("../configuration.js").default}} args - Client options.
+   * @returns {import("../background-jobs/types.js").BackgroundJobsProducer} - Adapter-backed producer.
+   */
+  backgroundJobsClient(args) {
+    return new BackgroundJobsAdapterClient(args)
+  }
+
   /**
    * Runs require command.
    * @abstract

package/build/environment-handlers/node.js

@@ -2,6 +2,8 @@
 
 import "../database/annotations-async-hooks.js"
 import Base from "./base.js"
+import BackgroundJobsClient from "../background-jobs/client.js"
+import SqlBackgroundJobsAdapter from "../background-jobs/sql-adapter.js"
 import CliCommandsDestroyMigration from "./node/cli/commands/destroy/migration.js"
 import CliCommandsInit from "./node/cli/commands/init.js"
 import CliCommandsGenerateBaseModels from "./node/cli/commands/generate/base-models.js"
@@ -65,6 +67,25 @@ function pathWithinAllowedPrefixes(filePath, allowedPathPrefixes) {
 }
 
 export default class VelociousEnvironmentHandlerNode extends Base{
+  /**
+   * Creates the built-in SQL persistence adapter.
+   * @param {{configuration: import("../configuration.js").default}} args - Adapter options.
+   * @returns {SqlBackgroundJobsAdapter} - SQL adapter.
+   */
+  createBackgroundJobsAdapter({configuration}) {
+    return new SqlBackgroundJobsAdapter({configuration})
+  }
+
+  /**
+   * Preserves the Node TCP producer and main-process wake-up path. The main
+   * owns the configured persistence adapter; Node producers never bypass it.
+   * @param {{configuration: import("../configuration.js").default}} args - Client options.
+   * @returns {import("../background-jobs/types.js").BackgroundJobsProducer} - Producer client.
+   */
+  backgroundJobsClient({configuration}) {
+    return new BackgroundJobsClient({configuration})
+  }
+
   /**
    * Gives concurrent shared-transaction child jobs independent proxy sessions.
    * A configured single-connection pool shares mutable transaction state between
@@ -1100,26 +1121,12 @@ export default class VelociousEnvironmentHandlerNode extends Base{
    * @returns {Promise<void>} - Resolves when complete.
    */
   async ensureFrameworkSchema({dbs}) {
-    const {default: BackgroundJobsStore} = await import("../background-jobs/store.js")
-    const store = new BackgroundJobsStore({configuration: this.getConfiguration()})
-    const databaseIdentifier = store.getDatabaseIdentifier() ?? "default"
-    const frameworkDb = dbs[databaseIdentifier]
-
-    // Only ensure the framework schema when the background-jobs database is actually
-    // part of this migrate operation. When it isn't among the migrated set — e.g.
-    // `db:tenants:migrate <tenant>`, which migrates only tenant databases — the
-    // framework store lives elsewhere (typically the default DB) and was already
-    // ensured by the plain `db:migrate` that precedes it. Reaching into it here would
-    // open a fresh connection to that shared database once per tenant worker for
-    // schema work that is already applied. So skip when the framework DB isn't in
-    // this set; the runtime store still creates it lazily if a plain migrate never
-    // ran. Queue-cap reconciliation never runs on this path at all — it belongs to
-    // main-process startup (`BackgroundJobsStore#reconcileQueueConcurrency`).
-    if (!frameworkDb) return
-
-    // Reuse the connection db:migrate already holds for this database; opening a
-    // nested checkout would deadlock a database whose pool is capped at one connection.
-    await store.ensureSchema(frameworkDb)
+    // Migration passes its already checked-out DB into the adapter hook. Do not
+    // run runtime readiness here: SQL readiness would open a nested checkout and
+    // can deadlock a single-connection migration pool.
+    const adapter = this.getConfiguration().getBackgroundJobsAdapter()
+
+    await adapter.ensureFrameworkSchema({dbs})
   }
 
   /**

package/build/frontend-model-controller.js

@@ -175,7 +175,6 @@ const frontendModelJoinedPathsSymbol = Symbol("frontendModelJoinedPaths")
 const frontendModelGroupedColumnsSymbol = Symbol("frontendModelGroupedColumns")
 const frontendModelWhereNoMatchSymbol = Symbol("frontendModelWhereNoMatch")
 const frontendModelClientSafeErrorMessage = "Request failed."
-const frontendModelDebugErrorEnvironments = new Set(["development", "test"])
 
 /**
  * Builds a client-safe sync replay validation error.
@@ -277,10 +276,10 @@ function frontendModelVelociousMetadataForError(error) {
 /**
  * Runs frontend model client message for error.
  * @param {unknown} error - Caught error.
- * @param {boolean} forwardUnexpectedErrorMessage - Whether unexpected error messages may be exposed.
+ * @param {boolean} exposeInternalErrorsToClients - Whether unexpected error messages may be exposed.
  * @returns {string} - Message safe to return to API clients.
  */
-function frontendModelClientMessageForError(error, forwardUnexpectedErrorMessage) {
+function frontendModelClientMessageForError(error, exposeInternalErrorsToClients) {
   if (error instanceof RecordNotFoundError) {
     return "Record not found."
   }
@@ -301,7 +300,7 @@ function frontendModelClientMessageForError(error, forwardUnexpectedErrorMessage
     return error.message
   }
 
-  if (forwardUnexpectedErrorMessage && error instanceof Error) return error.message
+  if (exposeInternalErrorsToClients && error instanceof Error) return error.message
 
   return frontendModelClientSafeErrorMessage
 }
@@ -310,14 +309,11 @@ function frontendModelClientMessageForError(error, forwardUnexpectedErrorMessage
  * Runs frontend model debug payload for error.
  * @param {object} args - Arguments.
  * @param {import("./configuration.js").default} args.configuration - Current configuration.
- * @param {string} args.environment - Current environment.
  * @param {unknown} args.error - Caught error.
- * @returns {import("./configuration-types.js").ClientErrorPayloadReporterPayload} - Optional debug payload for non-production environments.
+ * @returns {import("./configuration-types.js").ClientErrorPayloadReporterPayload} - Optional internal error details when client exposure is enabled.
  */
-function frontendModelDebugPayloadForError({configuration, environment, error}) {
-  const debugAllowed = frontendModelDebugErrorEnvironments.has(environment) || environment !== "production" && configuration.getExposeInternalErrorsToClients()
-
-  if (!debugAllowed) {
+function frontendModelDebugPayloadForError({configuration, error}) {
+  if (!configuration.getExposeInternalErrorsToClients()) {
     return {}
   }
 
@@ -3259,10 +3255,9 @@ export default class FrontendModelController extends Controller {
    * Runs frontend model client error payload for error.
    * @param {unknown} error - Caught error.
    * @param {FrontendModelEndpointErrorContext | undefined} [endpointErrorContext] - Frontend-model endpoint error context.
-   * @param {{forwardUnexpectedErrorMessage?: boolean}} [options] - Client error rendering options.
    * @returns {Promise<import("./configuration-types.js").ClientErrorPayloadReporterPayload>} - Client payload for the current environment.
    */
-  async frontendModelClientErrorPayloadForError(error, endpointErrorContext, {forwardUnexpectedErrorMessage = false} = {}) {
+  async frontendModelClientErrorPayloadForError(error, endpointErrorContext) {
     const velociousMetadata = frontendModelVelociousMetadataForError(error)
     const normalizedError = error instanceof Error ? error : new Error(String(error))
     /** @type {import("./configuration-types.js").ClientErrorPayloadReporterPayload} */
@@ -3312,15 +3307,20 @@ export default class FrontendModelController extends Controller {
       request: this.getRequest()
     })
 
+    if (!this.getConfiguration().getExposeInternalErrorsToClients()) {
+      delete reporterPayload.debugBacktrace
+      delete reporterPayload.debugErrorClass
+      delete reporterPayload.debugErrorMessage
+    }
+
     return {
       ...reporterPayload,
       ...this.frontendModelErrorPayload(frontendModelClientMessageForError(
         error,
-        forwardUnexpectedErrorMessage && !this.getConfiguration().getSecureFrontendModelErrors()
+        this.getConfiguration().getExposeInternalErrorsToClients()
       )),
       ...frontendModelDebugPayloadForError({
         configuration: this.getConfiguration(),
-        environment: this.getConfiguration().getEnvironment(),
         error
       }),
       ...(velociousMetadata ? {velocious: velociousMetadata} : {}),
@@ -4397,9 +4397,7 @@ export default class FrontendModelController extends Controller {
 
         responses.push({
           requestId,
-          response: await this.frontendModelClientErrorPayloadForError(error, errorContext, {
-            forwardUnexpectedErrorMessage: !isBuiltInCommand
-          })
+          response: await this.frontendModelClientErrorPayloadForError(error, errorContext)
         })
       }
     }
@@ -4623,9 +4621,7 @@ export default class FrontendModelController extends Controller {
       await this.frontendModelLogEndpointError({error, errorContext})
 
       await this.render({
-        json: /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (serializeFrontendModelTransportValue(await this.frontendModelClientErrorPayloadForError(error, errorContext, {
-          forwardUnexpectedErrorMessage: true
-        }), this.transportSerializationOptions()))
+        json: /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (serializeFrontendModelTransportValue(await this.frontendModelClientErrorPayloadForError(error, errorContext), this.transportSerializationOptions()))
       })
     }
   }

package/build/jobs/prune-terminal-background-jobs.js

@@ -1,6 +1,5 @@
 // @ts-check
 
-import BackgroundJobsStore from "../background-jobs/store.js"
 import Configuration from "../configuration.js"
 import VelociousJob from "../background-jobs/job.js"
 
@@ -59,9 +58,9 @@ export default class PruneTerminalBackgroundJobsJob extends VelociousJob {
   async perform() {
     const configuration = Configuration.current()
     const config = configuration.getBackgroundJobsConfig()
-    const store = new BackgroundJobsStore({configuration, databaseIdentifier: config.databaseIdentifier})
+    const adapter = await configuration.acquireReadyBackgroundJobsAdapter()
 
-    await store.pruneTerminalJobs({
+    await adapter.pruneTerminalJobs({
       completedTtlMs: config.retention.completedTtlMs,
       failedTtlMs: config.retention.failedTtlMs,
       batchSize: config.retention.batchSize

package/build/src/background-jobs/adapter-client.d.ts

@@ -0,0 +1,41 @@
+/** Platform-neutral producer client for a configured adapter. */
+export default class BackgroundJobsAdapterClient {
+    configuration: import("../configuration.js").default;
+    /**
+     * Creates an adapter-backed producer.
+     * @param {{configuration: import("../configuration.js").default}} args - Client options.
+     */
+    constructor({ configuration }: {
+        configuration: import("../configuration.js").default;
+    });
+    /**
+     * Enqueues a job through the configured adapter.
+     * @param {{jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} args - Job request.
+     * @returns {Promise<string>} - Job id.
+     */
+    enqueue(args: {
+        jobName: string;
+        args: Array<ReturnType<typeof JSON.parse>>;
+        options?: import("./types.js").BackgroundJobOptions;
+    }): Promise<string>;
+    /**
+     * Replaces a stable schedule through the configured adapter.
+     * @param {{scheduleKey: string, jobName: string, args: Array<ReturnType<typeof JSON.parse>>, options?: import("./types.js").BackgroundJobOptions}} args - Replacement request.
+     * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
+     */
+    replaceScheduled(args: {
+        scheduleKey: string;
+        jobName: string;
+        args: Array<ReturnType<typeof JSON.parse>>;
+        options?: import("./types.js").BackgroundJobOptions;
+    }): Promise<import("./types.js").BackgroundJobReplacementResult>;
+    /**
+     * Cancels a stable schedule through the configured adapter.
+     * @param {{scheduleKey: string}} args - Cancellation request.
+     * @returns {Promise<import("./types.js").BackgroundJobCancellationResult>} - Cancellation result.
+     */
+    cancelScheduled({ scheduleKey }: {
+        scheduleKey: string;
+    }): Promise<import("./types.js").BackgroundJobCancellationResult>;
+}
+//# sourceMappingURL=adapter-client.d.ts.map

package/build/src/background-jobs/adapter-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-client.d.ts","sourceRoot":"","sources":["../../../src/background-jobs/adapter-client.js"],"names":[],"mappings":"AAEA,iEAAiE;AACjE,MAAM,CAAC,OAAO,OAAO,2BAA2B;IAMvC,aAAa;IALpB;;;OAGG;IACH,YAAY,EAAC,aAAa,EAAC,EAFhB;QAAC,aAAa,EAAE,OAAO,qBAAqB,EAAE,OAAO,CAAA;KAErC,EAE1B;IAED;;;;OAIG;IACG,OAAO,CAAC,IAAI,EAHP;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,YAAY,EAAE,oBAAoB,CAAA;KAG1G,GAFL,OAAO,CAAC,MAAM,CAAC,CAM3B;IAED;;;;OAIG;IACG,gBAAgB,CAAC,IAAI,EAHhB;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,YAAY,EAAE,oBAAoB,CAAA;KAGtH,GAFd,OAAO,CAAC,OAAO,YAAY,EAAE,8BAA8B,CAAC,CAMxE;IAED;;;;OAIG;IACG,eAAe,CAAC,EAAC,WAAW,EAAC,EAHxB;QAAC,WAAW,EAAE,MAAM,CAAA;KAGI,GAFtB,OAAO,CAAC,OAAO,YAAY,EAAE,+BAA+B,CAAC,CAMzE;CACF"}