nextlimiter 1.0.0

package/src/store/memoryStore.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * MemoryStore — default storage backend.
+ *
+ * Uses a plain Map with periodic cleanup of expired entries.
+ * For multi-process / distributed deployments, swap this for RedisStore.
+ *
+ * Implements the NexLimit Store interface:
+ *   get(key)          → value | undefined
+ *   set(key, value, ttlMs)
+ *   increment(key, ttlMs) → number  (atomic increment, returns new value)
+ *   delete(key)
+ *   keys()            → string[]
+ *   clear()
+ */
+class MemoryStore {
+  constructor() {
+    /** @type {Map<string, { value: any, expiresAt: number }>} */
+    this._data = new Map();
+
+    // Clean up expired entries every 5 minutes to prevent memory leaks
+    this._cleanupInterval = setInterval(() => this._cleanup(), 5 * 60_000);
+
+    // Don't let this timer prevent process exit
+    if (this._cleanupInterval.unref) this._cleanupInterval.unref();
+  }
+
+  /**
+   * Get a stored value by key. Returns undefined if missing or expired.
+   * @param {string} key
+   */
+  get(key) {
+    const entry = this._data.get(key);
+    if (!entry) return undefined;
+    if (Date.now() > entry.expiresAt) {
+      this._data.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  /**
+   * Set a value with TTL.
+   * @param {string} key
+   * @param {any} value
+   * @param {number} ttlMs - Time to live in milliseconds
+   */
+  set(key, value, ttlMs) {
+    this._data.set(key, {
+      value,
+      expiresAt: Date.now() + ttlMs,
+    });
+  }
+
+  /**
+   * Atomic increment. Creates key with value 1 if it doesn't exist.
+   * Returns the new value after increment.
+   * @param {string} key
+   * @param {number} ttlMs - TTL applied only on first creation
+   * @returns {number}
+   */
+  increment(key, ttlMs) {
+    const entry = this._data.get(key);
+    const now = Date.now();
+
+    if (!entry || now > entry.expiresAt) {
+      this._data.set(key, { value: 1, expiresAt: now + ttlMs });
+      return 1;
+    }
+
+    entry.value += 1;
+    return entry.value;
+  }
+
+  /**
+   * Delete a key immediately.
+   * @param {string} key
+   */
+  delete(key) {
+    this._data.delete(key);
+  }
+
+  /**
+   * Return all non-expired keys.
+   * @returns {string[]}
+   */
+  keys() {
+    const now = Date.now();
+    const result = [];
+    for (const [key, entry] of this._data) {
+      if (now <= entry.expiresAt) result.push(key);
+    }
+    return result;
+  }
+
+  /** Remove all entries. */
+  clear() {
+    this._data.clear();
+  }
+
+  /** Remove expired entries to prevent unbounded memory growth. */
+  _cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this._data) {
+      if (now > entry.expiresAt) this._data.delete(key);
+    }
+  }
+
+  /** Stop the cleanup timer. Call when tearing down the store. */
+  destroy() {
+    clearInterval(this._cleanupInterval);
+    this._data.clear();
+  }
+
+  /** Current number of tracked keys (includes expired until next cleanup). */
+  get size() {
+    return this._data.size;
+  }
+}
+
+module.exports = { MemoryStore };

package/src/strategies/fixedWindow.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const { RateLimitResult } = require('../core/result');
+
+/**
+ * Fixed Window strategy.
+ *
+ * Divides time into fixed intervals. Counts requests per interval.
+ * Simple, low memory usage, but susceptible to boundary burst attacks
+ * (a client can send 2× the limit in a short period by straddling a window edge).
+ *
+ * Redis key format: `<prefix><key>:<windowStart>`
+ * The window timestamp in the key means entries auto-expire naturally.
+ *
+ * @param {string} key         - Rate limit key (e.g. "nexlimit:ip:1.2.3.4")
+ * @param {object} config      - Resolved NexLimit config
+ * @param {object} store       - Store instance
+ * @returns {RateLimitResult}
+ */
+function fixedWindowCheck(key, config, store) {
+  const now = Date.now();
+  const windowStart = Math.floor(now / config.windowMs) * config.windowMs;
+  const windowEnd   = windowStart + config.windowMs;
+  const storeKey    = `${key}:fw:${windowStart}`;
+
+  const count = store.increment(storeKey, config.windowMs);
+  const allowed = count <= config.max;
+
+  return new RateLimitResult({
+    allowed,
+    limit:    config.max,
+    remaining: config.max - count,
+    resetAt:  windowEnd,
+    retryAfter: allowed ? 0 : Math.ceil((windowEnd - now) / 1000),
+    key,
+    strategy: 'fixed-window',
+  });
+}
+
+module.exports = { fixedWindowCheck };

