@steve31415/baselib 3.49.0 → 3.50.0

package/dist/db.d.ts

@@ -115,8 +115,16 @@ export declare const IDLE_PROBE_TIMEOUT_MS = 3000;
  *  - `connect`: a new connection failed to establish (handshake dropped,
  *    credential rejected, `connectionTimeoutMillis` hit mid-handshake).
  *    No statement ran, so the operation is safe to retry.
- *  - `wait`: the checkout timed out waiting for a free client. Pool
- *    starvation, not loss: the pool's `max` or a client held too long.
+ *    Also a checkout that timed out while the pool was still opening a
+ *    connection (`pool.connecting` > 0, message "a new connection did not
+ *    finish within the checkout timeout"): pg-pool queues a checkout that
+ *    finds an idle client, and if another checkout takes that client
+ *    first it hands the queued one a new connection, so a stalled
+ *    handshake surfaces with pg-pool's starvation error (coder
+ *    2026-11-02: total 4 of 6, 3 idle, a 15 s Cloud SQL handshake).
+ *  - `wait`: the checkout timed out waiting for a free client with no
+ *    connection being opened. Pool starvation, not loss: the pool's
+ *    `max` or a client held too long.
  *  - `idle`: a client idle in the pool died; pg-pool discards it and the
  *    next checkout opens a fresh one. Harmless by construction. With
  *    `meta.detectedAt: 'checkout'` the death went unnoticed until a
@@ -127,7 +135,8 @@ export declare const IDLE_PROBE_TIMEOUT_MS = 3000;
  *    any transaction or advisory lock it held is gone.
  *  Each event carries `elapsedMs` (time in that phase: the connect
  *  attempt, the wait, the idle spell, the checkout), the pg `code`, the
- *  pool's counts and, given a Cloud SQL credential reader,
+ *  pool's counts (`total`, `idle`, `waiting`, `connecting`, `max`) and,
+ *  given a Cloud SQL credential reader,
  *  `credentialRemainingMs`; the logger adds request activity, as on every
  *  server event (`activity.ts`: was Cloud Run CPU allocated?). Query:
  *  `['apps'] | where kind == 'db-connection-loss' | summarize count() by app, tostring(meta.phase)`.
@@ -169,7 +178,13 @@ export declare function createPool(opts?: PoolOptions): Promise<pg.Pool>;
  * drops the database `with (force)` can kill a backend mid-goodbye, and the
  * FATAL it sends back surfaces as an unhandled pool 'error' (it took down a
  * todo2 deploy with every test green, 2026-08-20). pg-pool emits 'remove' for
