express-performance-toolkit 1.0.0 → 2.0.0

package/src/rateLimit.ts

@@ -0,0 +1,86 @@
+import { Request, Response, NextFunction } from "express";
+import { MetricsStore } from "./store";
+import { RateLimitOptions } from "./types";
+
+interface RateLimitTracker {
+  count: number;
+  resetTime: number;
+}
+
+export function createRateLimiter(
+  store: MetricsStore,
+  options: RateLimitOptions | boolean | undefined
+) {
+  const enabled = typeof options === "boolean" ? options : options?.enabled !== false;
+  if (!enabled) {
+    return (req: Request, res: Response, next: NextFunction) => next();
+  }
+
+  const opts = typeof options === "object" ? options : {};
+  const windowMs = opts.windowMs || 60000;
+  const max = opts.max || 100;
+  const statusCode = opts.statusCode || 429;
+  const message = opts.message || "Too many requests, please try again later.";
+
+  // In-memory store mapping IP addresses to tracking objects
+  const hits = new Map<string, RateLimitTracker>();
+
+  // Cleanup interval to prevent memory leaks from inactive IPs
+  setInterval(() => {
+    const now = Date.now();
+    for (const [ip, tracker] of hits.entries()) {
+      if (now > tracker.resetTime) {
+        hits.delete(ip);
+      }
+    }
+  }, windowMs).unref(); // .unref() ensures this interval doesn't keep the Node process alive
+
+  const exclude = opts.exclude || [];
+
+  return (req: Request, res: Response, next: NextFunction) => {
+    // Check exclusions
+    const path = req.path;
+    const isExcluded = exclude.some((pattern) => {
+      if (typeof pattern === "string") return path.startsWith(pattern);
+      if (pattern instanceof RegExp) return pattern.test(path);
+      return false;
+    });
+
+    if (isExcluded) return next();
+
+    const ip = req.ip || req.connection.remoteAddress || "unknown";
+    const now = Date.now();
+    const routeKey = `${req.method} ${req.route ? req.route.path : req.path}`;
+
+    let tracker = hits.get(ip);
+
+    if (!tracker || now > tracker.resetTime) {
+      // Create new tracker or reset expired tracker
+      tracker = {
+        count: 1,
+        resetTime: now + windowMs,
+      };
+      hits.set(ip, tracker);
+      return next();
+    }
+
+    tracker.count++;
+
+    if (tracker.count > max) {
+      store.recordRateLimitHit(routeKey, ip, req.method, req.path);
+      
+      res.setHeader("Retry-After", Math.ceil((tracker.resetTime - now) / 1000));
+      res.setHeader("X-RateLimit-Limit", max);
+      res.setHeader("X-RateLimit-Remaining", 0);
+      res.setHeader("X-RateLimit-Reset", Math.ceil(tracker.resetTime / 1000));
+
+      res.status(statusCode).send(message);
+      return;
+    }
+
+    res.setHeader("X-RateLimit-Limit", max);
+    res.setHeader("X-RateLimit-Remaining", max - tracker.count);
+    res.setHeader("X-RateLimit-Reset", Math.ceil(tracker.resetTime / 1000));
+    next();
+  };
+}

package/src/store.ts