package/src/strategies/slidingWindow.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const { RateLimitResult } = require('../core/result');
+
+/**
+ * Sliding Window strategy using a weighted two-window approximation.
+ *
+ * This is the algorithm used by Cloudflare and Nginx's limit_req_zone.
+ * It avoids the boundary-burst problem of fixed window without the memory
+ * cost of a full sliding-window log.
+ *
+ * How it works:
+ *   count ≈ (prevWindowCount × prevWindowWeight) + currentWindowCount
+ *
+ * Where prevWindowWeight = fraction of previous window still "in view"
+ * based on how far into the current window we are.
+ *
+ * Example: windowMs = 60s, we are 15s into the current window.
+ *   prevWindowWeight = (60-15)/60 = 0.75
+ *   Effective count = (prevCount × 0.75) + currentCount
+ *
+ * This is O(1) memory per key — same as fixed window — but much more
+ * accurate. The approximation error is at most 1/(2 × windowMs).
+ *
+ * @param {string} key         - Rate limit key
+ * @param {object} config      - Resolved NexLimit config
+ * @param {object} store       - Store instance
+ * @returns {RateLimitResult}
+ */
+function slidingWindowCheck(key, config, store) {
+  const now         = Date.now();
+  const windowMs    = config.windowMs;
+  const windowStart = Math.floor(now / windowMs) * windowMs;
+  const prevStart   = windowStart - windowMs;
+
+  const currentKey = `${key}:sw:${windowStart}`;
+  const prevKey    = `${key}:sw:${prevStart}`;
+
+  // How far into the current window are we? (0.0 → 1.0)
+  const positionInWindow = (now - windowStart) / windowMs;
+
+  // Weight of the previous window (complement of current position)
+  const prevWeight = 1 - positionInWindow;
+
+  // Get counts from both windows
+  const currentCount = store.get(currentKey) || 0;
+  const prevCount    = store.get(prevKey)     || 0;
+
+  // Weighted approximation
+  const effectiveCount = Math.floor(prevCount * prevWeight) + currentCount;
+
+  if (effectiveCount >= config.max) {
+    return new RateLimitResult({
+      allowed:   false,
+      limit:     config.max,
+      remaining: 0,
+      resetAt:   windowStart + windowMs,
+      retryAfter: Math.ceil((windowStart + windowMs - now) / 1000),
+      key,
+      strategy: 'sliding-window',
+    });
+  }
+
+  // Increment current window. TTL = 2 full windows to keep prev window alive.
+  store.increment(currentKey, windowMs * 2);
+
+  return new RateLimitResult({
+    allowed:   true,
+    limit:     config.max,
+    remaining: config.max - effectiveCount - 1,
+    resetAt:   windowStart + windowMs,
+    retryAfter: 0,
+    key,
+    strategy: 'sliding-window',
+  });
+}
+
+module.exports = { slidingWindowCheck };

