velocious 1.0.446 → 1.0.448

package/README.md

@@ -22,7 +22,7 @@
 * 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))
-* Named database connection checkouts for debugging held connections (see [docs/database-connections.md](docs/database-connections.md))
+* Named database connection checkouts, bounded pool waits, and debugging held connections (see [docs/database-connections.md](docs/database-connections.md))
 * Optional built-in debug endpoint for inspecting server and database connection state (see [docs/debug-endpoint.md](docs/debug-endpoint.md))
 
 # Setup
@@ -1453,7 +1453,7 @@ database: {
 }
 ```
 
-`pool.max` caps live async-tracked connections for that pool. When the cap is reached, new checkouts wait until a matching checked-in connection can be handed over or capacity is freed. The built-in debug endpoint reports each in-use connection's `checkedOutForMs`, each idle connection's `idleForMs`, and queued `pendingCheckouts[].waitingForMs` so production diagnostics can distinguish long-held checkouts from pool-capacity waits.
+`pool.max` caps live async-tracked connections for that pool and defaults to `10` when omitted. When the cap is reached, new checkouts wait until a matching checked-in connection can be handed over or capacity is freed. Set `pool.max` to `null` only when a process is deliberately allowed to open an unbounded number of database connections. The built-in debug endpoint reports each in-use connection's `checkedOutForMs`, each idle connection's `idleForMs`, and queued `pendingCheckouts[].waitingForMs` so production diagnostics can distinguish long-held checkouts from pool-capacity waits.
 
 # Websockets
 

package/build/configuration-types.js

@@ -44,17 +44,19 @@
  * @property {boolean} [options.trustServerCertificate] - Whether to trust the server certificate (MSSQL).
  * @property {string} [password] - Password for the SQL user.
  * @property {object} [pool] - Connection pool configuration.
- * @property {number} [pool.max] - Maximum number of connections.
+ * @property {number | null} [pool.max] - Maximum number of connections. Set null to disable the cap.
  * @property {number} [pool.min] - Minimum number of connections.
  * @property {number} [pool.idleTimeoutMillis] - Idle timeout before releasing a connection.
+ * @property {number | null} [pool.checkoutTimeoutMillis] - Timeout while waiting for an available connection after the max connection cap is reached. Set null to wait indefinitely.
  * @property {string} [server] - SQL server hostname.
  * @property {string} [user] - SQL username.
  */
 
 /**
  * @typedef {object} DatabasePoolConfiguration
+ * @property {number | null} [checkoutTimeoutMillis] - Timeout while a checkout waits for an available async-tracked connection after the max live connection cap is reached. Set null to wait indefinitely. Default: 10000.
  * @property {number | null} [idleTimeoutMillis] - Idle timeout before closing a checked-in async-tracked connection. Set null to disable idle reaping. Default: 5000.
- * @property {number} [max] - Maximum live async-tracked connections for this pool. Extra checkouts wait until a matching connection is checked in or capacity is freed.
+ * @property {number | null} [max] - Maximum live async-tracked connections for this pool. Defaults to 10. Extra checkouts wait until a matching connection is checked in or capacity is freed. Set null to disable the cap.
  */
 
 /**

package/build/database/pool/async-tracked-multi-connection.js

@@ -6,7 +6,9 @@ import BasePool, {POOL_CONFIGURATION_KEY} from "./base.js"
 export const CLOSED_CONNECTION = Symbol("velociousClosedConnection")
 const IDLE_CONNECTION_CHECKED_IN_AT = Symbol("velociousIdleConnectionCheckedInAt")
 const CONNECTION_CHECKED_OUT_AT = Symbol("velociousConnectionCheckedOutAt")
+const DEFAULT_MAX_CONNECTIONS = 10
 const DEFAULT_IDLE_TIMEOUT_MILLIS = 5000
+const DEFAULT_CHECKOUT_TIMEOUT_MILLIS = 10000
 
 /**
  * PendingCheckout type.
@@ -17,6 +19,9 @@ const DEFAULT_IDLE_TIMEOUT_MILLIS = 5000
  * @property {string} reuseKey - Database configuration reuse key needed by the checkout.
  * @property {(connection: import("../drivers/base.js").default) => void} resolve - Resolves with an activated connection.
  * @property {(error: Error) => void} reject - Rejects when checkout cannot complete.
+ * @property {number | null} timeoutAt - Timestamp when the checkout will time out, or null when disabled.
+ * @property {number | null} timeoutMillis - Milliseconds to wait before rejecting, or null when disabled.
+ * @property {ReturnType<typeof setTimeout> | undefined} timeoutTimer - Timer that rejects the pending checkout.
  */
 
 export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends BasePool {
@@ -280,14 +285,37 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
   /**
    * Runs max connections.
-   * @returns {number | undefined} - Configured max live connections.
+   * @returns {number | null} - Configured max live connections.
    */
   maxConnections() {
     const value = this.getConfiguration().pool?.max
 
+    if (value === null) return null
     if (this.validMaxConnections(value)) return value
 
-    return
+    return DEFAULT_MAX_CONNECTIONS
+  }
+
+  /**
+   * Runs checkout timeout millis.
+   * @returns {number | null} - Pending checkout timeout in milliseconds, or null when disabled.
+   */
+  checkoutTimeoutMillis() {
+    const value = this.getConfiguration().pool?.checkoutTimeoutMillis
+
+    if (value === null) return null
+    if (this.validCheckoutTimeoutMillis(value)) return value
+
+    return DEFAULT_CHECKOUT_TIMEOUT_MILLIS
+  }
+
+  /**
+   * Runs valid checkout timeout millis.
+   * @param {?} value - Candidate checkout timeout.
+   * @returns {value is number} - Whether the value is a valid timeout.
+   */
+  validCheckoutTimeoutMillis(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
   }
 
   /**
@@ -320,7 +348,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
   canSpawnConnection() {
     const maxConnections = this.maxConnections()
 
-    return maxConnections === undefined || this.liveConnectionCount() < maxConnections
+    return maxConnections === null || this.liveConnectionCount() < maxConnections
   }
 
   /**
@@ -359,7 +387,23 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    */
   async waitForCheckout(databaseConfig, reuseKey, options = {}) {
     return await new Promise((resolve, reject) => {
-      this.pendingCheckouts.push({databaseConfig, enqueuedAt: Date.now(), options, reject, resolve, reuseKey})
+      const enqueuedAt = Date.now()
+      const timeoutMillis = this.checkoutTimeoutMillis()
+      /** @type {PendingCheckout} */
+      const checkout = {
+        databaseConfig,
+        enqueuedAt,
+        options,
+        reject,
+        resolve,
+        reuseKey,
+        timeoutAt: timeoutMillis === null ? null : enqueuedAt + timeoutMillis,
+        timeoutMillis,
+        timeoutTimer: undefined
+      }
+
+      checkout.timeoutTimer = this.startPendingCheckoutTimeout(checkout)
+      this.pendingCheckouts.push(checkout)
       void this.drainPendingCheckouts().catch((error) => {
         const checkoutError = error instanceof Error ? error : new Error("Failed to drain pending database connection checkouts.", {cause: error})
 
@@ -398,17 +442,19 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
       const checkout = this.pendingCheckouts[0]
 
       if (await this.closeIdleConnectionForPendingCheckoutCapacity(checkout)) continue
+      if (!this.pendingCheckouts.includes(checkout)) continue
       if (this.canSpawnConnection()) {
-        this.pendingCheckouts.shift()
+        this.removePendingCheckoutAt(0)
         await this.spawnAndResolvePendingCheckout(checkout)
         continue
       }
 
       const reapedConnection = await this.idleConnectionForPendingCheckout(checkout)
 
+      if (!this.pendingCheckouts.includes(checkout)) continue
       if (!reapedConnection) return
 
-      this.pendingCheckouts.shift()
+      this.removePendingCheckoutAt(0)
       await this.resolvePendingCheckout(checkout, reapedConnection)
     }
   }
@@ -424,7 +470,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
       if (!connection) continue
 
-      this.pendingCheckouts.splice(index, 1)
+      this.removePendingCheckoutAt(index)
       await this.resolvePendingCheckout(checkout, connection)
 
       return true
@@ -433,6 +479,71 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     return false
   }
 
+  /**
+   * Runs remove pending checkout at.
+   * @param {number} index - Pending checkout index.
+   * @returns {PendingCheckout} - Removed checkout.
+   */
+  removePendingCheckoutAt(index) {
+    const checkout = this.pendingCheckouts.splice(index, 1)[0]
+
+    this.clearPendingCheckoutTimeout(checkout)
+
+    return checkout
+  }
+
+  /**
+   * Runs start pending checkout timeout.
+   * @param {PendingCheckout} checkout - Pending checkout to time out.
+   * @returns {ReturnType<typeof setTimeout> | undefined} - Timer, if timeout is enabled.
+   */
+  startPendingCheckoutTimeout(checkout) {
+    if (checkout.timeoutMillis === null) return undefined
+
+    const timer = setTimeout(() => {
+      this.timeoutPendingCheckout(checkout)
+    }, checkout.timeoutMillis)
+
+    return timer
+  }
+
+  /**
+   * Runs timeout pending checkout.
+   * @param {PendingCheckout} checkout - Pending checkout to reject.
+   * @returns {void}
+   */
+  timeoutPendingCheckout(checkout) {
+    const index = this.pendingCheckouts.indexOf(checkout)
+
+    if (index === -1) return
+
+    this.removePendingCheckoutAt(index)
+    checkout.reject(this.pendingCheckoutTimeoutError(checkout))
+  }
+
+  /**
+   * Runs pending checkout timeout error.
+   * @param {PendingCheckout} checkout - Timed-out checkout.
+   * @returns {Error} - Timeout error.
+   */
+  pendingCheckoutTimeoutError(checkout) {
+    const checkoutName = checkout.options.name ? ` Checkout name: ${JSON.stringify(checkout.options.name)}.` : ""
+
+    return new Error(`Timed out after ${checkout.timeoutMillis}ms waiting for database connection checkout from pool "${this.identifier}".${checkoutName}`)
+  }
+
+  /**
+   * Runs clear pending checkout timeout.
+   * @param {PendingCheckout} checkout - Pending checkout.
+   * @returns {void}
+   */
+  clearPendingCheckoutTimeout(checkout) {
+    if (!checkout.timeoutTimer) return
+
+    clearTimeout(checkout.timeoutTimer)
+    checkout.timeoutTimer = undefined
+  }
+
   /**
    * Runs close idle connection for pending checkout capacity.
    * @param {PendingCheckout} checkout - Checkout waiting for a connection.
@@ -470,6 +581,8 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     if (connection) return connection
 
     await this.reapIdleConnections()
+    if (!this.pendingCheckouts.includes(checkout)) return
+
     connection = this.takeIdleConnectionForReuseKey(checkout.reuseKey, {includeOpenTransactions: false})
 
     return connection
@@ -760,14 +873,17 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
   /**
    * Runs pending checkout debug snapshots.
    * @param {number} now - Current timestamp.
-   * @returns {Array<Record<string, ?>>} - Pending checkout snapshots.
+   * @returns {import("./base.js").DatabasePoolPendingCheckoutDebugSnapshot[]} - Pending checkout snapshots.
    */
   pendingCheckoutDebugSnapshots(now) {
     return this.pendingCheckouts.map((checkout, index) => ({
       checkoutName: checkout.options.name,
       enqueuedAt: checkout.enqueuedAt,
       index,
+      remainingTimeoutMs: checkout.timeoutAt === null ? null : Math.max(0, checkout.timeoutAt - now),
       reuseKey: checkout.reuseKey,
+      timeoutAt: checkout.timeoutAt,
+      timeoutMillis: checkout.timeoutMillis,
       waitingForMs: Math.max(0, now - checkout.enqueuedAt)
     }))
   }
@@ -1129,6 +1245,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     this.pendingCheckouts = []
 
     for (const checkout of pendingCheckouts) {
+      this.clearPendingCheckoutTimeout(checkout)
       checkout.reject(error)
     }
   }

package/build/database/pool/base.js

@@ -12,6 +12,19 @@ export const POOL_CONFIGURATION_KEY = Symbol("velociousPoolConfigurationKey")
  * @property {string} [name] - Human-readable name for the checked-out connection.
  */
 
+/**
+ * DatabasePoolPendingCheckoutDebugSnapshot type.
+ * @typedef {object} DatabasePoolPendingCheckoutDebugSnapshot
+ * @property {string | undefined} checkoutName - Human-readable checkout name.
+ * @property {number} enqueuedAt - Timestamp when the checkout started waiting.
+ * @property {number} index - Pending checkout queue index.
+ * @property {number | null} remainingTimeoutMs - Milliseconds before the checkout times out, or null when disabled.
+ * @property {string} reuseKey - Database configuration reuse key needed by the checkout.
+ * @property {number | null} timeoutAt - Timestamp when the checkout will time out, or null when disabled.
+ * @property {number | null} timeoutMillis - Timeout configured for the checkout, or null when disabled.
+ * @property {number} waitingForMs - Milliseconds already spent waiting.
+ */
+
 /**
  * DatabasePoolDebugSnapshot type.
  * @typedef {object} DatabasePoolDebugSnapshot
@@ -21,7 +34,7 @@ export const POOL_CONFIGURATION_KEY = Symbol("velociousPoolConfigurationKey")
  * @property {number} idleCount - Number of idle connections.
  * @property {string} identifier - Database identifier.
  * @property {number} inUseCount - Number of checked-out connections.
- * @property {Array<Record<string, ?>>} [pendingCheckouts] - Waiting checkout snapshots.
+ * @property {Array<DatabasePoolPendingCheckoutDebugSnapshot>} [pendingCheckouts] - Waiting checkout snapshots.
  * @property {number} pendingCheckoutCount - Number of queued checkout requests.
  * @property {string} poolClass - Pool class name.
  */

package/build/database/record/index.js

@@ -13,7 +13,7 @@
 
 /**
  * Model class constructor type used for static `this` typing.
- * @template {VelociousDatabaseRecord} T
+ * @template T
  * @typedef {{new (changes?: Record<string, unknown>): T}} ModelConstructor
  */
 
@@ -508,7 +508,7 @@ class VelociousDatabaseRecord {
   /**
    * Runs before validation.
    * @template R
-   * @this {new (...args: Array<?>) => R}
+   * @this {ModelConstructor<R>}
    * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
@@ -519,7 +519,7 @@ class VelociousDatabaseRecord {
   /**
    * Runs before save.
    * @template R
-   * @this {new (...args: Array<?>) => R}
+   * @this {ModelConstructor<R>}
    * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
@@ -530,7 +530,7 @@ class VelociousDatabaseRecord {
   /**
    * Runs before create.
    * @template R
-   * @this {new (...args: Array<?>) => R}
+   * @this {ModelConstructor<R>}
    * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
@@ -541,7 +541,7 @@ class VelociousDatabaseRecord {
   /**
    * Runs before update.
    * @template R
-   * @this {new (...args: Array<?>) => R}
+   * @this {ModelConstructor<R>}
    * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
@@ -552,7 +552,7 @@ class VelociousDatabaseRecord {
   /**
    * Runs before destroy.
    * @template R
-   * @this {new (...args: Array<?>) => R}
+   * @this {ModelConstructor<R>}
    * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
@@ -563,7 +563,7 @@ class VelociousDatabaseRecord {
   /**
    * Runs after save.
    * @template R
-   * @this {new (...args: Array<?>) => R}
+   * @this {ModelConstructor<R>}
    * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
@@ -574,7 +574,7 @@ class VelociousDatabaseRecord {
   /**
    * Runs after create.
    * @template R
-   * @this {new (...args: Array<?>) => R}
+   * @this {ModelConstructor<R>}
    * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
@@ -585,7 +585,7 @@ class VelociousDatabaseRecord {
   /**
    * Runs after update.
    * @template R
-   * @this {new (...args: Array<?>) => R}
+   * @this {ModelConstructor<R>}
    * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
@@ -596,7 +596,7 @@ class VelociousDatabaseRecord {
   /**
    * Runs after destroy.
    * @template R
-   * @this {new (...args: Array<?>) => R}
+   * @this {ModelConstructor<R>}
    * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */