velocious 1.0.631 → 1.0.633

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).
  */

package/build/configuration.js

@@ -22,6 +22,7 @@
 
 import { digg } from "diggerize"
 import gettextConfig from "gettext-universal/build/src/config.js"
+import UUID from "pure-uuid"
 import translate from "gettext-universal/build/src/translate.js"
 import Ability from "./authorization/ability.js"
 import BackgroundJobsAdapter from "./background-jobs/adapter.js"
@@ -31,6 +32,7 @@ import EventEmitter from "./utils/event-emitter.js"
 import VelociousWebsocketChannelSubscribers from "./http-server/websocket-channel-subscribers.js"
 import { CurrentConfigurationNotSetError, currentConfiguration, setCurrentConfiguration } from "./current-configuration.js"
 import { requestDetails } from "./error-reporting/request-details.js"
+import LogRedactor from "./log-redactor.js"
 import { frontendModelApiManifest, frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcesForBackendProject } from "./frontend-models/resource-definition.js"
 import { currentOfflineGrantSigningKey, normalizeOfflineGrantSigningKey } from "./sync/offline-grant.js"
 import PluginRoutes from "./routes/plugin-routes.js"
@@ -41,6 +43,7 @@ import { withTrackedStack } from "./utils/with-tracked-stack.js"
 import VelociousPackage from "./packages/velocious-package.js"
 import FrontendTenantSqliteLifecycle from "./tenants/frontend-tenant-sqlite-lifecycle.js"
 import { resolveGenerationId, resolveInitialGenerationState, resolveLifecycleSocketPath } from "./background-jobs/generation-identity.js"
+import { runShutdownSteps } from "./utils/shutdown-lifecycle.js"
 
 export { CurrentConfigurationNotSetError }
 
@@ -303,6 +306,16 @@ export default class VelociousConfiguration {
     }
 
     this._isInitialized = false
+    /** @type {import("./configuration-types.js").ApplicationProcessContext | undefined} */
+    this._applicationProcessContext = undefined
+    /** @type {import("./initializer.js").default[]} */
+    this._successfulInitializers = []
+    /** @type {boolean} */
+    this._applicationLifecycleInitialized = false
+    /** @type {Promise<void> | undefined} */
+    this._shutdownPromise = undefined
+    /** @type {Promise<void> | undefined} */
+    this._queuedInitializePromise = undefined
     this._modelsInitialized = false
     /**
      * Invalidates model phases that started before database connections closed.
@@ -323,6 +336,8 @@ export default class VelociousConfiguration {
      * @type {Promise<void> | undefined}
      */
     this._initializePromise = undefined
+    /** @type {number | undefined} */
+    this._initializePromiseGeneration = undefined
     const websocketInboundQueue = httpServer?.websocketInboundQueue
     const websocketOutboundQueue = httpServer?.websocketOutboundQueue
 
@@ -425,6 +440,7 @@ export default class VelociousConfiguration {
      * @type {((session: import("./http-server/client/websocket-session.js").default) => ReturnType<typeof JSON.parse> | Promise<ReturnType<typeof JSON.parse>>) | null} */
     this._websocketSessionIdentityResolver = null
     this._logging = logging
+    this._logRedactor = new LogRedactor({sensitiveNames: logging?.sensitiveNames})
     this._mailerBackend = mailerBackend
     this._routeResolverHooks = [...(routeResolverHooks || [])]
     this._addDebugEndpointRouteHook()
@@ -1445,6 +1461,14 @@ export default class VelociousConfiguration {
     }
   }
 
+  /**
+   * Gets the configuration-owned structured logging redactor.
+   * @returns {LogRedactor} - Structured logging redactor.
+   */
+  getLogRedactor() {
+    return this._logRedactor
+  }
+
   /**
    * Runs get query logging enabled.
    * @returns {boolean} - Whether database query logging is enabled.
@@ -2364,49 +2388,152 @@ export default class VelociousConfiguration {
    * @param {string} args.type - Type identifier.
    * @returns {Promise<void>} - Resolves when complete.
    */
