@steve31415/baselib 3.45.0 → 3.46.0

package/dist/s2s.d.ts

@@ -67,9 +67,20 @@ export declare function resolveS2sCaller(opts: S2sOptions & {
 export declare function s2sAuth(opts: S2sOptions): import("hono").MiddlewareHandler<any, string, {}, Response | (Response & import("hono").TypedResponse<{
     error: string;
 }, 429 | 401 | 403, "json">)>;
+/** A cached ID token is replaced this long before its `exp`, as
+ *  google-auth-library's own IdTokenClient does (its eager-refresh default).
+ *  Tokens live an hour. */
+export declare const ID_TOKEN_REFRESH_MARGIN_MS: number;
+/** The longest one mint may take. On Cloud Run gcp-metadata sends the
+ *  metadata-server request with no timeout at all; a healthy mint takes
+ *  milliseconds. */
+export declare const ID_TOKEN_MINT_TIMEOUT_MS = 5000;
 /** fetch() with an OIDC identity token for the target's canonical audience.
  *  In test mode, sends the synthetic X-Test-S2S-Caller header instead
- *  (identity from TEST_S2S_IDENTITY, default 'test-service@test'). */
+ *  (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. */
 export declare function serviceFetch(url: string, opts: {
     audience: string;
 } & RequestInit): Promise<Response>;

package/dist/s2s.js

@@ -182,10 +182,26 @@ export function s2sAuth(opts) {
 }
 // ---------------------------------------------------------------------------
 // Caller side
-const idTokenClients = new Map();
+/** A cached ID token is replaced this long before its `exp`, as
+ *  google-auth-library's own IdTokenClient does (its eager-refresh default).
+ *  Tokens live an hour. */
+export const ID_TOKEN_REFRESH_MARGIN_MS = 5 * 60_000;
+/** The longest one mint may take. On Cloud Run gcp-metadata sends the
+ *  metadata-server request with no timeout at all; a healthy mint takes
+ *  milliseconds. */
+export const ID_TOKEN_MINT_TIMEOUT_MS = 5_000;
+// serviceFetch calls the provider directly, which bypasses IdTokenClient's
+// token cache (it lives in getRequestMetadataAsync), so the cache, the
+// single flight and the bound are kept here. Failures are never cached.
+let idTokenProvider;
+const idTokens = new Map();
+const idTokenMints = new Map();
 /** fetch() with an OIDC identity token for the target's canonical audience.
  *  In test mode, sends the synthetic X-Test-S2S-Caller header instead
- *  (identity from TEST_S2S_IDENTITY, default 'test-service@test'). */
+ *  (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. */
 export async function serviceFetch(url, opts) {
     const { audience, ...init } = opts;
     const headers = new Headers(init.headers);
@@ -193,17 +209,75 @@ export async function serviceFetch(url, opts) {
         headers.set('x-test-s2s-caller', process.env.TEST_S2S_IDENTITY ?? 'test-service@test');
     }
     else {
-        let clientPromise = idTokenClients.get(audience);
-        if (!clientPromise) {
-            clientPromise = (async () => {
-                const { GoogleAuth } = await import('google-auth-library');
-                return new GoogleAuth().getIdTokenClient(audience);
-            })();
-            idTokenClients.set(audience, clientPromise);
-        }
-        const client = await clientPromise;
-        const token = await client.idTokenProvider.fetchIdToken(audience);
+        const token = await abortable(idTokenFor(audience), init.signal);
         headers.set('authorization', `Bearer ${token}`);
     }
     return fetch(url, { ...init, headers });
 }
+function idTokenFor(audience) {
+    const cached = idTokens.get(audience);
+    if (cached && Date.now() < cached.refreshAt)
+        return Promise.resolve(cached.token);
+    let mint = idTokenMints.get(audience);
+    if (!mint) {
+        mint = withinMs(mintIdToken(audience), ID_TOKEN_MINT_TIMEOUT_MS, `ID token mint for ${audience}`)
+            .then((token) => {
+            const expiresAt = idTokenExpiry(token);
+            if (expiresAt !== undefined) {
+                idTokens.set(audience, { token, refreshAt: expiresAt - ID_TOKEN_REFRESH_MARGIN_MS });
+            }
+            return token;
+        })
+            .finally(() => idTokenMints.delete(audience));
+        idTokenMints.set(audience, mint);
+    }
+    return mint;
+}
+async function mintIdToken(audience) {
+    idTokenProvider ??= (async () => {
+        const { GoogleAuth } = await import('google-auth-library');
+        return (await new GoogleAuth().getIdTokenClient(audience)).idTokenProvider;
+    })();
+    const provider = idTokenProvider;
+    // A failed credential lookup is retried by the next call.
+    provider.catch(() => {
+        if (idTokenProvider === provider)
+            idTokenProvider = undefined;
+    });
+    return (await provider).fetchIdToken(audience);
+}
+/** Our own token's `exp` in ms, unverified; undefined if unreadable. */
+function idTokenExpiry(token) {
+    try {
+        const exp = JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString()).exp;
+        return typeof exp === 'number' ? exp * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `promise`, or a rejection once `ms` pass. The work itself cannot be
+ *  cancelled (fetchIdToken takes no signal); it is only no longer awaited. */
+function withinMs(promise, ms, what) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${what} timed out after ${ms} ms`)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+/** `promise`, or a rejection with the signal's reason when it aborts (as
+ *  fetch rejects), leaving the promise itself to its other waiters. Always
+ *  subscribes to `promise`, so a mint no one waits for any more never
+ *  rejects unhandled. */
+function abortable(promise, signal) {
+    if (!signal)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}

package/dist/sync/broadcaster.d.ts

@@ -6,4 +6,8 @@ export declare class ScopeBroadcaster<T> {
      * after the remaining listeners have received the message. */
     publish(scopeKey: string, message: T, except?: (message: T) => void): void;
     count(scopeKey: string): number;
+    /** The scopes with at least one listener: for an app that must
+     * re-announce to every local scope, e.g. after its database bridge may
+     * have missed notifications. */
+    scopes(): string[];
 }

package/dist/sync/broadcaster.js

@@ -44,4 +44,10 @@ export class ScopeBroadcaster {
     count(scopeKey) {
         return this.listeners.get(scopeKey)?.size ?? 0;
     }
+    /** The scopes with at least one listener: for an app that must
+     * re-announce to every local scope, e.g. after its database bridge may
+     * have missed notifications. */
+    scopes() {
+        return [...this.listeners.keys()];
+    }
 }

package/dist/sync/db-bridge.d.ts

@@ -22,9 +22,11 @@ export interface DbBroadcastBridgeOptions {
     /** Each notification's parsed JSON payload. An invalid payload is logged
      *  and skipped; a throw is logged and does not reach pg. */
     onMessage: (message: unknown) => void;
-    /** Called after the listener reconnects (not on the first connect).
-     *  Notifications sent while it was down are lost and unknowable, so the
-     *  app re-announces availability to every local scope. */
+    /** Called on every connect after start() has returned: a reconnect after
+     *  a loss, or the first success after a failed first attempt (not on a
+     *  first attempt that succeeds). Notifications sent while nothing was
+     *  listening are lost and unknowable, so the app re-announces availability
+     *  to every local scope. */
     onRecovered: () => void;
     /** Skip messages whose top-level `origin` is this bridge's `originId`,
      *  for an app that delivers its own writes locally and publishes them via
@@ -50,12 +52,16 @@ export declare class DbBroadcastBridge {
     private listener;
     private stopped;
     private connecting;
-    private connectedOnce;
+    /** Set once start() has returned. From then on the app may have sessions
+     *  that a missed notification leaves stale, so every later connect is a
+     *  recovery. */
+    private startReturned;
     private reconnectAttempt;
     private reconnectTimer;
     private heartbeatTimer;
     constructor(options: DbBroadcastBridgeOptions);
-    /** Connects the listener; rejects if the first connect fails. */
+    /** Makes the first connect attempt; never rejects. A failure is logged
+     *  and retried on the reconnect ladder (see the header). */
     start(): Promise<void>;
     /** Idempotent. Releases the listener client back to the pool; call it
      *  before the pool ends. Nothing is delivered after it resolves. */

package/dist/sync/db-bridge.js

@@ -4,6 +4,16 @@
 // (another copy, the old revision during a deploy, a job) reaches every
 // copy's sessions. Rules: ~/plasticine-way/docs/DATABASE.md "Cross-instance
 // live delivery: LISTEN/NOTIFY". Moved here from todo's src/db-broadcast.ts.
+//
+// Lifecycle contract. start() makes the first connect attempt and resolves
+// when it ends, whether or not it connected; it never rejects. A failed first
+// attempt is logged as a loss (WARN 'database broadcast listener lost',
+// `atStart: true`) and enters the same reconnect ladder as a later loss, so a
+// process booting while the database is unreachable neither crash-loops on a
+// top-level `await start()` nor stays deaf for life. Every connect after
+// start() has returned (after a loss, or after a failed first attempt) logs
+// INFO 'database broadcast listener recovered' and calls onRecovered: the app
+// may have been serving sessions while nothing was listening.
 import { randomUUID } from 'node:crypto';
 /** How often the bridge proves its LISTEN connection alive with a `select
  *  1`. Cloud SQL drops idle connections silently, the error surfaces only on
@@ -31,7 +41,10 @@ export class DbBroadcastBridge {
     listener = null;
     stopped = true;
     connecting = false;
-    connectedOnce = false;
+    /** Set once start() has returned. From then on the app may have sessions
+     *  that a missed notification leaves stale, so every later connect is a
+     *  recovery. */
+    startReturned = false;
     reconnectAttempt = 0;
     reconnectTimer = null;
     heartbeatTimer = null;
@@ -49,12 +62,28 @@ export class DbBroadcastBridge {
         this.heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DB_BRIDGE_HEARTBEAT_TIMEOUT_MS;
         this.reconnectDelaysMs = options.reconnectDelaysMs ?? DB_BRIDGE_RECONNECT_DELAYS_MS;
     }
-    /** Connects the listener; rejects if the first connect fails. */
+    /** Makes the first connect attempt; never rejects. A failure is logged
+     *  and retried on the reconnect ladder (see the header). */
     async start() {
         if (!this.stopped)
             return;
         this.stopped = false;
-        await this.connectListener(true);
+        try {
+            await this.connectListener();
+        }
+        catch (error) {
+            if (!this.stopped) {
+                this.logger.warn('database broadcast listener lost', {
+                    channel: this.channel,
+                    error: String(error),
+                    atStart: true,
+                });
+                this.scheduleReconnect();
+            }
+        }
+        finally {
+            this.startReturned = true;
+        }
     }
     /** Idempotent. Releases the listener client back to the pool; call it
      *  before the pool ends. Nothing is delivered after it resolves. */
@@ -86,7 +115,7 @@ export class DbBroadcastBridge {
         const payload = this.ignoreOwn ? { ...message, origin: this.originId } : message;
         await queryable.query('select pg_notify($1, $2)', [this.channel, JSON.stringify(payload)]);
     }
-    async connectListener(initial) {
+    async connectListener() {
         if (this.stopped || this.connecting || this.listener)
             return;
         this.connecting = true;
@@ -122,16 +151,11 @@ export class DbBroadcastBridge {
             this.adjustPoolMin(1);
             client.on('notification', (notification) => this.onNotification(notification.payload));
             this.scheduleHeartbeat(client);
-            const recovered = this.connectedOnce;
-            this.connectedOnce = true;
             this.reconnectAttempt = 0;
-            if (recovered) {
+            if (this.startReturned) {
                 this.logger.info('database broadcast listener recovered', { channel: this.channel });
                 this.callApp('onRecovered', () => this.onRecovered());
             }
-            else if (!initial) {
-                this.logger.info('database broadcast listener connected', { channel: this.channel });
-            }
         }
         finally {
             this.connecting = false;
@@ -193,7 +217,7 @@ export class DbBroadcastBridge {
         const delay = delays[Math.min(this.reconnectAttempt++, delays.length - 1)];
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
-            void this.connectListener(false).catch((error) => {
+            void this.connectListener().catch((error) => {
                 this.logger.warn('database broadcast reconnect failed', { channel: this.channel, error: String(error) });
                 this.scheduleReconnect();
             });

package/package.json

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