npm - api-observe - Versions diffs - 1.0.2 → 1.1.1 - Mend

api-observe 1.0.2 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/lib/dashboard/index.js CHANGED Viewed

@@ -12,7 +12,7 @@ function getDashboardHtml() {
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>ps-observe | API Failure Tracker</title>
+  <title>observe | API Failure Tracker</title>
   <style>
     * { margin: 0; padding: 0; box-sizing: border-box; }
@@ -306,7 +306,7 @@ function getDashboardHtml() {
 </head>
 <body>
   <header>
-    <h1>ps-observe</h1>
+    <h1>observe</h1>
     <div class="stats">
       <span class="count" id="totalCount">0</span> failures tracked
     </div>
@@ -329,6 +329,7 @@ function getDashboardHtml() {
     </select>
     <input type="number" id="filterStatus" placeholder="Status code..." min="100" max="599" />
     <input type="text" id="filterUrl" placeholder="URL contains..." />
+    <input type="text" id="filterCorrelationId" placeholder="Correlation ID..." />
     <button class="refresh-btn" onclick="loadFailures()">Refresh</button>
     <button class="danger" onclick="clearAll()">Clear All</button>
   </div>
@@ -373,12 +374,14 @@ function getDashboardHtml() {
       const method = document.getElementById('filterMethod').value;
       const statusCode = document.getElementById('filterStatus').value;
       const url = document.getElementById('filterUrl').value;
+      const correlationId = document.getElementById('filterCorrelationId').value.trim();
       if (type) params.set('type', type);
       if (service) params.set('service', service);
       if (method) params.set('method', method);
       if (statusCode) params.set('statusCode', statusCode);
       if (url) params.set('url', url);
+      if (correlationId) params.set('correlationId', correlationId);
       params.set('limit', PAGE_SIZE);
       params.set('offset', currentOffset);

package/lib/failure-store.js CHANGED Viewed

@@ -46,7 +46,7 @@ class FailureStore {
   /**
    * Query failures with optional filters.
-   * @param {{ service?: string, statusCode?: number, from?: string, to?: string, method?: string, url?: string, limit?: number, offset?: number }} [filters]
+   * @param {{ service?: string, statusCode?: number, from?: string, to?: string, method?: string, url?: string, correlationId?: string, limit?: number, offset?: number }} [filters]
    * @returns {{ data: object[], total: number }}
    */
   query(filters = {}) {
@@ -81,6 +81,10 @@ class FailureStore {
       const url = filters.url.toLowerCase();
       results = results.filter(e => e.url?.toLowerCase().includes(url));
     }
+    if (filters.correlationId) {
+      const cid = String(filters.correlationId).toLowerCase();
+      results = results.filter(e => e.correlationId?.toLowerCase().includes(cid));
+    }
     if (filters.from) {
       const from = new Date(filters.from).getTime();
       results = results.filter(e => new Date(e.timestamp).getTime() >= from);

package/lib/interceptor.js CHANGED Viewed

@@ -15,6 +15,8 @@
  * transforms it.
  */
+const { requestContext } = require('./request-context');
 /**
  * Attach the observe interceptor to a BaseHttpClient instance.
  *
@@ -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 CHANGED Viewed

@@ -7,7 +7,7 @@
  *
  * Usage in a consuming service:
  *
- *   const observer = require('@pruservices/ps-observe');
+ *   const observer = require('api-observe');
  *
  *   fastify.register(observer, {
  *     // (optional) max failure records to keep in memory (default: 500)
@@ -31,11 +31,31 @@
  *     // Option B: Auto-attach to all clients on an object
  *     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');
+const CTX_KEY = Symbol.for('ps-observe.ctx');
 async function observerPlugin(fastify, opts) {
   const store = new FailureStore({
@@ -44,6 +64,7 @@ async function observerPlugin(fastify, opts) {
   });
   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('observer', {
@@ -61,11 +82,21 @@ async function observerPlugin(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 observerPlugin(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,50 +136,125 @@ async function observerPlugin(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);
 }
+/**
+ * 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;

package/lib/request-context.js ADDED Viewed

@@ -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/lib/router.js CHANGED Viewed

@@ -42,8 +42,8 @@ function createRouter(store) {
     // ── List failures ──────────────────────────────────────────────────────
     if (method === 'GET' && path === '/observe/api/failures') {
-      const { service, statusCode, method: m, url, from, to, limit, offset, type } = query || {};
-      const result = store.query({ service, statusCode, method: m, url, from, to, limit, offset, type });
+      const { service, statusCode, method: m, url, from, to, limit, offset, type, correlationId } = query || {};
+      const result = store.query({ service, statusCode, method: m, url, from, to, limit, offset, type, correlationId });
       return { status: 200, headers: { 'content-type': 'application/json' }, body: result };
     }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "api-observe",
-  "version": "1.0.2",
+  "version": "1.1.01",
   "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"
   }
 }