@@ -1,4 +1,7 @@
-import { LogEntry, Metrics, RouteStats } from './types';
+import { LogEntry, Metrics, RouteStats, BlockedEvent } from "./types";
+import { monitorEventLoopDelay } from "perf_hooks";
+import { analyzeMetrics } from "./analyzer";
+import * as v8 from "v8";
 
 /**
  * In-memory metrics store — shared state between all middleware components.
@@ -6,13 +9,19 @@ import { LogEntry, Metrics, RouteStats } from './types';
  */
 export class MetricsStore {
   private maxLogs: number;
+  private maxRoutes: number = 200; // Cap unique routes to prevent memory leaks
   private logs: LogEntry[];
+  private blockedEvents: BlockedEvent[] = [];
+  private histogram: ReturnType<typeof monitorEventLoopDelay>;
   private stats: {
     totalRequests: number;
     totalResponseTime: number;
     slowRequests: number;
+    highQueryRequests: number;
+    rateLimitHits: number;
     cacheHits: number;
     cacheMisses: number;
+    totalBytesSent: number;
     cacheSize: number;
     statusCodes: Record<number, number>;
     routes: Record<string, RouteStats>;
@@ -26,21 +35,23 @@ export class MetricsStore {
       totalRequests: 0,
       totalResponseTime: 0,
       slowRequests: 0,
+      highQueryRequests: 0,
+      rateLimitHits: 0,
       cacheHits: 0,
       cacheMisses: 0,
+      totalBytesSent: 0,
       cacheSize: 0,
       statusCodes: {},
       routes: {},
       startTime: Date.now(),
     };
+    this.histogram = monitorEventLoopDelay({ resolution: 10 });
+    this.histogram.enable();
   }
 
   /** Add a request log entry to the ring buffer. */
-  addLog(entry: LogEntry): void {
-    this.logs.push({
-      ...entry,
-      timestamp: entry.timestamp || Date.now(),
-    });
+  recordLog(log: LogEntry): void {
+    this.logs.push(log);
 
     // Ring buffer — drop oldest entries when full
     if (this.logs.length > this.maxLogs) {
@@ -49,35 +60,101 @@ export class MetricsStore {
 
     // Update aggregate stats
     this.stats.totalRequests++;
-    this.stats.totalResponseTime += entry.responseTime || 0;
+    this.stats.totalResponseTime += log.responseTime || 0;
 
     // Track status codes
-    const code = entry.statusCode || 0;
-    this.stats.statusCodes[code] = (this.stats.statusCodes[code] || 0) + 1;
+    this.stats.totalBytesSent += log.bytesSent;
 
     // Track per-route stats
-    const routeKey = `${entry.method} ${entry.path}`;
+    // Use normalized path (routePattern) if available, fallback to actual path
+    const routeKey = `${log.method} ${log.routePattern || log.path}`;
+    
     if (!this.stats.routes[routeKey]) {
-      this.stats.routes[routeKey] = {
-        count: 0,
-        totalTime: 0,
-        slowCount: 0,
-        avgTime: 0,
-      };
+      // Prevent unbounded growth of the routes map
+      if (Object.keys(this.stats.routes).length >= this.maxRoutes) {
+        // Fallback to a catch-all for excessive new routes
+        const othersKey = `${log.method} [Other]`;
+        if (!this.stats.routes[othersKey]) {
+          this.stats.routes[othersKey] = this.createNewRouteStats();
+        }
+        this.updateRouteStats(this.stats.routes[othersKey], log);
+      } else {
+        this.stats.routes[routeKey] = this.createNewRouteStats();
+        this.updateRouteStats(this.stats.routes[routeKey], log);
+      }
+    } else {
+      this.updateRouteStats(this.stats.routes[routeKey], log);
     }
-    const route = this.stats.routes[routeKey];
+
+    const code = log.statusCode;
+    this.stats.statusCodes[code] = (this.stats.statusCodes[code] || 0) + 1;
+  }
+
+  private createNewRouteStats(): RouteStats {
+    return {
+      count: 0,
+      totalTime: 0,
+      slowCount: 0,
+      highQueryCount: 0,
+      rateLimitHits: 0,
+      avgTime: 0,
+      totalBytes: 0,
+      avgSize: 0,
+    };
+  }
+
+  private updateRouteStats(route: RouteStats, log: LogEntry): void {
     route.count++;
-    route.totalTime += entry.responseTime || 0;
+    route.totalTime += log.responseTime;
+    route.totalBytes += log.bytesSent;
     route.avgTime = Math.round(route.totalTime / route.count);
-    if (entry.slow) {
+    route.avgSize = Math.round(route.totalBytes / route.count);
+
+    if (log.slow) {
+      this.stats.slowRequests++;
       route.slowCount++;
     }
+
+    if (log.highQueries) {
+      this.stats.highQueryRequests++;
+      route.highQueryCount++;
+    }
   }
 
   recordSlowRequest(): void {
     this.stats.slowRequests++;
   }
 
+  recordRateLimitHit(
+    routeKey: string,
+    ip: string,
+    method: string,
+    path: string,
+  ): void {
+    this.stats.rateLimitHits++;
+
+    // Track blocked event details
+    this.blockedEvents.push({
+      ip,
+      path,
+      method,
+      timestamp: Date.now(),
+    });
+
+    // Keep only last 100 blocked events
+    if (this.blockedEvents.length > 100) {
+      this.blockedEvents.shift();
+    }
+
+    if (!this.stats.routes[routeKey]) {
+      if (Object.keys(this.stats.routes).length >= this.maxRoutes) {
+        return; // Don't track rate limits for new routes if at capacity
+      }
+      this.stats.routes[routeKey] = this.createNewRouteStats();
+    }
+    this.stats.routes[routeKey].rateLimitHits++;
+  }
+
   recordCacheHit(): void {
     this.stats.cacheHits++;
   }
@@ -90,6 +167,13 @@ export class MetricsStore {
     this.stats.cacheSize = size;
   }
 
+  private calculateCacheHitRate(): number {
+    const cacheTotal = this.stats.cacheHits + this.stats.cacheMisses;
+    return cacheTotal > 0
+      ? Math.round((this.stats.cacheHits / cacheTotal) * 100)
+      : 0;
+  }
+
   /** Get all metrics data for the dashboard. */
   getMetrics(): Metrics {
     const avgResponseTime =
@@ -97,25 +181,44 @@ export class MetricsStore {
         ? Math.round(this.stats.totalResponseTime / this.stats.totalRequests)
         : 0;
 
-    const cacheTotal = this.stats.cacheHits + this.stats.cacheMisses;
-    const cacheHitRate =
-      cacheTotal > 0
-        ? Math.round((this.stats.cacheHits / cacheTotal) * 100)
-        : 0;
+    const mem = process.memoryUsage();
+    const heapStats = v8.getHeapStatistics();
 
-    return {
+    const metrics: Metrics = {
       uptime: Date.now() - this.stats.startTime,
       totalRequests: this.stats.totalRequests,
       avgResponseTime,
       slowRequests: this.stats.slowRequests,
+      highQueryRequests: this.stats.highQueryRequests,
+      rateLimitHits: this.stats.rateLimitHits,
       cacheHits: this.stats.cacheHits,
       cacheMisses: this.stats.cacheMisses,
-      cacheHitRate,
-      cacheSize: this.stats.cacheSize,
+      cacheHitRate: this.calculateCacheHitRate(),
+      cacheSize: 0, // Will be populated in index.ts if cache is enabled
+      totalBytesSent: this.stats.totalBytesSent,
+      avgResponseSize:
+        this.stats.totalRequests > 0
+          ? Math.round(this.stats.totalBytesSent / this.stats.totalRequests)
+          : 0,
+      insights: [], // Placeholder, filled below
+      eventLoopLag: Math.round(this.histogram.mean / 1e6),
+      memoryUsage: {
+        rss: mem.rss,
+        heapTotal: mem.heapTotal,
+        heapUsed: mem.heapUsed,
+        heapLimit: heapStats.heap_size_limit,
+        external: mem.external,
+      },
       statusCodes: { ...this.stats.statusCodes },
       routes: { ...this.stats.routes },
       recentLogs: this.logs.slice(-100),
+      blockedEvents: [...this.blockedEvents],
     };
+
+    // Generate insights
+    metrics.insights = analyzeMetrics(metrics);
+
+    return metrics;
   }
 
   /** Reset all metrics. */
@@ -124,11 +227,17 @@ export class MetricsStore {
     this.stats.totalRequests = 0;
     this.stats.totalResponseTime = 0;
     this.stats.slowRequests = 0;
+    this.stats.highQueryRequests = 0;
+    this.stats.rateLimitHits = 0;
     this.stats.cacheHits = 0;
     this.stats.cacheMisses = 0;
     this.stats.cacheSize = 0;
     this.stats.statusCodes = {};
     this.stats.routes = {};
     this.stats.startTime = Date.now();
+    this.blockedEvents = [];
+    this.histogram.disable();
+    this.histogram = monitorEventLoopDelay({ resolution: 10 });
+    this.histogram.enable();
   }
 }

package/src/types.ts

@@ -43,6 +43,12 @@ export interface LoggerOptions {
   slowThreshold?: number;
   /** Log to console (default: true) */
   console?: boolean;
+  /** Log to file path (optional) */
+  file?: string;
+  /** Enable automatic daily log rotation (appends YYYY-MM-DD to filename) (default: false) */
+  rotation?: boolean;
+  /** Delete log files older than this many days (default: 7). Requires rotation: true */
+  maxDays?: number;
   /** Custom log formatter */
   formatter?: (entry: LogEntry) => string;
 }
@@ -54,11 +60,37 @@ export interface QueryHelperOptions {
   threshold?: number;
 }
 
+export interface DashboardAuthOptions {
+  /** Admin username (default: 'admin') */
+  username?: string;
+  /** Admin password (default: 'perf-toolkit') */
+  password?: string;
+  /** Secret key for session cookie (default: 'toolkit-secret') */
+  secret?: string;
+}
+
 export interface DashboardOptions {
   /** Enable dashboard (default: true) */
   enabled?: boolean;
   /** Dashboard mount path (default: '/__perf') */
   path?: string;
+  /** Authentication settings. If provided, user must login to see dashboard. */
+  auth?: DashboardAuthOptions;
+}
+
+export interface RateLimitOptions {
+  /** Enable rate limiting (default: false) */
+  enabled?: boolean;
+  /** Time window in milliseconds (default: 60000 - 1 minute) */
+  windowMs?: number;
+  /** Maximum number of requests per windowMs (default: 100) */
+  max?: number;
+  /** Response status code (default: 429) */
+  statusCode?: number;
+  /** Response message string or object */
+  message?: string | object;
+  /** URL patterns to exclude from rate limiting (e.g. ['/__perf*']) */
+  exclude?: (string | RegExp)[];
 }
 
 export interface ToolkitOptions {
@@ -72,6 +104,8 @@ export interface ToolkitOptions {
   queryHelper?: boolean | QueryHelperOptions;
   /** Performance dashboard */
   dashboard?: boolean | DashboardOptions;
+  /** Rate limiting */
+  rateLimit?: boolean | RateLimitOptions;
   /** Max log entries to keep in memory (default: 1000) */
   maxLogs?: number;
 }
@@ -81,22 +115,71 @@ export interface ToolkitOptions {
 export interface LogEntry {
   method: string;
   path: string;
+  routePattern?: string;
   statusCode: number;
   responseTime: number;
   timestamp: number;
+  bytesSent: number;
   slow: boolean;
   cached: boolean;
   queryCount?: number;
+  highQueries?: boolean;
   contentLength?: number;
   userAgent?: string;
   ip?: string;
 }
 
+export interface BlockedEvent {
+  ip: string;
+  path: string;
+  timestamp: number;
+  method: string;
+}
+
 export interface RouteStats {
   count: number;
   totalTime: number;
   slowCount: number;
+  highQueryCount: number;
+  rateLimitHits: number;
   avgTime: number;
+  totalBytes: number;
+  avgSize: number;
+}
+
+export interface Insight {
+  type: "info" | "warning" | "error";
+  title: string;
+  message: string;
+  action?: string;
+}
+
+export interface MetricSnapshot {
+  uptime: number;
+  totalRequests: number;
+  avgResponseTime: number;
+  slowRequests: number;
+  highQueryRequests: number;
+  rateLimitHits: number;
+  cacheHits: number;
+  cacheMisses: number;
+  cacheHitRate: number;
+  cacheSize: number;
+  totalBytesSent: number;
+  avgResponseSize: number;
+  insights: Insight[];
+  eventLoopLag: number;
+  memoryUsage: {
+    rss: number;
+    heapTotal: number;
+    heapUsed: number;
+    heapLimit: number; // Added v8 heap limit
+    external: number;
+  };
+  statusCodes: Record<number, number>;
+  routes: Record<string, RouteStats>;
+  recentLogs: LogEntry[];
+  blockedEvents: BlockedEvent[];
 }
 
 export interface Metrics {
@@ -104,13 +187,27 @@ export interface Metrics {
   totalRequests: number;
   avgResponseTime: number;
   slowRequests: number;
+  highQueryRequests: number;
+  rateLimitHits: number;
   cacheHits: number;
   cacheMisses: number;
   cacheHitRate: number;
   cacheSize: number;
+  totalBytesSent: number;
+  avgResponseSize: number;
+  insights: Insight[];
+  eventLoopLag: number;
+  memoryUsage: {
+    rss: number;
+    heapTotal: number;
+    heapUsed: number;
+    heapLimit: number; // Added v8 heap limit
+    external: number;
+  };
   statusCodes: Record<number, number>;
   routes: Record<string, RouteStats>;
   recentLogs: LogEntry[];
+  blockedEvents: BlockedEvent[];
 }
 
 export interface CacheEntry {
@@ -148,6 +245,7 @@ declare global {
       perfToolkit?: {
         startTime: number;
         queryCount: number;
+        highQueries?: boolean;
         trackQuery: (label?: string) => void;
       };
     }

package/tests/analyzer.test.ts

@@ -0,0 +1,108 @@
+import { analyzeMetrics } from "../src/analyzer";
+import { Metrics } from "../src/types";
+
+describe("Smart Insights Engine", () => {
+  const mockMetrics: Metrics = {
+    uptime: 1000,
+    totalRequests: 10,
+    avgResponseTime: 100,
+    slowRequests: 0,
+    highQueryRequests: 0,
+    rateLimitHits: 0,
+    cacheHits: 0,
+    cacheMisses: 10,
+    cacheHitRate: 0,
+    cacheSize: 0,
+    totalBytesSent: 1000,
+    avgResponseSize: 100,
+    insights: [],
+    eventLoopLag: 10,
+    memoryUsage: {
+      rss: 100,
+      heapTotal: 200,
+      heapUsed: 50,
+      external: 10,
+    },
+    statusCodes: { 200: 10 },
+    routes: {},
+    recentLogs: [],
+    blockedEvents: [],
+  };
+
+  it("should suggest caching for slow routes", () => {
+    const metrics: Metrics = {
+      ...mockMetrics,
+      routes: {
+        "GET /api/slow": {
+          count: 10,
+          totalTime: 8000,
+          avgTime: 800,
+          slowCount: 10,
+          highQueryCount: 0,
+          rateLimitHits: 0,
+          totalBytes: 1000,
+          avgSize: 100,
+        },
+      },
+    };
+
+    const insights = analyzeMetrics(metrics);
+    expect(insights.some((i) => i.title.includes("Caching Opportunity"))).toBe(
+      true
+    );
+  });
+
+  it("should warn about N+1 queries", () => {
+    const metrics: Metrics = {
+      ...mockMetrics,
+      routes: {
+        "GET /api/n-plus-one": {
+          count: 10,
+          totalTime: 1000,
+          avgTime: 100,
+          slowCount: 0,
+          highQueryCount: 8, // 80%
+          rateLimitHits: 0,
+          totalBytes: 1000,
+          avgSize: 100,
+        },
+      },
+    };
+
+    const insights = analyzeMetrics(metrics);
+    expect(insights.some((i) => i.title.includes("N+1 Query"))).toBe(true);
+  });
+
+  it("should warn about heavy payloads", () => {
+    const metrics: Metrics = {
+      ...mockMetrics,
+      routes: {
+        "GET /api/heavy": {
+          count: 10,
+          totalTime: 1000,
+          avgTime: 100,
+          slowCount: 0,
+          highQueryCount: 0,
+          rateLimitHits: 0,
+          totalBytes: 20 * 1024 * 1024,
+          avgSize: 2 * 1024 * 1024, // 2MB
+        },
+      },
+    };
+
+    const insights = analyzeMetrics(metrics);
+    expect(insights.some((i) => i.title.includes("Heavy Payload"))).toBe(true);
+  });
+
+  it("should warn about event loop lag", () => {
+    const metrics: Metrics = {
+      ...mockMetrics,
+      eventLoopLag: 150,
+    };
+
+    const insights = analyzeMetrics(metrics);
+    expect(insights.some((i) => i.title.includes("Event Loop Lagging"))).toBe(
+      true
+    );
+  });
+});

package/tests/auth.test.ts

@@ -0,0 +1,79 @@
+import request from "supertest";
+import express from "express";
+import { performanceToolkit } from "../src/index";
+
+describe("Dashboard Authentication", () => {
+  it("should require login if auth is enabled", async () => {
+    const app = express();
+    const toolkit = performanceToolkit({
+      dashboard: {
+        enabled: true,
+        auth: {
+          username: "testuser",
+          password: "testpassword",
+        },
+      },
+    });
+
+    app.use(toolkit.middleware);
+    app.use('/__perf', toolkit.dashboardRouter);
+
+    // Should return 401 for protected data
+    const resp = await request(app).get("/__perf/api/metrics");
+    expect(resp.status).toBe(401);
+
+    // Try login
+    const loginResp = await request(app)
+      .post("/__perf/api/login")
+      .send({ username: "testuser", password: "testpassword" });
+
+    expect(loginResp.status).toBe(200);
+    expect(loginResp.headers["set-cookie"]).toBeDefined();
+
+    // With cookie, should work
+    const cookie = loginResp.headers["set-cookie"];
+    const metricsResp = await request(app)
+      .get("/__perf/api/metrics")
+      .set("Cookie", cookie);
+
+    expect(metricsResp.status).toBe(200);
+  });
+
+  it("should handle invalid credentials", async () => {
+    const app = express();
+    const toolkit = performanceToolkit({
+      dashboard: {
+        enabled: true,
+        auth: {
+          username: "admin",
+          password: "password",
+        },
+      },
+    });
+
+    app.use(toolkit.middleware);
+    app.use('/__perf', toolkit.dashboardRouter);
+
+    const loginResp = await request(app)
+      .post("/__perf/api/login")
+      .send({ username: "admin", password: "wrong" });
+
+    expect(loginResp.status).toBe(401);
+  });
+
+  it("should allow access if auth is disabled", async () => {
+    const app = express();
+    const toolkit = performanceToolkit({
+      dashboard: {
+        enabled: true,
+        auth: undefined,
+      },
+    });
+
+    app.use(toolkit.middleware);
+    app.use("/__perf", toolkit.dashboardRouter);
+
+    const resp = await request(app).get("/__perf/api/metrics");
+    expect(resp.status).toBe(200);
+  });
+});