@steve31415/baselib 3.13.0 → 3.15.0

package/dist/activity.d.ts

@@ -1,7 +1,9 @@
 export declare function requestStarted(): void;
 export declare function requestEnded(): void;
-/** The fields a diagnostic event carries: requests in flight right now and
- *  how long ago the last one ended (undefined before the first request). */
+/** The fields an event carries: requests in flight right now and how long
+ *  ago the last one ended. Before the first request has ended there is no
+ *  such moment, so `sinceLastRequestMs` is omitted rather than invented;
+ *  `inFlightRequests` alone marks a server that has not finished one yet. */
 export declare function activitySnapshot(): {
     inFlightRequests: number;
     sinceLastRequestMs?: number;
@@ -10,5 +12,5 @@ export declare function activitySnapshot(): {
  *  request ends when the handler returns its Response; a streaming body
  *  that outlives that is not tracked. */
 export declare function trackActivity<A extends unknown[]>(fetch: (...args: A) => Response | Promise<Response>): (...args: A) => Promise<Response>;
-/** Test hook: forget everything. */
+/** Test hook: forget everything, including the logger registration. */
 export declare function resetActivity(): void;

package/dist/activity.js

@@ -1,5 +1,5 @@
-// Request activity of this process, for log events that need to know
-// whether Cloud Run had CPU allocated at the time: with request-based
+// Request activity of this process, carried by every server log event so
+// any of them can say whether Cloud Run had CPU allocated at the time: with request-based
 // billing (the fleet default) an instance's CPU is throttled to almost
 // nothing between requests, and timers, connection handshakes and
 // credential refreshes crawl. A connection failure logged with
@@ -7,10 +7,13 @@
 // throttled tail; one with `inFlightRequests: 1` did not.
 //
 // `startServer` tracks every HTTP request automatically. A custom server
-// wraps its fetch handler with `trackActivity`. WebSocket sessions are not
+// wraps its fetch handler with `trackActivity`. Wrapping is also what
+// registers this module as the logger's process-meta source (process-meta.ts), so a
+// process that serves nothing logs no activity fields. WebSocket sessions are not
 // counted (they hold CPU on Cloud Run, but the upgrade bypasses fetch), so
 // on a WebSocket-heavy app zero in-flight requests does not prove the
 // instance was idle.
+import { setProcessMetaSource } from './process-meta.js';
 let inFlight = 0;
 let lastRequestEndedAt = 0;
 export function requestStarted() {
@@ -20,8 +23,10 @@ export function requestEnded() {
     inFlight = Math.max(0, inFlight - 1);
     lastRequestEndedAt = Date.now();
 }
-/** The fields a diagnostic event carries: requests in flight right now and
- *  how long ago the last one ended (undefined before the first request). */
+/** The fields an event carries: requests in flight right now and how long
+ *  ago the last one ended. Before the first request has ended there is no
+ *  such moment, so `sinceLastRequestMs` is omitted rather than invented;
+ *  `inFlightRequests` alone marks a server that has not finished one yet. */
 export function activitySnapshot() {
     return {
         inFlightRequests: inFlight,
@@ -32,6 +37,7 @@ export function activitySnapshot() {
  *  request ends when the handler returns its Response; a streaming body
  *  that outlives that is not tracked. */
 export function trackActivity(fetch) {
+    setProcessMetaSource(activitySnapshot);
     return async (...args) => {
         requestStarted();
         try {
@@ -42,8 +48,9 @@ export function trackActivity(fetch) {
         }
     };
 }
-/** Test hook: forget everything. */
+/** Test hook: forget everything, including the logger registration. */
 export function resetActivity() {
+    setProcessMetaSource(undefined);
     inFlight = 0;
     lastRequestEndedAt = 0;
 }

package/dist/db.d.ts

@@ -100,9 +100,9 @@ export declare const FLEET_POOL_DEFAULTS: {
  *    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, `inFlightRequests` + `sinceLastRequestMs` (`activity.ts`:
- *  was Cloud Run CPU allocated?) and, given a Cloud SQL credential reader,
- *  `credentialRemainingMs`. Query:
+ *  pool's counts 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)`.
  *
  *  The checked-out path is the one that used to crash the process: pg-pool

package/dist/db.js

@@ -5,8 +5,8 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import pg from 'pg';
-import { activitySnapshot } from './activity.js';
 import { requireEnv } from './config.js';
+import { processMeta } from './process-meta.js';
 import { serializeError } from './log-core.js';
 // DATE columns come back as 'YYYY-MM-DD' strings, not JS Dates: calendar
 // dates are timezone-free by meaning, and a Date object smears them across
@@ -106,9 +106,9 @@ const instrumented = new WeakSet();
  *    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, `inFlightRequests` + `sinceLastRequestMs` (`activity.ts`:
- *  was Cloud Run CPU allocated?) and, given a Cloud SQL credential reader,
- *  `credentialRemainingMs`. Query:
+ *  pool's counts 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)`.
  *
  *  The checked-out path is the one that used to crash the process: pg-pool
@@ -134,7 +134,6 @@ export function logPoolErrors(pool, logger, options = {}) {
             ...(since === undefined ? {} : { elapsedMs: Date.now() - since }),
             code: err.code,
             pool: { total: pool.totalCount, idle: pool.idleCount, waiting: pool.waitingCount },
-            ...activitySnapshot(),
             ...(options.credentialExpiry
                 ? expiry === undefined
                     ? { credentialUnknown: true }
@@ -144,8 +143,9 @@ export function logPoolErrors(pool, logger, options = {}) {
         };
         if (log)
             log.warn(message, meta);
+        // No logger to add the activity fields, so add them here.
         else
-            console.warn(message, { kind: CONNECTION_LOSS_KIND, ...meta, error: serializeError(err) });
+            console.warn(message, { kind: CONNECTION_LOSS_KIND, ...processMeta(), ...meta, error: serializeError(err) });
     };
     // Per-client bookkeeping across one checkout: the borrower-side error
     // listener (pg-pool drops its own at checkout) and when the client was

package/dist/http.js

@@ -55,8 +55,9 @@ export function startServer(opts) {
     assertBootSafety();
     logUncaughtErrors(opts.logger);
     const port = opts.port ?? Number(process.env.PORT ?? 8080);
-    // Every request counts as activity (activity.ts) so connection-loss
-    // events can say whether Cloud Run had CPU allocated at the time.
+    // Every request counts as activity (activity.ts), and wrapping registers
+    // the logger's activity source: every event from here on says whether
+    // Cloud Run had CPU allocated at the time.
     const server = serve({ fetch: trackActivity(opts.app.fetch), port }, (info) => {
         opts.logger.info('server started', { port: info.port });
     });

package/dist/log-core.d.ts

@@ -121,6 +121,10 @@ export interface EventFactoryOptions {
     app: string;
     source: 'server' | 'browser';
     context?: Record<string, unknown>;
+    /** Process-level fields merged under `meta` on every event, read at event
+     *  time (the server logger passes process-meta.ts's request-activity source).
+     *  Ignored for browser events. The caller's own meta wins on a name clash. */
+    processMeta?: () => Record<string, unknown> | undefined;
 }
 export declare function makeEvent(opts: EventFactoryOptions, level: LogLevel, message: string, meta?: Record<string, unknown>): LogEvent;
 /** The event for one logger call plus, the first time a site's meta breaks
@@ -152,5 +156,9 @@ export declare function shapeMeta(meta: Record<string, unknown>): {
     issues: ShapeIssue[];
     leaves: number;
 };
+/** Toggle strict shape checking — for tests that exercise the rewrite/WARN
+ *  behavior itself. Restore with setLogShapeStrict(true) (or leave it: vitest
+ *  isolates module state per file). */
+export declare function setLogShapeStrict(on: boolean): void;
 /** Forget which sites have been flagged (tests). */
 export declare function resetLogShapeWarnings(): void;

package/dist/log-core.js

@@ -361,6 +361,11 @@ function buildEvent(opts, level, message, meta) {
         if (rewrites.length > 0)
             m = { ...m, logShape: rewrites.join('+') };
     }
+    // Added after shaping: a fixed vocabulary that must not count against the
+    // site's leaf budget.
+    const processMeta = opts.source === 'server' ? opts.processMeta?.() : undefined;
+    if (processMeta)
+        m = { ...processMeta, ...m };
     const event = {
         _time: new Date().toISOString(),
         app: opts.app,
@@ -377,6 +382,12 @@ function buildEvent(opts, level, message, meta) {
  *  the shape rules in this process, a WARN `kind=log-shape` naming the site. */
 export function makeEvents(opts, level, message, meta) {
     const { event, issues } = buildEvent(opts, level, message, meta);
+    if (issues.length > 0 && strict) {
+        throw new Error(`log-shape (strict): "${message}" — ${issues.map(describeIssue).join('; ')}. ` +
+            'Fix the logging site: keys are columns (OPERATIONS.md). ' +
+            '(Strict mode is on under vitest so shape bugs fail tests instead of ' +
+            'shipping as rewrites; setLogShapeStrict(false) to test the rewrite itself.)');
+    }
     const fresh = issues.filter((i) => {
         const key = `${i.kind}\n${message}`;
         if (flagged.has(key))
@@ -457,6 +468,27 @@ export function shapeMeta(meta) {
 // Sites already flagged in this process, by issue kind and message: the
 // first offending event is worth a WARN, the ten-thousandth is not.
 const flagged = new Set();
+// Strict mode: makeEvents throws on a shape issue instead of rewriting.
+// On by default under vitest so a shape bug fails the suite that exercises
+// the logging site rather than reaching production as a rewritten event
+// with a once-per-process WARN. LOG_SHAPE_STRICT=1/0 overrides the default
+// either way (production stays permissive: a logger must never throw there).
+function strictDefault() {
+    // log-core is shared with the browser build; no bare `process` access.
+    if (typeof process === 'undefined' || !process.env)
+        return false;
+    const explicit = process.env.LOG_SHAPE_STRICT;
+    if (explicit !== undefined && explicit !== '')
+        return explicit !== '0';
+    return process.env.VITEST !== undefined;
+}
+let strict = strictDefault();
+/** Toggle strict shape checking — for tests that exercise the rewrite/WARN
+ *  behavior itself. Restore with setLogShapeStrict(true) (or leave it: vitest
+ *  isolates module state per file). */
+export function setLogShapeStrict(on) {
+    strict = on;
+}
 /** Forget which sites have been flagged (tests). */
 export function resetLogShapeWarnings() {
     flagged.clear();

package/dist/log.d.ts

@@ -1,6 +1,6 @@
 import { Logger, LogShipper, ShipperOptions } from './log-core.js';
-export { LogShipper, serializeError, truncate } from './log-core.js';
-export type { Logger, LogEvent, LogLevel, ShipperOptions, ShippedBatch, ShipFailureReason, } from './log-core.js';
+export { LogShipper, makeEvent, makeEvents, serializeError, setLogShapeStrict, truncate } from './log-core.js';
+export type { EventFactoryOptions, Logger, LogEvent, LogLevel, ShipperOptions, ShippedBatch, ShipFailureReason, } from './log-core.js';
 export interface LoggerOptions {
     /** App name, e.g. 'auth'. Becomes the `app` field queried in Axiom. */
     app: string;

package/dist/log.js

@@ -9,7 +9,11 @@
 // log-core's key-shape guard rewrites offenders and WARNs once per site.
 import { writeSync } from 'node:fs';
 import { LogShipper, makeEvents, truncate, } from './log-core.js';
-export { LogShipper, serializeError, truncate } from './log-core.js';
+import { processMeta } from './process-meta.js';
+// makeEvent/makeEvents are exported for app test fakes: routing a recording
+// logger's calls through makeEvents applies the key-shape guard (strict under
+// vitest) to fake-logged sites too.
+export { LogShipper, makeEvent, makeEvents, serializeError, setLogShapeStrict, truncate } from './log-core.js';
 // Registry of every shipper created here (plus any registered explicitly),
 // used by flushAllLoggers and graceful shutdown. Shipper-level on purpose:
 // with() children share their root's shipper, so registering loggers leaked
@@ -144,7 +148,7 @@ export function createLogger(opts) {
         process.once('beforeExit', () => void shipper.finalFlush());
     }
     function build(context) {
-        const factory = { app: opts.app, source: 'server', context };
+        const factory = { app: opts.app, source: 'server', context, processMeta };
         const emit = (level, message, meta) => {
             for (const event of makeEvents(factory, level, message, meta)) {
                 if (stdout)

package/dist/process-meta.d.ts

@@ -0,0 +1,3 @@
+export declare function setProcessMetaSource(next: (() => Record<string, unknown>) | undefined): void;
+/** The registered source's fields now; undefined when none is registered. */
+export declare function processMeta(): Record<string, unknown> | undefined;

package/dist/process-meta.js

@@ -0,0 +1,16 @@
+// The one process-wide source of fields the server logger merges under
+// `meta` on every event. Today that is request activity (activity.ts),
+// registered by whatever serves HTTP (trackActivity, so startServer and
+// custom servers alike): a process that never registers — a Cloud Run Job,
+// a CLI, a test — emits no such fields at all, so absence means "not a
+// server" and 0 means "idle server". Internal: not part of the package's
+// public surface, and kept apart from log.ts so neither the logger nor
+// activity.ts depends on the other.
+let source;
+export function setProcessMetaSource(next) {
+    source = next;
+}
+/** The registered source's fields now; undefined when none is registered. */
+export function processMeta() {
+    return source?.();
+}

package/package.json

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