-  async initialize({type} = {type: "undefined"}) {
+  initialize({type} = {type: "undefined"}) {
+    if (this._queuedInitializePromise) return this._queuedInitializePromise
+
+    if (this._shutdownPromise) {
+      return this._queueInitialize({continueAfterWaitFailure: true, type, waitFor: this._shutdownPromise})
+    }
+
     if (this._closeDatabaseConnectionsPromise) {
-      await this._closeDatabaseConnectionsPromise
+      return this._queueInitialize({continueAfterWaitFailure: false, type, waitFor: this._closeDatabaseConnectionsPromise})
     }
 
+    return this._beginInitialize({type})
+  }
+
+  /**
+   * Starts or joins initialization after lifecycle blockers have settled.
+   * @param {object} args - Startup options.
+   * @param {string} args.type - Generic application process type.
+   * @returns {Promise<void>} - Shared startup promise.
+   */
+  _beginInitialize({type}) {
     const initializationGeneration = this._modelInitializationGeneration
 
-    if (this._isInitialized) return
+    if (this._initializePromise && this._initializePromiseGeneration === initializationGeneration) {
+      return this._initializePromise
+    }
+
+    if (this._initializePromise) {
+      return this._queueInitialize({continueAfterWaitFailure: false, type, waitFor: this._initializePromise})
+    }
+
+    if (this._isInitialized) {
+      this._initializePromise = Promise.resolve()
+      this._initializePromiseGeneration = initializationGeneration
+
+      return this._initializePromise
+    }
     // Memoize the in-progress initialization so concurrent callers await the same
     // bootstrap instead of racing. `_isInitialized` was previously set to `true`
     // up front, so a second caller (e.g. a pooled runner with
     // `pooledRunnerConcurrency > 1` starting several jobs on a cold child) could
     // skip initialization and load models / perform a job while the first call
     // was still awaiting model discovery and initializers. Mirrors connectBeacon.
-    if (this._initializePromise) {
-      const initializePromise = this._initializePromise
+    const initializePromise = this._runInitialize({initializationGeneration, type})
+
+    this._initializePromise = initializePromise
+    this._initializePromiseGeneration = initializationGeneration
 
-      await initializePromise
+    return initializePromise
+  }
 
-      if (this._modelInitializationGeneration === initializationGeneration && !this._isInitialized) {
-        if (this._initializePromise === initializePromise) {
+  /**
+   * Queues one shared initialization behind an incompatible lifecycle phase.
+   * @param {object} args - Queue options.
+   * @param {boolean} args.continueAfterWaitFailure - Whether a completed failed shutdown still permits replacement startup.
+   * @param {string} args.type - Replacement process type.
+   * @param {Promise<void>} args.waitFor - Lifecycle phase that must settle first.
+   * @returns {Promise<void>} - Shared queued startup promise.
+   */
+  _queueInitialize({continueAfterWaitFailure, type, waitFor}) {
+    if (this._queuedInitializePromise) return this._queuedInitializePromise
+
+    const queuedInitializePromise = (async () => {
+      await this._waitForInitializeBlocker({continueAfterWaitFailure, waitFor})
+
+      if (this._shutdownPromise === waitFor) this._shutdownPromise = undefined
+      if (this._initializePromise === waitFor) {
+        this._initializePromise = undefined
+        this._initializePromiseGeneration = undefined
+      }
+
+      const shutdownPromise = this._shutdownPromise
+
+      if (shutdownPromise) {
+        await this._waitForInitializeBlocker({continueAfterWaitFailure: true, waitFor: shutdownPromise})
+        if (this._shutdownPromise === shutdownPromise) this._shutdownPromise = undefined
+      }
+
+      if (this._initializePromise && this._initializePromiseGeneration !== this._modelInitializationGeneration) {
+        const staleInitializePromise = this._initializePromise
+
+        await staleInitializePromise
+        if (this._initializePromise === staleInitializePromise) {
           this._initializePromise = undefined
+          this._initializePromiseGeneration = undefined
         }
-
-        return await this.initialize({type})
       }
 
-      return
+      await this._beginInitialize({type})
+    })().finally(() => {
+      this._queuedInitializePromise = undefined
+    })
+
+    this._queuedInitializePromise = queuedInitializePromise
+
+    return queuedInitializePromise
+  }
+
+  /**
+   * Waits for a lifecycle phase before queued initialization proceeds.
+   * @param {object} args - Wait policy.
+   * @param {boolean} args.continueAfterWaitFailure - Whether replacement startup remains available after a failed phase.
+   * @param {Promise<void>} args.waitFor - Lifecycle phase that must settle first.
+   * @returns {Promise<void>} - Resolves when queued initialization may continue.
+   */
+  async _waitForInitializeBlocker({continueAfterWaitFailure, waitFor}) {
+    try {
+      await waitFor
+    } catch (error) {
+      if (!continueAfterWaitFailure) throw error
+    }
+  }
+
+  /**
+   * Runs one atomic framework and application initialization attempt.
+   * @param {object} args - Initialization identity.
+   * @param {number} args.initializationGeneration - Framework model generation.
+   * @param {string} args.type - Generic application process type.
+   * @returns {Promise<void>} - Resolves when initialized.
+   */
+  async _runInitialize({initializationGeneration, type}) {
+    const startsApplicationLifecycle = !this._applicationLifecycleInitialized
+
+    if (startsApplicationLifecycle) {
+      this._applicationProcessContext = Object.freeze({
+        instanceId: new UUID(4).format(),
+        type
+      })
     }
 
-    const initializePromise = (async () => {
+    try {
       await this.initializeModels({type})
 
       // Model initialization can be invalidated by a concurrent connection close.
       // If models are not ready, stop without marking the configuration initialized
       // so the next caller retries a full bootstrap.
-      if (this._modelInitializationGeneration !== initializationGeneration || !this._modelsInitialized) return
+      if (this._modelInitializationGeneration !== initializationGeneration || !this._modelsInitialized) {
+        if (startsApplicationLifecycle) this._resetApplicationLifecycle()
+        return
+      }
 
       await this.getEnvironmentHandler().autoDiscoverResources(this)
       this._mergeDiscoveredAbilityResources()
       this._validateResourceRelationshipsOnModels()
 
-      if (this._initializers) {
+      if (startsApplicationLifecycle && this._initializers) {
         const initializers = await this._initializers({configuration: this})
         const {requireContext, ...restArgs} = initializers
 
@@ -2415,37 +2542,106 @@ export default class VelociousConfiguration {
         if (requireContext) {
           for (const initializerKey of requireContext.keys()) {
             const InitializerClass = requireContext(initializerKey).default
-            const initializerInstance = new InitializerClass({configuration: this, type})
+            const processContext = this._applicationProcessContext
+
+            if (!processContext) throw new Error("Application process context is not available during initializer startup")
+
+            const initializerInstance = new InitializerClass({configuration: this, processContext, type})
 
             await initializerInstance.run()
+            this._successfulInitializers.push(initializerInstance)
           }
         }
       }
 
+      if (startsApplicationLifecycle) this._applicationLifecycleInitialized = true
+
       if (this._modelInitializationGeneration === initializationGeneration) {
         this._isInitialized = true
       }
-    })()
+    } catch (error) {
+      if (startsApplicationLifecycle) {
+        let teardownError
 
-    this._initializePromise = initializePromise
+        try {
+          await this._teardownSuccessfulInitializers()
+        } catch (caughtTeardownError) {
+          teardownError = caughtTeardownError
+        } finally {
+          this._resetApplicationLifecycle()
+        }
 
-    try {
-      await initializePromise
-    } catch (error) {
-      // Let a later call retry a failed initialization instead of every future
-      // caller awaiting the same cached rejection.
-      if (this._initializePromise === initializePromise) {
-        this._initializePromise = undefined
+        if (teardownError instanceof AggregateError) {
+          throw new AggregateError(
+            [error, ...teardownError.errors],
+            "Application process startup and cleanup failed",
+            {cause: error}
+          )
+        }
+
+        if (teardownError !== undefined) {
+          throw new AggregateError(
+            [error, teardownError],
+            "Application process startup and cleanup failed",
+            {cause: error}
+          )
+        }
       }
+
       throw error
+    } finally {
+      if (!this._isInitialized && this._initializePromiseGeneration === initializationGeneration) {
+        this._initializePromise = undefined
+        this._initializePromiseGeneration = undefined
+      }
     }
+  }
 
-    // If the inner IIFE returned without marking the configuration initialized
-    // (e.g. because models were invalidated mid-bootstrap), clear the promise so
-    // a later call retries a full bootstrap.
-    if (!this._isInitialized && this._initializePromise === initializePromise) {
-      this._initializePromise = undefined
-    }
+  /**
+   * Tears down every successfully started initializer in reverse order.
+   * @returns {Promise<void>} - Resolves when every teardown succeeds.
+   */
+  async _teardownSuccessfulInitializers() {
+    const successfulInitializers = this._successfulInitializers.splice(0).reverse()
+
+    await runShutdownSteps({
+      message: "Application initializer teardown failed",
+      steps: successfulInitializers.map((initializer) => async () => await initializer.teardown())
+    })
+  }
+
+  /** Clears application-owned lifecycle state after every teardown attempt. */
+  _resetApplicationLifecycle() {
+    this._applicationLifecycleInitialized = false
+    this._applicationProcessContext = undefined
+    this._successfulInitializers = []
+  }
+
+  /**
+   * Tears down the current application lifecycle once.
+   * @returns {Promise<void>} - Exact shared shutdown promise.
+   */
+  shutdown() {
+    if (this._shutdownPromise) return this._shutdownPromise
+
+    const initializePromise = this._initializePromise
+    const shutdownPromise = (async () => {
+      try {
+        if (initializePromise) await initializePromise
+        await this._teardownSuccessfulInitializers()
+      } finally {
+        this._resetApplicationLifecycle()
+        this._isInitialized = false
+        if (this._initializePromise === initializePromise) {
+          this._initializePromise = undefined
+          this._initializePromiseGeneration = undefined
+        }
+      }
+    })()
+
+    this._shutdownPromise = shutdownPromise
+
+    return shutdownPromise
   }
 
   /**
@@ -3312,7 +3508,9 @@ export default class VelociousConfiguration {
   async clientErrorPayloadForError(args) {
     /** @type {import("./configuration-types.js").ClientErrorPayloadReporterPayload} */
     const payload = {}
-    const details = requestDetails(args.request)
+    const requestTiming = this.getCurrentRequestTiming()
+    const sensitiveValues = requestTiming ? requestTiming.getLogSensitiveValues() : new Set()
+    const details = requestDetails(args.request, {redactor: this.getLogRedactor(), sensitiveValues})
 
     for (const reporter of this._clientErrorPayloadReporters) {
       const reporterPayload = await reporter({
@@ -3328,6 +3526,32 @@ export default class VelociousConfiguration {
     return payload
   }
 
+  /**
+   * Runs one test attempt in a revocable database-access context.
+   * @template T
+   * @param {{revoked: boolean}} scope - Attempt-owned access scope.
+   * @param {() => T | Promise<T>} callback - Attempt work.
+   * @returns {T | Promise<T>} - Callback result.
+   */
+  runWithTestDatabaseAccessScope(scope, callback) {
+    return this.getEnvironmentHandler().runWithTestDatabaseAccessScope(scope, callback)
+  }
+
+  /**
+   * Runs persistent framework work without inheriting a test attempt's revocable database-access scope.
+   * @template T
+   * @param {() => T | Promise<T>} callback - Persistent work to run.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async withoutCurrentTestDatabaseAccessScope(callback) {
+    return await this.getEnvironmentHandler().runWithCapturedTestDatabaseAccessScope(undefined, callback)
+  }
+
+  /** Throws when a timed-out test attempt tries to start more database work. */
+  assertDatabaseAccessAllowed() {
+    this.getEnvironmentHandler().assertTestDatabaseAccessAllowed()
+  }
+
   /**
    * Runs with connections.
    * @template T
@@ -3336,6 +3560,7 @@ export default class VelociousConfiguration {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withConnections(optionsOrCallback, callback) {
+    this.assertDatabaseAccessAllowed()
     const {
       callback: actualWithConnectionsCallback,
       databaseIdentifiers,
@@ -3366,6 +3591,7 @@ export default class VelociousConfiguration {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withTransaction({databaseIdentifier, name = "Configuration.withTransaction", ...restArgs}, callback) {
+    this.assertDatabaseAccessAllowed()
     restArgsError(restArgs)
 
     if (!databaseIdentifier) throw new Error("Configuration.withTransaction requires a databaseIdentifier")
@@ -3379,6 +3605,7 @@ export default class VelociousConfiguration {
     const pool = this.getDatabasePool(databaseIdentifier)
 
     return await pool.withOperationConnection({name}, async (connection, owner) => {
+      this.assertDatabaseAccessAllowed()
       const operation = new DatabaseOperation({
         configuration: this,
         databaseConfiguration,
@@ -3390,7 +3617,10 @@ export default class VelociousConfiguration {
       })
 
       try {
-        return await operation.transaction(async () => await callback(operation))
+        return await operation.transaction(async () => {
+          this.assertDatabaseAccessAllowed()
+          return await callback(operation)
+        })
       } finally {
         operation.complete()
       }
@@ -3407,6 +3637,7 @@ export default class VelociousConfiguration {
    * @returns {Promise<T>} - Callback result.
    */
   async withDatabaseOperation({databaseConfiguration, databaseIdentifier, name = "Configuration.withDatabaseOperation", schemaGeneration, tenant, ...restArgs}, callback) {
+    this.assertDatabaseAccessAllowed()
     restArgsError(restArgs)
 
     if (!databaseIdentifier) throw new Error("Configuration.withDatabaseOperation requires a databaseIdentifier")
@@ -3417,6 +3648,7 @@ export default class VelociousConfiguration {
     const configurationReuseKey = pool.getConfigurationReuseKey(databaseConfiguration)
 
     return await pool.withCapturedOperationConnection({databaseConfiguration, name}, async (connection, owner) => {
+      this.assertDatabaseAccessAllowed()
       const operation = new DatabaseOperation({
         configuration: this,
         databaseConfiguration,
@@ -3446,6 +3678,7 @@ export default class VelociousConfiguration {
   async withDatabaseIdentifierConnections({callback, dbs, identifiers, name, stackLabel}) {
     const stack = Error().stack
     const actualCallback = async () => {
+      this.assertDatabaseAccessAllowed()
       return await withTrackedStack(stack || stackLabel, async () => {
         return await callback(dbs)
       })
@@ -3479,6 +3712,7 @@ export default class VelociousConfiguration {
    * @returns {Record<string, import("./database/drivers/base.js").default>} A map of database connections with identifier as key
    */
   getCurrentConnections(databaseIdentifiers = this.getDatabaseIdentifiers()) {
+    this.assertDatabaseAccessAllowed()
     /**
      * Dbs.
      * @type {{[key: string]: import("./database/drivers/base.js").default}} */
@@ -3568,6 +3802,7 @@ export default class VelociousConfiguration {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async ensureConnections(optionsOrCallback, callback) {
+    this.assertDatabaseAccessAllowed()
     const {
       callback: actualWithConnectionsCallback,
       databaseIdentifiers,