limitforge 0.0.0-stage → 8.0.0

package/index.d.ts

@@ -0,0 +1,192 @@
+import type { Request, Response, NextFunction, RequestHandler } from 'express';
+
+export type RateLimiterAlgorithm = 'fixed-window' | 'sliding-window' | 'token-bucket';
+export type FailStrategy = 'fail-open' | 'fail-closed';
+
+export interface StoreConsumeParams {
+  key: string;
+  limit?: number;
+  windowMs?: number;
+  algorithm?: RateLimiterAlgorithm;
+  capacity?: number;
+  refillRate?: number;
+  refillIntervalMs?: number;
+  cost?: number;
+  now?: number;
+}
+
+export interface StoreConsumeResult {
+  allowed: boolean;
+  count?: number;
+  remaining?: number;
+  reset?: number;
+  retryAfter?: number;
+  degraded?: boolean;
+  circuitState?: string;
+}
+
+export interface IRateLimitStore {
+  consume(params: StoreConsumeParams): Promise<StoreConsumeResult> | StoreConsumeResult;
+  resetKey?(key: string): Promise<void> | void;
+  destroy?(): void;
+}
+
+export interface RateLimiterOptions {
+  limit?: number | ((req: Request) => number | Promise<number>);
+  windowMs?: number | ((req: Request) => number | Promise<number>);
+  store?: IRateLimitStore;
+  fallbackStore?: boolean | IRateLimitStore;
+  algorithm?: RateLimiterAlgorithm;
+  capacity?: number | ((req: Request) => number | Promise<number>);
+  refillRate?: number | ((req: Request) => number | Promise<number>);
+  refillIntervalMs?: number;
+  cost?: number | ((req: Request) => number | Promise<number>);
+  keyGenerator?: (req: Request) => string | Promise<string>;
+  hashClientIdentifier?: boolean | ((identifier: string) => string);
+  timeoutMs?: number;
+  failureThreshold?: number;
+  resetTimeoutMs?: number;
+  failStrategy?: FailStrategy;
+  metrics?: boolean | MetricsCollector;
+  openTelemetry?: boolean | { tracer?: any; getSpan?: (req: Request) => any };
+  onStoreError?: (err: Error, req: Request, res: Response, next: NextFunction) => void;
+  statusCode?: number;
+  message?: string | object | ((req: Request, res: Response) => any);
+  skip?: (req: Request) => boolean | Promise<boolean>;
+  skipFailedRequests?: boolean;
+  skipSuccessfulRequests?: boolean;
+}
+
+export declare function rateLimiter(options?: RateLimiterOptions): RequestHandler;
+export default rateLimiter;
+
+export declare class MemoryStore implements IRateLimitStore {
+  constructor(options?: { cleanupIntervalMs?: number });
+  consume(params: StoreConsumeParams): StoreConsumeResult;
+  resetKey(key: string): void;
+  destroy(): void;
+}
+
+export interface RedisClientLike {
+  eval(script: string, options: { keys: string[]; arguments: (string | number)[] }): Promise<any>;
+  sendCommand?(args: string[]): Promise<any>;
+}
+
+export declare class RedisStore implements IRateLimitStore {
+  constructor(options: { client: RedisClientLike; prefix?: string });
+  consume(params: StoreConsumeParams): Promise<StoreConsumeResult>;
+  resetKey(key: string): Promise<void>;
+}
+
+export interface CircuitBreakerOptions {
+  failureThreshold?: number;
+  resetTimeoutMs?: number;
+  name?: string;
+  breakerId?: string;
+  onStateChange?: (oldState: string, newState: string) => void;
+}
+
+export declare class CircuitBreaker {
+  constructor(options?: CircuitBreakerOptions);
+  execute<T>(action: () => Promise<T>): Promise<T>;
+  getState(): 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+  trip(): void;
+  reset(): void;
+}
+
+export declare class ResilientStore implements IRateLimitStore {
+  primaryStore: IRateLimitStore;
+  fallbackStore: IRateLimitStore;
+  breaker: CircuitBreaker;
+  constructor(options: {
+    primaryStore: IRateLimitStore;
+    fallbackStore?: IRateLimitStore;
+    breaker?: CircuitBreaker;
+    timeoutMs?: number;
+    failureThreshold?: number;
+    resetTimeoutMs?: number;
+    breakerId?: string;
+  });
+  consume(params: StoreConsumeParams): Promise<StoreConsumeResult>;
+  resetKey(key: string): Promise<void>;
+  getStats(): {
+    circuitBreaker: { state: string; failureCount: number };
+    primaryStore: string;
+    fallbackStore: string;
+  };
+}
+
+export declare class MetricsCollector {
+  constructor(options?: { maxSeries?: number; metricMap?: Map<string, any> });
+  recordRequest(params: {
+    outcome: 'allowed' | 'blocked';
+    normalized_route?: string;
+    method?: string;
+    status_code?: number;
+    store?: string;
+    degraded?: boolean;
+  }): void;
+  recordStoreDuration(params: {
+    store: string;
+    operation: string;
+    outcome: 'success' | 'failure' | 'timeout';
+    duration_ms: number;
+  }): void;
+  recordCircuitBreakerState(params: {
+    state: 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+    breaker?: string;
+  }): void;
+  getSnapshot(): any;
+  reset(): void;
+}
+
+export declare const defaultMetricsCollector: MetricsCollector;
+
+export declare class OpenTelemetryBridge {
+  constructor(options?: { tracer?: any; getSpan?: (req: Request) => any });
+  startSpan(name?: string, options?: any): any;
+  resolveSpan(req: Request): any;
+  recordEvaluation(params: {
+    req: Request;
+    result: StoreConsumeResult;
+    algorithm?: string;
+    normalizedRoute?: string;
+    store?: string;
+  }): void;
+  recordStoreError(params: { req: Request; storeError: Error; store?: string }): void;
+}
+
+export declare class StoreTimeoutError extends Error {
+  code: string;
+  timeoutMs: number;
+  constructor(timeoutMs: number, operation?: string);
+}
+
+export declare class CircuitBreakerOpenError extends Error {
+  code: string;
+  retryAfter: number;
+  constructor(message?: string, retryAfter?: number);
+}
+
+export declare const MAX_IDENTIFIER_LENGTH: number;
+
+export declare function buildRateLimitKey(params: {
+  method?: string;
+  route?: string;
+  clientIdentifier?: string;
+  algorithm?: string;
+  prefix?: string;
+  hashClientIdentifier?: boolean | ((id: string) => string);
+}): string;
+
+export declare function normalizeRoute(path: string): string;
+export declare function sanitizePath(path: string): string;
+export declare function createPrometheusExporter(collector?: MetricsCollector): RequestHandler;
+export declare function formatPrometheusMetrics(snapshot: any): string;
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, operation?: string): Promise<T>;
+export declare function runBenchmark(options?: any): Promise<any>;
+export declare function calculatePercentiles(latencies: bigint[]): any;
+
+export declare const METRIC_NAMES: Record<string, string>;
+export declare const METRIC_TYPE: Record<string, string>;
+export declare const CIRCUIT_STATE: Record<string, string>;

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "limitforge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "8.0.0",
+  "description": "Production-ready distributed rate limiting and resilience middleware for Express.js supporting Redis Lua, Token Bucket, Sliding Window, Circuit Breakers, and Prometheus metrics",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "./src/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "node --watch examples/express-demo/server.js",
+    "start": "node examples/express-demo/server.js",
+    "demo:multi": "node examples/express-demo/multi-instance.js",
+    "demo:sliding": "node examples/express-demo/sliding-demo.js",
+    "demo:saas": "node examples/express-demo/saas-demo.js",
+    "demo:burst": "node examples/express-demo/burst-demo.js",
+    "demo:resilience": "node examples/express-demo/resilience-demo.js",
+    "demo:observability": "node examples/express-demo/observability-demo.js",
+    "demo:stack": "node examples/observability-stack/server.js",
+    "demo:simulate": "node examples/observability-stack/simulate-traffic.js",
+    "benchmark": "node scripts/benchmark.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "rate-limiter",
+    "express",
+    "middleware",
+    "fixed-window",
+    "sliding-window",
+    "rolling-window",
+    "token-bucket",
+    "multi-tenant",
+    "dynamic-policy",
+    "circuit-breaker",
+    "resilience",
+    "prometheus",
+    "opentelemetry",
+    "in-memory",
+    "redis",
+    "distributed",
+    "lua",
+    "zset",
+    "limitforge"
+  ],
+  "author": "Anivesh Sikarwar <aniveshsikarwar@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Anivesh91/RateShield.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Anivesh91/RateShield/issues"
+  },
+  "homepage": "https://github.com/Anivesh91/RateShield#readme",
+  "peerDependencies": {
+    "express": "^4.21.2 || ^5.0.0",
+    "redis": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "redis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "redis": "^6.2.1",
+    "supertest": "^7.0.0"
+  }
+}

