api-observe 1.0.1 → 1.1.0

package/README.md

@@ -40,10 +40,10 @@ await fastify.register(apiObserve, {
 // Attach to your HTTP clients after registration
 fastify.after(() => {
   // Option A: single client
-  fastify.psObserve.attach(myHttpClient);
+  fastify.observer.attach(myHttpClient);
 
   // Option B: auto-attach to all clients on an object
-  fastify.psObserve.attachToAll(fastify.services);
+  fastify.observer.attachToAll(fastify.services);
 });
 
 await fastify.listen({ port: 3000 });

package/lib/interceptor.js

@@ -15,6 +15,8 @@
  * transforms it.
  */
 
+const { requestContext } = require('./request-context');
+
 /**
  * Attach the observe interceptor to a BaseHttpClient instance.
  *
@@ -33,8 +35,8 @@ function attachInterceptor(client, store, opts = {}) {
   }
 
   // Mark this client so we don't double-attach
-  if (client.__psObserveAttached) return;
-  client.__psObserveAttached = true;
+  if (client.__observerAttached) return;
+  client.__observerAttached = true;
 
   // ── Eject existing response interceptors ───────────���────────────────────
   // Save them, clear them, add ours first, then re-add the originals.
@@ -90,6 +92,12 @@ function attachInterceptor(client, store, opts = {}) {
 
       store.add(record);
 
+      // Mark the in-flight Fastify request (if any) so the response-level
+      // hook in plugin.js does not record a duplicate when the controller
+      // catches this error and replies with its own 4xx/5xx.
+      const ctx = requestContext.getStore();
+      if (ctx) ctx.captured = true;
+
       // Re-throw the original error so BaseHttpClient's handler still works
       throw error;
     },

package/lib/plugin.js

@@ -7,9 +7,9 @@
  *
  * Usage in a consuming service:
  *
- *   const psObserve = require('@pruservices/ps-observe');
+ *   const observer = require('api-observe');
  *
- *   fastify.register(psObserve, {
+ *   fastify.register(observer, {
  *     // (optional) max failure records to keep in memory (default: 500)
  *     maxEntries: 500,
  *
@@ -26,27 +26,48 @@
  *   // After registering your service clients, attach the interceptors:
  *   fastify.after(() => {
  *     // Option A: Attach to individual clients
- *     fastify.psObserve.attach(myClient);
+ *     fastify.observer.attach(myClient);
  *
  *     // Option B: Auto-attach to all clients on an object
- *     fastify.psObserve.attachToAll(fastify.services);
+ *     fastify.observer.attachToAll(fastify.services);
  *   });
+ *
+ * ── Capture sources ───────────────────────────────────────────────────────
+ *
+ *  The plugin captures failures from three sources, deduplicated to one
+ *  record per failed user request:
+ *
+ *  1. Axios interceptor  — full upstream request/response when a downstream
+ *                          HTTP call fails (timeouts, network errors, non-2xx).
+ *  2. onError hook       — uncaught errors thrown during the request lifecycle
+ *                          (validation, controllers, hooks, serialization).
+ *  3. onSend hook        — any reply with statusCode >= 400 sent without an
+ *                          exception (controllers that build error responses
+ *                          directly via reply.send/reply.code instead of
+ *                          throwing). Captures 404s from setNotFoundHandler too.
+ *
+ *  Sources 1 and 2 mark the request via AsyncLocalStorage so source 3 skips
+ *  recording a duplicate when the same request has already been captured.
  */
 
 const { FailureStore } = require('./failure-store');
-const { attachInterceptor, attachToAll } = require('./interceptor');
+const { attachInterceptor, attachToAll, defaultSanitize } = require('./interceptor');
 const { registerRoutes } = require('./routes');
+const { requestContext } = require('./request-context');
 
-async function psObservePlugin(fastify, opts) {
+const CTX_KEY = Symbol.for('ps-observe.ctx');
+
+async function observerPlugin(fastify, opts) {
   const store = new FailureStore({
     maxEntries: opts.maxEntries,
     ttlMs: opts.ttlMs,
   });
 
   const sanitizeOpts = opts.sanitize ? { sanitize: opts.sanitize } : {};
+  const sanitize = opts.sanitize ?? defaultSanitize;
 
   // Decorate fastify with the observe API so consumers can attach clients
-  fastify.decorate('psObserve', {
+  fastify.decorate('observer', {
     /** Attach interceptor to a single BaseHttpClient instance */
     attach(client) {
       attachInterceptor(client, store, sanitizeOpts);
@@ -61,11 +82,21 @@ async function psObservePlugin(fastify, opts) {
     store,
   });
 
+  // ── Per-request context (AsyncLocalStorage) ───────────────────────────────
+  // `enterWith` makes the store visible to the rest of the synchronous
+  // execution and any async operations spawned from it — so when the axios
+  // interceptor records a capture deep in the call stack, it can reach back
+  // and mark this request as already captured.
+  fastify.addHook('onRequest', (request, reply, done) => {
+    const ctx = { captured: false, startedAt: Date.now() };
+    request[CTX_KEY] = ctx;
+    requestContext.enterWith(ctx);
+    done();
+  });
+
   // ── Catch controller-level errors via onError hook ────────────────────────
   // This fires for ANY error thrown during the request lifecycle (controllers,
   // hooks, serialization, etc.) — not just upstream HTTP failures.
-  const sanitize = opts.sanitize ?? require('./interceptor').defaultSanitize;
-
   fastify.addHook('onError', (request, reply, error, done) => {
     // Skip /observe routes to avoid recursive captures
     if (request.url.startsWith('/observe')) {
@@ -73,10 +104,8 @@ async function psObservePlugin(fastify, opts) {
       return;
     }
 
-    // Determine error source
-    const isUpstream = error.name === 'UpstreamError' || error.name === 'UpstreamTimeoutError';
-
     // Skip upstream errors — they're already captured by the axios interceptor
+    const isUpstream = error.name === 'UpstreamError' || error.name === 'UpstreamTimeoutError';
     if (isUpstream) {
       done();
       return;
@@ -107,51 +136,126 @@ async function psObservePlugin(fastify, opts) {
       response: null,
     });
 
+    const ctx = request[CTX_KEY];
+    if (ctx) ctx.captured = true;
+
     done();
   });
 
-  // ── Catch 404s via onResponse hook ──────────────────────────────────────
-  // 404s bypass onError because they're handled by setNotFoundHandler which
-  // sends a reply directly without throwing. We catch them after the response.
-  fastify.addHook('onResponse', (request, reply, done) => {
+  // ── Catch any 4xx/5xx reply via onSend ────────────────────────────────────
+  // Covers controllers that build error responses directly (reply.code(400)
+  // .send(...)) without throwing — including the RFC-7807 problem+json
+  // pattern where the HTTP status is hard-coded to 400 and the semantic
+  // status (404, 502, 504, …) lives in the body. Also covers 404s from
+  // setNotFoundHandler since it sends a reply without throwing.
+  fastify.addHook('onSend', (request, reply, payload, done) => {
     if (request.url.startsWith('/observe')) {
-      done();
+      done(null, payload);
       return;
     }
 
-    if (reply.statusCode === 404) {
-      store.add({
-        type: 'controller',
-        service: '404 Not Found',
-        method: request.method,
-        url: request.url,
-        correlationId: request.correlationId ?? request.headers['x-correlation-id'] ?? null,
-        durationMs: reply.elapsedTime != null ? Math.round(reply.elapsedTime) : null,
-        errorMessage: `Route ${request.method} ${request.url} not found`,
-        errorCode: null,
-        errorName: 'NotFound',
-        stack: null,
-
-        request: {
-          headers: sanitize(request.headers),
-          params: request.params ?? null,
-          query: request.query ?? null,
-          body: sanitize(request.body),
-        },
-
-        statusCode: 404,
-        response: null,
-      });
+    if (reply.statusCode < 400) {
+      done(null, payload);
+      return;
     }
 
-    done();
+    // Skip if the axios interceptor or onError hook already recorded this
+    // request — we want one record per failed user request.
+    const ctx = request[CTX_KEY];
+    if (ctx && ctx.captured) {
+      done(null, payload);
+      return;
+    }
+
+    // Try to surface the response body so the dashboard shows what was
+    // actually sent to the client.
+    const parsedBody = parsePayload(payload);
+    const semanticStatus = (parsedBody && typeof parsedBody === 'object' && Number.isFinite(parsedBody.status))
+      ? parsedBody.status
+      : reply.statusCode;
+    const errorTitle = (parsedBody && typeof parsedBody === 'object' && parsedBody.title)
+      || (reply.statusCode === 404 ? 'NotFound' : 'Error');
+    const errorDetail = (parsedBody && typeof parsedBody === 'object' && (parsedBody.detail || parsedBody.message))
+      || `HTTP ${reply.statusCode}`;
+
+    const startedAt = ctx?.startedAt ?? null;
+    const durationMs = startedAt
+      ? Date.now() - startedAt
+      : (reply.elapsedTime != null ? Math.round(reply.elapsedTime) : null);
+
+    store.add({
+      type: 'controller',
+      service: request.routeOptions?.url ?? request.url,
+      method: request.method,
+      url: request.url,
+      correlationId: request.correlationId ?? request.headers['x-correlation-id'] ?? null,
+      durationMs,
+      errorMessage: errorDetail,
+      errorCode: null,
+      errorName: errorTitle,
+      stack: null,
+
+      request: {
+        headers: sanitize(request.headers),
+        params: request.params ?? null,
+        query: request.query ?? null,
+        body: sanitize(request.body),
+      },
+
+      // Use the semantic status from the body when available so a 502 carried
+      // inside an HTTP-400 problem+json envelope is visible as 502 in the
+      // dashboard while still recording the raw HTTP code below.
+      statusCode: semanticStatus,
+      response: {
+        statusCode: reply.statusCode,
+        headers: safeReplyHeaders(reply),
+        body: sanitize(parsedBody),
+      },
+    });
+
+    if (ctx) ctx.captured = true;
+
+    done(null, payload);
   });
 
   // Register the dashboard and API routes
   registerRoutes(fastify, store);
 }
 
-// Skip encapsulation so psObserve decorator is visible to the parent scope
-psObservePlugin[Symbol.for('skip-override')] = true;
+/**
+ * Parse a Fastify onSend payload into a plain JS value. Returns the original
+ * payload (or its string form) when JSON parsing fails or it is a stream.
+ */
+function parsePayload(payload) {
+  if (payload == null) return null;
+
+  if (typeof payload === 'string') {
+    try { return JSON.parse(payload); } catch { return payload; }
+  }
+
+  if (Buffer.isBuffer(payload)) {
+    const str = payload.toString('utf8');
+    try { return JSON.parse(str); } catch { return str; }
+  }
+
+  // Stream or already-an-object — leave as-is. We don't read streams here
+  // because that would consume them before the client sees the response.
+  if (typeof payload === 'object' && typeof payload.pipe === 'function') {
+    return '[stream]';
+  }
+
+  return payload;
+}
+
+function safeReplyHeaders(reply) {
+  try {
+    return reply.getHeaders ? reply.getHeaders() : null;
+  } catch {
+    return null;
+  }
+}
+
+// Skip encapsulation so observer decorator is visible to the parent scope
+observerPlugin[Symbol.for('skip-override')] = true;
 
-module.exports = psObservePlugin;
+module.exports = observerPlugin;

package/lib/request-context.js

@@ -0,0 +1,18 @@
+'use strict';
+
+/**
+ * @file lib/request-context.js
+ * @description Shared AsyncLocalStorage used to flow per-request state between
+ *              the axios interceptor and the Fastify hooks.
+ *
+ * Without this, the axios interceptor cannot tell the response-level capture
+ * hook ("onSend") that an upstream failure was already recorded for the
+ * current request — leading to duplicate entries when an upstream 4xx is
+ * caught and translated by the controller into a 4xx reply.
+ */
+
+const { AsyncLocalStorage } = require('async_hooks');
+
+const requestContext = new AsyncLocalStorage();
+
+module.exports = { requestContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-observe",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Framework-agnostic plugin that captures and displays API failure details — works with Fastify, Express, NestJS, Koa, or plain Node.js HTTP",
   "main": "lib/index.js",
   "files": [
@@ -9,7 +9,7 @@
     "http.js"
   ],
   "scripts": {
-    "test": "node --test test/"
+    "test": "node --test test/*.test.js"
   },
   "keywords": [
     "fastify",
@@ -39,5 +39,9 @@
     "fastify-plugin": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "axios": "^1.6.0",
+    "fastify": "^4.0.0"
   }
 }