@piwitests/instrumentation-nitro 0.55.0 → 0.57.0

package/README.md

@@ -6,7 +6,7 @@ During a Playwright test run, the reporter reads this header from every response
 
 **Active in development and test only, by default.** Capture and probe verification run only outside production, using the same Development/Test allow-list as the ASP.NET package. Controlled by the `PIWI_TEST_LOGS_DISABLED` environment variable:
 
-- unset — capture is on when `NODE_ENV` is unset, `development`, or `test`; off for any other value (`production`, `staging`, `prod`, …)
+- unset — capture is on when `NODE_ENV` is `development` or `test`; off for any other value (`production`, `staging`, `prod`, …) and when `NODE_ENV` is not set at all, as when a built server is started with `node .output/server/index.mjs`
 - `PIWI_TEST_LOGS_DISABLED=true` — capture is off everywhere
 - `PIWI_TEST_LOGS_DISABLED=false` — capture is on even in production builds (useful for a production-mode test deployment)
 
@@ -42,7 +42,7 @@ export default defineNitroConfig({ modules: ['@piwitests/instrumentation-nitro/m
 export default defineNuxtConfig({ nitro: { modules: ['@piwitests/instrumentation-nitro/module'] } })
 ```
 
-The manifest then lists every route Nitro scanned (`routes/`, `api/`) and every handler the config declares, middleware and a fallback catch-all (`/**`) left out, each with its method (`GET` for a route that answers any method), its pattern (`/api/orders/:id`) and its file relative to the git repository. Without the module, it lists only the routes the server has answered since it started, which the reporter, reading it before any test runs, rarely sees. Nuxt pages are rendered by one catch-all route, so they are not listed: name them in a `piwi.manifest.json`.
+The manifest then lists every route Nitro scanned (`routes/`, `api/`) and every handler the config declares, middleware and a fallback catch-all (`/**`) left out, each with its method (`GET` for a route that answers any method), its pattern (`/api/orders/:id`) and its file relative to the git repository. Without the module, it lists only the routes the server has answered since it started (a route handler matched, so neither a 404 nor a public asset), which the reporter, reading it before any test runs, rarely sees. Nuxt pages are rendered by one catch-all route, so they are not listed: name them in a `piwi.manifest.json`.
 
 ## What gets captured
 
@@ -63,7 +63,7 @@ Each captured entry contains:
 | `message`   | Log message (truncated at 500 characters)                                            |
 | `stack`     | Shrunk stack trace when an `Error` was logged (max 5 frames, internal frames dropped) |
 
-Up to 50 entries per request are included. The header is always emitted (with an empty array when no entries were captured) so the Piwi reporter can confirm the plugin is active.
+Up to 50 entries per request are included, the first ones logged; an entry logged once the response ended (a timer or a lazy client the request started) is dropped. A request the server makes to itself while rendering a page (`$fetch` or `useFetch` during server-side rendering) adds its entries and spans to the page's request. The header is always emitted (with an empty array when no entries were captured) so the Piwi reporter can confirm the plugin is active.
 
 ## How it works
 

package/dist/index.d.ts

@@ -39,7 +39,8 @@ export interface PiwiServerSpan {
 /**
  * Record a server-side span for the in-flight request. Shows up in the Piwi
  * Dashboard test-case view (and AI diagnosis) under the request's root span.
- * No-op outside a request scope or once the per-request span cap is reached.
+ * No-op outside a request scope, once the per-request span cap is reached, or
+ * once the request's response has ended.
  */
 export declare function recordServerSpan(span: PiwiServerSpan): void;
 declare const piwiTestLogs: NitroAppPlugin;

package/dist/index.js

@@ -4,7 +4,7 @@ import { gzipSync } from 'node:zlib';
 import { consola } from 'consola';
 import { createError } from 'h3';
 import { verifyProbeHeader, ProbeNonceCache } from './probe.js';
-import { buildRouteManifest, recordObservedRoute, collapsePathPattern, } from './manifest.js';
+import { buildRouteManifest, recordObservedRoute, matchedRoutePattern, } from './manifest.js';
 import { declaredRoutes } from './route-table.js';
 import { routeMatchesRequest, faultStatus, faultDelayMs, isThrowFault, isExtremeFault, isDataFault, isDependencyFault, dependencyCallMatches, mutateResponseBody, appliedFaultLabel, } from './faults.js';
 export { verifyProbeHeader, signProbeMessage, probeSigningMessage, PROBE_TTL_MS, } from './probe.js';
@@ -57,6 +57,16 @@ function markProbeApplied(store) {
     if (store.probe)
         store.probeApplied = appliedFaultLabel(store.probe);
 }
+/** Record a log entry on a request still in flight, up to `MAX_ENTRIES`. */
+function pushLog(store, entry) {
+    if (!store.ended && store.logs.length < MAX_ENTRIES)
+        store.logs.push(entry);
+}
+/** Record a span on a request still in flight, up to `MAX_SPANS`. */
+function pushSpan(store, span) {
+    if (!store.ended && store.spans.length < MAX_SPANS)
+        store.spans.push(span);
+}
 /** Signed probe nonces already honored this process, so a header is single-use. */
 const probeNonces = new ProbeNonceCache();
 // Links consola calls and recorded spans to the request being handled. The store
@@ -66,24 +76,24 @@ const als = new AsyncLocalStorage();
 /**
  * Record a server-side span for the in-flight request. Shows up in the Piwi
  * Dashboard test-case view (and AI diagnosis) under the request's root span.
- * No-op outside a request scope or once the per-request span cap is reached.
+ * No-op outside a request scope, once the per-request span cap is reached, or
+ * once the request's response has ended.
  */
 export function recordServerSpan(span) {
     const store = als.getStore();
-    if (!store || store.spans.length >= MAX_SPANS)
-        return;
-    store.spans.push(span);
+    if (store)
+        pushSpan(store, span);
 }
 // The consola reporter is process-global — register it only once.
 let reporterAdded = false;
-// Capture and probe verification run only outside production (the ASP.NET
-// package's default allow-list is Development and Test): only an unset/empty
-// NODE_ENV or `development`/`test` is treated as non-production. Any other value
-// (`production`, `staging`, `prod`, …) disables capture unless
-// PIWI_TEST_LOGS_DISABLED is explicitly `false`, so a signed probe header is
-// never honored on a production-like deployment that skipped `NODE_ENV=production`.
+// Capture and probe verification run only in development and test (the ASP.NET
+// package's default allow-list is Development and Test): NODE_ENV must be
+// `development` or `test`. Any other value, or none at all (`node
+// .output/server/index.mjs` sets none), disables capture unless
+// PIWI_TEST_LOGS_DISABLED is explicitly `false`, so a deployment that never set
+// NODE_ENV exposes no server logs, handler files or route manifest.
 const NODE_ENV = process.env.NODE_ENV;
-const IS_DEV_OR_TEST = !NODE_ENV || NODE_ENV === 'development' || NODE_ENV === 'test';
+const IS_DEV_OR_TEST = NODE_ENV === 'development' || NODE_ENV === 'test';
 const TEST_LOGS_DISABLED = process.env.PIWI_TEST_LOGS_DISABLED === 'true' ||
     (!IS_DEV_OR_TEST && process.env.PIWI_TEST_LOGS_DISABLED !== 'false');
 /** The shared secret a probe run signs the `X-Piwi-Probe` header with. */
@@ -123,11 +133,11 @@ const piwiTestLogs = (nitroApp) => {
                 if (logObj.level > 1)
                     return; // Warning (1) and Error/Fatal (0) only
                 const store = als.getStore();
-                if (!store)
+                if (!store || store.ended)
                     return;
                 const msg = logObj.args.map(String).join(' ');
                 const stack = logObj.args.map(extractStack).find(Boolean);
-                store.logs.push({
+                pushLog(store, {
                     timestamp: Date.now(),
                     level: logObj.level <= 0 ? 'Error' : 'Warning',
                     category: logObj.tag ?? '',
@@ -156,7 +166,13 @@ const piwiTestLogs = (nitroApp) => {
             res.end(JSON.stringify(buildRouteManifest(routes)));
             return;
         }
-        const store = { logs: [], spans: [], startMs: Date.now() };
+        const enclosing = als.getStore();
+        const store = {
+            logs: [],
+            spans: [],
+            startMs: Date.now(),
+            ...(enclosing && !enclosing.ended ? { parent: enclosing } : {}),
+        };
         event.context._piwiLogs = store.logs;
         event.context._piwiSpans = store.spans;
         // The beforeResponse hook fires outside this handler's async scope (it is
@@ -204,7 +220,7 @@ const piwiTestLogs = (nitroApp) => {
                 if (nitroErrors?.length) {
                     for (const { error } of nitroErrors) {
                         const msg = error instanceof Error ? (error.message || String(error)) : String(error);
-                        store.logs.push({
+                        pushLog(store, {
                             timestamp: Date.now(),
                             level: 'Error',
                             category: 'server',
@@ -213,8 +229,7 @@ const piwiTestLogs = (nitroApp) => {
                         });
                     }
                 }
-                const logPayload = store.logs.length > MAX_ENTRIES ? store.logs.slice(0, MAX_ENTRIES) : store.logs;
-                res.setHeader('X-Piwi-Logs', gzipSync(Buffer.from(JSON.stringify(logPayload))).toString('base64'));
+                res.setHeader('X-Piwi-Logs', gzipSync(Buffer.from(JSON.stringify(store.logs))).toString('base64'));
                 // Synthesize the root request span (server-side processing time, route,
                 // status), correlate any app-recorded child spans under it, and ship the
                 // whole tree. When the caller sent a W3C traceparent, reuse its trace id
@@ -225,13 +240,10 @@ const piwiTestLogs = (nitroApp) => {
                 const statusCode = Number(res.statusCode) || 0;
                 const traceId = parseTraceparent(event.node.req.headers['traceparent']) ?? randomBytes(16).toString('hex');
                 const handlerFile = resolveHandlerFile(event);
-                // Record this route for the declared-surface manifest. Prefer the matched
-                // route's own pattern (`path` in h3 1.x, `route` in later versions); fall
-                // back to collapsing the concrete path.
-                const matchedRoute = event.context?.matchedRoute;
-                const matchedPattern = matchedRoute?.route ?? matchedRoute?.path;
-                const pattern = typeof matchedPattern === 'string' && matchedPattern ? matchedPattern : collapsePathPattern(path);
-                recordObservedRoute(observedRoutes, { method, pattern, handler: handlerFile });
+                // Record the route the router matched for the declared-surface manifest.
+                const pattern = matchedRoutePattern(event.context?.matchedRoute);
+                if (pattern)
+                    recordObservedRoute(observedRoutes, { method, pattern, handler: handlerFile });
                 const rootSpan = {
                     id: randomBytes(8).toString('hex'),
                     name: `${method} ${path}`.trim(),
@@ -256,7 +268,14 @@ const piwiTestLogs = (nitroApp) => {
                         s.parentId = rootSpan.id;
                 const spanPayload = [rootSpan, ...store.spans].slice(0, MAX_SPANS);
                 res.setHeader('X-Piwi-Trace', gzipSync(Buffer.from(JSON.stringify(spanPayload))).toString('base64'));
+                if (store.parent) {
+                    for (const entry of store.logs)
+                        pushLog(store.parent, entry);
+                    for (const span of spanPayload)
+                        pushSpan(store.parent, span);
+                }
             }
+            store.ended = true;
             return originalEnd(...args);
         };
         return als.run(store, async () => {

package/dist/manifest.d.ts

@@ -20,9 +20,15 @@ export interface RouteManifest {
 /**
  * Collapse a concrete request path to a pattern: numeric and uuid segments become
  * `:id` / `:uuid`, so `/api/orders/42` and `/api/orders/43` fold to one route.
- * Used only when the matched route carries no pattern of its own.
  */
 export declare function collapsePathPattern(path: string): string;
+/**
+ * The pattern a request is recorded under: the one of the route the router
+ * matched it to (`path` in h3 1.x, `route` in later versions). Null when no
+ * route handler matched it: a 404, or a public asset served before the router,
+ * neither of which is a route of the app.
+ */
+export declare function matchedRoutePattern(matchedRoute: unknown): string | null;
 /**
  * Record an observed route in the accumulator, keeping the first handler file
  * seen for it. Bounded so a pathological app (or an unbounded set of patterns

package/dist/manifest.js

@@ -10,7 +10,6 @@
 /**
  * Collapse a concrete request path to a pattern: numeric and uuid segments become
  * `:id` / `:uuid`, so `/api/orders/42` and `/api/orders/43` fold to one route.
- * Used only when the matched route carries no pattern of its own.
  */
 export function collapsePathPattern(path) {
     const clean = path.split('?')[0] ?? path;
@@ -27,6 +26,17 @@ export function collapsePathPattern(path) {
         })
             .join('/'));
 }
+/**
+ * The pattern a request is recorded under: the one of the route the router
+ * matched it to (`path` in h3 1.x, `route` in later versions). Null when no
+ * route handler matched it: a 404, or a public asset served before the router,
+ * neither of which is a route of the app.
+ */
+export function matchedRoutePattern(matchedRoute) {
+    const matched = matchedRoute;
+    const pattern = matched?.route ?? matched?.path;
+    return typeof pattern === 'string' && pattern ? pattern : null;
+}
 /** The unique key for a route in the accumulator: method plus pattern. */
 function routeKey(method, pattern) {
     return `${method.toUpperCase()} ${pattern}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piwitests/instrumentation-nitro",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "description": "Nitro/Nuxt server plugin for sending backend logs to Piwi Dashboard via the X-Piwi-Logs response header",
   "homepage": "https://piwitests.dev",
   "repository": {