api-observe 1.0.0

package/lib/failure-store.js

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * @file lib/failure-store.js
+ * @description In-memory ring buffer that stores the last N API failure records.
+ *
+ * Each failure record contains full request/response details:
+ *   - timestamp, service, method, url, correlationId
+ *   - request: headers, params, body
+ *   - response: statusCode, headers, body
+ *   - durationMs, errorMessage
+ */
+
+class FailureStore {
+  /**
+   * @param {{ maxEntries?: number, ttlMs?: number }} [opts]
+   */
+  constructor(opts = {}) {
+    this._maxEntries = opts.maxEntries ?? 500;
+    this._ttlMs = opts.ttlMs ?? 24 * 60 * 60 * 1000; // 24 hours
+    this._entries = [];
+    this._idCounter = 0;
+  }
+
+  /**
+   * Add a failure record to the store.
+   * @param {object} failure
+   * @returns {object} The stored record (with id and timestamp).
+   */
+  add(failure) {
+    const record = {
+      id: ++this._idCounter,
+      timestamp: new Date().toISOString(),
+      ...failure,
+    };
+
+    this._entries.push(record);
+
+    // Trim to max size
+    if (this._entries.length > this._maxEntries) {
+      this._entries = this._entries.slice(-this._maxEntries);
+    }
+
+    return record;
+  }
+
+  /**
+   * Query failures with optional filters.
+   * @param {{ service?: string, statusCode?: number, from?: string, to?: string, method?: string, url?: string, limit?: number, offset?: number }} [filters]
+   * @returns {{ data: object[], total: number }}
+   */
+  query(filters = {}) {
+    const now = Date.now();
+    let results = this._entries.filter(e => {
+      // Evict expired entries on read
+      if (now - new Date(e.timestamp).getTime() > this._ttlMs) return false;
+      return true;
+    });
+
+    // Update internal store (lazy eviction)
+    this._entries = results;
+
+    // Apply filters
+    if (filters.type) {
+      const type = filters.type.toLowerCase();
+      results = results.filter(e => (e.type || 'upstream').toLowerCase() === type);
+    }
+    if (filters.service) {
+      const svc = filters.service.toLowerCase();
+      results = results.filter(e => e.service?.toLowerCase().includes(svc));
+    }
+    if (filters.statusCode) {
+      const code = Number(filters.statusCode);
+      results = results.filter(e => e.statusCode === code);
+    }
+    if (filters.method) {
+      const method = filters.method.toUpperCase();
+      results = results.filter(e => e.method?.toUpperCase() === method);
+    }
+    if (filters.url) {
+      const url = filters.url.toLowerCase();
+      results = results.filter(e => e.url?.toLowerCase().includes(url));
+    }
+    if (filters.from) {
+      const from = new Date(filters.from).getTime();
+      results = results.filter(e => new Date(e.timestamp).getTime() >= from);
+    }
+    if (filters.to) {
+      const to = new Date(filters.to).getTime();
+      results = results.filter(e => new Date(e.timestamp).getTime() <= to);
+    }
+
+    // Sort newest first
+    results.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
+
+    const total = results.length;
+    const offset = Number(filters.offset) || 0;
+    const limit = Number(filters.limit) || 50;
+
+    return {
+      data: results.slice(offset, offset + limit),
+      total,
+      limit,
+      offset,
+    };
+  }
+
+  /**
+   * Get a single failure by ID.
+   * @param {number} id
+   * @returns {object|null}
+   */
+  getById(id) {
+    return this._entries.find(e => e.id === Number(id)) ?? null;
+  }
+
+  /**
+   * Get summary stats grouped by service.
+   * @returns {object}
+   */
+  summary() {
+    const now = Date.now();
+    const active = this._entries.filter(
+      e => now - new Date(e.timestamp).getTime() <= this._ttlMs,
+    );
+
+    const byService = {};
+    const byStatus = {};
+    const byType = {};
+
+    for (const entry of active) {
+      const svc = entry.service || 'unknown';
+      byService[svc] = (byService[svc] || 0) + 1;
+
+      const code = entry.statusCode || 'unknown';
+      byStatus[code] = (byStatus[code] || 0) + 1;
+
+      const type = entry.type || 'upstream';
+      byType[type] = (byType[type] || 0) + 1;
+    }
+
+    return {
+      totalFailures: active.length,
+      byService,
+      byStatusCode: byStatus,
+      byType,
+      oldestEntry: active[0]?.timestamp ?? null,
+      newestEntry: active[active.length - 1]?.timestamp ?? null,
+    };
+  }
+
+  /** Clear all entries. */
+  clear() {
+    this._entries = [];
+    this._idCounter = 0;
+  }
+}
+
+module.exports = { FailureStore };

