te.js 2.1.0 → 2.1.2

package/rate-limit/base.js

@@ -1,165 +1,165 @@
-import TejError from '../server/error.js';
-import MemoryStorage from './storage/memory.js';
-import RedisStorage from './storage/redis.js';
-import dbManager from '../database/index.js';
-
-/**
- * Base rate limiter class implementing common functionality for rate limiting algorithms
- *
- * @abstract
- * @class
- * @description
- * This is the base class for all rate limiting algorithms. It provides common configuration
- * options and storage handling, while allowing specific algorithms to implement their own logic.
- * Only one algorithm can be active per instance - the algorithm is determined by which options
- * object is provided (tokenBucketConfig, slidingWindowConfig, or fixedWindowConfig).
- *
- * @example
- * // Using with Redis storage and token bucket algorithm
- * const limiter = new TokenBucketRateLimiter({
- *   maxRequests: 10,
- *   timeWindowSeconds: 60,
- *   store: 'redis',
- *   tokenBucketConfig: {
- *     refillRate: 0.5,
- *     burstSize: 15
- *   }
- * });
- */
-class RateLimiter {
-  /**
-   * Creates a new rate limiter instance
-   *
-   * @param {Object} options - Configuration options for the rate limiter
-   * @param {number} [options.maxRequests=60] - Maximum number of requests allowed within the time window.
-   *                                           This is the default rate limit cap that applies across all algorithms.
-   *                                           For token bucket, this affects the default refill rate.
-   * @param {number} [options.timeWindowSeconds=60] - Time window in seconds for rate limiting.
-   *                                                 For fixed window, this is the window duration.
-   *                                                 For sliding window, this is the total time span considered.
-   *                                                 For token bucket, this affects the default refill rate calculation.
-   * @param {string} [options.keyPrefix='rl:'] - Prefix for storage keys. Useful when implementing different rate limit
-   *                                           rules with different prefixes (e.g., 'rl:api:', 'rl:web:').
-   * @param {string} [options.store='memory'] - Storage backend to use ('memory' or 'redis')
-   * @param {Object} [options.tokenBucketConfig] - Token bucket algorithm specific options
-   * @param {Object} [options.slidingWindowConfig] - Sliding window algorithm specific options
-   * @param {Object} [options.fixedWindowConfig] - Fixed window algorithm specific options
-   */
-  constructor(options) {
-    // Common options for all algorithms
-    this.options = {
-      maxRequests: 60, // Maximum number of requests
-      timeWindowSeconds: 60, // Time window in seconds
-      keyPrefix: 'rl:', // Key prefix for storage
-      store: 'memory', // Default to memory storage
-      ...options,
-    };
-
-    // Only one algorithm can be active per instance
-    if (options?.tokenBucketConfig && options?.slidingWindowConfig) {
-      throw new TejError(
-        400,
-        'Cannot use multiple rate limiting algorithms. Choose either tokenBucketConfig or slidingWindowConfig or fixedWindowConfig.',
-      );
-    }
-
-    if (options?.tokenBucketConfig && options?.fixedWindowConfig) {
-      throw new TejError(
-        500,
-        'Cannot use multiple rate limiting algorithms. Choose either tokenBucketConfig or slidingWindowConfig or fixedWindowConfig.',
-      );
-    }
-
-    if (options?.slidingWindowConfig && options?.fixedWindowConfig) {
-      throw new TejError(
-        500,
-        'Cannot use multiple rate limiting algorithms. Choose either tokenBucketConfig or slidingWindowConfig or fixedWindowConfig.',
-      );
-    }
-
-    // Set default values for algorithm options if any are provided
-    this.tokenBucketOptions = options?.tokenBucketConfig
-      ? {
-          refillRate: this.options.maxRequests / this.options.timeWindowSeconds, // Tokens per second
-          burstSize: this.options.maxRequests, // Maximum token capacity
-          ...options.tokenBucketConfig,
-        }
-      : null;
-
-    this.slidingWindowOptions = options?.slidingWindowConfig
-      ? {
-          granularity: 1, // Time precision in seconds
-          weights: { current: 1, previous: 0 }, // Weights for current and previous windows
-          ...options.slidingWindowConfig,
-        }
-      : null;
-
-    this.fixedWindowOptions = options?.fixedWindowConfig
-      ? {
-          strictWindow: false, // If true, windows align with clock
-          ...options.fixedWindowConfig,
-        }
-      : null;
-
-    // Initialize storage based on store type
-    if (this.options.store === 'redis') {
-      if (!dbManager.hasConnection('redis')) {
-        throw new TejError(
-          500,
-          'Redis store selected but no Redis connection available. Call withRedis() first.',
-        );
-      }
-      const redisClient = dbManager.getConnection('redis');
-      this.storage = new RedisStorage(redisClient);
-    } else {
-      this.storage = new MemoryStorage();
-    }
-  }
-
-  /**
-   * Generate storage key for the rate limit identifier
-   *
-   * @param {string} identifier - Unique identifier for the rate limit (e.g. IP address, user ID)
-   * @returns {string} The storage key with prefix
-   */
-  getKey(identifier) {
-    return `${this.options.keyPrefix}${identifier}`;
-  }
-
-  /**
-   * Abstract method for checking if request is allowed
-   * Must be implemented by concrete rate limiter classes
-   *
-   * @abstract
-   * @param {string} identifier - Unique identifier for the rate limit (e.g. IP address, user ID)
-   * @returns {Promise<Object>} Rate limit check result
-   * @returns {boolean} result.success - Whether the request is allowed
-   * @returns {number} result.remainingRequests - Number of requests remaining in the window
-   * @returns {number} result.resetTime - Unix timestamp when the rate limit resets
-   * @throws {Error} If not implemented by child class
-   */
-  async consume(identifier) {
-    throw new TejError(500, 'Not implemented');
-  }
-
-  /**
-   * Get algorithm-specific options for the specified algorithm type
-   *
-   * @param {string} type - Algorithm type ('tokenBucketConfig', 'slidingWindowConfig', or 'fixedWindowConfig')
-   * @returns {Object|null} The algorithm-specific options, or null if type not found
-   */
-  getAlgorithmOptions(type) {
-    switch (type) {
-      case 'token-bucket':
-        return this.tokenBucketOptions;
-      case 'sliding-window':
-        return this.slidingWindowOptions;
-      case 'fixed-window':
-        return this.fixedWindowOptions;
-      default:
-        return null;
-    }
-  }
-}
-
-export default RateLimiter;
+import TejError from '../server/error.js';
+import MemoryStorage from './storage/memory.js';
+import RedisStorage from './storage/redis.js';
+import dbManager from '../database/index.js';
+
+/**
+ * Base rate limiter class implementing common functionality for rate limiting algorithms
+ *
+ * @abstract
+ * @class
+ * @description
+ * This is the base class for all rate limiting algorithms. It provides common configuration
+ * options and storage handling, while allowing specific algorithms to implement their own logic.
+ * Only one algorithm can be active per instance - the algorithm is determined by which options
+ * object is provided (tokenBucketConfig, slidingWindowConfig, or fixedWindowConfig).
+ *
+ * @example
+ * // Using with Redis storage and token bucket algorithm
+ * const limiter = new TokenBucketRateLimiter({
+ *   maxRequests: 10,
+ *   timeWindowSeconds: 60,
+ *   store: 'redis',
+ *   tokenBucketConfig: {
+ *     refillRate: 0.5,
+ *     burstSize: 15
+ *   }
+ * });
+ */
+class RateLimiter {
+  /**
+   * Creates a new rate limiter instance
+   *
+   * @param {Object} options - Configuration options for the rate limiter
+   * @param {number} [options.maxRequests=60] - Maximum number of requests allowed within the time window.
+   *                                           This is the default rate limit cap that applies across all algorithms.
+   *                                           For token bucket, this affects the default refill rate.
+   * @param {number} [options.timeWindowSeconds=60] - Time window in seconds for rate limiting.
+   *                                                 For fixed window, this is the window duration.
+   *                                                 For sliding window, this is the total time span considered.
+   *                                                 For token bucket, this affects the default refill rate calculation.
+   * @param {string} [options.keyPrefix='rl:'] - Prefix for storage keys. Useful when implementing different rate limit
+   *                                           rules with different prefixes (e.g., 'rl:api:', 'rl:web:').
+   * @param {string} [options.store='memory'] - Storage backend to use ('memory' or 'redis')
+   * @param {Object} [options.tokenBucketConfig] - Token bucket algorithm specific options
+   * @param {Object} [options.slidingWindowConfig] - Sliding window algorithm specific options
+   * @param {Object} [options.fixedWindowConfig] - Fixed window algorithm specific options
+   */
+  constructor(options) {
+    // Common options for all algorithms
+    this.options = {
+      maxRequests: 60, // Maximum number of requests
+      timeWindowSeconds: 60, // Time window in seconds
+      keyPrefix: 'rl:', // Key prefix for storage
+      store: 'memory', // Default to memory storage
+      ...options,
+    };
+
+    // Only one algorithm can be active per instance
+    if (options?.tokenBucketConfig && options?.slidingWindowConfig) {
+      throw new TejError(
+        400,
+        'Cannot use multiple rate limiting algorithms. Choose either tokenBucketConfig or slidingWindowConfig or fixedWindowConfig.',
+      );
+    }
+
+    if (options?.tokenBucketConfig && options?.fixedWindowConfig) {
+      throw new TejError(
+        500,
+        'Cannot use multiple rate limiting algorithms. Choose either tokenBucketConfig or slidingWindowConfig or fixedWindowConfig.',
+      );
+    }
+
+    if (options?.slidingWindowConfig && options?.fixedWindowConfig) {
+      throw new TejError(
+        500,
+        'Cannot use multiple rate limiting algorithms. Choose either tokenBucketConfig or slidingWindowConfig or fixedWindowConfig.',
+      );
+    }
+
+    // Set default values for algorithm options if any are provided
+    this.tokenBucketOptions = options?.tokenBucketConfig
+      ? {
+          refillRate: this.options.maxRequests / this.options.timeWindowSeconds, // Tokens per second
+          burstSize: this.options.maxRequests, // Maximum token capacity
+          ...options.tokenBucketConfig,
+        }
+      : null;
+
+    this.slidingWindowOptions = options?.slidingWindowConfig
+      ? {
+          granularity: 1, // Time precision in seconds
+          weights: { current: 1, previous: 0 }, // Weights for current and previous windows
+          ...options.slidingWindowConfig,
+        }
+      : null;
+
+    this.fixedWindowOptions = options?.fixedWindowConfig
+      ? {
+          strictWindow: false, // If true, windows align with clock
+          ...options.fixedWindowConfig,
+        }
+      : null;
+
+    // Initialize storage based on store type
+    if (this.options.store === 'redis') {
+      if (!dbManager.hasConnection('redis')) {
+        throw new TejError(
+          500,
+          'Redis store selected but no Redis connection available. Call withRedis() first.',
+        );
+      }
+      const redisClient = dbManager.getConnection('redis');
+      this.storage = new RedisStorage(redisClient);
+    } else {
+      this.storage = new MemoryStorage();
+    }
+  }
+
+  /**
+   * Generate storage key for the rate limit identifier
+   *
+   * @param {string} identifier - Unique identifier for the rate limit (e.g. IP address, user ID)
+   * @returns {string} The storage key with prefix
+   */
+  getKey(identifier) {
+    return `${this.options.keyPrefix}${identifier}`;
+  }
+
+  /**
+   * Abstract method for checking if request is allowed
+   * Must be implemented by concrete rate limiter classes
+   *
+   * @abstract
+   * @param {string} identifier - Unique identifier for the rate limit (e.g. IP address, user ID)
+   * @returns {Promise<Object>} Rate limit check result
+   * @returns {boolean} result.success - Whether the request is allowed
+   * @returns {number} result.remainingRequests - Number of requests remaining in the window
+   * @returns {number} result.resetTime - Unix timestamp when the rate limit resets
+   * @throws {Error} If not implemented by child class
+   */
+  async consume(identifier) {
+    throw new TejError(500, 'Not implemented');
+  }
+
+  /**
+   * Get algorithm-specific options for the specified algorithm type
+   *
+   * @param {string} type - Algorithm type ('tokenBucketConfig', 'slidingWindowConfig', or 'fixedWindowConfig')
+   * @returns {Object|null} The algorithm-specific options, or null if type not found
+   */
+  getAlgorithmOptions(type) {
+    switch (type) {
+      case 'token-bucket':
+        return this.tokenBucketOptions;
+      case 'sliding-window':
+        return this.slidingWindowOptions;
+      case 'fixed-window':
+        return this.fixedWindowOptions;
+      default:
+        return null;
+    }
+  }
+}
+
+export default RateLimiter;

