deepline 0.3.113 → 0.3.115

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/postgres-pool.ts

@@ -28,6 +28,10 @@ import {
   RuntimeSchedulerSubmissionAdmissionError,
   RuntimeSchedulerSaturatedError,
 } from './scheduler-capacity';
+import {
+  PLAY_ADMISSION_LARGE_BATCH_SIZE,
+  PLAY_ADMISSION_MAX_ACQUIRE_QUEUE_WAIT_MS,
+} from '../admission-transport-policy';
 import { RUNTIME_RELIABILITY_POLICY } from '../runtime-reliability-policy';
 export {
   isRuntimeSchedulerCapacityError,
@@ -163,6 +167,23 @@ export type RuntimeSchedulerPoolOptions = {
   url: string;
   applicationName?: string;
   maxClients?: number;
+  /**
+   * Serverless launchers must not pin a scarce PgBouncer client between
+   * requests. Long-lived workers retain the default; Vercel callers opt into
+   * a short idle lifetime through the shared Absurd pool resolver.
+   */
+  idleTimeoutMs?: number;
+  /**
+   * Optional request-local acquire queue capacity. The dense webhook batch
+   * owns a finite 256-source wave, so it may reserve enough scheduler waiters
+   * for that wave without widening ordinary worker/request callers.
+   */
+  maxAcquireQueueDepth?: number;
+  /**
+   * Optional request-local waiter lifetime. A bounded batch may spend longer
+   * than the ordinary single-launch acquire timeout draining its finite wave.
+   */
+  maxAcquireQueueWaitMs?: number;
 };
 
 export type RuntimeSchedulerQueryClient = {
@@ -328,6 +349,7 @@ export class RuntimeSchedulerPoolAdmission {
 type PoolEntry = {
   pool: Pool;
   maxClients: number;
+  maxAcquireQueueDepth: number;
   admission: RuntimeSchedulerPoolAdmission;
   breaker: BreakerState;
   stats: {
@@ -489,6 +511,14 @@ function getPoolEntry(options: RuntimeSchedulerPoolOptions): PoolEntry {
   assertRuntimeSchedulerHotPathUrl(options.url);
   const maxClients =
     options.maxClients ?? RUNTIME_SCHEDULER_POOL_DEFAULTS.maxClients;
+  const idleTimeoutMs =
+    options.idleTimeoutMs ?? RUNTIME_SCHEDULER_POOL_DEFAULTS.idleTimeoutMs;
+  const maxAcquireQueueDepth =
+    options.maxAcquireQueueDepth ??
+    RUNTIME_SCHEDULER_POOL_DEFAULTS.maxAcquireQueueDepth;
+  const maxAcquireQueueWaitMs =
+    options.maxAcquireQueueWaitMs ??
+    RUNTIME_SCHEDULER_POOL_DEFAULTS.acquireTimeoutMs;
   if (maxClients > RUNTIME_SCHEDULER_POOL_DEFAULTS.maxClientsHardCap) {
     throw new Error(
       `Runtime scheduler pool maxClients=${maxClients} exceeds the hard cap of ` +
@@ -496,16 +526,46 @@ function getPoolEntry(options: RuntimeSchedulerPoolOptions): PoolEntry {
         'instead of widening a single process pool.',
     );
   }
+  if (!Number.isSafeInteger(idleTimeoutMs) || idleTimeoutMs < 0) {
+    throw new Error(
+      `Runtime scheduler pool idleTimeoutMs=${idleTimeoutMs} must be a non-negative integer.`,
+    );
+  }
+  if (
+    !Number.isSafeInteger(maxAcquireQueueDepth) ||
+    maxAcquireQueueDepth < 1 ||
+    maxAcquireQueueDepth > PLAY_ADMISSION_LARGE_BATCH_SIZE
+  ) {
+    throw new Error(
+      `Runtime scheduler pool maxAcquireQueueDepth=${maxAcquireQueueDepth} ` +
+        `must be an integer between 1 and ${PLAY_ADMISSION_LARGE_BATCH_SIZE}.`,
+    );
+  }
+  if (
+    !Number.isSafeInteger(maxAcquireQueueWaitMs) ||
+    maxAcquireQueueWaitMs < RUNTIME_SCHEDULER_POOL_DEFAULTS.acquireTimeoutMs ||
+    maxAcquireQueueWaitMs > PLAY_ADMISSION_MAX_ACQUIRE_QUEUE_WAIT_MS
+  ) {
+    throw new Error(
+      `Runtime scheduler pool maxAcquireQueueWaitMs=${maxAcquireQueueWaitMs} ` +
+        `must be between ${RUNTIME_SCHEDULER_POOL_DEFAULTS.acquireTimeoutMs} and ` +
+        `${PLAY_ADMISSION_MAX_ACQUIRE_QUEUE_WAIT_MS}.`,
+    );
+  }
   const registry = getPoolRegistry();
   const connectionString = normalizePostgresConnectionStringForPg(options.url);
-  const key = `${connectionString}::${maxClients}`;
+  // The connection lifetime is part of a Pool's semantics. Do not let a
+  // serverless short-idle caller accidentally reuse a long-lived worker pool
+  // merely because both target the same runtime database.
+  const key = `${connectionString}::${maxClients}::${idleTimeoutMs}::${maxAcquireQueueDepth}::${maxAcquireQueueWaitMs}`;
   const existing = registry.get(key);
   if (existing) {
     // Next dev can retain the process-global pool across a module hot reload.
     // Upgrade that live entry in place when this admission layer first lands.
     existing.admission ??= new RuntimeSchedulerPoolAdmission(
       maxClients,
-      RUNTIME_SCHEDULER_POOL_DEFAULTS.maxAcquireQueueDepth,
+      maxAcquireQueueDepth,
+      maxAcquireQueueWaitMs,
     );
     return existing;
   }
@@ -515,7 +575,7 @@ function getPoolEntry(options: RuntimeSchedulerPoolOptions): PoolEntry {
     application_name:
       options.applicationName ?? 'deepline-runtime-scheduler-pool',
     max: maxClients,
-    idleTimeoutMillis: RUNTIME_SCHEDULER_POOL_DEFAULTS.idleTimeoutMs,
+    idleTimeoutMillis: idleTimeoutMs,
     connectionTimeoutMillis: RUNTIME_SCHEDULER_POOL_DEFAULTS.acquireTimeoutMs,
     query_timeout: RUNTIME_SCHEDULER_POOL_DEFAULTS.queryTimeoutMs,
     keepAlive: true,
@@ -523,9 +583,11 @@ function getPoolEntry(options: RuntimeSchedulerPoolOptions): PoolEntry {
   const entry: PoolEntry = {
     pool,
     maxClients,
+    maxAcquireQueueDepth,
     admission: new RuntimeSchedulerPoolAdmission(
       maxClients,
-      RUNTIME_SCHEDULER_POOL_DEFAULTS.maxAcquireQueueDepth,
+      maxAcquireQueueDepth,
+      maxAcquireQueueWaitMs,
     ),
     breaker: {
       consecutiveFailures: 0,
@@ -653,10 +715,7 @@ export async function withRuntimeSchedulerClient<T>(
     ) {
       throwIfSchedulerAborted(signal);
       breakerGate(entry);
-      if (
-        entry.pool.waitingCount >=
-        RUNTIME_SCHEDULER_POOL_DEFAULTS.maxAcquireQueueDepth
-      ) {
+      if (entry.pool.waitingCount >= entry.maxAcquireQueueDepth) {
         entry.stats.saturationRejections += 1;
         throw new RuntimeSchedulerSaturatedError(entry.pool.waitingCount);
       }