package/lib/index.js

@@ -0,0 +1,35 @@
+'use strict';
+
+/**
+ * @file lib/index.js
+ * @description Entry point for ps-observe.
+ *
+ * Exports:
+ *   - default: Fastify plugin (register this for Fastify apps)
+ *   - expressMiddleware: Express/Connect middleware factory
+ *   - createHttpHandler: Plain Node.js http handler factory
+ *   - FailureStore: For standalone use without any framework
+ *   - attachInterceptor: For manual attachment to a single BaseHttpClient
+ *   - attachToAll: For auto-attachment to all clients on an object
+ *   - createRouter: Framework-agnostic route handler factory
+ */
+
+const plugin = require('./plugin');
+const { FailureStore } = require('./failure-store');
+const { attachInterceptor, attachToAll } = require('./interceptor');
+const { expressMiddleware } = require('./adapters/express');
+const { createHttpHandler } = require('./adapters/http');
+const { createRouter } = require('./router');
+
+// Default export is the Fastify plugin (backwards compatible)
+module.exports = plugin;
+
+// Framework adapters
+module.exports.expressMiddleware = expressMiddleware;
+module.exports.createHttpHandler = createHttpHandler;
+
+// Core building blocks
+module.exports.FailureStore = FailureStore;
+module.exports.attachInterceptor = attachInterceptor;
+module.exports.attachToAll = attachToAll;
+module.exports.createRouter = createRouter;

package/lib/interceptor.js