package/rate-limit/index.js

@@ -1,147 +1,147 @@
-import TejError from '../server/error.js';
-import FixedWindowRateLimiter from './algorithms/fixed-window.js';
-import SlidingWindowRateLimiter from './algorithms/sliding-window.js';
-import TokenBucketRateLimiter from './algorithms/token-bucket.js';
-import dbManager from '../database/index.js';
-
-/**
- * Creates a rate limiting middleware function with the specified algorithm and storage
- *
- * @param {Object} options - Configuration options for the rate limiter
- * @param {number} options.maxRequests - Maximum number of requests allowed within the time window
- * @param {number} options.timeWindowSeconds - Time window in seconds
- * @param {string} [options.algorithm='sliding-window'] - Rate limiting algorithm to use:
- *                                                     - 'token-bucket': Best for handling traffic bursts
- *                                                     - 'sliding-window': Best for smooth rate limiting
- *                                                     - 'fixed-window': Simplest approach
- * @param {string} [options.store='memory'] - Storage backend to use:
- *                                         - 'memory': In-memory storage (default)
- *                                         - 'redis': Redis-based storage (requires global Redis config)
- * @param {Object} [options.algorithmOptions] - Algorithm-specific options
- * @param {Function} [options.keyGenerator] - Optional function to generate unique identifiers
- * @param {Object} [options.headerFormat] - Rate limit header format configuration
- * @param {string} [options.headerFormat.type='standard'] - Type of headers to use:
- *                                                       - 'legacy': Use X-RateLimit-* headers
- *                                                       - 'standard': Use RateLimit-* headers (draft 6+)
- *                                                       - 'both': Use both legacy and standard headers
- * @param {boolean} [options.headerFormat.draft7=false] - Whether to include draft 7 policy header
- * @param {boolean} [options.headerFormat.draft8=false] - Whether to include draft 8 reset format
- * @param {Function} [options.onRateLimited] - Optional callback when rate limit is exceeded
- * @returns {Function} Middleware function for use with te.js
- */
-function rateLimiter(options) {
-  const {
-    algorithm = 'sliding-window',
-    store = 'memory',
-    keyGenerator = (ammo) => ammo.ip,
-    headerFormat = { type: 'standard' },
-    onRateLimited,
-    ...limiterOptions
-  } = options;
-
-  // Check Redis connectivity if Redis store is selected
-  if (store === 'redis' && !dbManager.hasConnection('redis', {})) {
-    throw new TejError(
-      400,
-      'Redis store selected but no Redis connection found. Please use withRedis() before using withRateLimit()',
-    );
-  }
-
-  // Map algorithm names to their config property names
-  const configMap = {
-    'token-bucket': 'tokenBucketConfig',
-    'sliding-window': 'slidingWindowConfig',
-    'fixed-window': 'fixedWindowConfig',
-  };
-
-  const configKey = configMap[algorithm];
-  if (!configKey) {
-    throw new TejError(
-      400,
-      `Invalid algorithm: ${algorithm}. Must be one of: ${Object.keys(configMap).join(', ')}`,
-    );
-  }
-
-  // Create algorithm-specific config
-  const limiterConfig = {
-    maxRequests: limiterOptions.maxRequests,
-    timeWindowSeconds: limiterOptions.timeWindowSeconds,
-    [configKey]: limiterOptions.algorithmOptions || {},
-    store, // Pass the store type to the limiter
-  };
-
-  // Create the appropriate limiter instance
-  let limiter;
-  switch (algorithm) {
-    case 'token-bucket':
-      limiter = new TokenBucketRateLimiter(limiterConfig);
-      break;
-    case 'sliding-window':
-      limiter = new SlidingWindowRateLimiter(limiterConfig);
-      break;
-    case 'fixed-window':
-      limiter = new FixedWindowRateLimiter(limiterConfig);
-      break;
-    default:
-      throw new TejError(400, 'Invalid algorithm specified');
-  }
-
-  // Helper to set headers based on format
-  const setRateLimitHeaders = (ammo, result) => {
-    const { type = 'standard', draft7 = false, draft8 = false } = headerFormat;
-    const useStandard = type === 'standard' || type === 'both';
-    const useLegacy = type === 'legacy' || type === 'both';
-
-    if (useStandard) {
-      // Standard headers (draft 6+)
-      ammo.res.setHeader('RateLimit-Limit', limiter.options.maxRequests);
-      ammo.res.setHeader('RateLimit-Remaining', result.remainingRequests);
-
-      // Draft 8 uses delta-seconds format
-      if (draft8) {
-        const resetDelta = result.resetTime - Math.floor(Date.now() / 1000);
-        ammo.res.setHeader('RateLimit-Reset', resetDelta);
-      } else {
-        ammo.res.setHeader('RateLimit-Reset', result.resetTime);
-      }
-
-      // Draft 7 added optional policy information
-      if (draft7) {
-        const policy = `${limiter.options.maxRequests};w=${limiter.options.timeWindowSeconds}`;
-        ammo.res.setHeader('RateLimit-Policy', policy);
-      }
-    }
-
-    if (useLegacy) {
-      // Legacy X- headers
-      ammo.res.setHeader('X-RateLimit-Limit', limiter.options.maxRequests);
-      ammo.res.setHeader('X-RateLimit-Remaining', result.remainingRequests);
-      ammo.res.setHeader('X-RateLimit-Reset', result.resetTime);
-    }
-
-    // Always set Retry-After on 429 responses
-    if (!result.success) {
-      const retryAfter = result.resetTime - Math.floor(Date.now() / 1000);
-      ammo.res.setHeader('Retry-After', retryAfter);
-    }
-  };
-
-  // Return middleware function
-  return async (ammo, next) => {
-    const key = keyGenerator(ammo);
-    const result = await limiter.consume(key);
-
-    setRateLimitHeaders(ammo, result);
-
-    if (!result.success) {
-      if (onRateLimited) {
-        return onRateLimited(ammo);
-      }
-      return ammo.throw(429, 'Too Many Requests');
-    }
-
-    await next();
-  };
-}
-
-export default rateLimiter;
+import TejError from '../server/error.js';
+import FixedWindowRateLimiter from './algorithms/fixed-window.js';
+import SlidingWindowRateLimiter from './algorithms/sliding-window.js';
+import TokenBucketRateLimiter from './algorithms/token-bucket.js';
+import dbManager from '../database/index.js';
+
+/**
+ * Creates a rate limiting middleware function with the specified algorithm and storage
+ *
+ * @param {Object} options - Configuration options for the rate limiter
+ * @param {number} options.maxRequests - Maximum number of requests allowed within the time window
+ * @param {number} options.timeWindowSeconds - Time window in seconds
+ * @param {string} [options.algorithm='sliding-window'] - Rate limiting algorithm to use:
+ *                                                     - 'token-bucket': Best for handling traffic bursts
+ *                                                     - 'sliding-window': Best for smooth rate limiting
+ *                                                     - 'fixed-window': Simplest approach
+ * @param {string} [options.store='memory'] - Storage backend to use:
+ *                                         - 'memory': In-memory storage (default)
+ *                                         - 'redis': Redis-based storage (requires global Redis config)
+ * @param {Object} [options.algorithmOptions] - Algorithm-specific options
+ * @param {Function} [options.keyGenerator] - Optional function to generate unique identifiers
+ * @param {Object} [options.headerFormat] - Rate limit header format configuration
+ * @param {string} [options.headerFormat.type='standard'] - Type of headers to use:
+ *                                                       - 'legacy': Use X-RateLimit-* headers
+ *                                                       - 'standard': Use RateLimit-* headers (draft 6+)
+ *                                                       - 'both': Use both legacy and standard headers
+ * @param {boolean} [options.headerFormat.draft7=false] - Whether to include draft 7 policy header
+ * @param {boolean} [options.headerFormat.draft8=false] - Whether to include draft 8 reset format
+ * @param {Function} [options.onRateLimited] - Optional callback when rate limit is exceeded
+ * @returns {Function} Middleware function for use with te.js
+ */
+function rateLimiter(options) {
+  const {
+    algorithm = 'sliding-window',
+    store = 'memory',
+    keyGenerator = (ammo) => ammo.ip,
+    headerFormat = { type: 'standard' },
+    onRateLimited,
+    ...limiterOptions
+  } = options;
+
+  // Check Redis connectivity if Redis store is selected
+  if (store === 'redis' && !dbManager.hasConnection('redis', {})) {
+    throw new TejError(
+      400,
+      'Redis store selected but no Redis connection found. Please use withRedis() before using withRateLimit()',
+    );
+  }
+
+  // Map algorithm names to their config property names
+  const configMap = {
+    'token-bucket': 'tokenBucketConfig',
+    'sliding-window': 'slidingWindowConfig',
+    'fixed-window': 'fixedWindowConfig',
+  };
+
+  const configKey = configMap[algorithm];
+  if (!configKey) {
+    throw new TejError(
+      400,
+      `Invalid algorithm: ${algorithm}. Must be one of: ${Object.keys(configMap).join(', ')}`,
+    );
+  }
+
+  // Create algorithm-specific config
+  const limiterConfig = {
+    maxRequests: limiterOptions.maxRequests,
+    timeWindowSeconds: limiterOptions.timeWindowSeconds,
+    [configKey]: limiterOptions.algorithmOptions || {},
+    store, // Pass the store type to the limiter
+  };
+
+  // Create the appropriate limiter instance
+  let limiter;
+  switch (algorithm) {
+    case 'token-bucket':
+      limiter = new TokenBucketRateLimiter(limiterConfig);
+      break;
+    case 'sliding-window':
+      limiter = new SlidingWindowRateLimiter(limiterConfig);
+      break;
+    case 'fixed-window':
+      limiter = new FixedWindowRateLimiter(limiterConfig);
+      break;
+    default:
+      throw new TejError(400, 'Invalid algorithm specified');
+  }
+
+  // Helper to set headers based on format
+  const setRateLimitHeaders = (ammo, result) => {
+    const { type = 'standard', draft7 = false, draft8 = false } = headerFormat;
+    const useStandard = type === 'standard' || type === 'both';
+    const useLegacy = type === 'legacy' || type === 'both';
+
+    if (useStandard) {
+      // Standard headers (draft 6+)
+      ammo.res.setHeader('RateLimit-Limit', limiter.options.maxRequests);
+      ammo.res.setHeader('RateLimit-Remaining', result.remainingRequests);
+
+      // Draft 8 uses delta-seconds format
+      if (draft8) {
+        const resetDelta = result.resetTime - Math.floor(Date.now() / 1000);
+        ammo.res.setHeader('RateLimit-Reset', resetDelta);
+      } else {
+        ammo.res.setHeader('RateLimit-Reset', result.resetTime);
+      }
+
+      // Draft 7 added optional policy information
+      if (draft7) {
+        const policy = `${limiter.options.maxRequests};w=${limiter.options.timeWindowSeconds}`;
+        ammo.res.setHeader('RateLimit-Policy', policy);
+      }
+    }
+
+    if (useLegacy) {
+      // Legacy X- headers
+      ammo.res.setHeader('X-RateLimit-Limit', limiter.options.maxRequests);
+      ammo.res.setHeader('X-RateLimit-Remaining', result.remainingRequests);
+      ammo.res.setHeader('X-RateLimit-Reset', result.resetTime);
+    }
+
+    // Always set Retry-After on 429 responses
+    if (!result.success) {
+      const retryAfter = result.resetTime - Math.floor(Date.now() / 1000);
+      ammo.res.setHeader('Retry-After', retryAfter);
+    }
+  };
+
+  // Return middleware function
+  return async (ammo, next) => {
+    const key = keyGenerator(ammo);
+    const result = await limiter.consume(key);
+
+    setRateLimitHeaders(ammo, result);
+
+    if (!result.success) {
+      if (onRateLimited) {
+        return onRateLimited(ammo);
+      }
+      return ammo.throw(429, 'Too Many Requests');
+    }
+
+    await next();
+  };
+}
+
+export default rateLimiter;