margin-ts 0.6.0 → 0.6.2

package/src/adapters/express.ts

@@ -0,0 +1,342 @@
+/**
+ * Express middleware adapter for margin.
+ *
+ * Tracks per-route health: latency, error rate, request rate.
+ * Exposes /margin/health endpoint with typed classifications.
+ *
+ * Usage:
+ *   import express from 'express';
+ *   import { marginMiddleware, marginHealthRoute } from 'margin-ts/adapters/express';
+ *
+ *   const app = express();
+ *   app.use(marginMiddleware());
+ *   app.get('/margin/health', marginHealthRoute());
+ *
+ * Zero dependencies beyond margin-ts core (express types are optional).
+ */
+
+import {
+  Confidence,
+  Health,
+  Thresholds,
+  createThresholds,
+  classify,
+  Observation,
+  Expression,
+  createExpression,
+  observationSigma,
+  expressionToString,
+  expressionToDict,
+  DriftState,
+  DriftDirection,
+  classifyDrift,
+  AnomalyState,
+  classifyAnomaly,
+} from '../index.js';
+
+// -----------------------------------------------------------------------
+// Route metrics tracking
+// -----------------------------------------------------------------------
+
+interface RouteMetrics {
+  route: string;
+  totalRequests: number;
+  totalErrors: number;       // status >= 500
+  total4xx: number;          // status 400-499
+  latencies: number[];       // last N response times in ms
+  timestamps: Date[];        // when each request happened
+  maxWindow: number;
+}
+
+function createRouteMetrics(route: string, maxWindow = 200): RouteMetrics {
+  return {
+    route,
+    totalRequests: 0,
+    totalErrors: 0,
+    total4xx: 0,
+    latencies: [],
+    timestamps: [],
+    maxWindow,
+  };
+}
+
+function recordRequest(rm: RouteMetrics, latencyMs: number, statusCode: number): void {
+  rm.totalRequests++;
+  if (statusCode >= 500) rm.totalErrors++;
+  if (statusCode >= 400 && statusCode < 500) rm.total4xx++;
+  rm.latencies.push(latencyMs);
+  rm.timestamps.push(new Date());
+  if (rm.latencies.length > rm.maxWindow) {
+    rm.latencies.shift();
+    rm.timestamps.shift();
+  }
+}
+
+// -----------------------------------------------------------------------
+// Default thresholds
+// -----------------------------------------------------------------------
+
+export interface EndpointThresholds {
+  p50Latency: Thresholds;
+  p99Latency: Thresholds;
+  errorRate: Thresholds;
+  requestRate: Thresholds;
+}
+
+export const DEFAULT_THRESHOLDS: EndpointThresholds = {
+  p50Latency: createThresholds(100, 500, false),     // ms, lower is better
+  p99Latency: createThresholds(500, 2000, false),     // ms, lower is better
+  errorRate: createThresholds(0.01, 0.10, false),     // ratio, lower is better
+  requestRate: createThresholds(1.0, 0.1, true),      // req/s, higher is better
+};
+
+// -----------------------------------------------------------------------
+// Metrics → Observations
+// -----------------------------------------------------------------------
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.ceil(sorted.length * p) - 1;
+  return sorted[Math.max(0, Math.min(idx, sorted.length - 1))];
+}
+
+function classifyRoute(
+  rm: RouteMetrics,
+  thresholds: EndpointThresholds,
+  now: Date,
+): Observation[] {
+  if (rm.latencies.length < 3) return [];
+
+  const sorted = [...rm.latencies].sort((a, b) => a - b);
+  const p50 = percentile(sorted, 0.5);
+  const p99 = percentile(sorted, 0.99);
+  const errorRate = rm.totalRequests > 0 ? rm.totalErrors / rm.totalRequests : 0;
+
+  // Request rate: requests in window / window duration
+  let requestRate = 0;
+  if (rm.timestamps.length >= 2) {
+    const windowMs = rm.timestamps[rm.timestamps.length - 1].getTime() - rm.timestamps[0].getTime();
+    if (windowMs > 0) requestRate = (rm.timestamps.length / windowMs) * 1000;
+  }
+
+  const prefix = rm.route === '*' ? '' : `${rm.route}:`;
+
+  const observations: Observation[] = [
+    {
+      name: `${prefix}p50_latency`,
+      health: classify(p50, Confidence.HIGH, thresholds.p50Latency),
+      value: p50,
+      baseline: thresholds.p50Latency.intact,
+      confidence: Confidence.HIGH,
+      higherIsBetter: false,
+      provenance: [],
+      measuredAt: now,
+    },
+    {
+      name: `${prefix}p99_latency`,
+      health: classify(p99, Confidence.HIGH, thresholds.p99Latency),
+      value: p99,
+      baseline: thresholds.p99Latency.intact,
+      confidence: Confidence.HIGH,
+      higherIsBetter: false,
+      provenance: [],
+      measuredAt: now,
+    },
+    {
+      name: `${prefix}error_rate`,
+      health: classify(errorRate, Confidence.HIGH, thresholds.errorRate),
+      value: errorRate,
+      baseline: 0.001,
+      confidence: Confidence.HIGH,
+      higherIsBetter: false,
+      provenance: [],
+      measuredAt: now,
+    },
+    {
+      name: `${prefix}request_rate`,
+      health: classify(requestRate, Confidence.MODERATE, thresholds.requestRate),
+      value: requestRate,
+      baseline: 10.0,
+      confidence: Confidence.MODERATE,
+      higherIsBetter: true,
+      provenance: [],
+      measuredAt: now,
+    },
+  ];
+
+  return observations;
+}
+
+// -----------------------------------------------------------------------
+// Middleware
+// -----------------------------------------------------------------------
+
+export interface MarginMiddlewareOptions {
+  /** Track per-route or aggregate only (default: true) */
+  perRoute?: boolean;
+  /** Max latency samples to keep per route (default: 200) */
+  window?: number;
+  /** Custom thresholds */
+  thresholds?: EndpointThresholds;
+  /** Routes to ignore (e.g. ['/margin/health', '/favicon.ico']) */
+  ignore?: string[];
+  /** Normalize route paths: replace numeric segments with :id (default: true) */
+  normalizePaths?: boolean;
+}
+
+/** The shared state object — accessible for custom endpoints */
+export interface MarginState {
+  routes: Map<string, RouteMetrics>;
+  aggregate: RouteMetrics;
+  options: Required<MarginMiddlewareOptions>;
+}
+
+function normalizePath(path: string): string {
+  return path.replace(/\/\d+/g, '/:id').replace(/\/[0-9a-f]{24}/g, '/:id');
+}
+
+/**
+ * Express middleware that tracks request latency and error rates.
+ *
+ * Attach to your app before routes:
+ *   app.use(marginMiddleware());
+ */
+export function marginMiddleware(options: MarginMiddlewareOptions = {}): any {
+  const opts: Required<MarginMiddlewareOptions> = {
+    perRoute: options.perRoute ?? true,
+    window: options.window ?? 200,
+    thresholds: options.thresholds ?? DEFAULT_THRESHOLDS,
+    ignore: options.ignore ?? ['/margin/health', '/favicon.ico'],
+    normalizePaths: options.normalizePaths ?? true,
+  };
+
+  const state: MarginState = {
+    routes: new Map(),
+    aggregate: createRouteMetrics('*', opts.window),
+    options: opts,
+  };
+
+  const middleware = (req: any, res: any, next: any) => {
+    const path: string = req.path || req.url || '/';
+
+    if (opts.ignore.includes(path)) {
+      next();
+      return;
+    }
+
+    const start = Date.now();
+
+    // Hook into response finish
+    const onFinish = () => {
+      res.removeListener('finish', onFinish);
+      const latency = Date.now() - start;
+      const status: number = res.statusCode || 200;
+
+      // Aggregate
+      recordRequest(state.aggregate, latency, status);
+
+      // Per-route
+      if (opts.perRoute) {
+        const route = opts.normalizePaths ? normalizePath(path) : path;
+        if (!state.routes.has(route)) {
+          state.routes.set(route, createRouteMetrics(route, opts.window));
+        }
+        recordRequest(state.routes.get(route)!, latency, status);
+      }
+    };
+
+    res.on('finish', onFinish);
+    next();
+  };
+
+  // Attach state to middleware for access by health route
+  (middleware as any).__marginState = state;
+
+  return middleware;
+}
+
+// -----------------------------------------------------------------------
+// Health endpoint
+// -----------------------------------------------------------------------
+
+export interface HealthResponse {
+  status: string;
+  expression: string;
+  aggregate: Record<string, unknown>;
+  routes?: Record<string, Record<string, unknown>>;
+  drift?: Record<string, unknown>;
+}
+
+/**
+ * Express route handler for /margin/health.
+ *
+ * Returns typed health classification for all tracked routes.
+ *
+ *   app.get('/margin/health', marginHealthRoute());
+ *
+ * Or pass the middleware directly:
+ *   const mw = marginMiddleware();
+ *   app.use(mw);
+ *   app.get('/margin/health', marginHealthRoute(mw));
+ */
+export function marginHealthRoute(middleware?: any): any {
+  return (req: any, res: any) => {
+    // Find state from middleware
+    let state: MarginState | undefined;
+    if (middleware && (middleware as any).__marginState) {
+      state = (middleware as any).__marginState;
+    } else if (req.app) {
+      // Walk through app middleware stack to find ours
+      const stack = req.app._router?.stack || [];
+      for (const layer of stack) {
+        if (layer.handle?.__marginState) {
+          state = layer.handle.__marginState;
+          break;
+        }
+      }
+    }
+
+    if (!state) {
+      res.status(500).json({ error: 'margin middleware not found' });
+      return;
+    }
+
+    const now = new Date();
+    const thresholds = state.options.thresholds;
+
+    // Aggregate health
+    const aggObs = classifyRoute(state.aggregate, thresholds, now);
+    const aggExpr = createExpression(aggObs, [], 'aggregate');
+
+    // Determine overall status
+    const SEVERITY_MAP: Record<Health, number> = {
+      [Health.INTACT]: 0, [Health.RECOVERING]: 1, [Health.DEGRADED]: 2,
+      [Health.ABLATED]: 3, [Health.OOD]: 4,
+    };
+    const worstHealth = aggObs.reduce(
+      (worst, o) => SEVERITY_MAP[o.health] > SEVERITY_MAP[worst] ? o.health : worst,
+      Health.INTACT,
+    );
+
+    const response: HealthResponse = {
+      status: worstHealth,
+      expression: expressionToString(aggExpr),
+      aggregate: expressionToDict(aggExpr),
+    };
+
+    // Per-route health
+    if (state.options.perRoute && state.routes.size > 0) {
+      const routes: Record<string, Record<string, unknown>> = {};
+      for (const [route, metrics] of state.routes) {
+        const obs = classifyRoute(metrics, thresholds, now);
+        if (obs.length > 0) {
+          const expr = createExpression(obs, [], route);
+          routes[route] = expressionToDict(expr);
+        }
+      }
+      response.routes = routes;
+    }
+
+    res.json(response);
+  };
+}