@@ -0,0 +1,180 @@
+'use strict';
+
+/**
+ * @file lib/interceptor.js
+ * @description Hooks into a BaseHttpClient's axios instance to capture API
+ *              failures with full request/response details.
+ *
+ * The key challenge is interceptor ordering. BaseHttpClient registers its own
+ * response interceptor in its constructor, which converts axios errors into
+ * UpstreamError/UpstreamTimeoutError (losing the original .config and .response).
+ *
+ * To capture the raw error details, we eject the existing response interceptors,
+ * add ours first, then re-add the originals. This way our interceptor sees the
+ * original axios error with full request/response data before BaseHttpClient
+ * transforms it.
+ */
+
+/**
+ * Attach the observe interceptor to a BaseHttpClient instance.
+ *
+ * @param {object} client - A BaseHttpClient instance (has _axios and serviceName)
+ * @param {import('./failure-store').FailureStore} store
+ * @param {{ sanitize?: (data: any) => any }} [opts]
+ */
+function attachInterceptor(client, store, opts = {}) {
+  const sanitize = opts.sanitize ?? defaultSanitize;
+  const axiosInstance = client._axios;
+
+  if (!axiosInstance) {
+    throw new Error(
+      `ps-observe: Cannot attach interceptor — client "${client.serviceName}" has no _axios instance`,
+    );
+  }
+
+  // Mark this client so we don't double-attach
+  if (client.__psObserveAttached) return;
+  client.__psObserveAttached = true;
+
+  // ── Eject existing response interceptors ───────────���────────────────────
+  // Save them, clear them, add ours first, then re-add the originals.
+  // This ensures our interceptor runs BEFORE BaseHttpClient's error handler.
+  const existingInterceptors = [];
+  axiosInstance.interceptors.response.handlers.forEach((handler) => {
+    if (handler) {
+      existingInterceptors.push(handler);
+    }
+  });
+
+  // Eject all existing response interceptors
+  axiosInstance.interceptors.response.handlers.length = 0;
+
+  // ── Add our interceptor FIRST ───────────────────────────────────────────
+  axiosInstance.interceptors.response.use(
+    // Success — pass through, we only care about failures
+    response => response,
+
+    // Error — capture failure details then re-throw the ORIGINAL error
+    // so BaseHttpClient's interceptor can still transform it as usual
+    error => {
+      const config = error.config || {};
+      const response = error.response;
+      const durationMs = Date.now() - (config.metadata?.startMs ?? Date.now());
+
+      const record = {
+        type: 'upstream',
+        service: client.serviceName,
+        method: config.method?.toUpperCase() ?? 'UNKNOWN',
+        url: buildFullUrl(config),
+        correlationId: config.correlationId ?? config.headers?.['x-correlation-id'] ?? null,
+        durationMs,
+        errorMessage: error.message,
+        errorCode: error.code ?? null,
+
+        // Request details
+        request: {
+          headers: sanitize(config.headers),
+          params: config.params ?? null,
+          body: sanitize(config.data),
+        },
+
+        // Response details (null if no response, e.g. timeout/network error)
+        statusCode: response?.status ?? null,
+        response: response
+          ? {
+              headers: response.headers ?? null,
+              body: sanitize(response.data),
+            }
+          : null,
+      };
+
+      store.add(record);
+
+      // Re-throw the original error so BaseHttpClient's handler still works
+      throw error;
+    },
+  );
+
+  // ── Re-add the original interceptors AFTER ours ─────────────���───────────
+  for (const handler of existingInterceptors) {
+    axiosInstance.interceptors.response.handlers.push(handler);
+  }
+}
+
+/**
+ * Attach the interceptor to every BaseHttpClient found on a service instance.
+ *
+ * @param {object} serviceContainer - Object whose values may be BaseHttpClient instances
+ * @param {import('./failure-store').FailureStore} store
+ * @param {{ sanitize?: (data: any) => any }} [opts]
+ */
+function attachToAll(serviceContainer, store, opts = {}) {
+  for (const key of Object.keys(serviceContainer)) {
+    const val = serviceContainer[key];
+
+    // Direct BaseHttpClient
+    if (isHttpClient(val)) {
+      attachInterceptor(val, store, opts);
+      continue;
+    }
+
+    // Service wrapper that has a .client property (e.g. PsPartiesService)
+    if (val && isHttpClient(val.client)) {
+      attachInterceptor(val.client, store, opts);
+    }
+  }
+}
+
+// ��─ Helpers ───────────────────────────────────────────────────────────────────
+
+function isHttpClient(obj) {
+  return obj && typeof obj === 'object' && obj._axios && obj.serviceName;
+}
+
+function buildFullUrl(config) {
+  const base = config.baseURL ?? '';
+  const path = config.url ?? '';
+  if (base && path) return `${base.replace(/\/$/, '')}/${path.replace(/^\//, '')}`;
+  return base || path || 'unknown';
+}
+
+/**
+ * Default sanitizer — redacts common sensitive headers/fields.
+ */
+function defaultSanitize(data) {
+  if (!data || typeof data !== 'object') return data;
+
+  const REDACTED = '[REDACTED]';
+  const SENSITIVE_KEYS = new Set([
+    'authorization',
+    'x-access-token',
+    'cookie',
+    'set-cookie',
+    'secret',
+    'password',
+    'token',
+    'refresh',
+    'x-api-key',
+  ]);
+
+  // Handle string data (e.g. serialized JSON body)
+  if (typeof data === 'string') {
+    try {
+      data = JSON.parse(data);
+    } catch {
+      return data;
+    }
+  }
+
+  const sanitized = Array.isArray(data) ? [...data] : { ...data };
+
+  for (const key of Object.keys(sanitized)) {
+    if (SENSITIVE_KEYS.has(key.toLowerCase())) {
+      sanitized[key] = REDACTED;
+    }
+  }
+
+  return sanitized;
+}
+
+module.exports = { attachInterceptor, attachToAll, defaultSanitize };

