velocious 1.0.631 → 1.0.632

package/README.md

@@ -32,11 +32,12 @@
 * Per-record ability checks via `.abilities(...)` on frontend queries + `record.can(action)` (see [docs/abilities.md](docs/abilities.md))
 * Translated model attributes with current-locale relationship sorting (see [docs/translations.md](docs/translations.md))
 * Cross-process broadcast bus for `broadcastToChannel` via `velocious beacon`, including background job runner processes (see [docs/beacon.md](docs/beacon.md))
+* Rails-style application process initializer teardown with immutable process identity, reverse idempotent shutdown, and explicit HTTP/background-job ownership (see [docs/application-process-lifecycle.md](docs/application-process-lifecycle.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 Node SQL/TCP workers plus a Browser/Expo local SQLite store and in-process dispatcher, including failure events, authorized database-scoped dashboard counts, and an opt-in release-scoped main/worker generation protocol with acknowledged activation, asynchronous retirement, and retired-main recovery. Production compliance additionally requires downstream supervisor retention/activation ordering and release pins (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))
+* Rails-style request and database query logging with structured credential redaction (see [docs/logging.md](docs/logging.md))
 * EJS-backed mailers with delivery, queueing, and payload rendering support (see [docs/mailers.md](docs/mailers.md))
 * Trusted reverse proxy handling for `request.remoteAddress()` (see [docs/trusted-proxies.md](docs/trusted-proxies.md))
 * In-process driver schema metadata caching (see [docs/schema-metadata-cache.md](docs/schema-metadata-cache.md))
@@ -60,6 +61,12 @@ npx velocious init
 
 By default, Velocious looks for your configuration in `src/config/configuration.js`. If you keep the configuration elsewhere, make sure your app imports it early and calls `configuration.setCurrent()`.
 
+Application initializers may implement `teardown()` and inspect their frozen
+`getProcessContext()` value. Long-lived process owners call
+`configuration.shutdown()` before framework connection cleanup; see the
+[application process lifecycle guide](docs/application-process-lifecycle.md) for
+promise identity, errors, process types, and pooled/forked runner semantics.
+
 # Node SQLite driver
 
 Projects using `velocious/build/src/database/drivers/sqlite/index.js` must install its optional peer dependencies:
@@ -1908,7 +1915,8 @@ const configuration = new Configuration({
     console: false,            // disable console output
     file: true,                // enable file output
     directory: "/custom/logs", // optional, defaults to "<project>/log" in Node
-    filePath: "/tmp/app.log"   // optional explicit path
+    filePath: "/tmp/app.log",  // optional explicit path
+    sensitiveNames: ["integrationPin"] // optional app-specific additions
   }
 })
 ```
@@ -1969,6 +1977,8 @@ Model queries use operation names such as `Task Load`, `Task Count`, `Task Pluck
 
 Query logging defaults to off in the `test` environment to keep CI output quiet and is skipped when no output emits `info`. Override it with `logging: {queryLogging: true}` when a test build should write SQL timing logs, and use the normal logging output settings to send those logs to console or file.
 
+- **Credential redaction**: Request headers, parsed body/params, nested arrays, URL queries, WebSocket authentication params, rendered SQL diagnostics, and request/frontend-model errors are redacted before formatting and output fan-out. Defaults match common authorization, authentication, credential, password, secret, token, API-key, cookie/session, and base64-content name variants case-insensitively. Add application names with `logging.sensitiveNames`; entries must be non-blank strings. Exact request-scoped values are replaced in SQL/error text while safe fields, SQL shape, timing, source lines, error class/backtrace, and correlation metadata remain visible. Import `LOG_REDACTION_MARKER` from `velocious/build/src/log-redactor.js` when code needs to compare the deterministic marker. See [logging and credential redaction](docs/logging.md#credential-redaction).
+
 ## Listen for framework errors
 
 Velocious emits framework errors (including uncaught controller action errors) on the configuration error event bus:

package/build/application.js

@@ -9,6 +9,7 @@ import SyncPublisher from "./sync/sync-publisher.js"
 import SyncWebsocketChannel from "./sync/sync-websocket-channel.js"
 import websocketEventsHost from "./http-server/websocket-events-host.js"
 import restArgsError from "./utils/rest-args-error.js"
+import { runShutdownSteps } from "./utils/shutdown-lifecycle.js"
 
 /**
  * HttpServerConfiguration type.
@@ -40,6 +41,8 @@ export default class VelociousApplication {
      * Stores the http server lock value.
      * @type {HttpServerLock | undefined} */
     this.httpServerLock = undefined
+    /** @type {Promise<void> | undefined} */
+    this._stopPromise = undefined
   }
 
   /**
@@ -186,17 +189,34 @@ export default class VelociousApplication {
    * Runs stop.
    * @returns {Promise<void>} - Resolves when complete.
    */
