velocious 1.0.719 → 1.0.721

package/build/background-jobs/main.js

@@ -9,7 +9,7 @@ import Logger from "../logger.js"
 import PruneTerminalBackgroundJobsJob from "../jobs/prune-terminal-background-jobs.js"
 import VelociousError from "../velocious-error.js"
 import shutdownLifecycle, { runShutdownSteps } from "../utils/shutdown-lifecycle.js"
-import { validateGenerationId, workerIdBelongsToGeneration } from "./generation-identity.js"
+import { parseGenerationWorkerId, validateGenerationId, workerIdBelongsToGeneration } from "./generation-identity.js"
 import BackgroundJobsLifecycleControlServer from "./lifecycle-control-server.js"
 
 /**
@@ -40,6 +40,8 @@ const WORKER_LIVENESS_SWEEP_MS = 15000
 /** Grace for workers from the previous main generation to reconnect and adopt leases. */
 const WORKER_RECONNECT_GRACE_MS = 30000
 const GENERATION_ORPHANED_AFTER_MS = 60 * 60 * 1000
+/** Prefix of the per-generation liveness advisory lock one live main holds for its whole generation. */
+const GENERATION_LIVENESS_LOCK_PREFIX = "background-jobs:generation-liveness"
 const WORKER_RECONNECT_GRACE_VALIDATION_MESSAGE = `workerReconnectGraceMs must be an integer between 0 and ${MAX_TIMER_MS}`
 
 /**
@@ -246,6 +248,11 @@ export default class BackgroundJobsMain {
     this._beaconClient = undefined
     /** @type {BackgroundJobsLifecycleControlServer | undefined} */
     this.lifecycleControlServer = undefined
+    /**
+     * Dedicated advisory-lock connection holding this main's generation liveness
+     * lock for the whole lifetime of the main (generation mode only).
+     * @type {import("../database/drivers/base.js").default | undefined} */
+    this._livenessLockConnection = undefined
   }
 
   /**
@@ -296,6 +303,7 @@ export default class BackgroundJobsMain {
       if (this.generationId && !this.adapter.supportsOwnedEnqueueFromHandoff()) {
         throw new Error("The configured background jobs adapter does not support atomic owned-handoff enqueue")
       }
+      if (this.generationId) await this._acquireGenerationLivenessLock()
 
       if (!this.generationId || this.initialGenerationState !== "candidate") {
         this.startupHandoffSnapshot = await this._generationOwnedHandoffSnapshot()
@@ -389,7 +397,11 @@ export default class BackgroundJobsMain {
               try {
                 await this._drainStartupHandoffReclaim()
               } finally {
-                await this._stopBeaconAndServer()
+                try {
+                  await this._releaseGenerationLivenessLock()
+                } finally {
+                  await this._stopBeaconAndServer()
+                }
               }
             }
           }
@@ -624,6 +636,7 @@ export default class BackgroundJobsMain {
     }
     this.lifecycleState = "active"
     this._creditReadyWorkers()
+    await this._settleForeignGenerationHandoffs()
     this.logger.info(() => ["Background jobs generation activation acknowledged", {generationId: this.generationId}])
     void this._drain().catch((error) => {
       this.logger.error(() => ["Background jobs generation post-activation drain failed", {error, generationId: this.generationId}])
@@ -751,6 +764,154 @@ export default class BackgroundJobsMain {
    * retained solely to perform this cleanup.
    * @returns {void}
    */
