nextlimiter 1.1.0 → 1.3.0

package/bin/commands/benchmark.js

@@ -0,0 +1,125 @@
+'use strict';
+const http = require('http');
+const https = require('https');
+
+function parseArgs() {
+    const args = process.argv.slice(3);
+    const options = { url: null, duration: 10, concurrency: 10, rps: 0 };
+    
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--url') options.url = args[++i];
+        else if (args[i] === '--duration') options.duration = parseInt(args[++i], 10);
+        else if (args[i] === '--concurrency') options.concurrency = parseInt(args[++i], 10);
+        else if (args[i] === '--rps') options.rps = parseInt(args[++i], 10);
+    }
+    
+    if (!options.url) {
+        console.error('Usage: npx nextlimiter benchmark --url <url> [options]');
+        process.exit(1);
+    }
+    return options;
+}
+
+function fetchTarget(targetUrl) {
+    const t0 = Date.now();
+    return new Promise((resolve) => {
+        const parsed = new URL(targetUrl);
+        const lib = parsed.protocol === 'https:' ? https : http;
+        const req = lib.request({
+            hostname: parsed.hostname,
+            port: parsed.port,
+            path: parsed.pathname + parsed.search,
+            method: 'GET',
+            timeout: 10000
+        }, (res) => {
+            res.on('data', () => {});
+            res.on('end', () => resolve({ t: Date.now() - t0, s: res.statusCode }));
+        });
+        req.on('error', () => resolve({ t: Date.now() - t0, s: 0 }));
+        req.on('timeout', () => { req.destroy(); resolve({ t: Date.now() - t0, s: 0 }); });
+        req.end();
+    });
+}
+
+function calculatePercentile(arr, p) {
+    if (arr.length === 0) return 0;
+    arr.sort((a,b) => a - b);
+    const idx = Math.floor(arr.length * p);
+    return arr[idx];
+}
+
+function drawProgressBar(pct, text) {
+    if (!process.stdout.isTTY) return;
+    const cw = process.stdout.columns || 80;
+    const meta = ` ${pct.toFixed(0)}% | ${text}`;
+    const barLen = Math.max(10, cw - meta.length - 4);
+    const filled = Math.floor(barLen * (pct / 100));
+    const empty = barLen - filled;
+    
+    const bar = '[' + '█'.repeat(filled) + '░'.repeat(empty) + ']';
+    process.stdout.write(`\r${bar}${meta}`);
+}
+
+module.exports = async function() {
+    const opts = parseArgs();
+    console.log(`Benchmarking ${opts.url} for ${opts.duration} seconds with ${opts.concurrency} workers...`);
+
+    const endAt = Date.now() + (opts.duration * 1000);
+    let running = true;
+    let totalReqs = 0, blocked = 0;
+    const latencies = [];
+    const codes = { 200: 0, 429: 0 };
+    let intervalTimer;
+
+    const worker = async () => {
+        while (running && Date.now() < endAt) {
+            const res = await fetchTarget(opts.url);
+            totalReqs++;
+            latencies.push(res.t);
+            if (res.s === 429) { blocked++; codes[429] = (codes[429] || 0) + 1; }
+            else if (res.s > 0) { codes[res.s] = (codes[res.s] || 0) + 1; }
+            
+            if (opts.rps > 0) {
+                const sleepMs = 1000 / opts.rps;
+                await new Promise(r => setTimeout(r, sleepMs));
+            }
+        }
+    };
+
+    const workers = [];
+    for (let i = 0; i < opts.concurrency; i++) {
+        workers.push(worker());
+    }
+
+    intervalTimer = setInterval(() => {
+        const remaining = endAt - Date.now();
+        if (remaining <= 0) return;
+        const elapsed = (opts.duration * 1000) - remaining;
+        const pct = Math.min(100, (elapsed / (opts.duration * 1000)) * 100);
+        const avg = latencies.length > 0 ? Math.round(latencies.reduce((a,b)=>a+b, 0) / latencies.length) : 0;
+        drawProgressBar(pct, `${totalReqs} req | ${blocked} blocked | ${avg}ms avg \x1b[K`);
+    }, 500);
+
+    await Promise.all(workers);
+    clearInterval(intervalTimer);
+    if (process.stdout.isTTY) process.stdout.write('\n\n');
+
+    const durationSec = opts.duration;
+    const throughput = (totalReqs / durationSec).toFixed(1);
+    const blockPct = totalReqs > 0 ? ((blocked / totalReqs) * 100).toFixed(2) : '0.00';
+    const avgLat = totalReqs > 0 ? Math.round(latencies.reduce((a,b)=>a+b,0) / latencies.length) : 0;
+    const p95 = calculatePercentile(latencies, 0.95);
+    const p99 = calculatePercentile(latencies, 0.99);
+    
+    let codesText = Object.entries(codes).filter(([_,v])=>v>0).map(([k,v])=>`${k}: ${v}`).join(', ');
+    
+    console.log(`Benchmark Results — ${opts.url}`);
+    console.log(`Duration:        ${durationSec.toFixed(1)}s`);
+    console.log(`Total requests:  ${totalReqs}`);
+    console.log(`Req/sec:         ${throughput}`);
+    console.log(`Blocked:         ${blocked} (${blockPct}%)`);
+    console.log(`Avg latency:     ${avgLat}ms`);
+    console.log(`p95 latency:     ${p95}ms`);
+    console.log(`p99 latency:     ${p99}ms`);
+    console.log(`Status codes:    ${codesText}`);
+};