package/src/strategies/tokenBucket.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const { RateLimitResult } = require('../core/result');
+
+/**
+ * Token Bucket strategy.
+ *
+ * Tokens refill continuously at a steady rate. Each request consumes one
+ * token. Allows controlled bursts up to `capacity` tokens while enforcing
+ * a long-term average rate of `max` requests per `windowMs`.
+ *
+ * State per key: { tokens: float, lastRefill: timestamp }
+ *
+ * Refill rate = config.max / config.windowMs  (tokens per millisecond)
+ * Capacity    = config.max  (maximum accumulated tokens)
+ *
+ * This is the algorithm used by Stripe for their API rate limiting.
+ * It feels more "fair" to clients than window-based approaches because
+ * occasional bursts are explicitly allowed.
+ *
+ * @param {string} key      - Rate limit key
+ * @param {object} config   - Resolved NexLimit config
+ * @param {object} store    - Store instance
+ * @returns {RateLimitResult}
+ */
+function tokenBucketCheck(key, config, store) {
+  const now        = Date.now();
+  const capacity   = config.max;
+  const refillRate = config.max / config.windowMs; // tokens per ms
+  const storeKey   = `${key}:tb`;
+
+  let bucket = store.get(storeKey);
+
+  if (!bucket) {
+    // First request: full bucket, consume one token
+    bucket = { tokens: capacity - 1, lastRefill: now };
+    store.set(storeKey, bucket, config.windowMs * 2);
+    return new RateLimitResult({
+      allowed:   true,
+      limit:     capacity,
+      remaining: Math.floor(bucket.tokens),
+      resetAt:   now + config.windowMs,
+      retryAfter: 0,
+      key,
+      strategy: 'token-bucket',
+    });
+  }
+
+  // Refill tokens proportional to elapsed time
+  const elapsed = now - bucket.lastRefill;
+  bucket.tokens = Math.min(capacity, bucket.tokens + elapsed * refillRate);
+  bucket.lastRefill = now;
+
+  if (bucket.tokens < 1) {
+    // Not enough tokens: calculate when one token will be available
+    const msUntilToken = Math.ceil((1 - bucket.tokens) / refillRate);
+    store.set(storeKey, bucket, config.windowMs * 2);
+
+    return new RateLimitResult({
+      allowed:   false,
+      limit:     capacity,
+      remaining: 0,
+      resetAt:   now + msUntilToken,
+      retryAfter: Math.ceil(msUntilToken / 1000),
+      key,
+      strategy: 'token-bucket',
+    });
+  }
+
+  // Consume one token
+  bucket.tokens -= 1;
+  store.set(storeKey, bucket, config.windowMs * 2);
+
+  return new RateLimitResult({
+    allowed:   true,
+    limit:     capacity,
+    remaining: Math.floor(bucket.tokens),
+    resetAt:   now + Math.ceil((capacity - bucket.tokens) / refillRate),
+    retryAfter: 0,
+    key,
+    strategy: 'token-bucket',
+  });
+}
+
+module.exports = { tokenBucketCheck };

package/src/utils/keyGenerator.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Built-in key generators.
+ * Each returns a string that uniquely identifies the rate-limit subject.
+ */
+
+/**
+ * Extract real client IP, respecting common proxy headers.
+ * Order: X-Forwarded-For → X-Real-IP → req.ip → req.socket.remoteAddress
+ *
+ * @param {object} req - Express request
+ * @returns {string}
+ */
+function getIP(req) {
+  const forwarded = req.headers['x-forwarded-for'];
+  if (forwarded) {
+    // X-Forwarded-For can be a comma-separated list; first entry is client IP
+    return forwarded.split(',')[0].trim();
+  }
+  return (
+    req.headers['x-real-ip'] ||
+    req.ip ||
+    (req.socket && req.socket.remoteAddress) ||
+    'unknown'
+  );
+}
+
+/**
+ * Rate limit by authenticated user ID.
+ * Looks for userId in: req.user.id → req.user._id → req.userId → req.auth.userId
+ *
+ * Falls back to IP if no user is found (unauthenticated requests).
+ *
+ * @param {object} req
+ * @returns {string}
+ */
+function getUserId(req) {
+  const userId =
+    (req.user && (req.user.id || req.user._id || req.user.userId)) ||
+    req.userId ||
+    (req.auth && req.auth.userId);
+
+  return userId ? `user:${userId}` : `ip:${getIP(req)}`;
+}
+
+/**
+ * Rate limit by API key.
+ * Looks for key in: Authorization header (Bearer) → X-API-Key header → query.apiKey
+ *
+ * Falls back to IP if no API key found.
+ *
+ * @param {object} req
+ * @returns {string}
+ */
+function getApiKey(req) {
+  // Bearer token in Authorization header
+  const auth = req.headers['authorization'];
+  if (auth && auth.startsWith('Bearer ')) {
+    return `apikey:${auth.slice(7)}`;
+  }
+
+  // X-API-Key custom header
+  const headerKey = req.headers['x-api-key'];
+  if (headerKey) return `apikey:${headerKey}`;
+
+  // Query parameter fallback
+  const queryKey = req.query && req.query.apiKey;
+  if (queryKey) return `apikey:${queryKey}`;
+
+  // Final fallback: IP
+  return `ip:${getIP(req)}`;
+}
+
+/**
+ * Resolve a key generator function from the `keyBy` config value.
+ *
+ * @param {string|function} keyBy - 'ip' | 'user-id' | 'api-key' | custom fn
+ * @returns {function}
+ */
+function resolveKeyGenerator(keyBy) {
+  if (typeof keyBy === 'function') return keyBy;
+
+  switch (keyBy) {
+    case 'ip':      return getIP;
+    case 'user-id': return getUserId;
+    case 'api-key': return getApiKey;
+    default:
+      throw new Error(
+        `[NexLimit] Unknown keyBy value: "${keyBy}". Use 'ip', 'user-id', 'api-key', or a custom function.`
+      );
+  }
+}
+
+module.exports = { getIP, getUserId, getApiKey, resolveKeyGenerator };