+  /**
+   * Builds the per-generation liveness advisory-lock name for one generation on
+   * this main's background-jobs database. A live main holds this lock for its
+   * whole lifetime; a foreign generation whose lock is free (or stale) has no
+   * live main supervising its durable handoffs.
+   * @param {string} generationId - Generation to name.
+   * @returns {string} - Lock name.
+   */
+  _generationLivenessLockName(generationId) {
+    const databaseIdentifier = this.configuration.getBackgroundJobsConfig().databaseIdentifier || "default"
+
+    return `${GENERATION_LIVENESS_LOCK_PREFIX}:${databaseIdentifier}:${generationId}`
+  }
+
+  /**
+   * Acquires this main's own generation liveness lock on a dedicated connection
+   * it holds until stop. Contention means a still-live main of the same
+   * generation exists (a deploy anomaly); the main keeps running without the
+   * marker and cross-generation settlement conservatively leaves its rows to it.
+   * @returns {Promise<void>} - Resolves after the marker is held or degraded.
+   */
+  async _acquireGenerationLivenessLock() {
+    if (!this.generationId || this._livenessLockConnection) return
+    const lockName = this._generationLivenessLockName(this.generationId)
+
+    try {
+      const connection = await this.configuration.getDatabasePool(this._livenessLockDatabaseIdentifier()).spawnConnection()
+      const acquired = await connection.tryAcquireAdvisoryLock(lockName)
+
+      if (!acquired) {
+        await connection.close()
+        this.logger.warn(() => ["Background jobs generation liveness lock is already held by another live main of this generation", {generationId: this.generationId}])
+
+        return
+      }
+
+      this.configuration.registerAdvisoryLockConnection(connection)
+      this._livenessLockConnection = connection
+    } catch (error) {
+      this.logger.warn(() => ["Failed to acquire background jobs generation liveness lock", {error, generationId: this.generationId}])
+    }
+  }
+
+  /**
+   * Releases this main's generation liveness marker during stop so a later
+   * generation activation can prove this generation is gone. Closing the
+   * dedicated connection releases the advisory lock on every tier.
+   * @returns {Promise<void>} - Resolves after the marker is released.
+   */
+  async _releaseGenerationLivenessLock() {
+    const connection = this._livenessLockConnection
+
+    this._livenessLockConnection = undefined
+    if (!connection) return
+
+    this.configuration.unregisterAdvisoryLockConnection(connection)
+
+    try {
+      await connection.releaseHeldAdvisoryLocks()
+    } finally {
+      await connection.close()
+    }
+  }
+
+  /**
+   * Database identifier whose pools carry the generation liveness locks. This
+   * matches the built-in store's own resolution of the background-jobs config.
+   * @returns {string} - Database identifier.
+   */
+  _livenessLockDatabaseIdentifier() {
+    return this.configuration.getBackgroundJobsConfig().databaseIdentifier || "default"
+  }
+
+  /**
+   * One activation event: snapshot all durable handoffs, group the rows whose
+   * worker identity belongs to a foreign generation, and settle each group only
+   * after proving that generation has no live main (its liveness lock is free).
+   * Own-generation rows, identity-free legacy rows, and rows of live foreign
+   * generations stay owned by their existing recovery paths. Failures are
+   * reported as framework errors and never fail activation.
+   * @returns {Promise<void>} - Resolves after settlement or its reported failure.
+   */
+  async _settleForeignGenerationHandoffs() {
+    if (!this.generationId) return
+
+    try {
+      const handoffs = await this.store.snapshotHandedOffJobs()
+      /** @type {Map<string, import("./types.js").BackgroundJobHandoffSnapshot[]>} */
+      const handoffsByForeignGeneration = new Map()
+
+      for (const handoff of handoffs) {
+        const parsed = parseGenerationWorkerId(handoff.workerId)
+        if (!parsed || parsed.generationId === this.generationId) continue
+
+        const group = handoffsByForeignGeneration.get(parsed.generationId) || []
+        group.push(handoff)
+        handoffsByForeignGeneration.set(parsed.generationId, group)
+      }
+
+      for (const [foreignGenerationId, foreignHandoffs] of handoffsByForeignGeneration) {
+        const settledJobs = await this._settleForeignGenerationHandoffGroup({foreignGenerationId, handoffs: foreignHandoffs})
+
+        if (settledJobs.length > 0) await this._handleOrphanedJobs({jobs: settledJobs, warning: "Marked orphaned background jobs whose generation was retired before this generation activated"})
+      }
+    } catch (error) {
+      const normalizedError = error instanceof Error ? error : new Error(String(error))
+      const payload = {context: {generationId: this.generationId, stage: "background-job-activation-cross-generation-settlement"}, error: normalizedError}
+      const errorEvents = this.configuration.getErrorEvents()
+
+      this.logger.error(() => ["Failed to settle foreign-generation handoffs at activation:", normalizedError])
+      errorEvents.emit("framework-error", payload)
+      errorEvents.emit("all-error", {...payload, errorType: "framework-error"})
+    }
+  }
+
+  /**
+   * Settles one foreign generation's exact handoffs under a proof of absence:
+   * acquire that generation's liveness lock on a dedicated connection and hold
+   * it across the fenced store transition. A busy lock means a live main of
+   * that generation still supervises its rows (retired-and-draining included),
+   * so nothing here may touch them.
+   * @param {object} args - Options.
+   * @param {string} args.foreignGenerationId - Generation whose rows are candidates.
+   * @param {import("./types.js").BackgroundJobHandoffSnapshot[]} args.handoffs - Exact snapshot rows.
+   * @returns {Promise<import("./types.js").BackgroundJobRow[]>} - Accepted orphan transitions.
+   */
+  async _settleForeignGenerationHandoffGroup({foreignGenerationId, handoffs}) {
+    const lockName = this._generationLivenessLockName(foreignGenerationId)
+    const connection = await this.configuration.getDatabasePool(this._livenessLockDatabaseIdentifier()).spawnConnection()
+
+    try {
+      const acquired = await connection.tryAcquireAdvisoryLock(lockName)
+
+      if (!acquired) return []
+
+      return await this.store.markOrphanedHandoffs({
+        error: "Job orphaned when a new generation activated while its owning generation was not live",
+        handoffs
+      })
+    } finally {
+      try {
+        await connection.releaseHeldAdvisoryLocks()
+      } finally {
+        await connection.close()
+      }
+    }
+  }
+
   _setupStartupHandoffReclaim() {
     if (this.startupHandoffSnapshot.length === 0) return
     if (this._startupHandoffReclaimTimer || this._startupHandoffReclaimPromise || this._startupHandoffGraceElapsed) return

package/build/configuration.js

@@ -273,6 +273,7 @@ export default class VelociousConfiguration {
    * served this lock" surface (design §3).
    * @type {Map<string, {backend: import("./database/advisory-lock-backend-policy.js").AdvisoryLockTier, fencingSupported: boolean, servedAt: string}>} */
   _advisoryLockAcquisitions = new Map()
+  _advisoryLockReentries = new Map()
 
   /** @type {Map<string, number>} */
   _schemaCacheGenerationsByReuseKey = new Map()
@@ -4355,19 +4356,36 @@ export default class VelociousConfiguration {
     this._advisoryLockAcquisitions.set(lockName, {backend, fencingSupported, servedAt: new Date().toISOString()})
   }
 
+  /**
+   * Counts one re-entry of an advisory lock the calling async context already
+   * holds (`Monitor` semantics, see `advisory-lock-runner.js`).
+   *
+   * This is the measurement that decides whether a hand-passed `*LockHeld`
+   * boolean is still load-bearing: a name whose reentries stay at zero over a
+   * real workload is not nesting at all, while a name that reenters is one
+   * where the framework now owns the depth and the application flag can go.
+   * @param {object} args - Re-entry record.
+   * @param {string} args.lockName - Lock name.
+   * @returns {void}
+   */
+  recordAdvisoryLockReentry({lockName}) {
+    this._advisoryLockReentries.set(lockName, (this._advisoryLockReentries.get(lockName) ?? 0) + 1)
+  }
+
   /**
    * The "which backend served this lock" diagnostics surface (design §3):
    * per lock name, the tier of the most recent acquisition, whether that tier
    * carries fencing tokens, and the resolved policy (minimum/allowed/preferred
    * tiers) for the name.
    * @param {string} lockName - Lock name.
-   * @returns {{acquisition: {backend: import("./database/advisory-lock-backend-policy.js").AdvisoryLockTier, fencingSupported: boolean, servedAt: string} | null, lockServer: {connected: boolean, lastError: string | null, lastProbeAt: string | null, leasedNames: string[]} | null, policy: import("./database/advisory-lock-backend-policy.js").ResolvedAdvisoryLockBackendPolicy}} - Backend status for the name.
+   * @returns {{acquisition: {backend: import("./database/advisory-lock-backend-policy.js").AdvisoryLockTier, fencingSupported: boolean, servedAt: string} | null, lockServer: {connected: boolean, lastError: string | null, lastProbeAt: string | null, leasedNames: string[]} | null, policy: import("./database/advisory-lock-backend-policy.js").ResolvedAdvisoryLockBackendPolicy, reentries: number}} - Backend status for the name.
    */
   getAdvisoryLockBackendStatus(lockName) {
     return {
       acquisition: this._advisoryLockAcquisitions.get(lockName) ?? null,
       lockServer: this._advisoryLockLockServerBackend?.getStatus() ?? null,
-      policy: this.resolveAdvisoryLockPolicy(lockName)
+      policy: this.resolveAdvisoryLockPolicy(lockName),
+      reentries: this._advisoryLockReentries.get(lockName) ?? 0
     }
   }
 

package/build/database/advisory-lock-file-backend.js

@@ -59,7 +59,7 @@ export default class AdvisoryLockFileBackend {
     this.pathStyle = pathStyle
     this.pollIntervalMs = pollIntervalMs
     this.holderId = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
-    /** @type {Map<string, {timer: ReturnType<typeof setInterval>}>} */
+    /** @type {Map<string, {depth: number, timer: ReturnType<typeof setInterval>}>} */
     this.holdsByName = new Map()
   }
 
@@ -113,7 +113,17 @@ export default class AdvisoryLockFileBackend {
    * @returns {Promise<boolean>} - True when this backend became the lock owner.
    */
   async tryAcquire(name) {
-    if (this.holdsByName.has(name)) return false
+    // Already held by this backend instance: a re-entrant acquisition
+    // (`Monitor` semantics) adds a level instead of contending with itself.
+    // Refusing it made a nested hold time out on this tier while the same
+    // nesting worked on the database tiers.
+    const existingHold = this.holdsByName.get(name)
+
+    if (existingHold) {
+      existingHold.depth += 1
+
+      return true
+    }
 
     await this.ensureDirectory()
 
@@ -141,6 +151,14 @@ export default class AdvisoryLockFileBackend {
 
     if (!hold) return false
 
+    // One release per acquisition: a re-entrant hold keeps the lock until its
+    // outermost level releases, exactly like the database tiers.
+    if (hold.depth > 1) {
+      hold.depth -= 1
+
+      return true
+    }
+
     this.clearHold(name)
 
     const owner = await this.readOwner(this.lockPathFor(name))
@@ -236,7 +254,7 @@ export default class AdvisoryLockFileBackend {
 
     if (typeof timer.unref === "function") timer.unref()
 
-    this.holdsByName.set(name, {timer})
+    this.holdsByName.set(name, {depth: 1, timer})
 
     return true
   }

package/build/database/advisory-lock-lock-server-backend.js

@@ -15,7 +15,7 @@ import {AdvisoryLockServiceUnavailableError} from "./advisory-lock-errors.js"
  * @property {(type: string, args: {onMessage: (body: Record<string, unknown>) => void, params: Record<string, unknown>, timeoutMs: number}) => LockServerConnectionLike} openConnection - Opens the 1:1 connection.
  * @property {() => Promise<void> | void} [close] - Closes the transport.
  * @typedef {{epoch: number, name: string, timer: ReturnType<typeof setInterval>, leaseExpiresAt: number}} LockServerHold
- * @typedef {{status: "acquired", epoch: number, leaseExpiresAt: number} | {status: "busy"} | {status: "timeout"}} LockServerAcquireResult
+ * @typedef {{status: "acquired", epoch: number, leaseExpiresAt: number} | {status: "already-held", epoch: number, leaseExpiresAt: number} | {status: "busy"} | {status: "timeout"}} LockServerAcquireResult
  */
 
 /** Protocol version spoken by the centralized lock server (consens-lock v2). */
@@ -181,6 +181,16 @@ export default class AdvisoryLockLockServerBackend {
       return true
     }
 
+    // `already-held` means the server says *this connection* already owns the
+    // lease: a re-entrant acquisition (`Monitor` semantics), not contention.
+    // Reporting it as "not acquired" is what turned every nested hold into a
+    // timeout once a name moved to this tier.
+    if (result.status === "already-held") {
+      this.startRenewal(name, result.epoch)
+
+      return true
+    }
+
     if (result.status === "busy") return false
 
     return false
@@ -197,7 +207,7 @@ export default class AdvisoryLockLockServerBackend {
     /** @type {LockServerAcquireResult} */
     const result = /** @type {LockServerAcquireResult} */ (await this.request("try-acquire", {name}))
 
-    if (result.status !== "acquired") return false
+    if (result.status !== "acquired" && result.status !== "already-held") return false
 
     this.startRenewal(name, result.epoch)
 

package/build/database/advisory-lock-runner.js

@@ -1,5 +1,6 @@
 // @ts-check
 
+import {AsyncLocalStorage} from "node:async_hooks"
 import timeout, {TimeoutError} from "awaitery/build/timeout.js"
 import {DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS} from "./advisory-lock-bound.js"
 import {
@@ -59,6 +60,27 @@ class AdvisoryLockBusyError extends Error {
   }
 }
 
+/**
+ * Advisory locks held by one async context, keyed by
+ * `<databaseIdentifier>\u0000<lock name>` and carrying the re-entry depth plus
+ * the provenance of the tier that actually holds the lock.
+ *
+ * Re-entry is scoped to the async context, not to the process: a nested call
+ * made inside a held callback belongs to the same logical operation and must
+ * not contend with itself, while an unrelated concurrent request in the same
+ * process is a different context and must still wait. That is Ruby's `Monitor`
+ * ("re-entrant for the holding thread") expressed with the async-context
+ * analogue of a thread.
+ *
+ * Without this, the four tiers disagreed on re-entry: a nested acquisition on
+ * a `dedicatedConnection` opened a second connection and self-deadlocked, the
+ * file tier refused it as held, and the lock-server tier received
+ * `already-held` and treated it as contention. Applications worked around it
+ * with hand-passed `*LockHeld` booleans, which is exactly the parameter a
+ * monitor makes redundant.
+ */
+const heldAdvisoryLocks = new AsyncLocalStorage()
+
 /**
  * Thrown when a callback holds an advisory lock longer than `holdTimeoutMs`.
  */
@@ -107,6 +129,10 @@ export default class AdvisoryLockRunner {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withAdvisoryLock(name, callback, args = {}) {
+    const heldEntry = this.heldEntryFor(name)
+
+    if (heldEntry) return await this.runReentrantCallback({callback, entry: heldEntry, name})
+
     const lockServerResult = await this.attemptLockServer({args, callback, mode: "wait", name})
 
     // The wait mode never returns a deferred outcome, so the value member is present.
@@ -159,6 +185,10 @@ export default class AdvisoryLockRunner {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withAdvisoryLockOrFail(name, callback, args = {}) {
+    const heldEntry = this.heldEntryFor(name)
+
+    if (heldEntry) return await this.runReentrantCallback({callback, entry: heldEntry, name})
+
     const lockServerResult = await this.attemptLockServer({args, callback, mode: "or-fail", name})
 
     // The or-fail mode throws on contention, so the value member is present.
@@ -218,6 +248,10 @@ export default class AdvisoryLockRunner {
    * @returns {Promise<{acquired: true, result: T} | {acquired: false, reason: "contended", lockName: string}>} - Either the held-callback result or the defer outcome.
    */
   async withAdvisoryLockOrDefer(name, callback, args = {}) {
+    const heldEntry = this.heldEntryFor(name)
+
+    if (heldEntry) return {acquired: true, result: await this.runReentrantCallback({callback, entry: heldEntry, name})}
+
     const lockServerResult = await this.attemptLockServer({args, callback, mode: "defer", name})
 
     if (lockServerResult) {
@@ -266,13 +300,69 @@ export default class AdvisoryLockRunner {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async runLockedCallback({callback, holdTimeoutMs, lockBackend, name, release}) {
+    const store = new Map(heldAdvisoryLocks.getStore() ?? [])
+
+    store.set(this.lockStorageKey(name), {depth: 1, lockBackend})
+
     try {
-      return await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs, lockBackend)
+      // The lock is released outside the context scope: a release path that
+      // touches the same name (a cleanup hook, an error reporter) must not look
+      // like a re-entry of a hold that is already over.
+      return await heldAdvisoryLocks.run(store, async () => await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs, lockBackend))
     } finally {
       await release()
     }
   }
 
+  /**
+   * Returns the held entry when this async context already holds the lock.
+   * @param {string} name - Lock name.
+   * @returns {{depth: number, lockBackend: AdvisoryLockBackendProvenance} | null} - The held entry, or null when this context does not hold the lock.
+   */
+  heldEntryFor(name) {
+    const store = heldAdvisoryLocks.getStore()
+
+    if (!store) return null
+
+    return store.get(this.lockStorageKey(name)) ?? null
+  }
+
+  /**
+   * Runs a callback as a re-entry of a lock this async context already holds.
+   *
+   * The re-entry adds no backend round trip and cannot fail on contention: the
+   * outer hold already owns the lock, so mutual exclusion is unchanged. The
+   * outer hold owns the hold timeout and the lease; a re-entry does not start a
+   * second one, and the callback therefore receives the outer provenance without
+   * a `control`.
+   * @template T
+   * @param {{callback: (args?: {control?: import("awaitery/build/timeout.js").TimeoutControl, lockBackend: AdvisoryLockBackendProvenance}) => Promise<T>, entry: {depth: number, lockBackend: AdvisoryLockBackendProvenance}, name: string}} args - Re-entry request.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async runReentrantCallback({callback, entry, name}) {
+    entry.depth += 1
+    this.configuration.recordAdvisoryLockReentry({lockName: name})
+
+    try {
+      return await callback({lockBackend: entry.lockBackend})
+    } finally {
+      entry.depth -= 1
+    }
+  }
+
+  /**
+   * Builds the async-context storage key for one lock name.
+   *
+   * The database identifier is part of the key because it is part of the lock's
+   * identity: two tenant databases reusing one name hold two different locks,
+   * and a nested call in the other database is not a re-entry.
+   * @param {string} name - Lock name.
+   * @returns {string} - Storage key for the held-entry map.
+   */
+  lockStorageKey(name) {
+    return `${this.databaseIdentifier}\u0000${name}`
+  }
+
   /**
    * Serves one acquisition on the lock-server tier when the lock name prefers
    * it (design §1/§9), falling *upward* to the driver path when the server is

package/build/routes/base-route.js

@@ -109,10 +109,11 @@ export default class VelociousBaseRoute {
    * Runs namespace.
    * @abstract
    * @param {string} name - Name.
-   * @param {(arg: import("./namespace-route.js").default) => void} callback - Callback function.
+   * @param {object | ((arg: import("./namespace-route.js").default) => void)} options - Namespace options or the draw callback (legacy form).
+   * @param {((arg: import("./namespace-route.js").default) => void) | undefined} [callback] - Callback function.
    * @returns {void} - No return value.
    */
-  namespace(name, callback) { throw new Error("'namespace' not implemented") } // eslint-disable-line no-unused-vars
+  namespace(name, options, callback) { throw new Error("'namespace' not implemented") } // eslint-disable-line no-unused-vars
 
   /**
    * Runs post.

package/build/routes/basic-route.js

@@ -6,10 +6,11 @@ export default class VelociousBasicRoute extends BaseRoute {
   /**
    * Runs get.
    * @param {string} name - Route name.
+   * @param {{on?: "member" | "collection"} | {skipControllerConnections?: boolean}} [options] - Route options; `skipControllerConnections: true` skips the request-scoped controller connection for this route.
    */
-  get(name) {
+  get(name, options = {}) {
     const GetRoute = VelociousBasicRoute.GetRouteType
-    const route = new GetRoute({name})
+    const route = new GetRoute({name, ...options})
 
     this.routes.push(route)
   }
@@ -51,35 +52,59 @@ export default class VelociousBasicRoute extends BaseRoute {
 
   /**
    * Runs namespace.
-   * @param {string} name - Name.
-   * @param {(arg: import("./namespace-route.js").default) => void} callback - Callback function.
+   * @param {string} name - Route name.
+   * @param {{skipControllerConnections?: boolean} | ((arg: import("./namespace-route.js").default) => void)} [options] - Namespace options (`skipControllerConnections: true` skips the request-scoped controller connection for every route declared inside this namespace; a per-route option still overrides it) or the draw callback (legacy form).
+   * @param {((arg: import("./namespace-route.js").default) => void) | undefined} [callback] - Callback function.
    * @returns {void} - No return value.
    */
-  namespace(name, callback) {
+  namespace(name, options = {}, callback) {
     const NamespaceRoute = VelociousBasicRoute.NameSpaceRouteType
 
     if (!NamespaceRoute) throw new Error("No NamespaceRoute registered")
 
+    // Backward compatible: the second argument may be the draw callback.
+    if (typeof options === "function") {
+      callback = options
+      options = {}
+    }
+
+    const namespaceOptions = /** @type {{skipControllerConnections?: boolean}} */ (options)
+    const skipControllerConnections = namespaceOptions.skipControllerConnections === true
+
     const route = new NamespaceRoute({name})
 
     this.routes.push(route)
 
     if (callback) {
+      const originalGet = route.get.bind(route)
+      const originalPost = route.post.bind(route)
+
+      route.get = (routeName, routeOptions = {}) => {
+        const subOptions = /** @type {{skipControllerConnections?: boolean}} */ (routeOptions)
+        return originalGet(routeName, {...routeOptions, skipControllerConnections: subOptions.skipControllerConnections ?? skipControllerConnections})
+      }
+
+      route.post = (routeName, routeOptions = {}) => {
+        const subOptions = /** @type {{skipControllerConnections?: boolean}} */ (routeOptions)
+        return originalPost(routeName, {...routeOptions, skipControllerConnections: subOptions.skipControllerConnections ?? skipControllerConnections})
+      }
+
       callback(route)
     }
   }
 
   /**
    * Runs post.
-   * @param {string} name - Name.
+   * @param {string} name - Route name.
+   * @param {{on?: "member" | "collection"} | {skipControllerConnections?: boolean}} [options] - Route options; `skipControllerConnections: true` skips the request-scoped controller connection for this route.
    * @returns {void} - No return value.
    */
-  post(name) {
+  post(name, options = {}) {
     const PostRoute = VelociousBasicRoute.PostRouteType
 
     if (!PostRoute) throw new Error("No PostRoute registered")
 
-    const route = new PostRoute({name})
+    const route = new PostRoute({name, ...options})
 
     this.routes.push(route)
   }

package/build/routes/get-route.js

@@ -28,16 +28,32 @@ function assignActionAndController(params, name) {
 }
 
 class VelociousRouteGetRoute extends BaseRoute {
+  /**
+   * When true the resolver skips the request-scoped controller connection for
+   * this route: the action runs without an ambient `ensureConnections` checkout,
+   * so a long-lived action (streaming response, long wait) does not pin a pool
+   * connection for its whole lifetime. Each explicit `ensureConnections` call
+   * inside the action still opens and returns its own short-lived connection.
+   * @type {boolean}
+   */
+  skipControllerConnections = false
+
   /**
    * Runs constructor.
    * @param {object} args - Options object.
    * @param {string} args.name - Name.
+   * @param {boolean} [args.skipControllerConnections] - Skip the request-scoped controller connection for this route.
    */
-  constructor({name, ...restArgs}) {
+  constructor({name, skipControllerConnections = false, ...restArgs}) {
     super()
     restArgsError(restArgs)
     this.name = name
     this.regExp = new RegExp(`^(${escapeStringRegexp(name)})(.*)$`)
+    if (skipControllerConnections !== true && skipControllerConnections !== false) {
+      throw new Error(`Expected get route 'skipControllerConnections' to be a boolean, got: ${String(skipControllerConnections)}`)
+    }
+
+    this.skipControllerConnections = skipControllerConnections
   }
 
   getHumanPaths() {

package/build/routes/post-route.js

@@ -27,16 +27,32 @@ function assignActionAndController(params, name) {
 }
 
 class VelociousRoutePostRoute extends BaseRoute {
+  /**
+   * When true the resolver skips the request-scoped controller connection for
+   * this route: the action runs without an ambient `ensureConnections` checkout,
+   * so a long-lived action (streaming response, long wait) does not pin a pool
+   * connection for its whole lifetime. Each explicit `ensureConnections` call
+   * inside the action still opens and returns its own short-lived connection.
+   * @type {boolean}
+   */
+  skipControllerConnections = false
+
   /**
    * Runs constructor.
    * @param {object} args - Options object.
    * @param {string} args.name - Name.
+   * @param {boolean} [args.skipControllerConnections] - Skip the request-scoped controller connection for this route.
    */
-  constructor({name, ...restArgs}) {
+  constructor({name, skipControllerConnections = false, ...restArgs}) {
     super()
     restArgsError(restArgs)
     this.name = name
     this.regExp = new RegExp(`^(${escapeStringRegexp(name)})(.*)$`)
+    if (skipControllerConnections !== true && skipControllerConnections !== false) {
+      throw new Error(`Expected post route 'skipControllerConnections' to be a boolean, got: ${String(skipControllerConnections)}`)
+    }
+
+    this.skipControllerConnections = skipControllerConnections
   }
 
   getHumanPaths() {