package/lib/plugin.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * @file lib/plugin.js
+ * @description Fastify plugin that wires up the failure store, interceptors,
+ *              and dashboard routes.
+ *
+ * Usage in a consuming service:
+ *
+ *   const psObserve = require('@pruservices/ps-observe');
+ *
+ *   fastify.register(psObserve, {
+ *     // (optional) max failure records to keep in memory (default: 500)
+ *     maxEntries: 500,
+ *
+ *     // (optional) TTL in ms before entries are evicted (default: 24h)
+ *     ttlMs: 24 * 60 * 60 * 1000,
+ *
+ *     // (optional) custom sanitizer for request/response bodies
+ *     sanitize: (data) => data,
+ *
+ *     // (optional) prefix for observe routes (default: '')
+ *     prefix: '',
+ *   });
+ *
+ *   // After registering your service clients, attach the interceptors:
+ *   fastify.after(() => {
+ *     // Option A: Attach to individual clients
+ *     fastify.psObserve.attach(myClient);
+ *
+ *     // Option B: Auto-attach to all clients on an object
+ *     fastify.psObserve.attachToAll(fastify.services);
+ *   });
+ */
+
+const { FailureStore } = require('./failure-store');
+const { attachInterceptor, attachToAll } = require('./interceptor');
+const { registerRoutes } = require('./routes');
+
+async function psObservePlugin(fastify, opts) {
+  const store = new FailureStore({
+    maxEntries: opts.maxEntries,
+    ttlMs: opts.ttlMs,
+  });
+
+  const sanitizeOpts = opts.sanitize ? { sanitize: opts.sanitize } : {};
+
+  // Decorate fastify with the observe API so consumers can attach clients
+  fastify.decorate('psObserve', {
+    /** Attach interceptor to a single BaseHttpClient instance */
+    attach(client) {
+      attachInterceptor(client, store, sanitizeOpts);
+    },
+
+    /** Auto-attach to all BaseHttpClient instances found on an object */
+    attachToAll(serviceContainer) {
+      attachToAll(serviceContainer, store, sanitizeOpts);
+    },
+
+    /** Direct access to the failure store (for advanced use) */
+    store,
+  });
+
+  // ── 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')) {
+      done();
+      return;
+    }
+
+    // Determine error source
+    const isUpstream = error.name === 'UpstreamError' || error.name === 'UpstreamTimeoutError';
+
+    // Skip upstream errors — they're already captured by the axios interceptor
+    if (isUpstream) {
+      done();
+      return;
+    }
+
+    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: null,
+      errorMessage: error.message,
+      errorCode: error.code ?? null,
+      errorName: error.name ?? 'Error',
+      stack: error.stack ?? null,
+
+      // Incoming request details
+      request: {
+        headers: sanitize(request.headers),
+        params: request.params ?? null,
+        query: request.query ?? null,
+        body: sanitize(request.body),
+      },
+
+      // No upstream response for controller errors
+      statusCode: error.statusCode ?? 500,
+      response: null,
+    });
+
+    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) => {
+    if (request.url.startsWith('/observe')) {
+      done();
+      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,
+      });
+    }
+
+    done();
+  });
+
+  // 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;
+
+module.exports = psObservePlugin;