package/bin/commands/inspect.js

@@ -0,0 +1,64 @@
+'use strict';
+const http = require('http');
+const https = require('https');
+
+function parseArgs() {
+    const args = process.argv.slice(3);
+    const options = { url: args[0] };
+    
+    if (!options.url || options.url.startsWith('-')) {
+        console.error('Usage: npx nextlimiter inspect <url>');
+        process.exit(1);
+    }
+    try { new URL(options.url); } catch(e) { console.error('Invalid URL'); process.exit(1); }
+    return options;
+}
+
+module.exports = async function() {
+    const opts = parseArgs();
+    const parsed = new URL(opts.url);
+    const lib = parsed.protocol === 'https:' ? https : http;
+    
+    return new Promise((resolve) => {
+        const req = lib.request({
+            hostname: parsed.hostname,
+            port: parsed.port,
+            path: parsed.pathname + parsed.search,
+            method: 'GET',
+            timeout: 10000
+        }, (res) => {
+            res.on('data', () => {});
+            res.on('end', () => {
+                const h = res.headers;
+                const pad = (s, len=26) => String(s).padEnd(len);
+                
+                console.log(`┌─ nextlimiter inspect ──────────────────┐`);
+                console.log(`│ URL:        ${pad(opts.url)} │`);
+                console.log(`│ Status:     ${pad(res.statusCode + ' ' + http.STATUS_CODES[res.statusCode])} │`);
+                
+                if (h['x-ratelimit-limit']) console.log(`│ Limit:      ${pad(h['x-ratelimit-limit'])} │`);
+                if (h['x-ratelimit-remaining']) console.log(`│ Remaining:  ${pad(h['x-ratelimit-remaining'])} │`);
+                if (h['x-ratelimit-reset']) {
+                    const date = new Date(parseInt(h['x-ratelimit-reset'], 10) * 1000);
+                    const txt = !isNaN(date.getTime()) ? date.toISOString().replace('T', ' ').substring(0, 19) + ' UTC' : h['x-ratelimit-reset'];
+                    console.log(`│ Reset:      ${pad(txt)} │`);
+                }
+                if (h['x-ratelimit-strategy']) console.log(`│ Strategy:   ${pad(h['x-ratelimit-strategy'])} │`);
+                if (h['retry-after']) console.log(`│ Retry-After: ${pad(h['retry-after'] + ' seconds')} │`);
+                
+                const other = Object.keys(h).filter(k => k.startsWith('x-ratelimit-') && !['x-ratelimit-limit','x-ratelimit-remaining','x-ratelimit-reset','x-ratelimit-strategy'].includes(k));
+                other.forEach(k => {
+                    const v = typeof h[k] === 'string' ? h[k].substring(0, 26) : h[k];
+                    const keyTxt = k.substring('x-ratelimit-'.length);
+                    console.log(`│ ${String(keyTxt + ':').padEnd(11)} ${pad(v)} │`);
+                });
+                console.log(`└────────────────────────────────────────┘`);
+                resolve();
+            });
+        });
+        
+        req.on('error', (err) => { console.error('Error fetching:', err.message); process.exit(1); resolve(); });
+        req.on('timeout', () => { console.error('Request timed out'); process.exit(1); resolve(); });
+        req.end();
+    });
+};

