@steve31415/baselib 3.53.0 → 3.54.0

package/dist/rum.d.ts

@@ -1,3 +1,4 @@
+import { type MetricWithAttribution } from 'web-vitals/attribution';
 export interface RumOptions {
     app?: string;
     dataset?: string;
@@ -6,4 +7,16 @@ export interface RumOptions {
     /** Defaults to the page's pw-build-id meta tag. */
     buildId?: string;
 }
+/**
+ * The same-origin resource of one initiator type (`script`, `fetch`) that
+ * finished last before `before` (ms since navigation start) — for a single-page
+ * app, the entry script and the first data fetch that first paint waited on.
+ * Times are ms since navigation start; `bytes` 0 means served from cache.
+ */
+export declare function lastResourceBefore(entries: readonly PerformanceResourceTiming[], initiatorType: string, before: number): Record<string, string | number | undefined> | undefined;
+/**
+ * Flat breakdown fields for one metric (all durations in whole ms). Kept to a
+ * fixed, small set of columns per metric — never keyed by data.
+ */
+export declare function breakdownFields(m: MetricWithAttribution): Record<string, unknown>;
 export declare function initRum(opts?: RumOptions): void;

package/dist/rum.js

@@ -4,12 +4,150 @@
 // no-op. Metrics finalize on tab-hide, so the shipper flushes there with
 // keepalive fetch.
 //
+// Each row also carries the reporting `device` and a few flat breakdown
+// fields from web-vitals' attribution build, so a slow load can be split
+// into its phases from the row alone (connection setup vs server wait vs
+// the app's script and first data fetch) instead of being reconstructed by
+// lining server request logs up against client timestamps (Reader, 2026-11-03:
+// a 5 s /nyt load on the phone with 0.15 s of server time, explained only by
+// that reconstruction).
+//
 // Browser-only module — do not import server-side.
-import { onCLS, onFCP, onINP, onLCP, onTTFB } from 'web-vitals';
+import { onCLS, onFCP, onINP, onLCP, onTTFB, } from 'web-vitals/attribution';
 import { LogShipper } from './log-core.js';
+import { deviceLabel } from './log-browser.js';
 function metaContent(name) {
     return document.querySelector(`meta[name="${name}"]`)?.content || undefined;
 }
+const ms = (n) => (n === undefined || !Number.isFinite(n) ? undefined : Math.round(n));
+const clip = (s, max = 120) => (s === undefined ? undefined : s.slice(0, max));
+/** Path (no origin, no query) of a same-origin resource URL, else the URL clipped. */
+function resourcePath(url) {
+    try {
+        const u = new URL(url, location.href);
+        return u.origin === location.origin ? u.pathname : clip(url, 200);
+    }
+    catch {
+        return clip(url, 200);
+    }
+}
+/**
+ * The same-origin resource of one initiator type (`script`, `fetch`) that
+ * finished last before `before` (ms since navigation start) — for a single-page
+ * app, the entry script and the first data fetch that first paint waited on.
+ * Times are ms since navigation start; `bytes` 0 means served from cache.
+ */
+export function lastResourceBefore(entries, initiatorType, before) {
+    let pick;
+    for (const e of entries) {
+        if (e.initiatorType !== initiatorType || e.responseEnd <= 0 || e.responseEnd > before)
+            continue;
+        let sameOrigin = false;
+        try {
+            sameOrigin = new URL(e.name, location.href).origin === location.origin;
+        }
+        catch {
+            sameOrigin = false;
+        }
+        if (!sameOrigin)
+            continue;
+        if (!pick || e.responseEnd > pick.responseEnd)
+            pick = e;
+    }
+    if (!pick)
+        return undefined;
+    return {
+        path: resourcePath(pick.name),
+        start_ms: ms(pick.startTime),
+        first_byte_ms: ms(pick.responseStart > 0 ? pick.responseStart : undefined),
+        end_ms: ms(pick.responseEnd),
+        bytes: pick.transferSize,
+        protocol: pick.nextHopProtocol || undefined,
+    };
+}
+function prefixed(prefix, fields) {
+    const out = {};
+    if (!fields)
+        return out;
+    for (const [k, v] of Object.entries(fields))
+        if (v !== undefined)
+            out[`${prefix}_${k}`] = v;
+    return out;
+}
+function resourceEntries() {
+    try {
+        return performance.getEntriesByType('resource');
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Flat breakdown fields for one metric (all durations in whole ms). Kept to a
+ * fixed, small set of columns per metric — never keyed by data.
+ */
+export function breakdownFields(m) {
+    const fields = {};
+    switch (m.name) {
+        case 'TTFB': {
+            const a = m.attribution;
+            const nav = a.navigationEntry;
+            Object.assign(fields, {
+                waiting_ms: ms(a.waitingDuration),
+                cache_ms: ms(a.cacheDuration),
+                dns_ms: ms(a.dnsDuration),
+                connect_ms: ms(a.connectionDuration),
+                request_ms: ms(a.requestDuration),
+                protocol: nav?.nextHopProtocol || undefined,
+            });
+            break;
+        }
+        case 'FCP': {
+            const a = m.attribution;
+            Object.assign(fields, {
+                ttfb_ms: ms(a.timeToFirstByte),
+                after_ttfb_ms: ms(a.firstByteToFCP),
+                load_state: a.loadState,
+            });
+            const entries = resourceEntries();
+            Object.assign(fields, prefixed('script', lastResourceBefore(entries, 'script', m.value)));
+            Object.assign(fields, prefixed('fetch', lastResourceBefore(entries, 'fetch', m.value)));
+            break;
+        }
+        case 'LCP': {
+            const a = m.attribution;
+            Object.assign(fields, {
+                ttfb_ms: ms(a.timeToFirstByte),
+                resource_delay_ms: ms(a.resourceLoadDelay),
+                resource_ms: ms(a.resourceLoadDuration),
+                render_delay_ms: ms(a.elementRenderDelay),
+                target: clip(a.target),
+            });
+            break;
+        }
+        case 'INP': {
+            const a = m.attribution;
+            Object.assign(fields, {
+                input_delay_ms: ms(a.inputDelay),
+                processing_ms: ms(a.processingDuration),
+                presentation_ms: ms(a.presentationDelay),
+                interaction_type: a.interactionType,
+                target: clip(a.interactionTarget),
+                load_state: a.loadState,
+            });
+            break;
+        }
+        case 'CLS': {
+            const a = m.attribution;
+            Object.assign(fields, { target: clip(a.largestShiftTarget), load_state: a.loadState });
+            break;
+        }
+    }
+    for (const k of Object.keys(fields))
+        if (fields[k] === undefined)
+            delete fields[k];
+    return fields;
+}
 export function initRum(opts = {}) {
     const app = opts.app ?? metaContent('pw-log-app') ?? 'unknown';
     const token = opts.token ?? metaContent('pw-log-token');
@@ -18,6 +156,7 @@ export function initRum(opts = {}) {
     const buildId = opts.buildId ?? metaContent('pw-build-id');
     const dataset = opts.dataset ?? 'rum';
     const baseUrl = (opts.baseUrl ?? 'https://api.axiom.co').replace(/\/$/, '');
+    const device = deviceLabel(navigator.userAgent, navigator.maxTouchPoints ?? 0);
     const shipper = new LogShipper({
         url: `${baseUrl}/v1/datasets/${dataset}/ingest`,
         token,
@@ -25,6 +164,13 @@ export function initRum(opts = {}) {
         intervalMs: 5000,
     });
     const report = (m) => {
+        let breakdown = {};
+        try {
+            breakdown = breakdownFields(m);
+        }
+        catch {
+            // Diagnostics only: a browser quirk in attribution never costs the metric.
+        }
         shipper.enqueue({
             _time: new Date().toISOString(),
             app,
@@ -41,7 +187,9 @@ export function initRum(opts = {}) {
             metric_id: m.id,
             navigation_type: m.navigationType,
             path: location.pathname,
+            device,
             ...(buildId ? { build_id: buildId } : {}),
+            ...breakdown,
         });
     };
     onLCP(report);

package/dist/socket-age.js

@@ -54,11 +54,21 @@ function withAgeCap(events, path, maxAgeMs, graceMs, logger) {
         if (cutAt === null || logged)
             return;
         logged = true;
-        logger.info('socket age cap', { path, ageMs: cutAt - openedAt, terminated });
+        logger.info('socket age cap', { path, ageMs: Math.round(cutAt - openedAt), terminated });
     };
     const cut = (ws) => {
         ageTimer = null;
-        cutAt = Date.now();
+        // Node starts a timer's countdown from the event loop's cached time, not
+        // from the setTimeout call, so it can fire a little before `maxAgeMs` has
+        // really passed since onOpen (the age test saw 299 ms of a 300 ms cap,
+        // 2 runs in 30). Re-arm for the remainder: a socket is never cut young.
+        const remaining = openedAt + maxAgeMs - performance.now();
+        if (remaining > 0) {
+            ageTimer = setTimeout(() => cut(ws), remaining);
+            ageTimer.unref?.();
+            return;
+        }
+        cutAt = performance.now();
         try {
             ws.close(CLOSE_SERVICE_RESTART, 'socket age limit');
         }
@@ -79,7 +89,7 @@ function withAgeCap(events, path, maxAgeMs, graceMs, logger) {
             events.onOpen?.(evt, ws);
             if (ws.readyState !== WS_OPEN)
                 return;
-            openedAt = Date.now();
+            openedAt = performance.now();
             ageTimer = setTimeout(() => cut(ws), maxAgeMs);
             ageTimer.unref?.();
         },

package/package.json

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