@steve31415/baselib 3.55.0 → 3.56.0

package/dist/auth.d.ts

@@ -28,7 +28,8 @@ declare module 'hono' {
 export interface RequireIdentityOptions extends S2sOptions {
     /** Base URL of the auth service. */
     authUrl?: string;
-    /** Injectable for tests (defaults to global fetch). */
+    /** Injectable for tests (default: fetch with the auth host's address
+     *  cached in-process, fleet-dns.ts). */
     whoamiFetch?: typeof fetch;
     logger?: Logger;
     /** Distinguishes API requests (401/403 JSON) from page requests (redirect

package/dist/auth.js

@@ -31,6 +31,7 @@ import { createMiddleware } from 'hono/factory';
 import { authMode } from './config.js';
 import { truncate } from './log-core.js';
 import { RateLimiter, resolveS2sCaller } from './s2s.js';
+import { fleetAddressState, fleetFetch } from './fleet-dns.js';
 export const DEFAULT_AUTH_URL = 'https://auth.apps.snewman.net';
 export const SESSION_COOKIE = 'pw_session';
 /** The `code` in a 403 JSON body when a signed-in user is refused by the
@@ -45,7 +46,8 @@ function parseRole(value) {
 }
 export function requireIdentity(opts) {
     const authUrl = (opts.authUrl ?? DEFAULT_AUTH_URL).replace(/\/$/, '');
-    const whoamiFetch = opts.whoamiFetch ?? fetch;
+    const whoamiFetch = opts.whoamiFetch ?? fleetFetch;
+    const authHost = new URL(authUrl).hostname;
     const hitMs = opts.cacheTtl?.hitMs ?? 600_000;
     const missMs = opts.cacheTtl?.missMs ?? 30_000;
     const policy = opts.userAccess ?? 'owner';
@@ -155,6 +157,10 @@ export function requireIdentity(opts) {
     async function callWhoami(c, key, cached, cookieHeader, joiners) {
         const started = Date.now();
         const cacheState = !cached ? 'absent' : cached.user ? 'expired-user' : 'expired-unauthenticated';
+        // Whether this call must look up the auth host's address (absent) or has
+        // it cached in-process (fresh, or stale and refreshing in the
+        // background); undefined for a non-fleet authUrl.
+        const authAddress = fleetAddressState(authHost);
         const callFields = {
             cacheState,
             ...(cached ? { entryAgeMs: started - cached.filled } : {}),
@@ -166,6 +172,7 @@ export function requireIdentity(opts) {
             path: truncate(c.req.path, 200),
             upgrade: (c.req.header('upgrade') ?? '').toLowerCase() === 'websocket',
             cookieCount: cookieHeader.split(';').filter((part) => part.includes('=')).length,
+            ...(authAddress ? { authAddress } : {}),
         };
         hitsSinceLastCall = 0;
         callCount++;

package/dist/fleet-dns.d.ts

@@ -0,0 +1,52 @@
+import { type LookupAddress } from 'node:dns';
+import type { LookupFunction } from 'node:net';
+import { Agent } from 'undici';
+export declare const FLEET_DOMAIN_SUFFIX = ".apps.snewman.net";
+/** How long a resolved fleet address is used before a background refresh.
+ *  Long, because the address is a reserved static IP and a change is
+ *  healed by the connect-failure path anyway. */
+export declare const FLEET_ADDRESS_TTL_MS: number;
+export declare function isFleetHost(hostname: string): boolean;
+export type FleetAddressState = 'fresh' | 'stale' | 'absent';
+export interface FleetAddressCacheOptions {
+    /** All addresses for a fleet host (default: dns.promises.lookup, all). */
+    resolve?: (hostname: string) => Promise<LookupAddress[]>;
+    /** Non-fleet hosts, and families the cached answer lacks (default dns.lookup). */
+    systemLookup?: LookupFunction;
+    ttlMs?: number;
+    now?: () => number;
+    /** Called when a connect failure drops an entry. */
+    onInvalidate?: (e: {
+        hostname: string;
+        addresses: string[];
+        reason: string;
+    }) => void;
+}
+export declare class FleetAddressCache {
+    private readonly entries;
+    private readonly inflight;
+    private readonly resolve;
+    private readonly systemLookup;
+    private readonly ttlMs;
+    private readonly now;
+    private readonly onInvalidate?;
+    constructor(opts?: FleetAddressCacheOptions);
+    /** net.connect's `lookup` option. */
+    readonly lookup: LookupFunction;
+    /** undefined for a non-fleet host. */
+    state(hostname: string): FleetAddressState | undefined;
+    /** Forget a host's address, so its next connection resolves afresh. */
+    invalidate(hostname: string, reason: string): void;
+    private refresh;
+    private answer;
+}
+/** An undici Agent whose connections resolve through `cache` and drop the
+ *  cached address when a connection fails for an address reason. */
+export declare function createFleetAgent(cache: FleetAddressCache): Agent;
+/** The dispatcher baselib's server-to-server calls use. */
+export declare function fleetDispatcher(): Agent;
+/** The process-wide cache's state for `hostname` (undefined: not a fleet host). */
+export declare function fleetAddressState(hostname: string): FleetAddressState | undefined;
+/** fetch() through fleetDispatcher(). `dispatcher` is Node's (undici's)
+ *  extension of RequestInit, absent from the DOM type. */
+export declare const fleetFetch: typeof fetch;

package/dist/fleet-dns.js

@@ -0,0 +1,164 @@
+// An in-process address cache for fleet hosts (*.apps.snewman.net), used by
+// the server-to-server calls baselib makes: the session check against auth
+// (whoami) and serviceFetch.
+//
+// Why: on Cloud Run, Node's dns.lookup goes through getaddrinfo to the
+// metadata-server resolver, which keeps an answer for at most ~300 s
+// whatever the record's TTL (the fleet's A records carry 3600 s since
+// 2026-10-30; it made no difference). An infrequent caller therefore paid a
+// ~60 ms lookup on almost every call: whoami took 113 ms p50 when the app's
+// previous call was 300-3600 s earlier against 52 ms under 300 s, 79 % of
+// calls in the slow bucket (2026-10-30 → 11-05,
+// ~/migration/research/whoami-latency-2026-10-30.md, "Follow-up 2026-11-05").
+//
+// What: every fleet host resolves to the one static load-balancer address,
+// so a resolved answer is kept for FLEET_ADDRESS_TTL_MS and, once older,
+// still served at once while a background lookup refreshes it. A connection
+// that fails in a way an address change would cause (refused, timed out,
+// unreachable) drops the entry, so the next call resolves afresh: an
+// address change heals after one failed call. Only the lookup changes: the
+// URL, Host header and TLS server name (SNI) are still the hostname. Other
+// hosts go straight to dns.lookup, uncached.
+import dns from 'node:dns';
+import { Agent, buildConnector } from 'undici';
+import { processMeta } from './process-meta.js';
+export const FLEET_DOMAIN_SUFFIX = '.apps.snewman.net';
+/** How long a resolved fleet address is used before a background refresh.
+ *  Long, because the address is a reserved static IP and a change is
+ *  healed by the connect-failure path anyway. */
+export const FLEET_ADDRESS_TTL_MS = 60 * 60_000;
+/** Connect errors that a stale address would cause. Anything else (a TLS
+ *  or HTTP failure) says nothing about the address and keeps the entry. */
+const ADDRESS_FAILURE_CODES = new Set(['ECONNREFUSED', 'ETIMEDOUT', 'EHOSTUNREACH', 'ENETUNREACH', 'UND_ERR_CONNECT_TIMEOUT']);
+export function isFleetHost(hostname) {
+    return normalize(hostname).endsWith(FLEET_DOMAIN_SUFFIX);
+}
+function normalize(hostname) {
+    return hostname.toLowerCase().replace(/\.$/, '');
+}
+export class FleetAddressCache {
+    entries = new Map();
+    inflight = new Map();
+    resolve;
+    systemLookup;
+    ttlMs;
+    now;
+    onInvalidate;
+    constructor(opts = {}) {
+        this.resolve = opts.resolve ?? ((hostname) => dns.promises.lookup(hostname, { all: true }));
+        this.systemLookup = opts.systemLookup ?? dns.lookup;
+        this.ttlMs = opts.ttlMs ?? FLEET_ADDRESS_TTL_MS;
+        this.now = opts.now ?? Date.now;
+        this.onInvalidate = opts.onInvalidate;
+    }
+    /** net.connect's `lookup` option. */
+    lookup = (hostname, options, callback) => {
+        if (!isFleetHost(hostname))
+            return this.systemLookup(hostname, options, callback);
+        const key = normalize(hostname);
+        const entry = this.entries.get(key);
+        if (entry) {
+            if (this.now() - entry.resolvedAt >= this.ttlMs)
+                this.refresh(key).catch(() => { }); // keep the old answer
+            return this.answer(entry, hostname, options, callback);
+        }
+        this.refresh(key).then((fresh) => this.answer(fresh, hostname, options, callback), (err) => callback(err, options.all ? [] : ''));
+    };
+    /** undefined for a non-fleet host. */
+    state(hostname) {
+        if (!isFleetHost(hostname))
+            return undefined;
+        const entry = this.entries.get(normalize(hostname));
+        if (!entry)
+            return 'absent';
+        return this.now() - entry.resolvedAt < this.ttlMs ? 'fresh' : 'stale';
+    }
+    /** Forget a host's address, so its next connection resolves afresh. */
+    invalidate(hostname, reason) {
+        const key = normalize(hostname);
+        const entry = this.entries.get(key);
+        if (!entry)
+            return;
+        this.entries.delete(key);
+        this.onInvalidate?.({ hostname: key, addresses: entry.addresses.map((a) => a.address), reason });
+    }
+    // One resolution per host at a time; a failure is never cached.
+    refresh(key) {
+        let pending = this.inflight.get(key);
+        if (!pending) {
+            pending = this.resolve(key)
+                .then((addresses) => {
+                if (addresses.length === 0)
+                    throw Object.assign(new Error(`no address for ${key}`), { code: 'ENOTFOUND' });
+                const entry = { addresses, resolvedAt: this.now() };
+                this.entries.set(key, entry);
+                return entry;
+            })
+                .finally(() => this.inflight.delete(key));
+            this.inflight.set(key, pending);
+        }
+        return pending;
+    }
+    answer(entry, hostname, options, callback) {
+        const family = familyNumber(options.family);
+        const addresses = family ? entry.addresses.filter((a) => a.family === family) : entry.addresses;
+        if (addresses.length === 0)
+            return this.systemLookup(hostname, options, callback);
+        if (options.all)
+            callback(null, addresses);
+        else
+            callback(null, addresses[0].address, addresses[0].family);
+    }
+}
+function familyNumber(family) {
+    if (family === 'IPv4')
+        return 4;
+    if (family === 'IPv6')
+        return 6;
+    return family ?? 0;
+}
+/** The code of a connect error, looking inside the AggregateError that
+ *  Node's happy-eyeballs connect raises when every address failed. */
+function addressFailureCode(err) {
+    const codes = [err, ...(err.errors ?? [])].map((e) => e?.code);
+    return codes.find((c) => typeof c === 'string' && ADDRESS_FAILURE_CODES.has(c));
+}
+/** An undici Agent whose connections resolve through `cache` and drop the
+ *  cached address when a connection fails for an address reason. */
+export function createFleetAgent(cache) {
+    const connect = buildConnector({ lookup: cache.lookup });
+    return new Agent({
+        connect: (opts, callback) => connect(opts, (...args) => {
+            const err = args[0];
+            if (err) {
+                const code = addressFailureCode(err);
+                if (code)
+                    cache.invalidate(opts.hostname, code);
+            }
+            callback(...args);
+        }),
+    });
+}
+let shared;
+function sharedFleet() {
+    if (!shared) {
+        const cache = new FleetAddressCache({
+            // Rare (the load balancer's address would have to change), so worth
+            // a line. No logger reaches this module: stdout, like db.ts's backstop.
+            onInvalidate: (e) => console.warn('fleet address dropped after connect failure', { ...processMeta(), ...e }),
+        });
+        shared = { cache, agent: createFleetAgent(cache) };
+    }
+    return shared;
+}
+/** The dispatcher baselib's server-to-server calls use. */
+export function fleetDispatcher() {
+    return sharedFleet().agent;
+}
+/** The process-wide cache's state for `hostname` (undefined: not a fleet host). */
+export function fleetAddressState(hostname) {
+    return sharedFleet().cache.state(hostname);
+}
+/** fetch() through fleetDispatcher(). `dispatcher` is Node's (undici's)
+ *  extension of RequestInit, absent from the DOM type. */
+export const fleetFetch = (input, init) => fetch(input, { ...init, dispatcher: fleetDispatcher() });

package/dist/s2s.d.ts

@@ -80,7 +80,8 @@ export declare const ID_TOKEN_MINT_TIMEOUT_MS = 5000;
  *  (identity from TEST_S2S_IDENTITY, default 'test-service@test'). The token
  *  is cached per audience until ID_TOKEN_REFRESH_MARGIN_MS before it
  *  expires; concurrent calls share one mint, which is bounded by
- *  ID_TOKEN_MINT_TIMEOUT_MS, and `init.signal` also ends the wait for it. */
+ *  ID_TOKEN_MINT_TIMEOUT_MS, and `init.signal` also ends the wait for it.
+ *  Fleet hosts' addresses are cached in-process (fleet-dns.ts). */
 export declare function serviceFetch(url: string, opts: {
     audience: string;
 } & RequestInit): Promise<Response>;

package/dist/s2s.js

@@ -17,6 +17,7 @@ import { OAuth2Client } from 'google-auth-library';
 import { createHash } from 'node:crypto';
 import { authMode } from './config.js';
 import { truncate } from './log-core.js';
+import { fleetFetch } from './fleet-dns.js';
 /** The fleet coding agent's service-account email, read from AGENT_SA — set at
  * deploy time by each service (SECURITY.md: agents have full access, so
  * grantAllows always admits this identity). Env-driven rather than a baked-in
@@ -201,7 +202,8 @@ const idTokenMints = new Map();
  *  (identity from TEST_S2S_IDENTITY, default 'test-service@test'). The token
  *  is cached per audience until ID_TOKEN_REFRESH_MARGIN_MS before it
  *  expires; concurrent calls share one mint, which is bounded by
- *  ID_TOKEN_MINT_TIMEOUT_MS, and `init.signal` also ends the wait for it. */
+ *  ID_TOKEN_MINT_TIMEOUT_MS, and `init.signal` also ends the wait for it.
+ *  Fleet hosts' addresses are cached in-process (fleet-dns.ts). */
 export async function serviceFetch(url, opts) {
     const { audience, ...init } = opts;
     const headers = new Headers(init.headers);
@@ -212,7 +214,7 @@ export async function serviceFetch(url, opts) {
         const token = await abortable(idTokenFor(audience), init.signal);
         headers.set('authorization', `Bearer ${token}`);
     }
-    return fetch(url, { ...init, headers });
+    return fleetFetch(url, { ...init, headers });
 }
 function idTokenFor(audience) {
     const cached = idTokens.get(audience);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.55.0",
+  "version": "3.56.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -133,6 +133,7 @@
     "google-auth-library": "^10.5.0",
     "hono": "^4.7.0",
     "pg": "^8.14.0",
+    "undici": "^6.29.1",
     "web-vitals": "^6.1.1",
     "zod": "^4.6.5"
   },