nextlimiter 1.0.5 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextlimiter",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Production-ready rate limiting for Node.js — sliding window, token bucket, SaaS plans, smart limiting, and built-in analytics.",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/src/analytics/prometheus.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * Pure Node.js Prometheus Exposition Formatter
+ * Zero dependencies. Converts limiter stats to valid Prometheus text format.
+ */
+
+class PrometheusFormatter {
+  constructor(limiter) {
+    this.limiter = limiter;
+  }
+
+  contentType() {
+    return 'text/plain; version=0.0.4; charset=utf-8';
+  }
+
+  /**
+   * Escape label values according to Prometheus rules:
+   * \ -> \\
+   * " -> \"
+   * \n -> \n
+   */
+  _escapeLabel(str) {
+    return String(str)
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      .replace(/\n/g, '\\n');
+  }
+
+  /**
+   * Format a single metric block (help, type, and samples).
+   */
+  _metricBlock(name, help, type, samples) {
+    if (!samples || samples.length === 0) return '';
+    let block = `# HELP ${name} ${help}\n`;
+    block += `# TYPE ${name} ${type}\n`;
+
+    for (const sample of samples) {
+      const labelEntries = Object.entries(sample.labels || {});
+      if (labelEntries.length > 0) {
+        const labelStrs = labelEntries.map(([k, v]) => `${k}="${this._escapeLabel(v)}"`);
+        block += `${name}{${labelStrs.join(',')}} ${sample.value}\n`;
+      } else {
+        block += `${name} ${sample.value}\n`;
+      }
+    }
+    return block + '\n';
+  }
+
+  format() {
+    const stats = this.limiter.getStats();
+    let output = '';
+
+    // 1. Total requests (Counter)
+    output += this._metricBlock(
+      'nextlimiter_requests_total',
+      'Total requests processed by nextlimiter',
+      'counter',
+      [
+        { labels: { status: 'allowed' }, value: stats.allowedRequests },
+        { labels: { status: 'blocked' }, value: stats.blockedRequests }
+      ]
+    );
+
+    // 2. Block rate (Gauge)
+    output += this._metricBlock(
+      'nextlimiter_block_rate',
+      'Ratio of blocked to total requests (0.0 to 1.0)',
+      'gauge',
+      [{ labels: {}, value: isNaN(stats.blockRate) ? 0 : stats.blockRate }]
+    );
+
+    // 3. Top blocked IPs (Gauge)
+    const topBlockedSamples = (stats.topBlocked || []).slice(0, 10).map((item) => {
+      // Clean up IP label
+      let ip = item.key.replace(/^nextlimiter:(ip:)?/, '');
+      return { labels: { ip }, value: item.count };
+    });
+    if (topBlockedSamples.length > 0) {
+      output += this._metricBlock(
+        'nextlimiter_top_blocked_ip',
+        'Block count per offending IP',
+        'gauge',
+        topBlockedSamples
+      );
+    }
+
+    // 4. Top keys by volume (Gauge)
+    const topKeysSamples = (stats.topKeys || []).slice(0, 10).map((item) => {
+      return { labels: { key: item.key }, value: item.count };
+    });
+    if (topKeysSamples.length > 0) {
+      output += this._metricBlock(
+        'nextlimiter_top_keys_total',
+        'Total request count per key',
+        'gauge',
+        topKeysSamples
+      );
+    }
+
+    // 5. Uptime seconds (Gauge)
+    output += this._metricBlock(
+      'nextlimiter_uptime_seconds',
+      'Seconds since limiter was created',
+      'gauge',
+      [{ labels: {}, value: stats.uptimeMs / 1000 }]
+    );
+
+    // 6. Info (Gauge = 1)
+    const version = '1.0.5'; // Current pkg version
+    output += this._metricBlock(
+      'nextlimiter_info',
+      'Static info about the limiter instance',
+      'gauge',
+      [{ labels: { strategy: stats.config.strategy, version }, value: 1 }]
+    );
+
+    return output;
+  }
+}
+
+module.exports = { PrometheusFormatter };

package/src/core/accessControl.js

@@ -21,14 +21,16 @@ const { ipMatchesList } = require('../utils/cidr');
  * checkAccess('1.2.3.4', {})
  * // → { action: 'allow', reason: 'proceed' }
  */