package/src/benchmark/benchmarkRunner.js

@@ -0,0 +1,235 @@
+import { rateLimiter } from '../limiter/rateLimiter.js';
+import { MemoryStore } from '../stores/memoryStore.js';
+import { MetricsCollector } from '../telemetry/metricsCollector.js';
+import { OpenTelemetryBridge } from '../telemetry/openTelemetryBridge.js';
+
+export function calculatePercentiles(samplesNs) {
+  if (!Array.isArray(samplesNs) || samplesNs.length === 0) {
+    return {
+      count: 0,
+      minUs: 0,
+      maxUs: 0,
+      meanUs: 0,
+      p50Us: 0,
+      p90Us: 0,
+      p95Us: 0,
+      p99Us: 0,
+      minMs: 0,
+      maxMs: 0,
+      meanMs: 0,
+      p50Ms: 0,
+      p90Ms: 0,
+      p95Ms: 0,
+      p99Ms: 0
+    };
+  }
+
+  const samplesUs = samplesNs
+    .map((ns) => (typeof ns === 'bigint' ? Number(ns) / 1000 : Number(ns) / 1000))
+    .sort((a, b) => a - b);
+
+  const count = samplesUs.length;
+  const sumUs = samplesUs.reduce((acc, val) => acc + val, 0);
+  const meanUs = sumUs / count;
+
+  const getPercentile = (p) => {
+    const rank = (p / 100) * (count - 1);
+    const lowerIndex = Math.floor(rank);
+    const upperIndex = Math.ceil(rank);
+    const fraction = rank - lowerIndex;
+    return samplesUs[lowerIndex] + (samplesUs[upperIndex] - samplesUs[lowerIndex]) * fraction;
+  };
+
+  const minUs = samplesUs[0];
+  const maxUs = samplesUs[count - 1];
+  const p50Us = getPercentile(50);
+  const p90Us = getPercentile(90);
+  const p95Us = getPercentile(95);
+  const p99Us = getPercentile(99);
+
+  return {
+    count,
+    minUs: Number(minUs.toFixed(2)),
+    maxUs: Number(maxUs.toFixed(2)),
+    meanUs: Number(meanUs.toFixed(2)),
+    p50Us: Number(p50Us.toFixed(2)),
+    p90Us: Number(p90Us.toFixed(2)),
+    p95Us: Number(p95Us.toFixed(2)),
+    p99Us: Number(p99Us.toFixed(2)),
+    minMs: Number((minUs / 1000).toFixed(4)),
+    maxMs: Number((maxUs / 1000).toFixed(4)),
+    meanMs: Number((meanUs / 1000).toFixed(4)),
+    p50Ms: Number((p50Us / 1000).toFixed(4)),
+    p90Ms: Number((p90Us / 1000).toFixed(4)),
+    p95Ms: Number((p95Us / 1000).toFixed(4)),
+    p99Ms: Number((p99Us / 1000).toFixed(4))
+  };
+}
+
+function createMockHttpPair(ip = '192.168.1.1', path = '/api/resource', method = 'GET') {
+  const req = {
+    method,
+    originalUrl: path,
+    path,
+    ip,
+    headers: { host: 'localhost:3000' },
+    socket: { remoteAddress: ip }
+  };
+
+  const headers = {};
+  const res = {
+    statusCode: 200,
+    headersSent: false,
+    setHeader(name, value) {
+      headers[name.toLowerCase()] = String(value);
+    },
+    getHeader(name) {
+      return headers[name.toLowerCase()];
+    },
+    status(code) {
+      this.statusCode = code;
+      return this;
+    },
+    json(body) {
+      this.body = body;
+      return this;
+    },
+    end() {
+      return this;
+    }
+  };
+
+  return { req, res };
+}
+
+export async function runBenchmark(options = {}) {
+  const iterations = options.iterations || 10000;
+  const warmup = options.warmup ?? 1000;
+  const nextStub = () => {};
+
+  const scenarios = [
+    {
+      name: '1. No-op Middleware (next() only)',
+      middleware: (req, res, next) => next()
+    },
+    {
+      name: '2. Fixed Window (Memory Store)',
+      middleware: rateLimiter({
+        limit: 1000000,
+        windowMs: 60000,
+        algorithm: 'fixed-window',
+        store: new MemoryStore()
+      })
+    },
+    {
+      name: '3. Sliding Window (Memory Store)',
+      middleware: rateLimiter({
+        limit: 1000000,
+        windowMs: 60000,
+        algorithm: 'sliding-window',
+        store: new MemoryStore()
+      })
+    },
+    {
+      name: '4. Token Bucket (Memory Store)',
+      middleware: rateLimiter({
+        capacity: 1000000,
+        refillRate: 100000,
+        algorithm: 'token-bucket',
+        store: new MemoryStore()
+      })
+    },
+    {
+      name: '5. Sliding Window + Metrics (Telemetry Enabled)',
+      middleware: rateLimiter({
+        limit: 1000000,
+        windowMs: 60000,
+        algorithm: 'sliding-window',
+        store: new MemoryStore(),
+        metricsCollector: new MetricsCollector()
+      })
+    },
+    {
+      name: '6. Sliding Window + Metrics + OpenTelemetry Bridge',
+      middleware: rateLimiter({
+        limit: 1000000,
+        windowMs: 60000,
+        algorithm: 'sliding-window',
+        store: new MemoryStore(),
+        metricsCollector: new MetricsCollector(),
+        openTelemetry: new OpenTelemetryBridge({
+          getSpan: (req) => req.span
+        })
+      })
+    }
+  ];
+
+  const results = [];
+
+  for (const scenario of scenarios) {
+    const mockSpan = {
+      attributes: {},
+      events: [],
+      setAttribute(k, v) { this.attributes[k] = v; },
+      addEvent(name, attrs) { this.events.push({ name, attrs }); }
+    };
+
+    // Warmup phase
+    for (let i = 0; i < warmup; i++) {
+      const { req, res } = createMockHttpPair(`10.0.0.${(i % 50) + 1}`, '/api/benchmark');
+      req.span = mockSpan;
+      await scenario.middleware(req, res, nextStub);
+    }
+
+    // Measurement phase
+    const samplesNs = [];
+    const totalStart = process.hrtime.bigint();
+
+    for (let i = 0; i < iterations; i++) {
+      const { req, res } = createMockHttpPair(`10.0.0.${(i % 100) + 1}`, '/api/benchmark');
+      req.span = mockSpan;
+
+      const start = process.hrtime.bigint();
+      await scenario.middleware(req, res, nextStub);
+      const durationNs = process.hrtime.bigint() - start;
+
+      samplesNs.push(durationNs);
+    }
+
+    const totalElapsedNs = process.hrtime.bigint() - totalStart;
+    const totalElapsedSec = Number(totalElapsedNs) / 1e9;
+    const opsPerSec = Math.round(iterations / totalElapsedSec);
+    const stats = calculatePercentiles(samplesNs);
+
+    results.push({
+      scenario: scenario.name,
+      iterations,
+      opsPerSec,
+      stats
+    });
+  }
+
+  const baselineStats = results[0].stats;
+  const enrichedResults = results.map((r, idx) => {
+    if (idx === 0) {
+      return { ...r, overheadP50Us: 0, overheadP99Us: 0 };
+    }
+    const overheadP50Us = Number((r.stats.p50Us - baselineStats.p50Us).toFixed(2));
+    const overheadP99Us = Number((r.stats.p99Us - baselineStats.p99Us).toFixed(2));
+    return {
+      ...r,
+      overheadP50Us: Math.max(0, overheadP50Us),
+      overheadP99Us: Math.max(0, overheadP99Us)
+    };
+  });
+
+  return {
+    timestamp: new Date().toISOString(),
+    nodeVersion: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    iterations,
+    warmup,
+    scenarios: enrichedResults
+  };
+}