- * each client once its socket has closed; wait for all of them. */
+ * each client once its socket has closed; wait for all of them.
+ *
+ * Only a client that finished connecting gets a 'remove': one still being
+ * opened that then fails leaves the pool silently, so counting it (as
+ * `totalCount` does) waited forever for an event that never came (found
+ * 2026-11-02 with a stalled handshake). Count the connected clients, and
+ * any that finish connecting while the pool ends. */
 export declare function endPool(pool: pg.Pool): Promise<void>;
 export declare function migrate(pool: pg.Pool, migrationsDir: string, logger?: Logger): Promise<{
     applied: string[];

package/dist/db.js

@@ -112,7 +112,20 @@ const CONNECTION_LOSS_KIND = 'db-connection-loss';
 const ACQUIRE_FAILED_MESSAGE = {
     connect: 'database pool: new connection failed',
     wait: 'database pool: checkout timed out waiting for a free client',
+    stalled: 'database pool: a new connection did not finish within the checkout timeout',
 };
+/** pg-pool's client list, read for diagnostics only (pg-pool 3.x
+ *  `_clients`, pg 8.x `_connecting` / `_connected`). Undefined when a
+ *  version moves them; callers then fall back to the public counts. */
+function poolClients(pool) {
+    const clients = pool._clients;
+    return Array.isArray(clients) ? clients : undefined;
+}
+/** Clients the pool is still opening: counted in `totalCount`, neither idle
+ *  nor lent out. */
+function connectingCount(pool) {
+    return poolClients(pool)?.filter((c) => c._connecting === true).length;
+}
 const instrumented = new WeakSet();
 // Clients under an idle probe: their death is reported once, by the probe,
 // as an idle loss rather than a checked-out one.
@@ -127,7 +140,7 @@ function connectionLossWarner(pool, logger, credentialExpiry) {
             ...extra,
             ...(since === undefined ? {} : { elapsedMs: Date.now() - since }),
             code: err.code,
-            pool: { total: pool.totalCount, idle: pool.idleCount, waiting: pool.waitingCount },
+            pool: { total: pool.totalCount, idle: pool.idleCount, waiting: pool.waitingCount, connecting: connectingCount(pool), max: pool.options.max },
             ...(credentialExpiry
                 ? expiry === undefined
                     ? { credentialUnknown: true }
@@ -148,8 +161,16 @@ function connectionLossWarner(pool, logger, credentialExpiry) {
  *  - `connect`: a new connection failed to establish (handshake dropped,
  *    credential rejected, `connectionTimeoutMillis` hit mid-handshake).
  *    No statement ran, so the operation is safe to retry.
- *  - `wait`: the checkout timed out waiting for a free client. Pool
- *    starvation, not loss: the pool's `max` or a client held too long.
+ *    Also a checkout that timed out while the pool was still opening a
+ *    connection (`pool.connecting` > 0, message "a new connection did not
+ *    finish within the checkout timeout"): pg-pool queues a checkout that
+ *    finds an idle client, and if another checkout takes that client
+ *    first it hands the queued one a new connection, so a stalled
+ *    handshake surfaces with pg-pool's starvation error (coder
+ *    2026-11-02: total 4 of 6, 3 idle, a 15 s Cloud SQL handshake).
+ *  - `wait`: the checkout timed out waiting for a free client with no
+ *    connection being opened. Pool starvation, not loss: the pool's
+ *    `max` or a client held too long.
  *  - `idle`: a client idle in the pool died; pg-pool discards it and the
  *    next checkout opens a fresh one. Harmless by construction. With
  *    `meta.detectedAt: 'checkout'` the death went unnoticed until a
@@ -160,7 +181,8 @@ function connectionLossWarner(pool, logger, credentialExpiry) {
  *    any transaction or advisory lock it held is gone.
  *  Each event carries `elapsedMs` (time in that phase: the connect
  *  attempt, the wait, the idle spell, the checkout), the pg `code`, the
- *  pool's counts and, given a Cloud SQL credential reader,
+ *  pool's counts (`total`, `idle`, `waiting`, `connecting`, `max`) and,
+ *  given a Cloud SQL credential reader,
  *  `credentialRemainingMs`; the logger adds request activity, as on every
  *  server event (`activity.ts`: was Cloud Run CPU allocated?). Query:
  *  `['apps'] | where kind == 'db-connection-loss' | summarize count() by app, tostring(meta.phase)`.
@@ -224,8 +246,11 @@ export function logPoolErrors(pool, logger, options = {}) {
         // A checkout after end() is the caller's shutdown bug, not a lost connection.
         if (message.startsWith('Cannot use a pool after calling end'))
             return;
-        const phase = message === 'timeout exceeded when trying to connect' ? 'wait' : 'connect';
-        warn(phase, ACQUIRE_FAILED_MESSAGE[phase], err, started);
+        if (message !== 'timeout exceeded when trying to connect')
+            return warn('connect', ACQUIRE_FAILED_MESSAGE.connect, err, started);
+        // The pool's own timeout: starvation only if nothing was being opened.
+        const opening = (connectingCount(pool) ?? 0) > 0;
+        warn(opening ? 'connect' : 'wait', opening ? ACQUIRE_FAILED_MESSAGE.stalled : ACQUIRE_FAILED_MESSAGE.wait, err, started);
     };
     pool.connect = ((cb) => {
         const started = Date.now();
@@ -353,18 +378,30 @@ export async function createPool(opts = {}) {
  * drops the database `with (force)` can kill a backend mid-goodbye, and the
  * FATAL it sends back surfaces as an unhandled pool 'error' (it took down a
  * todo2 deploy with every test green, 2026-08-20). pg-pool emits 'remove' for
- * each client once its socket has closed; wait for all of them. */
+ * each client once its socket has closed; wait for all of them.
+ *
+ * Only a client that finished connecting gets a 'remove': one still being
+ * opened that then fails leaves the pool silently, so counting it (as
+ * `totalCount` does) waited forever for an event that never came (found
+ * 2026-11-02 with a stalled handshake). Count the connected clients, and
+ * any that finish connecting while the pool ends. */
 export async function endPool(pool) {
-    let open = pool.totalCount;
-    const allClosed = new Promise((resolve) => {
-        if (open === 0)
-            return resolve();
-        pool.on('remove', () => {
-            if (--open === 0)
-                resolve();
-        });
+    const clients = poolClients(pool);
+    let open = clients ? clients.filter((c) => c._connected === true).length : pool.totalCount;
+    let resolveAll;
+    const allClosed = new Promise((resolve) => (resolveAll = resolve));
+    const settle = () => {
+        if (open <= 0)
+            resolveAll();
+    };
+    pool.on('connect', () => open++);
+    pool.on('remove', () => {
+        open--;
+        settle();
     });
     await pool.end();
+    // No client can start connecting once end() has resolved.
+    settle();
     await allClosed;
 }
 // Plain-SQL migrations: numbered files (001-*.sql, 002-*.sql, …) applied in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.49.0",
+  "version": "3.50.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",