-  async stop() {
-    await this.logger.debug("Stopping server")
+  stop() {
+    if (!this._stopPromise) this._stopPromise = this._stop()
 
-    try {
-      await this.httpServer?.stop()
-      this.configuration._httpServerInstance = undefined
-      await this.configuration.disconnectBeacon()
-      await this.configuration.closeDatabaseConnections()
-    } finally {
-      await this.releaseHttpServerLock()
-    }
+    return this._stopPromise
+  }
+
+  /**
+   * Stops application and framework resources.
+   * @returns {Promise<void>} - Resolves after every application and framework close succeeds.
+   */
+  async _stop() {
+    await runShutdownSteps({
+      message: "Application and framework shutdown failed",
+      steps: [
+        async () => await this.logger.debug("Stopping server"),
+        async () => {
+          try {
+            await this.httpServer?.stop()
+          } finally {
+            this.configuration._httpServerInstance = undefined
+          }
+        },
+        async () => await this.configuration.shutdown(),
+        async () => await this.configuration.disconnectBeacon(),
+        async () => await this.configuration.closeDatabaseConnections(),
+        async () => await this.releaseHttpServerLock()
+      ]
+    })
   }
 
   /**

package/build/background-jobs/forked-runner-child.js

@@ -10,8 +10,8 @@ import setRunnerProcessTitle from "./runner-process-title.js"
 // which jobs are running, how many of each, and which are eating resources.
 setRunnerProcessTitle()
 
-let finishing = false
-let shuttingDown = false
+/** @type {Promise<void> | undefined} */
+let shutdownPromise
 
 /**
  * Closes the runner's connections — releasing any advisory lock a killed-mid-job
@@ -21,12 +21,15 @@ let shuttingDown = false
  * @param {number} exitCode - Process exit code.
  * @returns {Promise<void>}
  */
-async function shutdownRunner(exitCode) {
-  if (shuttingDown || finishing) return
-  shuttingDown = true
+function shutdownRunner(exitCode) {
+  if (shutdownPromise) return shutdownPromise
 
-  await closeRunnerConnections(currentConfigurationOrNull())
-  process.exit(exitCode)
+  shutdownPromise = (async () => {
+    await closeRunnerConnections(currentConfigurationOrNull())
+    process.exit(exitCode)
+  })()
+
+  return shutdownPromise
 }
 
 /**
@@ -45,25 +48,13 @@ function isJobMessage(message) {
 /**
  * Runs finish.
  * @param {number} exitCode - Process exit code.
- * @returns {void}
+ * @returns {Promise<void>}
  */
-function finish(exitCode) {
-  finishing = true
-  process.exitCode = exitCode
-
-  if (process.connected && process.disconnect) {
-    process.disconnect()
+async function finish(exitCode) {
+  if (process.send) {
+    await new Promise((resolve) => process.send?.({type: "job-reported"}, () => resolve(undefined)))
   }
-
-  setImmediate(() => process.exit(exitCode))
-}
-
-/**
- * Runs report job finished.
- * @returns {void}
- */
-function reportJobFinished() {
-  if (process.send) process.send({type: "job-reported"})
+  await shutdownRunner(exitCode)
 }
 
 /**
@@ -79,7 +70,10 @@ async function runJobMessage(message) {
   // The per-job process title (and its restore) is set inside runJobPayload,
   // which reads the job class's `static processTitle`. This process boots with
   // the base "velocious background-jobs-runner" title set at module load above.
-  await runJobPayload(message.payload, {closeConnections: false})
+  await runJobPayload(message.payload, {
+    closeConnections: false,
+    processType: "background-jobs-forked-runner"
+  })
 }
 
 /**
@@ -88,15 +82,17 @@ async function runJobMessage(message) {
  * @returns {Promise<void>} - Resolves after completion is reported.
  */
 async function handleJobMessage(message) {
+  let exitCode
+
   try {
     await runJobMessage(message)
-    reportJobFinished()
-    finish(0)
+    exitCode = 0
   } catch (error) {
-    reportJobFinished()
     console.error("Forked background job runner failed:", error)
-    finish(1)
+    exitCode = 1
   }
+
+  await finish(exitCode)
 }
 
 for (const signal of ["SIGTERM", "SIGINT"]) {
@@ -104,7 +100,7 @@ for (const signal of ["SIGTERM", "SIGINT"]) {
 }
 
 process.once("disconnect", () => {
-  if (!finishing) void shutdownRunner(0)
+  void shutdownRunner(0)
 })
 
 process.once("message", (message) => {

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

@@ -4,6 +4,7 @@ import configurationResolver from "../configuration-resolver.js"
 import BackgroundJobRegistry from "./job-registry.js"
 import BackgroundJobsStatusReporter from "./status-reporter.js"
 import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
+import { closeRunnerConnections } from "./runner-graceful-shutdown.js"
 
 const BEACON_READY_TIMEOUT_MS = 5000
 
@@ -80,12 +81,13 @@ function runnerProcessTitle(JobClass, payload) {
  * @param {object} [options] - Runner options.
  * @param {boolean} [options.closeConnections] - Whether to gracefully close framework connections after the job.
  * @param {boolean} [options.manageProcessTitle] - Whether to set the per-job process title and restore it afterwards. Off for concurrent pooled runners, where interleaved snapshot/restore of the single process-wide `process.title` would corrupt it; the pooled child owns an aggregate title instead.
+ * @param {string} [options.processType] - Generic application process type.
  * @returns {Promise<"completed" | "rescheduled">} - Acknowledged outcome.
  */
-export default async function runJobPayload(payload, {closeConnections = true, manageProcessTitle = true} = {}) {
+export default async function runJobPayload(payload, {closeConnections = true, manageProcessTitle = true, processType = "background-jobs-runner"} = {}) {
   const configuration = await configurationResolver()
   configuration.setCurrent()
-  await configuration.initialize({type: "background-jobs-runner"})
+  await configuration.initialize({type: processType})
   await connectBeacon(configuration)
   const reporter = new BackgroundJobsStatusReporter({configuration})
 
@@ -167,11 +169,7 @@ export default async function runJobPayload(payload, {closeConnections = true, m
     // one) doesn't misreport a finished job as still running.
     if (manageProcessTitle) process.title = previousTitle
     if (closeConnections) {
-      try {
-        await configuration.disconnectBeacon()
-      } finally {
-        await configuration.closeDatabaseConnections()
-      }
+      await closeRunnerConnections(configuration)
     }
   }
 }

package/build/background-jobs/main.js

@@ -7,7 +7,7 @@ import BackgroundJobsScheduler from "./scheduler.js"
 import Logger from "../logger.js"
 import PruneTerminalBackgroundJobsJob from "../jobs/prune-terminal-background-jobs.js"
 import VelociousError from "../velocious-error.js"
-import shutdownLifecycle from "../utils/shutdown-lifecycle.js"
+import shutdownLifecycle, { runShutdownSteps } from "../utils/shutdown-lifecycle.js"
 import { validateGenerationId, workerIdBelongsToGeneration } from "./generation-identity.js"
 import BackgroundJobsLifecycleControlServer from "./lifecycle-control-server.js"
 
@@ -330,13 +330,19 @@ export default class BackgroundJobsMain {
         this._startGenerationRecoveryOwnership()
       }
     } catch (error) {
+      let cleanupError
+
       try {
         await this.stop()
-      } catch (cleanupError) {
+      } catch (caughtCleanupError) {
+        cleanupError = caughtCleanupError
+      }
+
+      if (cleanupError) {
         throw new AggregateError(
           [error, cleanupError],
           "Background jobs main startup and cleanup failed",
-          {cause: cleanupError}
+          {cause: error}
         )
       }
 
@@ -440,31 +446,30 @@ export default class BackgroundJobsMain {
    * Runs stop beacon and server.
    * @returns {Promise<void>} */
   async _stopBeaconAndServer() {
-    try {
-      await this.lifecycleControlServer?.close()
-      this.lifecycleControlServer = undefined
-    } finally {
-      try {
-        await this.configuration.disconnectBeacon()
-      } finally {
-        await this._closeServerAndDatabaseConnections()
-      }
-    }
-  }
-
-  /**
-   * Runs close server and database connections.
-   * @returns {Promise<void>} */
-  async _closeServerAndDatabaseConnections() {
-    try {
-      await this._closeServer()
-    } finally {
-      if (this.closeDatabaseConnectionsOnStop) {
-        await this.configuration.closeDatabaseConnections()
-      } else {
-        await this.configuration.closeBackgroundJobsAdapter()
-      }
-    }
+    await runShutdownSteps({
+      message: "Background jobs main application and framework shutdown failed",
+      steps: [
+        async () => {
+          try {
+            await this.lifecycleControlServer?.close()
+          } finally {
+            this.lifecycleControlServer = undefined
+          }
+        },
+        ...(this.closeDatabaseConnectionsOnStop
+          ? [async () => await this.configuration.shutdown()]
+          : []),
+        async () => await this.configuration.disconnectBeacon(),
+        async () => await this._closeServer(),
+        async () => {
+          if (this.closeDatabaseConnectionsOnStop) {
+            await this.configuration.closeDatabaseConnections()
+          } else {
+            await this.configuration.closeBackgroundJobsAdapter()
+          }
+        }
+      ]
+    })
   }
 
   /**

package/build/background-jobs/pooled-runner-child.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 import runJobPayload, { BackgroundJobPerformedFailure } from "./job-runner.js"
-import { closeRunnerConnections, currentConfigurationOrNull } from "./runner-graceful-shutdown.js"
+import { closeRunnerConnections, closeRunnerFrameworkConnections, currentConfigurationOrNull } from "./runner-graceful-shutdown.js"
 import setRunnerProcessTitle from "./runner-process-title.js"
 import PooledRunnerBrokerIdentity from "./pooled-runner-broker-identity.js"
 import { runWithSharedTransactionBrokerConfig } from "../testing/shared-transaction-proxy-driver.js"
@@ -10,7 +10,8 @@ const BASE_PROCESS_TITLE = "velocious background-jobs-runner"
 
 setRunnerProcessTitle()
 
-let shuttingDown = false
+/** @type {Promise<void> | undefined} */
+let shutdownPromise
 
 /**
  * Closes the runner's connections — releasing any advisory lock a killed-mid-pass
@@ -19,12 +20,15 @@ let shuttingDown = false
  * @param {number} exitCode - Process exit code.
  * @returns {Promise<void>}
  */
-async function shutdownRunner(exitCode) {
-  if (shuttingDown) return
-  shuttingDown = true
+function shutdownRunner(exitCode) {
+  if (shutdownPromise) return shutdownPromise
 
-  await closeRunnerConnections(currentConfigurationOrNull())
-  process.exit(exitCode)
+  shutdownPromise = (async () => {
+    await closeRunnerConnections(currentConfigurationOrNull())
+    process.exit(exitCode)
+  })()
+
+  return shutdownPromise
 }
 
 /**
@@ -36,7 +40,7 @@ async function shutdownRunner(exitCode) {
  */
 const runningJobIds = new Set()
 const brokerIdentity = new PooledRunnerBrokerIdentity({
-  closeConnections: async () => await closeRunnerConnections(currentConfigurationOrNull())
+  closeConnections: async () => await closeRunnerFrameworkConnections(currentConfigurationOrNull())
 })
 
 /**
@@ -107,7 +111,11 @@ async function runJob(payload, sharedTransactionBroker) {
   try {
     const status = await runWithSharedTransactionBrokerConfig(sharedTransactionBroker, async () => {
       return await brokerIdentity.run(sharedTransactionBroker, async () => {
-        return await runJobPayload(payload, {closeConnections: false, manageProcessTitle: false})
+        return await runJobPayload(payload, {
+          closeConnections: false,
+          manageProcessTitle: false,
+          processType: "background-jobs-pooled-runner"
+        })
       })
     })
     await sendOutcome({jobId: payload.id, acknowledged: true, status})

package/build/background-jobs/runner-graceful-shutdown.js

@@ -3,12 +3,13 @@
 import timeout from "awaitery/build/timeout.js"
 
 import Configuration, {CurrentConfigurationNotSetError} from "../configuration.js"
+import { runShutdownSteps } from "../utils/shutdown-lifecycle.js"
 
 /**
  * The subset of a configuration a runner closes on shutdown. Typed structurally so
  * the shutdown path stays typechecked without a broad cast, and a future signature
  * drift surfaces at the call sites (and in tests) instead of hiding behind `any`.
- * @typedef {{disconnectBeacon: () => Promise<void>, closeDatabaseConnections: () => Promise<void>}} RunnerCloseableConfiguration
+ * @typedef {{disconnectBeacon: () => Promise<void>, closeDatabaseConnections: () => Promise<void>, shutdown: () => Promise<void>}} RunnerCloseableConfiguration
  */
 /** Bounded grace for closing framework connections on shutdown before forcing exit. */
 const SHUTDOWN_CLOSE_TIMEOUT_MS = 5000
@@ -39,19 +40,34 @@ const SHUTDOWN_CLOSE_TIMEOUT_MS = 5000
 export async function closeRunnerConnections(configuration, closeTimeoutMs = SHUTDOWN_CLOSE_TIMEOUT_MS) {
   if (!configuration) return
 
-  const [beaconResult, databaseResult] = await Promise.allSettled([
+  await runShutdownSteps({
+    message: "Failed to close background-job runner application and framework resources",
+    steps: [
+      async () => await timeout({timeout: closeTimeoutMs}, () => configuration.shutdown()),
+      async () => await closeRunnerFrameworkConnections(configuration, closeTimeoutMs)
+    ]
+  })
+}
+
+/**
+ * Closes only a pooled runner's framework connections while its application
+ * process lifecycle remains active for later jobs.
+ * @param {RunnerCloseableConfiguration | null} configuration - Configuration whose framework connections to close.
+ * @param {number} [closeTimeoutMs] - Max time for each framework close.
+ * @returns {Promise<void>} - Resolves after framework cleanup.
+ */
+export async function closeRunnerFrameworkConnections(configuration, closeTimeoutMs = SHUTDOWN_CLOSE_TIMEOUT_MS) {
+  if (!configuration) return
+
+  const results = await Promise.allSettled([
     timeout({timeout: closeTimeoutMs}, () => configuration.disconnectBeacon()),
     timeout({timeout: closeTimeoutMs}, () => configuration.closeDatabaseConnections())
   ])
+  const steps = results.map((result) => async () => {
+    if (result.status === "rejected") throw result.reason
+  })
 
-  /** @type {unknown[]} */
-  const errors = []
-
-  if (beaconResult.status == "rejected") errors.push(beaconResult.reason)
-  if (databaseResult.status == "rejected") errors.push(databaseResult.reason)
-
-  if (errors.length == 1) throw errors[0]
-  if (errors.length > 1) throw new AggregateError(errors, "Failed to close background-job runner connections on shutdown")
+  await runShutdownSteps({message: "Failed to close background-job runner framework resources", steps})
 }
 
 /**

package/build/background-jobs/worker.js

@@ -8,7 +8,7 @@ import configurationResolver from "../configuration-resolver.js"
 import BackgroundJobsStatusReporter from "./status-reporter.js"
 import { randomUUID } from "crypto"
 import { fileURLToPath } from "node:url"
-import shutdownLifecycle from "../utils/shutdown-lifecycle.js"
+import shutdownLifecycle, { runShutdownSteps } from "../utils/shutdown-lifecycle.js"
 import BackgroundJobRescheduleSignal from "./reschedule-signal.js"
 import performBackgroundJob from "./perform-job.js"
 import { createGenerationWorkerId } from "./generation-identity.js"
@@ -295,13 +295,19 @@ export default class BackgroundJobsWorker {
     try {
       await this._connect({allowReconnect: false})
     } catch (error) {
+      let cleanupError
+
       try {
         await this.stop()
-      } catch (cleanupError) {
+      } catch (caughtCleanupError) {
+        cleanupError = caughtCleanupError
+      }
+
+      if (cleanupError) {
         throw new AggregateError(
           [error, cleanupError],
           "Background jobs worker startup and cleanup failed",
-          {cause: cleanupError}
+          {cause: error}
         )
       }
 
@@ -391,11 +397,7 @@ export default class BackgroundJobsWorker {
         if (this.jsonSocket) this.jsonSocket.close()
         if (!this.configuration) return
 
-        try {
-          await this.configuration.disconnectBeacon()
-        } finally {
-          if (this.closeDatabaseConnectionsOnStop) await this.configuration.closeDatabaseConnections()
-        }
+        await this._closeConfiguration()
       }
     })
   }
@@ -448,15 +450,34 @@ export default class BackgroundJobsWorker {
         if (this.jsonSocket) this.jsonSocket.close()
         if (!this.configuration) return
 
-        try {
-          await this.configuration.disconnectBeacon()
-        } finally {
-          if (this.closeDatabaseConnectionsOnStop) await this.configuration.closeDatabaseConnections()
-        }
+        await this._closeConfiguration()
       }
     })
   }
 
+  /**
+   * Closes application resources before framework resources when this worker owns them.
+   * @returns {Promise<void>} - Resolves after every owned close succeeds.
+   */
+  async _closeConfiguration() {
+    const configuration = this.configuration
+
+    if (!configuration) return
+
+    await runShutdownSteps({
+      message: "Background jobs worker application and framework shutdown failed",
+      steps: [
+        ...(this.closeDatabaseConnectionsOnStop
+          ? [async () => await configuration.shutdown()]
+          : []),
+        async () => await configuration.disconnectBeacon(),
+        ...(this.closeDatabaseConnectionsOnStop
+          ? [async () => await configuration.closeDatabaseConnections()]
+          : [])
+      ]
+    })
+  }
+
   /**
    * Waits for a set of in-flight job promises to settle, optionally bounded by
    * `timeoutMs`.

package/build/configuration-types.js

@@ -4,6 +4,13 @@
  * @module types
  */
 
+/**
+ * Immutable identity shared by application initializers for one process lifecycle.
+ * @typedef {object} ApplicationProcessContext
+ * @property {string} type - Generic process type supplied to `configuration.initialize()`.
+ * @property {string} instanceId - Opaque identity unique to this lifecycle.
+ */
+
 /**
  * @typedef {(args: {request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default, response: import("./http-server/client/response.js").default}) => Promise<void>} CorsType
  */
@@ -133,6 +140,7 @@
  * @property {Array<"debug-low-level" | "debug" | "info" | "warn" | "error">} [levels] - Override which log levels are emitted.
  * @property {boolean} [debugLowLevel] - Convenience flag to include very low-level debug logs.
  * @property {boolean} [queryLogging] - Enable/disable database query logging. Defaults to true outside test and false in test.
+ * @property {string[]} [sensitiveNames] - Additional case-insensitive sensitive header/parameter names to redact from logging.
  * @property {LoggerConfig[]} [loggers] - Logger instances (converted to outputs when configured).
  * @property {LoggingOutputConfig[]} [outputs] - Explicit logger outputs (overrides console/file defaults when provided).
  */