api-observe 1.0.0

package/express.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./lib/adapters/express');

package/http.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./lib/adapters/http');

package/lib/adapters/express.js

@@ -0,0 +1,127 @@
+'use strict';
+
+/**
+ * @file lib/adapters/express.js
+ * @description Express/Connect middleware adapter for ps-observe.
+ *
+ * Usage:
+ *
+ *   const express = require('express');
+ *   const { expressMiddleware } = require('ps-observe/express');
+ *
+ *   const app = express();
+ *   const observe = expressMiddleware({
+ *     maxEntries: 500,
+ *     ttlMs: 24 * 60 * 60 * 1000,
+ *     sanitize: (data) => data,
+ *   });
+ *
+ *   app.use(observe);
+ *
+ *   // Attach interceptors to your HTTP clients:
+ *   observe.attach(myClient);
+ *   observe.attachToAll(serviceContainer);
+ *
+ *   // Access the store directly:
+ *   observe.store;
+ */
+
+const { parse: parseUrl } = require('url');
+const { FailureStore } = require('../failure-store');
+const { attachInterceptor, attachToAll, defaultSanitize } = require('../interceptor');
+const { createRouter } = require('../router');
+
+/**
+ * Create an Express middleware that captures errors and serves the observe dashboard.
+ *
+ * @param {{ maxEntries?: number, ttlMs?: number, sanitize?: function }} [opts]
+ * @returns {function} Express middleware with .attach(), .attachToAll(), .store, .errorHandler()
+ */
+function expressMiddleware(opts = {}) {
+  const store = new FailureStore({
+    maxEntries: opts.maxEntries,
+    ttlMs: opts.ttlMs,
+  });
+
+  const sanitize = opts.sanitize ?? defaultSanitize;
+  const sanitizeOpts = opts.sanitize ? { sanitize: opts.sanitize } : {};
+  const router = createRouter(store);
+
+  // ── Main middleware: serves dashboard routes ─────────────────────────────
+  function middleware(req, res, next) {
+    const parsed = parseUrl(req.url, true);
+    const pathname = parsed.pathname;
+
+    // Only handle /observe routes
+    if (!pathname.startsWith('/observe')) {
+      next();
+      return;
+    }
+
+    const result = router(req.method, pathname, parsed.query);
+    if (!result) {
+      next();
+      return;
+    }
+
+    res.statusCode = result.status;
+    for (const [key, value] of Object.entries(result.headers)) {
+      res.setHeader(key, value);
+    }
+
+    const body = typeof result.body === 'string' ? result.body : JSON.stringify(result.body);
+    res.end(body);
+  }
+
+  // ── Error-capturing middleware (use AFTER your routes) ───────────────────
+  // Express error handlers have 4 parameters: (err, req, res, next)
+  function errorHandler(err, req, res, next) {
+    // Skip /observe routes to avoid recursive captures
+    const parsed = parseUrl(req.url);
+    if (parsed.pathname.startsWith('/observe')) {
+      next(err);
+      return;
+    }
+
+    store.add({
+      type: 'controller',
+      service: req.route?.path ?? req.originalUrl ?? req.url,
+      method: req.method,
+      url: req.originalUrl ?? req.url,
+      correlationId: req.headers['x-correlation-id'] ?? null,
+      durationMs: null,
+      errorMessage: err.message,
+      errorCode: err.code ?? null,
+      errorName: err.name ?? 'Error',
+      stack: err.stack ?? null,
+
+      request: {
+        headers: sanitize(req.headers),
+        params: req.params ?? null,
+        query: req.query ?? null,
+        body: sanitize(req.body),
+      },
+
+      statusCode: err.statusCode ?? err.status ?? 500,
+      response: null,
+    });
+
+    next(err);
+  }
+
+  // ── Attach helpers directly on the middleware function ───────────────────
+  middleware.attach = function (client) {
+    attachInterceptor(client, store, sanitizeOpts);
+  };
+
+  middleware.attachToAll = function (serviceContainer) {
+    attachToAll(serviceContainer, store, sanitizeOpts);
+  };
+
+  middleware.store = store;
+  middleware.errorHandler = errorHandler;
+
+  return middleware;
+}
+
+module.exports = { expressMiddleware };

