nextlimiter 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextlimiter",
-  "version": "1.1.0",
+  "version": "1.2.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/core/config.js

@@ -88,6 +88,15 @@ 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,
 };
 
 /**
@@ -98,13 +107,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 +147,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 +222,18 @@ 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;
+  }
+
   return base;
 }
 

package/src/core/limiter.js

@@ -14,6 +14,9 @@ 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 STRATEGY_MAP = {
   'fixed-window':   fixedWindowCheck,
@@ -77,6 +80,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 +122,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);
         }
@@ -307,6 +350,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 +387,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 };
       }
     }
 

package/src/core/ruleEngine.js

@@ -0,0 +1,89 @@
+'use strict';
+const { resolveKeyGenerator } = require('../utils/keyGenerator');
+const { fixedWindowCheck } = require('../strategies/fixedWindow');
+const { slidingWindowCheck } = require('../strategies/slidingWindow');
+const { tokenBucketCheck } = require('../strategies/tokenBucket');
+
+const STRATEGY_MAP = {
+  'fixed-window': fixedWindowCheck,
+  'sliding-window': slidingWindowCheck,
+  'token-bucket': tokenBucketCheck,
+};
+
+class RuleEngine {
+  constructor(rules, store, emitter, globalConfig) {
+    this._rules = rules.map((r, i) => {
+      const strategyName = r.strategy || 'sliding-window';
+      const strategyFn = STRATEGY_MAP[strategyName];
+      if (!strategyFn) throw new Error(`[NextLimiter] Unknown strategy in rule: ${strategyName}`);
+      return {
+        ...r,
+        name: r.name || `rule${i}`,
+        index: i,
+        keyGenerator: typeof r.keyBy === 'function' ? r.keyBy : resolveKeyGenerator(r.keyBy),
+        strategyFn
+      };
+    });
+    this._store = store;
+    this._emitter = emitter;
+    this._globalConfig = globalConfig;
+  }
+
+  async check(req) {
+    const promises = this._rules.map(rule => {
+      const rawKey = rule.keyGenerator(req);
+      const fullKey = `${this._globalConfig.keyPrefix}${rule.name}:${rule.keyBy}:${rawKey}`;
+      
+      const config = { max: rule.max, windowMs: rule.windowMs };
+      return Promise.resolve(rule.strategyFn(fullKey, config, this._store)).then(result => {
+        return {
+          ...result,
+          key: fullKey,
+          rawKey,
+          rule
+        };
+      });
+    });
+
+    const results = await Promise.all(promises);
+    
+    let allowed = true;
+    let failedRule = null;
+    let mostRestrictive = results[0];
+    let mostRestrictiveRemaining = Infinity;
+
+    // Find the most restrictive outcome and if any caused a block.
+    for (const res of results) {
+      if (!res.allowed) {
+        allowed = false;
+        if (!failedRule) failedRule = res.rule;
+      }
+      if (res.remaining < mostRestrictiveRemaining) {
+        mostRestrictiveRemaining = res.remaining;
+        mostRestrictive = res;
+      }
+    }
+
+    if (!allowed) {
+      let longestRetry = -1;
+      for (const res of results) {
+         if (!res.allowed && res.retryAfter > longestRetry) {
+             longestRetry = res.retryAfter;
+             mostRestrictive = res; // prioritize the one with highest retry limit to wait for
+         }
+      }
+    }
+
+    const compositeKey = results.map(r => r.key).join('|');
+
+    return {
+      allowed,
+      failedRule,
+      results,
+      mostRestrictive,
+      key: compositeKey
+    };
+  }
+}
+
+module.exports = { RuleEngine };

package/src/core/scheduler.js

@@ -0,0 +1,49 @@
+'use strict';
+
+class Scheduler {
+  constructor(schedule, baseConfig) {
+    this._schedule = schedule;
+    this._baseConfig = baseConfig;
+  }
+
+  resolve(now = new Date()) {
+    const currentHour = this._currentHourUTC(now);
+    
+    for (const entry of this._schedule) {
+      const { start, end } = this._parseHours(entry.hours);
+      if (currentHour >= start && currentHour <= end) {
+        return {
+          ...this._baseConfig,
+          max: entry.max,
+          windowMs: entry.windowMs !== undefined ? entry.windowMs : this._baseConfig.windowMs,
+          strategy: entry.strategy || this._baseConfig.strategy
+        };
+      }
+    }
+
+    return this._baseConfig;
+  }
+
+  _currentHourUTC(now) {
+    return now.getUTCHours();
+  }
+
+  _parseHours(rangeStr) {
+    const match = /^\s*(\d{1,2})\s*-\s*(\d{1,2})\s*$/.exec(rangeStr);
+    if (!match) throw new Error(`[NextLimiter] Invalid schedule hours format: "${rangeStr}" (expected "start-end" e.g. "9-17")`);
+    
+    const start = parseInt(match[1], 10);
+    const end = parseInt(match[2], 10);
+    
+    if (start < 0 || start > 23 || end < 0 || end > 23) {
+      throw new Error(`[NextLimiter] Schedule hours must be between 0 and 23. Got: ${rangeStr}`);
+    }
+    if (end < start) {
+      throw new Error(`[NextLimiter] Schedule end hour cannot be less than start hour. Got: ${rangeStr}`);
+    }
+
+    return { start, end };
+  }
+}
+
+module.exports = { Scheduler };

package/src/webhook/sender.js

@@ -0,0 +1,93 @@
+'use strict';
+const https = require('https');
+const crypto = require('crypto');
+
+class WebhookSender {
+  constructor(config = {}) {
+    this.webhook = config.webhook;
+    this.webhookRetries = config.webhookRetries !== undefined ? config.webhookRetries : 3;
+    this.webhookBackoff = config.webhookBackoff || 'exponential';
+    this.webhookTimeout = config.webhookTimeout || 5000;
+    this.webhookSecret = config.webhookSecret;
+  }
+
+  async send(payload) {
+    // Fire-and-forget
+    this._sendWithRetry(payload, this.webhookRetries, this._getInitialDelay()).catch(() => {
+      // Intentionally swallow errors — background fire and forget
+    });
+  }
+
+  async _sendWithRetry(payload, attemptsLeft, delayMs) {
+    try {
+      await this._makeRequest(payload);
+    } catch (err) {
+      if (attemptsLeft > 0) {
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+        const nextDelay = this._getNextDelay(delayMs);
+        await this._sendWithRetry(payload, attemptsLeft - 1, nextDelay);
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  _getInitialDelay() {
+    if (this.webhookBackoff === 'linear' || this.webhookBackoff === 'fixed') return 1000;
+    return 100; // exponential
+  }
+
+  _getNextDelay(currentDelay) {
+    if (this.webhookBackoff === 'linear') return currentDelay + 1000;
+    if (this.webhookBackoff === 'exponential') return currentDelay * 2;
+    return currentDelay; // fixed
+  }
+
+  _makeRequest(payload) {
+    return new Promise((resolve, reject) => {
+      const body = JSON.stringify(payload);
+      const urlObj = new URL(this.webhook);
+
+      const options = {
+        hostname: urlObj.hostname,
+        port: urlObj.port || (urlObj.protocol === 'https:' ? 443 : 80),
+        path: urlObj.pathname + urlObj.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(body)
+        }
+      };
+
+      if (this.webhookSecret) {
+        const sig = crypto.createHmac('sha256', this.webhookSecret).update(body).digest('hex');
+        options.headers['X-nextlimiter-signature'] = `sha256=${sig}`;
+      }
+
+      // We only support https natively as per requirement, though http objects won't crash here they just might fail protocol
+      const req = https.request(options, (res) => {
+        let responseBody = '';
+        res.on('data', chunk => { responseBody += chunk; });
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve({ statusCode: res.statusCode, body: responseBody });
+          } else {
+            reject(new Error(`Webhook failed with status: ${res.statusCode}`));
+          }
+        });
+      });
+
+      req.on('error', (err) => reject(err));
+      
+      req.setTimeout(this.webhookTimeout, () => {
+        req.destroy();
+        reject(new Error(`Webhook timed out after ${this.webhookTimeout}ms`));
+      });
+
+      req.write(body);
+      req.end();
+    });
+  }
+}
+
+module.exports = { WebhookSender };

package/types/index.d.ts

@@ -23,6 +23,41 @@ export interface PlanDefinition {
   description?: string;
 }
 
+export interface RuleConfig {
+  keyBy: 'ip' | 'api-key' | 'user-id' | string | ((req: Request) => string);
+  max: number;
+  windowMs: number;
+  strategy?: 'sliding-window' | 'token-bucket' | 'fixed-window';
+  name?: string;
+}
+
+export interface RuleEngineResult {
+  allowed: boolean;
+  failedRule: RuleConfig | null;
+  results: RateLimitResult[];
+  mostRestrictive: RateLimitResult;
+  key: string;
+}
+
+export interface ScheduleEntry {
+  hours: string;
+  max: number;
+  windowMs?: number;
+  strategy?: string;
+}
+
+export interface WebhookPayload {
+  event: string;
+  key: string;
+  ip: string;
+  limit: number;
+  count: number;
+  timestamp: string;
+  retryAfter: number;
+  strategy: string;
+  ruleName?: string;
+}
+
 export type BuiltInPlan = 'free' | 'pro' | 'enterprise';
 export type BuiltInPreset = 'strict' | 'relaxed' | 'api' | 'auth';
 export type Strategy = 'fixed-window' | 'sliding-window' | 'token-bucket';
@@ -105,6 +140,14 @@ export interface LimiterOptions {
 
   /** ms interval to emit 'stats' event. undefined = disabled. */
   statsInterval?: number;
+
+  rules?: RuleConfig[];
+  schedule?: ScheduleEntry[];
+  webhook?: string;
+  webhookRetries?: number;
+  webhookBackoff?: 'exponential' | 'linear' | 'fixed';
+  webhookTimeout?: number;
+  webhookSecret?: string;
 }
 
 // ── Rate limit result ────────────────────────────────────────────────────────