package/lib/router.js

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * @file lib/router.js
+ * @description Framework-agnostic route handler for observe endpoints.
+ *
+ * Each handler receives parsed request info and returns a plain response object:
+ *   { status: number, headers: object, body: string|object }
+ *
+ * Framework adapters (Fastify, Express, plain HTTP) call into this router
+ * so the actual route logic lives in one place.
+ */
+
+const { getDashboardHtml } = require('./dashboard/index');
+
+/**
+ * Create a router bound to a FailureStore instance.
+ *
+ * @param {import('./failure-store').FailureStore} store
+ * @returns {function} routeHandler(method, pathname, query, params) => response
+ */
+function createRouter(store) {
+  /**
+   * @param {string} method  - HTTP method (uppercase)
+   * @param {string} pathname - URL path, e.g. "/observe/api/failures/3"
+   * @param {object} query   - Parsed query parameters
+   * @returns {{ status: number, headers: object, body: any } | null}
+   *          null means "no matching route"
+   */
+  return function routeHandler(method, pathname, query) {
+    // Normalise: strip trailing slash (except root "/observe")
+    const path = pathname.replace(/\/$/, '') || '/';
+
+    // ── Dashboard ──────────────────────────────────────────────────────────
+    if (method === 'GET' && path === '/observe') {
+      return {
+        status: 200,
+        headers: { 'content-type': 'text/html; charset=utf-8' },
+        body: getDashboardHtml(),
+      };
+    }
+
+    // ── 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 });
+      return { status: 200, headers: { 'content-type': 'application/json' }, body: result };
+    }
+
+    // ── Single failure detail ──────────────────────────────────────────────
+    const detailMatch = path.match(/^\/observe\/api\/failures\/(\d+)$/);
+    if (method === 'GET' && detailMatch) {
+      const record = store.getById(detailMatch[1]);
+      if (!record) {
+        return { status: 404, headers: { 'content-type': 'application/json' }, body: { error: 'Failure record not found' } };
+      }
+      return { status: 200, headers: { 'content-type': 'application/json' }, body: record };
+    }
+
+    // ── Summary stats ──────────────────────────────────────────────────────
+    if (method === 'GET' && path === '/observe/api/summary') {
+      return { status: 200, headers: { 'content-type': 'application/json' }, body: store.summary() };
+    }
+
+    // ── Clear all ──────────────────────────────────────────────────────────
+    if (method === 'DELETE' && path === '/observe/api/failures') {
+      store.clear();
+      return { status: 200, headers: { 'content-type': 'application/json' }, body: { cleared: true } };
+    }
+
+    // No matching route
+    return null;
+  };
+}
+
+module.exports = { createRouter };

package/lib/routes.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/**
+ * @file lib/routes.js
+ * @description Fastify-specific route registration using the generic router.
+ *
+ *   GET  /observe              — HTML dashboard
+ *   GET  /observe/api/failures — List failures (with filters)
+ *   GET  /observe/api/failures/:id — Single failure detail
+ *   GET  /observe/api/summary  — Failure stats grouped by service / status code
+ *   DELETE /observe/api/failures — Clear all stored failures
+ */
+
+const { createRouter } = require('./router');
+
+/**
+ * Register observe routes on a Fastify instance.
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {import('./failure-store').FailureStore} store
+ */
+function registerRoutes(fastify, store) {
+  const router = createRouter(store);
+
+  // Catch-all handler for /observe routes
+  const handler = (req, reply) => {
+    const url = new URL(req.url, 'http://localhost');
+    const result = router(req.method, url.pathname, req.query);
+    if (!result) {
+      reply.code(404).send({ error: 'Not found' });
+      return;
+    }
+    reply.code(result.status).headers(result.headers).send(result.body);
+  };
+
+  fastify.get('/observe', handler);
+  fastify.get('/observe/api/failures', handler);
+  fastify.get('/observe/api/failures/:id', handler);
+  fastify.get('/observe/api/summary', handler);
+  fastify.delete('/observe/api/failures', handler);
+}
+
+module.exports = { registerRoutes };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "api-observe",
+  "version": "1.0.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": [
+    "lib/",
+    "express.js",
+    "http.js"
+  ],
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "fastify",
+    "express",
+    "nestjs",
+    "koa",
+    "observability",
+    "api-failures",
+    "monitoring",
+    "error-tracking",
+    "middleware"
+  ],
+  "author": "darenjob",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/darenjob/api-observe"
+  },
+  "peerDependencies": {
+    "fastify": ">=4.0.0",
+    "fastify-plugin": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "fastify": {
+      "optional": true
+    },
+    "fastify-plugin": {
+      "optional": true
+    }
+  }
+}