package/lib/adapters/http.js

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * @file lib/adapters/http.js
+ * @description Plain Node.js http handler adapter for ps-observe.
+ *
+ * Works with any framework that exposes a standard (req, res) interface:
+ * plain http.createServer, Koa (via koa-connect), NestJS, Hapi, etc.
+ *
+ * Usage:
+ *
+ *   const http = require('http');
+ *   const { createHttpHandler } = require('ps-observe/http');
+ *
+ *   const observe = createHttpHandler({
+ *     maxEntries: 500,
+ *     ttlMs: 24 * 60 * 60 * 1000,
+ *   });
+ *
+ *   const server = http.createServer((req, res) => {
+ *     // Let observe handle /observe routes
+ *     if (observe.handle(req, res)) return;
+ *
+ *     // Your app routes...
+ *     res.end('hello');
+ *   });
+ *
+ *   // Attach interceptors:
+ *   observe.attach(myClient);
+ *   observe.attachToAll(serviceContainer);
+ *
+ *   // Capture an error manually:
+ *   observe.captureError(err, { method: 'GET', url: '/foo', headers: {} });
+ */
+
+const { parse: parseUrl } = require('url');
+const { FailureStore } = require('../failure-store');
+const { attachInterceptor, attachToAll, defaultSanitize } = require('../interceptor');
+const { createRouter } = require('../router');
+
+/**
+ * Create a plain Node.js HTTP handler for observe.
+ *
+ * @param {{ maxEntries?: number, ttlMs?: number, sanitize?: function }} [opts]
+ * @returns {object} Handler with .handle(), .attach(), .attachToAll(), .captureError(), .store
+ */
+function createHttpHandler(opts = {}) {
+  const store = new FailureStore({
+    maxEntries: opts.maxEntries,
+    ttlMs: opts.ttlMs,
+  });
+
+  const sanitize = opts.sanitize ?? defaultSanitize;
+  const sanitizeOpts = opts.sanitize ? { sanitize: opts.sanitize } : {};
+  const router = createRouter(store);
+
+  /**
+   * Handle an incoming request. Returns true if the request was handled
+   * (i.e. it was an /observe route), false otherwise.
+   *
+   * @param {import('http').IncomingMessage} req
+   * @param {import('http').ServerResponse} res
+   * @returns {boolean}
+   */
+  function handle(req, res) {
+    const parsed = parseUrl(req.url, true);
+    const pathname = parsed.pathname;
+
+    if (!pathname.startsWith('/observe')) {
+      return false;
+    }
+
+    const result = router(req.method, pathname, parsed.query);
+    if (!result) {
+      return false;
+    }
+
+    res.statusCode = result.status;
+    for (const [key, value] of Object.entries(result.headers)) {
+      res.setHeader(key, value);
+    }
+
+    const body = typeof result.body === 'string' ? result.body : JSON.stringify(result.body);
+    res.end(body);
+    return true;
+  }
+
+  /**
+   * Manually capture an error into the failure store.
+   * Use this in frameworks where you handle errors yourself.
+   *
+   * @param {Error} err
+   * @param {{ method?: string, url?: string, headers?: object, params?: object, query?: object, body?: any }} [reqInfo]
+   */
+  function captureError(err, reqInfo = {}) {
+    store.add({
+      type: 'controller',
+      service: reqInfo.url ?? 'unknown',
+      method: reqInfo.method ?? 'UNKNOWN',
+      url: reqInfo.url ?? 'unknown',
+      correlationId: reqInfo.headers?.['x-correlation-id'] ?? null,
+      durationMs: null,
+      errorMessage: err.message,
+      errorCode: err.code ?? null,
+      errorName: err.name ?? 'Error',
+      stack: err.stack ?? null,
+
+      request: {
+        headers: sanitize(reqInfo.headers ?? {}),
+        params: reqInfo.params ?? null,
+        query: reqInfo.query ?? null,
+        body: sanitize(reqInfo.body),
+      },
+
+      statusCode: err.statusCode ?? err.status ?? 500,
+      response: null,
+    });
+  }
+
+  return {
+    handle,
+    captureError,
+    attach(client) {
+      attachInterceptor(client, store, sanitizeOpts);
+    },
+    attachToAll(serviceContainer) {
+      attachToAll(serviceContainer, store, sanitizeOpts);
+    },
+    store,
+  };
+}
+
+module.exports = { createHttpHandler };