package/bin/commands/test.js

@@ -0,0 +1,123 @@
+'use strict';
+const http = require('http');
+const https = require('https');
+
+function parseArgs() {
+    const args = process.argv.slice(3);
+    const options = { url: args[0], requests: 110, concurrency: 1, method: 'GET', headers: {}, delay: 0, json: false };
+    
+    if (!options.url || options.url.startsWith('-')) {
+        console.error('Usage: npx nextlimiter test <url> [options]');
+        process.exit(1);
+    }
+    try { new URL(options.url); } catch(e) { console.error('Invalid URL'); process.exit(1); }
+
+    for (let i = 1; i < args.length; i++) {
+        if (args[i] === '--requests') options.requests = parseInt(args[++i], 10);
+        else if (args[i] === '--concurrency') options.concurrency = parseInt(args[++i], 10);
+        else if (args[i] === '--method') options.method = args[++i];
+        else if (args[i] === '--header') {
+            const [k, v] = args[++i].split(':');
+            if (k && v) options.headers[k.trim()] = v.trim();
+        }
+        else if (args[i] === '--delay') options.delay = parseInt(args[++i], 10);
+        else if (args[i] === '--json') options.json = true;
+    }
+    return options;
+}
+
+function doRequest(targetUrl, method, headers) {
+    return new Promise((resolve) => {
+        const parsed = new URL(targetUrl);
+        const lib = parsed.protocol === 'https:' ? https : http;
+        const req = lib.request({
+            hostname: parsed.hostname,
+            port: parsed.port,
+            path: parsed.pathname + parsed.search,
+            method,
+            headers,
+            timeout: 10000
+        }, (res) => {
+            if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location) {
+                // simple redirect follow
+                return resolve(doRequest(res.headers.location, method, headers));
+            }
+            res.on('data', () => {});
+            res.on('end', () => resolve({
+                status: res.statusCode,
+                limit: res.headers['x-ratelimit-limit'],
+                remaining: res.headers['x-ratelimit-remaining'],
+                strategy: res.headers['x-ratelimit-strategy'],
+                retryAfter: res.headers['retry-after'] || res.headers['x-ratelimit-reset'],
+            }));
+        });
+        req.on('error', (err) => resolve({ error: err.message }));
+        req.on('timeout', () => { req.destroy(); resolve({ error: 'timeout' }) });
+        req.end();
+    });
+}
+
+function delayBlock(ms) {
+    return new Promise(r => setTimeout(r, ms));
+}
+
+module.exports = async function() {
+    const opts = parseArgs();
+    const isTTY = process.stdout.isTTY;
+    const cGreen = isTTY ? '\x1b[32m' : '';
+    const cYellow = isTTY ? '\x1b[33m' : '';
+    const cRed = isTTY ? '\x1b[31m' : '';
+    const cReset = isTTY ? '\x1b[0m' : '';
+
+    let allowed = 0, blocked = 0, blockStrategy = '', firstBlock = -1;
+
+    for (let i = 1; i <= opts.requests; i += opts.concurrency) {
+        const batch = [];
+        for (let j = 0; j < opts.concurrency && (i + j) <= opts.requests; j++) {
+            batch.push(doRequest(opts.url, opts.method, opts.headers));
+        }
+        
+        const results = await Promise.all(batch);
+        results.forEach((r, idx) => {
+            const reqNum = i + idx;
+            if (r.error) {
+                if (!opts.json) console.log(`Request ${reqNum}: ${cRed}Error: ${r.error}${cReset}`);
+                return;
+            }
+            if (r.status >= 200 && r.status < 300) {
+                allowed++;
+                if (!opts.json) console.log(`Request ${reqNum}:\t${cGreen}${r.status} OK${cReset} \t(remaining: ${r.remaining || '?'})`);
+            } else if (r.status === 429) {
+                blocked++;
+                if (firstBlock === -1) firstBlock = reqNum;
+                blockStrategy = blockStrategy || r.strategy || 'unknown';
+                if (!opts.json) {
+                    console.log(`Request ${reqNum}:\t${cYellow}429 Too Many Requests${cReset}`);
+                    if (idx === batch.length-1) { // print extra details on last item in block batch
+                       console.log(`  Retry-After:\t${r.retryAfter || '?'}`);
+                       console.log(`  Strategy:\t${blockStrategy}`);
+                       console.log(`  Limit:\t${r.limit || '?'}`);
+                    }
+                }
+            } else {
+                if (!opts.json) console.log(`Request ${reqNum}:\t${cRed}${r.status}${cReset}`);
+            }
+        });
+        
+        if (opts.delay) await delayBlock(opts.delay);
+    }
+
+    if (opts.json) {
+        console.log(JSON.stringify({ total: opts.requests, allowed, blocked, firstBlock, blockStrategy }));
+    } else {
+        const pad = (s, len=31) => String(s).padEnd(len);
+        console.log(`\n┌─────────────────────────────────┐`);
+        console.log(`│ Total requests:     ${pad(opts.requests, 12)}│`);
+        console.log(`│ Allowed:            ${pad(allowed, 12)}│`);
+        console.log(`│ Blocked (429):      ${pad(blocked, 12)}│`);
+        console.log(`│ Block rate:         ${pad(((blocked/opts.requests)*100).toFixed(2)+'%', 12)}│`);
+        console.log(`│ First block at:     ${pad(firstBlock === -1 ? 'none' : 'request ' + firstBlock, 12)}│`);
+        console.log(`│ Strategy detected:  ${pad(blockStrategy || 'N/A', 12)}│`);
+        console.log(`└─────────────────────────────────┘`);
+    }
+};