package/src/utils/logger.js

@@ -0,0 +1,76 @@
+'use strict';
+
+// ANSI color codes — auto-disabled on non-TTY environments
+const isTTY = process.stdout && process.stdout.isTTY;
+const c = {
+  reset:  isTTY ? '\x1b[0m'  : '',
+  bold:   isTTY ? '\x1b[1m'  : '',
+  dim:    isTTY ? '\x1b[2m'  : '',
+  red:    isTTY ? '\x1b[31m' : '',
+  green:  isTTY ? '\x1b[32m' : '',
+  yellow: isTTY ? '\x1b[33m' : '',
+  cyan:   isTTY ? '\x1b[36m' : '',
+  gray:   isTTY ? '\x1b[90m' : '',
+};
+
+/**
+ * Create a logger bound to a specific prefix and enabled flag.
+ *
+ * @param {string}  prefix  - e.g. '[NexLimit]'
+ * @param {boolean} enabled - logging on/off
+ * @returns {{ blocked, allowed, warn, info }}
+ */
+function createLogger(prefix, enabled) {
+  if (!enabled) {
+    return {
+      blocked: () => {},
+      allowed: () => {},
+      warn:    () => {},
+      info:    () => {},
+    };
+  }
+
+  const tag = `${c.bold}${c.cyan}${prefix}${c.reset}`;
+  const ts  = () => `${c.gray}${new Date().toISOString()}${c.reset}`;
+
+  return {
+    /**
+     * Log a blocked request.
+     * @param {string} key
+     * @param {number} count
+     * @param {number} limit
+     * @param {string} strategy
+     * @param {boolean} smart
+     */
+    blocked(key, count, limit, strategy, smart = false) {
+      const smartTag = smart ? ` ${c.yellow}[smart]${c.reset}` : '';
+      console.log(
+        `${ts()} ${tag} ${c.red}BLOCKED${c.reset}${smartTag} ` +
+        `${c.bold}${key}${c.reset} ` +
+        `${c.red}(${count}/${limit})${c.reset} ` +
+        `${c.dim}via ${strategy}${c.reset}`
+      );
+    },
+
+    /**
+     * Log an allowed request (only useful for debugging — off by default).
+     */
+    allowed(key, remaining, limit) {
+      console.log(
+        `${ts()} ${tag} ${c.green}ALLOWED${c.reset} ` +
+        `${c.bold}${key}${c.reset} ` +
+        `${c.dim}(${remaining}/${limit} remaining)${c.reset}`
+      );
+    },
+
+    warn(message) {
+      console.warn(`${ts()} ${tag} ${c.yellow}WARN${c.reset} ${message}`);
+    },
+
+    info(message) {
+      console.log(`${ts()} ${tag} ${c.cyan}INFO${c.reset} ${message}`);
+    },
+  };
+}
+
+module.exports = { createLogger };