-function checkAccess(ip, config) {
+function checkAccess(ip, config, emitter) {
   // Blacklist wins — always checked first regardless of whitelist
   if (config.blacklist && ipMatchesList(ip, config.blacklist)) {
+    if (emitter) emitter.emit('blacklisted', ip);
     return { action: 'block', reason: 'blacklisted' };
   }
 
   // Whitelist — bypass all rate limiting
   if (config.whitelist && ipMatchesList(ip, config.whitelist)) {
+    if (emitter) emitter.emit('whitelisted', ip);
     return { action: 'skip', reason: 'whitelisted' };
   }
 

package/src/core/config.js

@@ -87,6 +87,7 @@ const DEFAULT_CONFIG = {
   keyGenerator: null,       // (req) => string — custom key fn
   whitelist:     null,       // string[] — IPs/CIDRs that bypass rate limiting
   blacklist:     null,       // string[] — IPs/CIDRs that always get 403
+  statsInterval: undefined,  // ms interval to emit 'stats' event
 };
 
 /**
@@ -147,6 +148,17 @@ function resolveConfig(userOptions = {}) {
     base[listName] = valid.length > 0 ? valid : null;
   }
 
+  // Validate statsInterval
+  if (base.statsInterval !== undefined) {
+    if (typeof base.statsInterval !== 'number' || base.statsInterval <= 0) {
+      console.warn('[NextLimiter] config.statsInterval must be a positive number. Disabling.');
+      base.statsInterval = undefined;
+    } else if (base.statsInterval < 1000) {
+      console.warn('[NextLimiter] config.statsInterval must be at least 1000ms. Clamping to 1000ms.');
+      base.statsInterval = 1000;
+    }
+  }
+
   return base;
 }
 

package/src/core/limiter.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const EventEmitter                = require('events');
 const { resolveConfig }           = require('./config');
 const { MemoryStore }             = require('../store/memoryStore');
 const { fixedWindowCheck }        = require('../strategies/fixedWindow');
@@ -12,6 +13,7 @@ const { AnalyticsTracker }        = require('../analytics/tracker');
 const { SmartDetector }           = require('../smart/detector');
 const { setHeaders }              = require('../middleware/headers');
 const { checkAccess }             = require('./accessControl');
+const { PrometheusFormatter }     = require('../analytics/prometheus');
 
 const STRATEGY_MAP = {
   'fixed-window':   fixedWindowCheck,
@@ -32,11 +34,15 @@ const STRATEGY_MAP = {
  * // Programmatic check
  * const result = await limiter.check('user:42');
  */
-class Limiter {
+class Limiter extends EventEmitter {
   /**
    * @param {object} options - NextLimiter configuration (see config.js for defaults)
    */
   constructor(options = {}) {
+    super();
+    this.setMaxListeners(50);
+    this.on('error', () => {}); // default no-op handler prevents crashes
+
     this._config = resolveConfig(options);
 
     // Storage backend
@@ -63,7 +69,14 @@ class Limiter {
     this._analytics = new AnalyticsTracker();
 
     // Smart detector
-    this._smart = this._config.smart ? new SmartDetector(this._config) : null;
+    this._smart = this._config.smart ? new SmartDetector(this._config, this) : null;
+
+    // Stats event interval
+    if (this._config.statsInterval) {
+      this._statsTimer = setInterval(() => {
+        this.emit('stats', this.getStats());
+      }, this._config.statsInterval).unref();
+    }
   }
 
   // ── Public API ─────────────────────────────────────────────────────────────
@@ -86,7 +99,7 @@ class Limiter {
 
         // ── Access control (whitelist / blacklist) ───────────────────────────
         const clientIp = extractIp(req);
-        const access   = checkAccess(clientIp, this._config);
+        const access   = checkAccess(clientIp, this._config, this);
 
         if (access.action === 'block') {
           return res.status(403).json({
@@ -105,13 +118,17 @@ class Limiter {
         const key    = `${this._config.keyPrefix}${rawKey}`;
 
         const result = await this._runCheck(key);
+        
+        // Emit events
+        if (result.allowed) this.emit('allowed', rawKey, result);
+        else this.emit('blocked', rawKey, result);
 
         // Record analytics
         this._analytics.record(key, result.allowed);
 
         // Set headers
         if (this._config.headers) {
-          setHeaders(res, result, !result.allowed);
+          setHeaders(res, result);
         }
 
         if (!result.allowed) {
@@ -139,13 +156,49 @@ class Limiter {
 
         next();
       } catch (err) {
+        this.emit('error', err);
         // Never let rate limiter errors take down the application
-        this._log.warn(`Error in rate limiter: ${err.message}. Failing open.`);
+        this._log.warn(`Middleware error: ${err.message}. Failing open.`);
         next();
       }
     };
   }
 
+  /**
+   * Express route handler for serving Prometheus metrics.
+   * Exposes getStats() data in plain text format (version=0.0.4).
+   *
+   * @example
+   * app.get('/metrics', limiter.metricsHandler());
+   */
+  metricsHandler() {
+    return (req, res) => {
+      try {
+        const formatter = new PrometheusFormatter(this);
+        res.set('Content-Type', formatter.contentType());
+        res.send(formatter.format());
+      } catch (err) {
+        res.status(500).type('text/plain').send(`Error generating metrics: ${err.message}`);
+      }
+    };
+  }
+
+  /**
+   * Global middleware that automatically intercepts GET /metrics requests
+   * and serves the Prometheus exposition format. Passes through all other routes.
+   *
+   * @example
+   * app.use(limiter.metricsMiddleware());
+   */
+  metricsMiddleware() {
+    return (req, res, next) => {
+      if (req.method === 'GET' && req.path === '/metrics') {
+        return this.metricsHandler()(req, res);
+      }
+      next();
+    };
+  }
+
   /**
    * Programmatic rate limit check — use outside of HTTP middleware context.
    *
@@ -160,7 +213,7 @@ class Limiter {
     // Apply access control if the key looks like a plain IP address
     const looksLikeIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(String(key).trim());
     if (looksLikeIp) {
-      const access = checkAccess(key, this._config);
+      const access = checkAccess(key, this._config, this);
       if (access.action === 'block') {
         return {
           allowed:      false,
@@ -193,9 +246,35 @@ class Limiter {
     const fullKey = `${this._config.keyPrefix}${key}`;
     const result  = await this._runCheck(fullKey);
     this._analytics.record(fullKey, result.allowed);
+
+    if (result.allowed) this.emit('allowed', key, result);
+    else this.emit('blocked', key, result);
+
     return result;
   }
 
+  /**
+   * Reset rate limit state for a key.
+   *
+   * @param {string} key
+   */
+  resetKey(key) {
+    const fullKey = `${this._config.keyPrefix}${key}`;
+    this._store.delete(fullKey);
+    this.emit('reset', key);
+  }
+
+  /**
+   * Cleanly dispose of stats cycles and store buffers.
+   */
+  destroy() {
+    if (this._statsTimer) clearInterval(this._statsTimer);
+    if (this._store && typeof this._store.destroy === 'function') {
+      this._store.destroy();
+    }
+    this.removeAllListeners();
+  }
+
   /**
    * Manually reset the rate limit for a specific key.
    * Useful after a user upgrades their plan, or for admin overrides.

package/src/index.js

@@ -5,6 +5,7 @@ const { PRESETS, DEFAULT_PLANS } = require('./core/config');
 const { MemoryStore } = require('./store/memoryStore');
 const { RedisStore }  = require('./store/redisStore');
 const { ipMatchesCidr, ipMatchesList } = require('./utils/cidr');
+const { PrometheusFormatter } = require('./analytics/prometheus');
 
 /**
  * Create a fully configured rate limiter instance.
@@ -107,6 +108,9 @@ module.exports = {
   ipMatchesCidr,
   ipMatchesList,
 
+  // Analytics export
+  PrometheusFormatter,
+
   // Constants
   PRESETS,
   DEFAULT_PLANS,

package/src/smart/detector.js

@@ -18,9 +18,12 @@
 class SmartDetector {
   /**
    * @param {object} config - Resolved NextLimiter config
+   * @param {import('events').EventEmitter} [emitter] - Optional event emitter
    */
-  constructor(config) {
+  constructor(config, emitter) {
     this._config = config;
+    this._emitter = emitter;
+    this._penalizedSet = new Set();
 
     // Map: key → { windowStart, count, penalized, penaltyExpires }
     /** @type {Map<string, object>} */
@@ -64,6 +67,17 @@ class SmartDetector {
       if (state.count > normalRatePerObsWindow * config.smartThreshold) {
         state.penalized      = true;
         state.penaltyExpires = now + config.smartCooldownMs;
+
+        if (this._emitter && !this._penalizedSet.has(key)) {
+          this._penalizedSet.add(key);
+          this._emitter.emit('penalized', key, {
+            key,
+            normalLimit: config.max,
+            reducedLimit: Math.floor(config.max * config.smartPenaltyFactor),
+            cooldownMs: config.smartCooldownMs,
+            detectedAt: new Date().toISOString()
+          });
+        }
       }
 
       // Reset observation window
@@ -84,6 +98,7 @@ class SmartDetector {
     // Penalty expired — lift it
     if (state.penalized && now >= state.penaltyExpires) {
       state.penalized = false;
+      this._penalizedSet.delete(key);
     }
 
     return { penalized: false, effectiveMax: config.max };
@@ -111,6 +126,7 @@ class SmartDetector {
   /** Clear all tracking state. */
   reset() {
     this._state.clear();
+    this._penalizedSet.clear();
   }
 }
 

package/types/index.d.ts

@@ -1,7 +1,7 @@
 // NextLimiter — TypeScript type definitions
 // Compatible with @types/node and @types/express
-
 import { Request, Response, NextFunction } from 'express';
+import { EventEmitter } from 'events';
 
 // ── Store interface ──────────────────────────────────────────────────────────
 
@@ -102,6 +102,9 @@ export interface LimiterOptions {
 
   /** Array of IPs or CIDR ranges to block immediately (403) */
   blacklist?: string[];
+
+  /** ms interval to emit 'stats' event. undefined = disabled. */
+  statsInterval?: number;
 }
 
 // ── Rate limit result ────────────────────────────────────────────────────────
@@ -139,6 +142,20 @@ export interface RateLimitResult {
 
 // ── Analytics ────────────────────────────────────────────────────────────────
 
+export interface PenaltyInfo {
+  key: string;
+  normalLimit: number;
+  reducedLimit: number;
+  cooldownMs: number;
+  detectedAt: string;
+}
+
+export declare class PrometheusFormatter {
+  constructor(limiter: Limiter);
+  format(): string;
+  contentType(): string;
+}
+
 export interface KeyCount {
   key: string;
   count: number;
@@ -175,18 +192,36 @@ export interface LimiterStats {
 
 // ── Limiter class ────────────────────────────────────────────────────────────
 
-export declare class Limiter {
+export declare class Limiter extends EventEmitter {
   constructor(options?: LimiterOptions);
 
   /** Returns an Express-compatible middleware function */
   middleware(): (req: Request, res: Response, next: NextFunction) => Promise<void>;
 
+  /**
+   * Express route handler for serving Prometheus metrics.
+   * Exposes getStats() data in plain text format (version=0.0.4).
+   */
+  metricsHandler(): (req: any, res: any) => void;
+
+  /**
+   * Global middleware that automatically intercepts GET /metrics requests.
+   * Passes through all other routes.
+   */
+  metricsMiddleware(): (req: any, res: any, next: any) => void;
+
   /** Programmatic rate limit check by key string */
   check(key: string): Promise<RateLimitResult>;
 
   /** Reset rate limit state for a specific key */
   reset(key: string): Promise<void>;
 
+  /** Reset rate limit state and clear from store immediately */
+  resetKey(key: string): void;
+
+  /** Clean up stores and timers */
+  destroy(): void;
+
   /** Get analytics snapshot */
   getStats(): LimiterStats;
 
@@ -195,6 +230,25 @@ export declare class Limiter {
 
   /** Read-only resolved configuration */
   readonly config: Readonly<Required<LimiterOptions>>;
+
+  // Typed EventEmitter overloads
+  on(event: 'blocked',     listener: (key: string, result: RateLimitResult) => void): this;
+  on(event: 'allowed',     listener: (key: string, result: RateLimitResult) => void): this;
+  on(event: 'penalized',   listener: (key: string, info: PenaltyInfo) => void): this;
+  on(event: 'blacklisted', listener: (ip: string) => void): this;
+  on(event: 'whitelisted', listener: (ip: string) => void): this;
+  on(event: 'reset',       listener: (key: string) => void): this;
+  on(event: 'stats',       listener: (stats: LimiterStats) => void): this;
+  on(event: 'error',       listener: (err: Error) => void): this;
+
+  once(event: 'blocked',     listener: (key: string, result: RateLimitResult) => void): this;
+  once(event: 'allowed',     listener: (key: string, result: RateLimitResult) => void): this;
+  once(event: 'penalized',   listener: (key: string, info: PenaltyInfo) => void): this;
+  once(event: 'blacklisted', listener: (ip: string) => void): this;
+  once(event: 'whitelisted', listener: (ip: string) => void): this;
+  once(event: 'reset',       listener: (key: string) => void): this;
+  once(event: 'stats',       listener: (stats: LimiterStats) => void): this;
+  once(event: 'error',       listener: (err: Error) => void): this;
 }
 
 // ── Factory functions ────────────────────────────────────────────────────────