package/bin/nextlimiter.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const cmd = process.argv[2];
+
+if (!cmd || cmd === '--help' || cmd === '-h') {
+  console.log(`
+  Usage: npx nextlimiter <command> [options]
+
+  Commands:
+    test <url>              Fire N requests and show rate limit behaviour
+    benchmark --url <url>   Load test a URL and measure throughput
+    inspect <url>           Show rate limit headers for a single request
+
+  Examples:
+    npx nextlimiter test https://api.example.com/users
+    npx nextlimiter test https://api.example.com --requests 200 --delay 10
+    npx nextlimiter benchmark --url http://localhost:3000 --duration 30
+    npx nextlimiter inspect https://api.example.com
+  `);
+  process.exit(0);
+}
+
+if (cmd === '--version' || cmd === '-v') {
+  const pkg = require('../package.json');
+  console.log('v' + pkg.version);
+  process.exit(0);
+}
+
+const commands = {
+  test: require('./commands/test'),
+  benchmark: require('./commands/benchmark'),
+  inspect: require('./commands/inspect')
+};
+
+if (!commands[cmd]) {
+  console.error(`Unknown command: ${cmd}`);
+  process.exit(1);
+}
+
+commands[cmd]();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextlimiter",
-  "version": "1.1.0",
+  "version": "1.3.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",
@@ -10,7 +10,11 @@
     "./next": "./src/adapters/next.js",
     "./hono": "./src/adapters/hono.js"
   },