package/src/index.js

@@ -0,0 +1,30 @@
+export { default, rateLimiter } from './limiter/rateLimiter.js';
+export { MemoryStore } from './stores/memoryStore.js';
+export { RedisStore } from './stores/redisStore.js';
+export { ResilientStore } from './stores/resilientStore.js';
+
+export { buildRateLimitKey, MAX_IDENTIFIER_LENGTH } from './utils/keyBuilder.js';
+export { normalizeRoute, sanitizePath } from './utils/routeNormalizer.js';
+
+export { withTimeout } from './resilience/timeoutGuard.js';
+export { CircuitBreaker, CIRCUIT_STATE } from './resilience/circuitBreaker.js';
+export { StoreTimeoutError, CircuitBreakerOpenError } from './resilience/errors.js';
+
+export { MetricsCollector, defaultMetricsCollector } from './telemetry/metricsCollector.js';
+export { OpenTelemetryBridge } from './telemetry/openTelemetryBridge.js';
+export {
+  createPrometheusExporter,
+  formatPrometheusMetrics,
+  escapeLabelValue,
+  escapeHelpString,
+  formatLabels
+} from './telemetry/prometheusExporter.js';
+export {
+  METRIC_NAMES,
+  METRIC_TYPE,
+  METRIC_METADATA,
+  CIRCUIT_STATE_GAUGE_VALUES,
+  DEFAULT_STORE_DURATION_BUCKETS
+} from './telemetry/telemetryEvents.js';
+
+export { runBenchmark, calculatePercentiles } from './benchmark/benchmarkRunner.js';