@steve31415/baselib 3.49.0 → 3.51.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/dist/email.d.ts

@@ -36,10 +36,25 @@ export interface EmailDeps {
     fetchImpl?: typeof fetch;
     /** Merged into every log line so callers can attribute the send. */
     context?: Record<string, unknown>;
+    /** Whole-request deadline (connect, response and body), default
+     *  `DEFAULT_EMAIL_TIMEOUT_MS`. A timed-out send is an ordinary failure,
+     *  but Resend may have accepted it and delivered the email: retry with
+     *  the same `idempotencyKey` to be safe. */
+    timeoutMs?: number;
+    /** Sent as Resend's `Idempotency-Key` HTTP request header (not an email
+     *  header — those are `EmailMessage.headers`). Up to 256 characters; for
+     *  24 hours a retry with the same key and the same message returns the
+     *  original send's id without sending again. Derive it from what makes
+     *  the email unique (e.g. `digest:<user>:<date>`), never from the
+     *  attempt. See the header of this file for the verified semantics. */
+    idempotencyKey?: string;
 }
+export declare const DEFAULT_EMAIL_TIMEOUT_MS = 30000;
 /**
  * Send one email through Resend. Never throws: every failure is an ERROR
  * log (with enough of the message to redo the send by hand) and an
- * `{ ok: false, error }` result the caller surfaces where it matters.
+ * `{ ok: false, error }` result the caller surfaces where it matters. That
+ * includes a timeout (`deps.timeoutMs`), after which the email may
+ * nevertheless have been delivered.
  */
 export declare function sendEmail(msg: EmailMessage, deps: EmailDeps): Promise<SendEmailResult>;

package/dist/email.js

@@ -14,22 +14,38 @@
 // about external systems"): `POST https://api.resend.com/emails` with
 // `{from, to: [to], subject, text?, html?}` answers 200 `{id}`; failures are
 // 4xx/5xx with a JSON body.
+//
+// Idempotency (verified 2026-11-02 against
+// https://resend.com/docs/dashboard/emails/idempotency-keys and a live probe
+// to the `delivered@resend.dev` test sink): the HTTP request header
+// `Idempotency-Key`, 1–256 characters, kept 24 hours. A repeat with the same
+// key and the same body sends nothing and answers 200 with the original
+// `{id}`, so a replayed send is an ordinary success here. A repeat with a
+// different body is 409 `invalid_idempotent_request`; one that arrives while
+// the first is still in flight is 409 `concurrent_idempotent_requests`
+// (retry later); a key over 256 characters is 400 `invalid_idempotency_key`.
+// All three are failures: none confirms that this message was accepted.
 import { serializeError, truncate } from './log-core.js';
 export const RESEND_API_URL = 'https://api.resend.com/emails';
+export const DEFAULT_EMAIL_TIMEOUT_MS = 30_000;
 /**
  * Send one email through Resend. Never throws: every failure is an ERROR
  * log (with enough of the message to redo the send by hand) and an
- * `{ ok: false, error }` result the caller surfaces where it matters.
+ * `{ ok: false, error }` result the caller surfaces where it matters. That
+ * includes a timeout (`deps.timeoutMs`), after which the email may
+ * nevertheless have been delivered.
  */
 export async function sendEmail(msg, deps) {
     const { logger } = deps;
     const fetchImpl = deps.fetchImpl ?? fetch;
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_EMAIL_TIMEOUT_MS;
     const base = {
         to: msg.to,
         subject: truncate(msg.subject, 200),
         textLength: msg.text?.length ?? 0,
         htmlLength: msg.html?.length ?? 0,
         attachmentCount: msg.attachments?.length ?? 0,
+        ...(deps.idempotencyKey !== undefined ? { idempotencyKey: deps.idempotencyKey } : {}),
         ...deps.context,
     };
     const preview = { text: truncate(msg.text ?? '', 500), html: truncate(msg.html ?? '', 500) };
@@ -47,7 +63,12 @@ export async function sendEmail(msg, deps) {
     try {
         const res = await fetchImpl(RESEND_API_URL, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${deps.apiKey}` },
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${deps.apiKey}`,
+                ...(deps.idempotencyKey !== undefined ? { 'Idempotency-Key': deps.idempotencyKey } : {}),
+            },
+            signal: AbortSignal.timeout(timeoutMs),
             body: JSON.stringify({
                 from: msg.from,
                 to: [msg.to],
@@ -85,7 +106,13 @@ export async function sendEmail(msg, deps) {
     }
     catch (err) {
         const elapsedMs = Date.now() - start;
-        logger.error('email_send_error', { ...base, error: serializeError(err), elapsedMs, ...preview });
-        return { ok: false, error: `Network error: ${err instanceof Error ? err.message : String(err)}` };
+        const timedOut = err instanceof Error && err.name === 'TimeoutError';
+        logger.error('email_send_error', { ...base, error: serializeError(err), timedOut, timeoutMs, elapsedMs, ...preview });
+        return {
+            ok: false,
+            error: timedOut
+                ? `Timed out after ${timeoutMs} ms waiting for Resend; the email may still have been delivered`
+                : `Network error: ${err instanceof Error ? err.message : String(err)}`,
+        };
     }
 }

package/package.json

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