@steve31415/baselib 3.50.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/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.50.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",