@steve31415/baselib 3.48.3 → 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

@@ -2,6 +2,7 @@
 // (per-checkout instance — see TESTING.md). Cloud Run: the Cloud SQL Node
 // connector with IAM authentication (CLOUD_SQL_INSTANCE + DB_IAM_USER +
 // DB_NAME env vars) — no database passwords anywhere in the serving path.
+import { createHash } from 'node:crypto';
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import pg from 'pg';
@@ -111,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.
@@ -126,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 }
@@ -147,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
@@ -159,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)`.
@@ -223,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();
@@ -352,23 +378,37 @@ 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
-// order, recorded in schema_migrations, each inside a transaction, guarded by
-// an advisory lock so concurrent boots can't race. Applied at service boot.
+// order, recorded in schema_migrations with their content's sha256, each
+// inside a transaction, guarded by an advisory lock so concurrent boots can't
+// race. Applied at service boot; an applied file whose content has since
+// changed fails the boot.
 // Lock loss (see logPoolErrors): all the work runs on the lock's own client,
 // so a dead connection fails the next statement and the boot aborts — no
 // window in which a migration runs unlocked.
@@ -380,18 +420,48 @@ export async function migrate(pool, migrationsDir, logger) {
         await client.query('select pg_advisory_lock(hashtext($1))', ['baselib_migrate']);
         await client.query(`create table if not exists schema_migrations (
          name text primary key,
-         applied_at timestamptz not null default now()
+         applied_at timestamptz not null default now(),
+         sha256 text
        )`);
-        const { rows } = await client.query('select name from schema_migrations');
-        const done = new Set(rows.map((r) => r.name));
+        await client.query('alter table schema_migrations add column if not exists sha256 text');
+        const { rows } = await client.query('select name, sha256 from schema_migrations');
+        const recorded = new Map(rows.map((r) => [r.name, r.sha256]));
+        const contents = new Map();
         for (const file of files) {
-            if (done.has(file))
-                continue;
             const sql = await readFile(join(migrationsDir, file), 'utf8');
+            contents.set(file, { sql, sha256: createHash('sha256').update(sql).digest('hex') });
+        }
+        // A shipped migration file is never edited (plasticine-way docs/DATABASE.md): the
+        // runner skips a recorded name, so an edit would never reach the database while the
+        // code relying on it ships. Refuse to boot instead, before applying anything, so the
+        // new revision fails its start and the old one keeps serving (people, 2026-11-02).
+        // Rows recorded before hashes were kept get the file's current hash, once.
+        const edited = [];
+        for (const file of files) {
+            if (!recorded.has(file))
+                continue;
+            const { sha256 } = contents.get(file);
+            const was = recorded.get(file);
+            if (was == null) {
+                await client.query('update schema_migrations set sha256 = $2 where name = $1', [file, sha256]);
+            }
+            else if (was !== sha256) {
+                edited.push(file);
+            }
+        }
+        if (edited.length > 0) {
+            throw new Error(`migration ${edited.join(', ')} was edited after it was applied; a shipped migration is never ` +
+                'edited: restore the file and put the change in a new migration (a local database holding an ' +
+                'unshipped draft: drop it and re-run)');
+        }
+        for (const file of files) {
+            if (recorded.has(file))
+                continue;
+            const { sql, sha256 } = contents.get(file);
             try {
                 await client.query('begin');
                 await client.query(sql);
-                await client.query('insert into schema_migrations (name) values ($1)', [file]);
+                await client.query('insert into schema_migrations (name, sha256) values ($1, $2)', [file, sha256]);
                 await client.query('commit');
             }
             catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.48.3",
+  "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",