+  "bin": {
+    "nextlimiter": "./bin/nextlimiter.js"
+  },
   "files": [
+    "bin/",
     "src/",
     "types/",
     "README.md",

package/src/core/config.js

@@ -88,6 +88,18 @@ const DEFAULT_CONFIG = {
   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
+
+  rules:         null,       // RuleConfig[] — multiple rate limit constraints
+  schedule:      null,       // ScheduleEntry[] — time-based config overrides
+
+  webhook:           null,
+  webhookRetries:    3,
+  webhookBackoff:    'exponential',
+  webhookTimeout:    5000,
+  webhookSecret:     null,
+
+  drainRateMs:       undefined,  // leaky-bucket only
+  capacity:          undefined,  // leaky-bucket only
 };
 
 /**
@@ -98,13 +110,31 @@ const DEFAULT_CONFIG = {
 function resolveConfig(userOptions = {}) {
   let base = { ...DEFAULT_CONFIG };
 
-  // Apply named preset first (lowest priority)
-  if (userOptions.preset && PRESETS[userOptions.preset]) {
-    base = { ...base, ...PRESETS[userOptions.preset] };
+  // Apply preset
+  if (userOptions.preset) { // Use userOptions.preset here to ensure it's applied
+    const presetCfg = PRESETS[userOptions.preset];
+    if (!presetCfg) throw new Error(`[NextLimiter] Unknown preset: ${userOptions.preset}`);
+    // Merge preset config into base, allowing userOptions to override later
+    base = { ...base, ...presetCfg };
+  }
+
+  // Mutually exclusive core configurations
+  const hasRules = userOptions.rules !== undefined && userOptions.rules !== null;
+  const hasSchedule = userOptions.schedule !== undefined && userOptions.schedule !== null;
+  const hasMax = userOptions.max !== undefined && userOptions.max !== null;
+
+  if (hasRules && hasSchedule) {
+    throw new Error('[NextLimiter] config.rules and config.schedule are mutually exclusive.');
+  }
+  if (hasRules && hasMax) {
+    throw new Error('[NextLimiter] config.max/windowMs and config.rules are mutually exclusive.');
+  }
+  if (hasSchedule && hasMax) {
+    throw new Error('[NextLimiter] config.max/windowMs and config.schedule are mutually exclusive.');
   }
 
-  // Merge user options
-  base = { ...base, ...userOptions };
+  // Apply user overrides
+  Object.assign(base, userOptions);
 
   // Apply plan limits (overrides windowMs and max if plan is set)
   if (base.plan) {
@@ -120,9 +150,45 @@ function resolveConfig(userOptions = {}) {
     base._burstMax = planCfg.burstMax;
   }
 
-  // Validate
-  if (base.max <= 0) throw new Error('[NextLimiter] config.max must be greater than 0');
-  if (base.windowMs <= 0) throw new Error('[NextLimiter] config.windowMs must be greater than 0');
+  // Deep validate
+  if (base.rules) {
+    if (!Array.isArray(base.rules) || base.rules.length === 0) {
+      throw new Error('[NextLimiter] config.rules must be a non-empty array.');
+    }
+    for (const rule of base.rules) {
+      if (!rule.keyBy) throw new Error('[NextLimiter] Each rule must have a keyBy property.');
+      if (typeof rule.max !== 'number' || rule.max <= 0) throw new Error('[NextLimiter] Each rule must have a positive max integer.');
+      if (typeof rule.windowMs !== 'number' || rule.windowMs <= 0) throw new Error('[NextLimiter] Each rule must have a positive windowMs integer.');
+    }
+  } else if (base.schedule) {
+    if (!Array.isArray(base.schedule) || base.schedule.length === 0) {
+      throw new Error('[NextLimiter] config.schedule must be a non-empty array.');
+    }
+    let prevEnd = -1;
+    for (let i = 0; i < base.schedule.length; i++) {
+        const entry = base.schedule[i];
+        if (!entry.hours) throw new Error('[NextLimiter] Each schedule entry must have an hours string (e.g., "9-17").');
+        if (typeof entry.max !== 'number' || entry.max <= 0) throw new Error('[NextLimiter] Each schedule entry must have a positive max integer.');
+        
+        const match = /^\s*(\d{1,2})\s*-\s*(\d{1,2})\s*$/.exec(entry.hours);
+        if (!match) throw new Error(`[NextLimiter] Invalid hours format: ${entry.hours}`);
+        let s = parseInt(match[1], 10), e = parseInt(match[2], 10);
+        if (s < 0 || s > 23 || e < 0 || e > 23) throw new Error('[NextLimiter] Schedule hours must be between 0 and 23. Got: ' + entry.hours);
+        if (e < s) throw new Error(`[NextLimiter] Invalid schedule: end hour (${e}) cannot be less than start hour (${s}).`);
+        
+        // Basic overlap check
+        if (s <= prevEnd) console.warn(`[NextLimiter] Warning: Overlapping schedule entries detected.`);
+        prevEnd = e;
+    }
+    if (prevEnd < 23) console.warn(`[NextLimiter] Warning: Schedule entries do not cover a full 24-hr cycle.`);
+    // Base max/windowMs must still be valid for fallback
+    if (base.max <= 0) throw new Error('[NextLimiter] config.max must be greater than 0');
+    if (base.windowMs <= 0) throw new Error('[NextLimiter] config.windowMs must be greater than 0');
+  } else {
+    // Standard mode validation
+    if (base.max <= 0) throw new Error('[NextLimiter] config.max must be greater than 0');
+    if (base.windowMs <= 0) throw new Error('[NextLimiter] config.windowMs must be greater than 0');
+  }
 
   // Validate whitelist / blacklist (warn, never throw)
   for (const listName of ['whitelist', 'blacklist']) {
@@ -159,6 +225,36 @@ function resolveConfig(userOptions = {}) {
     }
   }
 
+  // Validate webhook
+  if (base.webhook) {
+    if (!base.webhook.startsWith('http://') && !base.webhook.startsWith('https://')) {
+        throw new Error('[NextLimiter] config.webhook must be a valid URL starting with http:// or https://');
+    }
+    if (base.webhook.startsWith('http://')) {
+        console.warn('[NextLimiter] Warning: Webhook URL is using insecure http://. Consider switching to https://');
+    }
+    if (base.webhookRetries < 0 || base.webhookRetries > 10) base.webhookRetries = 3;
+    if (base.webhookTimeout < 500) base.webhookTimeout = 5000;
+  }
+
+  // Validate new strategies
+  if (base.strategy === 'sliding-window-log' && base.max > 10000) {
+    console.warn('[NextLimiter] Warning: "sliding-window-log" stores an array of timestamps. Using max > 10000 may impact memory and performance.');
+  }
+
+  if (base.drainRateMs !== undefined || base.capacity !== undefined) {
+    if (base.strategy !== 'leaky-bucket') {
+      console.warn('[NextLimiter] Warning: drainRateMs and capacity are ignored for strategy "' + base.strategy + '"');
+    } else {
+      if (base.drainRateMs !== undefined && (typeof base.drainRateMs !== 'number' || base.drainRateMs <= 0)) {
+        throw new Error('[NextLimiter] drainRateMs must be a positive number');
+      }
+      if (base.capacity !== undefined && (typeof base.capacity !== 'number' || base.capacity <= 0 || !Number.isInteger(base.capacity))) {
+        throw new Error('[NextLimiter] capacity must be a positive integer');
+      }
+    }
+  }
+
   return base;
 }
 

package/src/core/limiter.js

@@ -6,6 +6,8 @@ const { MemoryStore }             = require('../store/memoryStore');
 const { fixedWindowCheck }        = require('../strategies/fixedWindow');
 const { slidingWindowCheck }      = require('../strategies/slidingWindow');
 const { tokenBucketCheck }        = require('../strategies/tokenBucket');
+const { slidingWindowLog }        = require('../strategies/slidingWindowLog');
+const { leakyBucket }             = require('../strategies/leakyBucket');
 const { resolveKeyGenerator }     = require('../utils/keyGenerator');
 const { extractIp }               = require('../utils/keyGenerator');
 const { createLogger }            = require('../utils/logger');
@@ -14,11 +16,17 @@ const { SmartDetector }           = require('../smart/detector');
 const { setHeaders }              = require('../middleware/headers');
 const { checkAccess }             = require('./accessControl');
 const { PrometheusFormatter }     = require('../analytics/prometheus');
+const { RuleEngine }              = require('./ruleEngine');
+const { WebhookSender }           = require('../webhook/sender');
+const { Scheduler }               = require('./scheduler');
+const { dashboardMiddleware }     = require('../dashboard/dashboardMiddleware');
 
 const STRATEGY_MAP = {
   'fixed-window':   fixedWindowCheck,
   'sliding-window': slidingWindowCheck,
   'token-bucket':   tokenBucketCheck,
+  'sliding-window-log': slidingWindowLog,
+  'leaky-bucket':   leakyBucket,
 };
 
 /**
@@ -77,6 +85,11 @@ class Limiter extends EventEmitter {
         this.emit('stats', this.getStats());
       }, this._config.statsInterval).unref();
     }
+
+    // Engine, Scheduler & Webhook
+    this.ruleEngine = this._config.rules ? new RuleEngine(this._config.rules, this._store, this, this._config) : null;
+    this.scheduler = this._config.schedule ? new Scheduler(this._config.schedule, this._config) : null;
+    this.webhookSender = this._config.webhook ? new WebhookSender(this._config) : null;
   }
 
   // ── Public API ─────────────────────────────────────────────────────────────
@@ -114,19 +127,54 @@ class Limiter extends EventEmitter {
         }
         // ────────────────────────────────────────────────────────────────────
 
-        const rawKey = this._keyGenerator(req);
-        const key    = `${this._config.keyPrefix}${rawKey}`;
-
-        const result = await this._runCheck(key);
+        let result;
+        let rawKey;
+        let key;
+        let failedRuleName;
+
+        if (this.ruleEngine) {
+          const ruleResult = await this.ruleEngine.check(req);
+          result = ruleResult.mostRestrictive;
+          rawKey = ruleResult.key; // composite key
+          key = ruleResult.key;
+          failedRuleName = ruleResult.failedRule ? ruleResult.failedRule.name : undefined;
+
+          if (this._config.headers) {
+            res.setHeader('X-RateLimit-Rule-Count', ruleResult.results.length);
+            if (!ruleResult.allowed && failedRuleName) {
+              res.setHeader('X-RateLimit-Failed-Rule', failedRuleName);
+            }
+          }
+        } else {
+          rawKey = this._keyGenerator(req);
+          key    = `${this._config.keyPrefix}${rawKey}`;
+          result = await this._runCheck(key);
+        }
         
         // Emit events
-        if (result.allowed) this.emit('allowed', rawKey, result);
-        else this.emit('blocked', rawKey, result);
+        if (result.allowed) {
+          this.emit('allowed', rawKey, result);
+        } else {
+          this.emit('blocked', rawKey, result);
+          if (this.webhookSender) {
+             this.webhookSender.send({
+               event: 'blocked',
+               key,
+               ip: clientIp,
+               limit: result.limit,
+               count: result.limit - result.remaining,
+               timestamp: new Date().toISOString(),
+               retryAfter: result.retryAfter,
+               strategy: result.strategy,
+               ...(failedRuleName ? { ruleName: failedRuleName } : {})
+             });
+          }
+        }
 
         // Record analytics
         this._analytics.record(key, result.allowed);
 
-        // Set headers
+        // Set headers (base headers overrides single rule headers if rule engine is active, that is fine)
         if (this._config.headers) {
           setHeaders(res, result);
         }
@@ -288,6 +336,19 @@ class Limiter extends EventEmitter {
     this._log.info(`Reset key: ${fullKey}`);
   }
 
+  /**
+   * Returns an Express middleware for displaying a live dashboard.
+   *
+   * @param {object} options
+   * @param {string} options.password - If set, enable HTTP Basic Auth
+   * @param {number} options.refreshMs - SSE push interval (default 2000ms)
+   * @param {string} options.path - Mount path prefix (default '/nextlimiter')
+   * @returns {function}
+   */
+  dashboardMiddleware(options = {}) {
+    return dashboardMiddleware(this, options);
+  }
+
   /**
    * Get analytics snapshot.
    *
@@ -307,6 +368,8 @@ class Limiter extends EventEmitter {
       };
     }
 
+    stats.activeSchedule = this.scheduler ? this.scheduler.resolve() : null;
+
     stats.config = {
       strategy: this._config.strategy,
       windowMs: this._config.windowMs,
@@ -342,14 +405,14 @@ class Limiter extends EventEmitter {
    * @returns {import('../core/result').RateLimitResult}
    */
   _runCheck(key) {
-    let effectiveConfig = this._config;
+    let effectiveConfig = this.scheduler ? this.scheduler.resolve() : this._config;
 
     // Apply smart penalty if relevant
     if (this._smart) {
       const { penalized, effectiveMax } = this._smart.check(key);
       if (penalized) {
         // Create a shallow config override with reduced max
-        effectiveConfig = { ...this._config, max: effectiveMax };
+        effectiveConfig = { ...effectiveConfig, max: effectiveMax };
       }
     }