package/src/adapters/nextjs.ts

@@ -0,0 +1,290 @@
+/**
+ * Next.js API route adapter for margin.
+ *
+ * One-liner health tracking for any API route:
+ *
+ *   // pages/api/users.ts (Pages Router)
+ *   import { withMargin } from 'margin-ts/adapters/nextjs';
+ *   export default withMargin(handler);
+ *
+ *   // app/api/users/route.ts (App Router)
+ *   import { withMarginApp } from 'margin-ts/adapters/nextjs';
+ *   export const GET = withMarginApp(handler);
+ *
+ *   // Health endpoint
+ *   // pages/api/margin/health.ts
+ *   import { marginHealthHandler } from 'margin-ts/adapters/nextjs';
+ *   export default marginHealthHandler();
+ *
+ * Tracks latency, error rate, and request count per route.
+ * Zero dependencies beyond margin-ts core.
+ */
+
+import {
+  Confidence,
+  Health,
+  Thresholds,
+  createThresholds,
+  classify,
+  Observation,
+  createExpression,
+  expressionToString,
+  expressionToDict,
+} from '../index.js';
+
+// -----------------------------------------------------------------------
+// Shared state — singleton across all wrapped routes
+// -----------------------------------------------------------------------
+
+interface RouteStats {
+  totalRequests: number;
+  totalErrors: number;
+  latencies: number[];
+  maxWindow: number;
+}
+
+const _routes = new Map<string, RouteStats>();
+const _MAX_WINDOW = 200;
+
+function getOrCreateRoute(route: string): RouteStats {
+  if (!_routes.has(route)) {
+    _routes.set(route, {
+      totalRequests: 0,
+      totalErrors: 0,
+      latencies: [],
+      maxWindow: _MAX_WINDOW,
+    });
+  }
+  return _routes.get(route)!;
+}
+
+function record(route: string, latencyMs: number, isError: boolean): void {
+  const stats = getOrCreateRoute(route);
+  stats.totalRequests++;
+  if (isError) stats.totalErrors++;
+  stats.latencies.push(latencyMs);
+  if (stats.latencies.length > stats.maxWindow) stats.latencies.shift();
+}
+
+// -----------------------------------------------------------------------
+// Thresholds
+// -----------------------------------------------------------------------
+
+export interface NextjsThresholds {
+  p50Latency: Thresholds;
+  p99Latency: Thresholds;
+  errorRate: Thresholds;
+}
+
+export const DEFAULT_NEXTJS_THRESHOLDS: NextjsThresholds = {
+  p50Latency: createThresholds(100, 500, false),
+  p99Latency: createThresholds(500, 2000, false),
+  errorRate: createThresholds(0.01, 0.10, false),
+};
+
+// -----------------------------------------------------------------------
+// Classification
+// -----------------------------------------------------------------------
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.ceil(sorted.length * p) - 1;
+  return sorted[Math.max(0, Math.min(idx, sorted.length - 1))];
+}
+
+function classifyRoute(route: string, stats: RouteStats, thresholds: NextjsThresholds) {
+  if (stats.latencies.length < 3) return null;
+
+  const sorted = [...stats.latencies].sort((a, b) => a - b);
+  const p50 = percentile(sorted, 0.5);
+  const p99 = percentile(sorted, 0.99);
+  const errorRate = stats.totalRequests > 0 ? stats.totalErrors / stats.totalRequests : 0;
+  const now = new Date();
+
+  const observations: Observation[] = [
+    {
+      name: `${route}:p50`, health: classify(p50, Confidence.HIGH, thresholds.p50Latency),
+      value: p50, baseline: thresholds.p50Latency.intact, confidence: Confidence.HIGH,
+      higherIsBetter: false, provenance: [], measuredAt: now,
+    },
+    {
+      name: `${route}:p99`, health: classify(p99, Confidence.HIGH, thresholds.p99Latency),
+      value: p99, baseline: thresholds.p99Latency.intact, confidence: Confidence.HIGH,
+      higherIsBetter: false, provenance: [], measuredAt: now,
+    },
+    {
+      name: `${route}:errors`, health: classify(errorRate, Confidence.HIGH, thresholds.errorRate),
+      value: errorRate, baseline: 0.001, confidence: Confidence.HIGH,
+      higherIsBetter: false, provenance: [], measuredAt: now,
+    },
+  ];
+
+  return createExpression(observations, [], route);
+}
+
+// -----------------------------------------------------------------------
+// Pages Router wrapper
+// -----------------------------------------------------------------------
+
+export interface WithMarginOptions {
+  route?: string;
+  thresholds?: NextjsThresholds;
+}
+
+/**
+ * Wrap a Pages Router API handler with margin health tracking.
+ *
+ *   export default withMargin(handler);
+ *   export default withMargin(handler, { route: '/api/users' });
+ */
+export function withMargin(
+  handler: (req: any, res: any) => any,
+  options: WithMarginOptions = {},
+): (req: any, res: any) => any {
+  return async (req: any, res: any) => {
+    const route = options.route || req.url || '/api/unknown';
+    const start = Date.now();
+
+    try {
+      const result = await handler(req, res);
+      const latency = Date.now() - start;
+      const status = res.statusCode || 200;
+      record(route, latency, status >= 500);
+      return result;
+    } catch (err) {
+      const latency = Date.now() - start;
+      record(route, latency, true);
+      throw err;
+    }
+  };
+}
+
+// -----------------------------------------------------------------------
+// App Router wrapper
+// -----------------------------------------------------------------------
+
+/**
+ * Wrap an App Router handler with margin health tracking.
+ *
+ *   export const GET = withMarginApp(handler);
+ *   export const POST = withMarginApp(handler, { route: '/api/users' });
+ */
+export function withMarginApp(
+  handler: (req: any) => any,
+  options: WithMarginOptions = {},
+): (req: any) => any {
+  return async (req: any) => {
+    const route = options.route || new URL(req.url || '/', 'http://localhost').pathname;
+    const start = Date.now();
+
+    try {
+      const response = await handler(req);
+      const latency = Date.now() - start;
+      const status = response?.status || 200;
+      record(route, latency, status >= 500);
+      return response;
+    } catch (err) {
+      const latency = Date.now() - start;
+      record(route, latency, true);
+      throw err;
+    }
+  };
+}
+
+// -----------------------------------------------------------------------
+// Health endpoint
+// -----------------------------------------------------------------------
+
+/**
+ * Pages Router: health endpoint handler.
+ *
+ *   // pages/api/margin/health.ts
+ *   import { marginHealthHandler } from 'margin-ts/adapters/nextjs';
+ *   export default marginHealthHandler();
+ */
+export function marginHealthHandler(thresholds?: NextjsThresholds): (req: any, res: any) => void {
+  const t = thresholds || DEFAULT_NEXTJS_THRESHOLDS;
+
+  return (_req: any, res: any) => {
+    const routeHealth: Record<string, any> = {};
+    let worstOverall = Health.INTACT;
+    const SEVERITY: Record<Health, number> = {
+      [Health.INTACT]: 0, [Health.RECOVERING]: 1, [Health.DEGRADED]: 2,
+      [Health.ABLATED]: 3, [Health.OOD]: 4,
+    };
+
+    for (const [route, stats] of _routes) {
+      const expr = classifyRoute(route, stats, t);
+      if (expr) {
+        routeHealth[route] = {
+          expression: expressionToString(expr),
+          ...expressionToDict(expr),
+          requests: stats.totalRequests,
+          errors: stats.totalErrors,
+        };
+        for (const obs of expr.observations) {
+          if (SEVERITY[obs.health] > SEVERITY[worstOverall]) {
+            worstOverall = obs.health;
+          }
+        }
+      }
+    }
+
+    res.status(200).json({
+      status: worstOverall,
+      routes: routeHealth,
+      totalRoutes: _routes.size,
+    });
+  };
+}
+
+/**
+ * App Router: health endpoint handler.
+ *
+ *   // app/api/margin/health/route.ts
+ *   import { marginHealthAppHandler } from 'margin-ts/adapters/nextjs';
+ *   export const GET = marginHealthAppHandler();
+ */
+export function marginHealthAppHandler(thresholds?: NextjsThresholds): (req: any) => any {
+  const t = thresholds || DEFAULT_NEXTJS_THRESHOLDS;
+
+  return (_req: any) => {
+    const routeHealth: Record<string, any> = {};
+    let worstOverall = Health.INTACT;
+    const SEVERITY: Record<Health, number> = {
+      [Health.INTACT]: 0, [Health.RECOVERING]: 1, [Health.DEGRADED]: 2,
+      [Health.ABLATED]: 3, [Health.OOD]: 4,
+    };
+
+    for (const [route, stats] of _routes) {
+      const expr = classifyRoute(route, stats, t);
+      if (expr) {
+        routeHealth[route] = {
+          expression: expressionToString(expr),
+          ...expressionToDict(expr),
+          requests: stats.totalRequests,
+          errors: stats.totalErrors,
+        };
+        for (const obs of expr.observations) {
+          if (SEVERITY[obs.health] > SEVERITY[worstOverall]) {
+            worstOverall = obs.health;
+          }
+        }
+      }
+    }
+
+    return new Response(JSON.stringify({
+      status: worstOverall,
+      routes: routeHealth,
+      totalRoutes: _routes.size,
+    }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  };
+}
+
+/** Clear all tracked routes (for testing). */
+export function resetRoutes(): void {
+  _routes.clear();
+}