@steve31415/baselib 3.51.0 → 3.52.0

package/dist/db.d.ts

@@ -72,7 +72,15 @@ export interface PoolLoggingOptions {
     /** Epoch ms when the connector's cached Cloud SQL credential expires
      *  (`cloudSqlCredentialExpiry`); logged as `credentialRemainingMs`. */
     credentialExpiry?: () => number | undefined;
+    /** A new connection that takes at least this long, succeeding or
+     *  failing, logs its handshake timings (`timeNewConnections`). Default
+     *  `SLOW_CONNECT_MS`. */
+    slowConnectMs?: number;
 }
+/** A healthy Cloud SQL connect takes ~80 ms (2026-10-30); 2 s is well
+ *  outside that and well inside the 15 s checkout timeout, so a stall that
+ *  the timeout later kills has already been seen to be slow. */
+export declare const SLOW_CONNECT_MS = 2000;
 /** Pool settings every fleet pool carries; `createPool` applies them and
  *  is the way to get them (a hand-built pool spreads this, but prefer
  *  `createPool` with `user` / `sessionOptions` over building one). Decided

package/dist/db.js

@@ -71,6 +71,10 @@ export function cloudSqlCredentialExpiry(connector, instanceOptions) {
  * `set local statement_timeout = 0` — migrate() runs each file in its own
  * transaction, so the override scopes to that migration. */
 export const DEFAULT_STATEMENT_TIMEOUT_MS = 10 * 60_000;
+/** A healthy Cloud SQL connect takes ~80 ms (2026-10-30); 2 s is well
+ *  outside that and well inside the 15 s checkout timeout, so a stall that
+ *  the timeout later kills has already been seen to be slow. */
+export const SLOW_CONNECT_MS = 2_000;
 /** Pool settings every fleet pool carries; `createPool` applies them and
  *  is the way to get them (a hand-built pool spreads this, but prefer
  *  `createPool` with `user` / `sessionOptions` over building one). Decided
@@ -203,6 +207,7 @@ export function logPoolErrors(pool, logger, options = {}) {
         return;
     instrumented.add(pool);
     const warn = connectionLossWarner(pool, logger, options.credentialExpiry);
+    timeNewConnections(pool, logger, options);
     // Per-client bookkeeping across one checkout: the borrower-side error
     // listener (pg-pool drops its own at checkout) and when the client was
     // taken and given back.
@@ -267,6 +272,89 @@ export function logPoolErrors(pool, logger, options = {}) {
         });
     });
 }
+const CONNECT_TIMING_MESSAGE = 'database pool: new connection was slow or failed; handshake timings';
+/** Time every new connection's handshake and log any that took
+ *  `slowConnectMs` or longer, whether it then succeeded or failed (INFO,
+ *  `kind=db-connect-timing`): how far it got (`reached`) and when
+ *  each step finished, in ms from the start — `tcpMs` (socket connected),
+ *  `tlsMs` (TLS done; the Cloud SQL connector's socket only), `authMs`
+ *  (the server accepted the login; with IAM authentication Cloud SQL checks
+ *  the token here). The point is the step a stall sits in: before `tcp` is
+ *  the network path, between `tcp` and `tls` the Cloud SQL front end or the
+ *  certificate, between `tls`/`tcp` and `authenticated` the database login.
+ *  pg-pool's own events cannot say this, and a handshake whose checkout
+ *  already timed out ends silently there (coder 2026-11-02 19:07Z: a 15 s
+ *  Cloud SQL handshake left only the waiter's timeout behind). The
+ *  waiter's WARN (`db-connection-loss`) stays the alarm; this is its
+ *  detail, hence INFO. Works by subclassing the pool's client class
+ *  (pg-pool reads `pool.Client` for each new connection; pg 8.x creates
+ *  the socket in the client's constructor). */
+function timeNewConnections(pool, logger, options) {
+    const slowMs = options.slowConnectMs ?? SLOW_CONNECT_MS;
+    const holder = pool;
+    const Base = holder.Client;
+    if (typeof Base !== 'function')
+        return;
+    const log = logger?.with({ kind: 'db-connect-timing' });
+    holder.Client = class TimedClient extends Base {
+        #started = Date.now();
+        #marks = {};
+        #reached = 'started';
+        constructor(...args) {
+            super(...args);
+            const connection = this.connection;
+            const mark = (step) => () => {
+                this.#marks[step] ??= Date.now() - this.#started;
+                this.#reached = step;
+            };
+            connection?.stream?.once?.('connect', mark('tcp'));
+            connection?.stream?.once?.('secureConnect', mark('tls'));
+            connection?.once?.('authenticationOk', mark('authenticated'));
+        }
+        #report(err) {
+            const elapsedMs = Date.now() - this.#started;
+            // A quick failure (refused, rejected) has the waiter's WARN and no
+            // stall to locate.
+            if (elapsedMs < slowMs)
+                return;
+            if (!err)
+                this.#reached = 'ready';
+            const expiry = options.credentialExpiry?.();
+            const meta = {
+                outcome: err ? 'failed' : 'slow',
+                reached: this.#reached,
+                elapsedMs,
+                tcpMs: this.#marks.tcp,
+                tlsMs: this.#marks.tls,
+                authMs: this.#marks.authenticated,
+                pool: { total: pool.totalCount, idle: pool.idleCount, waiting: pool.waitingCount, max: pool.options.max },
+                ...(options.credentialExpiry ? (expiry === undefined ? { credentialUnknown: true } : { credentialRemainingMs: expiry - Date.now() }) : {}),
+                ...(err ? { error: err } : {}),
+            };
+            if (log)
+                log.info(CONNECT_TIMING_MESSAGE, meta);
+            else
+                console.info(CONNECT_TIMING_MESSAGE, { kind: 'db-connect-timing', ...processMeta(), ...meta, ...(err ? { error: serializeError(err) } : {}) });
+        }
+        connect(callback) {
+            if (typeof callback === 'function') {
+                // pg calls back (null, client) on success; pass every argument on.
+                const done = callback;
+                return super.connect(((err, ...rest) => {
+                    this.#report(err ?? undefined);
+                    done(err, ...rest);
+                }));
+            }
+            return super.connect().then((client) => {
+                this.#report(undefined);
+                return client;
+            }, (err) => {
+                this.#report(err);
+                throw err;
+            });
+        }
+    };
+}
 const probed = new WeakSet();
 /** Hand out no pooled client that died while idle. A client idle for
  *  `afterIdleMs` or more runs `select 1` (bounded by `timeoutMs`) before

package/package.json

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