ratelimit-engine 0.0.0-stage → 1.0.0

package/src/algorithms/FixedWindow.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Fixed Window algorithm.
+ * Counts requests in a fixed time window that resets at a hard boundary.
+ * Simple and cheap. Known issue: bursts are possible at window boundaries.
+ */
+
+import { BaseAlgorithm } from './BaseAlgorithm.js'
+import { ErrorFactory }  from '../errors/ErrorFactory.js'
+import { ALGORITHM_NAMES } from '../constants/algorithms.js'
+import { DEFAULTS }        from '../constants/defaults.js'
+import { createLogger }    from '../logger/LoggerFactory.js'
+
+const logger = createLogger('FixedWindow')
+
+export class FixedWindow extends BaseAlgorithm {
+  /**
+   * @param {Object} options
+   * @param {number} options.limit     - Max requests per window.
+   * @param {number} options.windowMs  - Window duration in milliseconds.
+   */
+  constructor({ limit = DEFAULTS.MAX_REQUESTS, windowMs = DEFAULTS.WINDOW_MS } = {}) {
+    super(ALGORITHM_NAMES.FIXED_WINDOW)
+
+    if (limit <= 0) {
+      throw ErrorFactory.invalidValue('limit', limit, 'must be a positive integer')
+    }
+    if (windowMs <= 0) {
+      throw ErrorFactory.invalidValue('windowMs', windowMs, 'must be a positive integer')
+    }
+
+    this._limit    = limit
+    this._windowMs = windowMs
+  }
+
+  /**
+   * @param {string} key
+   * @param {import('../stores/BaseStore.js').BaseStore} store
+   * @returns {Promise<import('../types/index.js').RateLimitResult>}
+   */
+  async check(key, store) {
+    const now        = Date.now()
+    const windowKey  = `${key}:${Math.floor(now / this._windowMs)}`
+    const count      = await store.increment(windowKey, this._windowMs)
+    const resetAt    = new Date(Math.ceil(now / this._windowMs) * this._windowMs)
+    const remaining  = Math.max(0, this._limit - count)
+    const allowed    = count <= this._limit
+
+    logger.debug('Fixed window check', { key, count, limit: this._limit, allowed })
+
+    return {
+      allowed,
+      limit:       this._limit,
+      remaining,
+      resetAt,
+      retryAfter:  allowed ? undefined : Math.ceil((resetAt - now) / 1000),
+    }
+  }
+
+  /**
+   * @param {string} key
+   * @param {import('../stores/BaseStore.js').BaseStore} store
+   * @returns {Promise<void>}
+   */
+  async reset(key, store) {
+    const now       = Date.now()
+    const windowKey = `${key}:${Math.floor(now / this._windowMs)}`
+    await store.delete(windowKey)
+    logger.debug('Fixed window reset', { key })
+  }
+}

package/src/algorithms/LeakyBucket.js

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview Leaky Bucket algorithm.
+ * Requests are processed at a fixed leak rate regardless of burst size.
+ * Excess requests are dropped. Ideal for strict output rate control.
+ */
+
+import { BaseAlgorithm } from './BaseAlgorithm.js'
+import { ErrorFactory }  from '../errors/ErrorFactory.js'
+import { ALGORITHM_NAMES } from '../constants/algorithms.js'
+import { DEFAULTS }        from '../constants/defaults.js'
+import { createLogger }    from '../logger/LoggerFactory.js'
+
+const logger = createLogger('LeakyBucket')
+
+export class LeakyBucket extends BaseAlgorithm {
+  /**
+   * @param {Object} options
+   * @param {number} options.capacity  - Max bucket size (queue depth).
+   * @param {number} options.leakRate  - Requests allowed per second.
+   */
+  constructor({
+    capacity  = DEFAULTS.LEAKY_BUCKET_CAPACITY,
+    leakRate  = DEFAULTS.LEAKY_BUCKET_LEAK_RATE,
+  } = {}) {
+    super(ALGORITHM_NAMES.LEAKY_BUCKET)
+
+    if (capacity <= 0) {
+      throw ErrorFactory.invalidValue('capacity', capacity, 'must be a positive integer')
+    }
+    if (leakRate <= 0) {
+      throw ErrorFactory.invalidValue('leakRate', leakRate, 'must be a positive number')
+    }
+
+    this._capacity = capacity
+    this._leakRate = leakRate
+  }
+
+  /**
+   * @param {string} key
+   * @param {import('../stores/BaseStore.js').BaseStore} store
+   * @returns {Promise<import('../types/index.js').RateLimitResult>}
+   */
+  async check(key, store) {
+    const now      = Date.now()
+    const ttlMs    = Math.ceil((this._capacity / this._leakRate) * 1000)
+    const entry    = await store.get(key)
+    const lastMeta = entry?.meta ?? { queue: 0, lastLeak: now }
+
+    const elapsed   = (now - lastMeta.lastLeak) / 1000
+    const leaked    = elapsed * this._leakRate
+    const queue     = Math.max(0, lastMeta.queue - leaked)
+    const allowed   = queue < this._capacity
+    const newQueue  = allowed ? queue + 1 : queue
+    const remaining = Math.max(0, this._capacity - Math.ceil(newQueue))
+
+    const msUntilSlot = allowed
+      ? 0
+      : Math.ceil((queue - this._capacity + 1) / this._leakRate * 1000)
+    const resetAt = new Date(now + msUntilSlot)
+
+    await store.set(key, {
+      count:       Math.ceil(newQueue),
+      windowStart: now,
+      expiresAt:   now + ttlMs,
+      meta:        { queue: newQueue, lastLeak: now },
+    }, ttlMs)
+
+    logger.debug('Leaky bucket check', { key, queue, newQueue, allowed })
+
+    return {
+      allowed,
+      limit:      this._capacity,
+      remaining,
+      resetAt,
+      retryAfter: allowed ? undefined : Math.ceil(msUntilSlot / 1000),
+    }
+  }
+
+  /**
+   * @param {string} key
+   * @param {import('../stores/BaseStore.js').BaseStore} store
+   * @returns {Promise<void>}
+   */
+  async reset(key, store) {
+    await store.delete(key)
+    logger.debug('Leaky bucket reset', { key })
+  }
+}

package/src/algorithms/SlidingWindow.js

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview Sliding Window Log algorithm.
+ * Counts requests within a rolling window from "now - windowMs" to "now".
+ * Eliminates the boundary spike problem of Fixed Window.
+ */
+
+import { BaseAlgorithm } from './BaseAlgorithm.js'
+import { ErrorFactory }  from '../errors/ErrorFactory.js'
+import { ALGORITHM_NAMES } from '../constants/algorithms.js'
+import { DEFAULTS }        from '../constants/defaults.js'
+import { createLogger }    from '../logger/LoggerFactory.js'
+
+const logger = createLogger('SlidingWindow')
+
+export class SlidingWindow extends BaseAlgorithm {
+  /**
+   * @param {Object} options
+   * @param {number} options.limit     - Max requests per window.
+   * @param {number} options.windowMs  - Window duration in milliseconds.
+   */
+  constructor({ limit = DEFAULTS.MAX_REQUESTS, windowMs = DEFAULTS.WINDOW_MS } = {}) {
+    super(ALGORITHM_NAMES.SLIDING_WINDOW)
+
+    if (limit <= 0) {
+      throw ErrorFactory.invalidValue('limit', limit, 'must be a positive integer')
+    }
+    if (windowMs <= 0) {
+      throw ErrorFactory.invalidValue('windowMs', windowMs, 'must be a positive integer')
+    }
+
+    this._limit    = limit
+    this._windowMs = windowMs
+  }
+
+  /**
+   * Uses a weighted count across the current and previous windows
+   * to approximate a true sliding window without storing per-request timestamps.
+   *
+   * @param {string} key
+   * @param {import('../stores/BaseStore.js').BaseStore} store
+   * @returns {Promise<import('../types/index.js').RateLimitResult>}
+   */
+  async check(key, store) {
+    const now          = Date.now()
+    const currentSlot  = Math.floor(now / this._windowMs)
+    const prevSlot     = currentSlot - 1
+    const currentKey   = `${key}:${currentSlot}`
+    const prevKey      = `${key}:${prevSlot}`
+
+    const [currentEntry, prevEntry] = await Promise.all([
+      store.get(currentKey),
+      store.get(prevKey),
+    ])
+
+    const currentCount = currentEntry?.count ?? 0
+    const prevCount    = prevEntry?.count    ?? 0
+
+    // Weight the previous window count by how far into the current window we are
+    const windowProgress = (now % this._windowMs) / this._windowMs
+    const weightedCount  = Math.floor(prevCount * (1 - windowProgress)) + currentCount
+
+    const newCount  = await store.increment(currentKey, this._windowMs * 2)
+    const totalCount = Math.floor(prevCount * (1 - windowProgress)) + newCount
+    const remaining  = Math.max(0, this._limit - totalCount)
+    const allowed    = totalCount <= this._limit
+    const resetAt    = new Date((currentSlot + 1) * this._windowMs)
+
+    logger.debug('Sliding window check', {
+      key,
+      weightedCount,
+      totalCount,
+      limit: this._limit,
+      allowed,
+    })
+
+    return {
+      allowed,
+      limit:      this._limit,
+      remaining,
+      resetAt,
+      retryAfter: allowed ? undefined : Math.ceil((resetAt - now) / 1000),
+    }
+  }
+
+  /**
+   * @param {string} key
+   * @param {import('../stores/BaseStore.js').BaseStore} store
+   * @returns {Promise<void>}
+   */
+  async reset(key, store) {
+    const now         = Date.now()
+    const currentSlot = Math.floor(now / this._windowMs)
+    await Promise.all([
+      store.delete(`${key}:${currentSlot}`),
+      store.delete(`${key}:${currentSlot - 1}`),
+    ])
+    logger.debug('Sliding window reset', { key })
+  }
+}

package/src/algorithms/TokenBucket.js

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Token Bucket algorithm.
+ * Tokens refill at a fixed rate up to a maximum capacity.
+ * Allows controlled bursting — ideal for API gateways.
+ */
+
+import { BaseAlgorithm } from './BaseAlgorithm.js'
+import { ErrorFactory }  from '../errors/ErrorFactory.js'
+import { ALGORITHM_NAMES } from '../constants/algorithms.js'
+import { DEFAULTS }        from '../constants/defaults.js'
+import { createLogger }    from '../logger/LoggerFactory.js'
+
+const logger = createLogger('TokenBucket')
+
+export class TokenBucket extends BaseAlgorithm {
+  /**
+   * @param {Object} options
+   * @param {number} options.capacity    - Maximum tokens the bucket can hold.
+   * @param {number} options.refillRate  - Tokens added per second.
+   */
+  constructor({
+    capacity   = DEFAULTS.TOKEN_BUCKET_CAPACITY,
+    refillRate = DEFAULTS.TOKEN_BUCKET_REFILL_RATE,
+  } = {}) {
+    super(ALGORITHM_NAMES.TOKEN_BUCKET)
+
+    if (capacity <= 0) {
+      throw ErrorFactory.invalidValue('capacity', capacity, 'must be a positive integer')
+    }
+    if (refillRate <= 0) {
+      throw ErrorFactory.invalidValue('refillRate', refillRate, 'must be a positive number')
+    }
+
+    this._capacity   = capacity
+    this._refillRate = refillRate
+  }
+
+  /**
+   * @param {string} key
+   * @param {import('../stores/BaseStore.js').BaseStore} store
+   * @returns {Promise<import('../types/index.js').RateLimitResult>}
+   */
+  async check(key, store) {
+    const now       = Date.now()
+    const ttlMs     = Math.ceil((this._capacity / this._refillRate) * 1000)
+    const entry     = await store.get(key)
+    const lastEntry = entry?.meta ?? { tokens: this._capacity, lastRefill: now }
+
+    const elapsed       = (now - lastEntry.lastRefill) / 1000
+    const refilled      = elapsed * this._refillRate
+    const tokensNow     = Math.min(this._capacity, lastEntry.tokens + refilled)
+    const allowed       = tokensNow >= 1
+    const tokensAfter   = allowed ? tokensNow - 1 : tokensNow
+    const remaining     = Math.floor(tokensAfter)
+    const msUntilToken  = allowed ? 0 : Math.ceil((1 - tokensNow) / this._refillRate * 1000)
+    const resetAt       = new Date(now + msUntilToken)
+
+    await store.set(key, {
+      count:       this._capacity - remaining,
+      windowStart: now,
+      expiresAt:   now + ttlMs,
+      meta:        { tokens: tokensAfter, lastRefill: now },
+    }, ttlMs)
+
+    logger.debug('Token bucket check', { key, tokensNow, tokensAfter, allowed })
+
+    return {
+      allowed,
+      limit:      this._capacity,
+      remaining,
+      resetAt,
+      retryAfter: allowed ? undefined : Math.ceil(msUntilToken / 1000),
+    }
+  }
+
+  /**
+   * @param {string} key
+   * @param {import('../stores/BaseStore.js').BaseStore} store
+   * @returns {Promise<void>}
+   */
+  async reset(key, store) {
+    await store.delete(key)
+    logger.debug('Token bucket reset', { key })
+  }
+}

package/src/constants/algorithms.js

@@ -0,0 +1,18 @@
+/**
+ * Supported built-in algorithm identifiers.
+ */
+export const ALGORITHM_NAMES = Object.freeze({
+  FIXED_WINDOW:   'fixed-window',
+  SLIDING_WINDOW: 'sliding-window',
+  TOKEN_BUCKET:   'token-bucket',
+  LEAKY_BUCKET:   'leaky-bucket',
+  COMPOSITE:      'composite',
+})
+
+/**
+ * Composite algorithm evaluation modes.
+ */
+export const COMPOSITE_MODES = Object.freeze({
+  ALL: 'ALL',
+  ANY: 'ANY',
+})

package/src/constants/defaults.js

@@ -0,0 +1,15 @@
+/**
+ * Default configuration values used across the engine.
+ * All time values are in milliseconds unless noted.
+ */
+export const DEFAULTS = Object.freeze({
+  WINDOW_MS:            60_000,
+  MAX_REQUESTS:         100,
+  FAIL_OPEN:            true,
+  TOKEN_BUCKET_CAPACITY:    100,
+  TOKEN_BUCKET_REFILL_RATE: 10,
+  LEAKY_BUCKET_CAPACITY:    100,
+  LEAKY_BUCKET_LEAK_RATE:   10,
+  STORE_TTL_BUFFER_MS:  5_000,
+  KEY_PREFIX:           'rle:',
+})

package/src/constants/errors.js

@@ -0,0 +1,42 @@
+/**
+ * Error codes used across the engine.
+ * Each code maps to a unique, machine-readable string.
+ */
+export const ERROR_CODES = Object.freeze({
+  CONFIGURATION_MISSING_FIELD:   'CONFIGURATION_MISSING_FIELD',
+  CONFIGURATION_INVALID_VALUE:   'CONFIGURATION_INVALID_VALUE',
+  CONFIGURATION_INVALID_ALGO:    'CONFIGURATION_INVALID_ALGO',
+  CONFIGURATION_INVALID_STORE:   'CONFIGURATION_INVALID_STORE',
+
+  STORE_UNAVAILABLE:             'STORE_UNAVAILABLE',
+  STORE_READ_FAILED:             'STORE_READ_FAILED',
+  STORE_WRITE_FAILED:            'STORE_WRITE_FAILED',
+
+  RATE_LIMIT_EXCEEDED:           'RATE_LIMIT_EXCEEDED',
+
+  ALGORITHM_CHECK_FAILED:        'ALGORITHM_CHECK_FAILED',
+  ALGORITHM_RESET_FAILED:        'ALGORITHM_RESET_FAILED',
+
+  ADAPTER_INVALID_REQUEST:       'ADAPTER_INVALID_REQUEST',
+})
+
+/**
+ * Human-readable error messages keyed by error code.
+ */
+export const ERROR_MESSAGES = Object.freeze({
+  [ERROR_CODES.CONFIGURATION_MISSING_FIELD]: 'Required configuration field is missing',
+  [ERROR_CODES.CONFIGURATION_INVALID_VALUE]: 'Configuration field has an invalid value',
+  [ERROR_CODES.CONFIGURATION_INVALID_ALGO]:  'Provided algorithm is not a valid BaseAlgorithm instance',
+  [ERROR_CODES.CONFIGURATION_INVALID_STORE]: 'Provided store is not a valid BaseStore instance',
+
+  [ERROR_CODES.STORE_UNAVAILABLE]:           'Store is currently unavailable',
+  [ERROR_CODES.STORE_READ_FAILED]:           'Store read operation failed',
+  [ERROR_CODES.STORE_WRITE_FAILED]:          'Store write operation failed',
+
+  [ERROR_CODES.RATE_LIMIT_EXCEEDED]:         'Rate limit exceeded',
+
+  [ERROR_CODES.ALGORITHM_CHECK_FAILED]:      'Algorithm check operation failed',
+  [ERROR_CODES.ALGORITHM_RESET_FAILED]:      'Algorithm reset operation failed',
+
+  [ERROR_CODES.ADAPTER_INVALID_REQUEST]:     'Adapter received an invalid request object',
+})

package/src/constants/headers.js

@@ -0,0 +1,18 @@
+/**
+ * Standard HTTP response header names used by the engine.
+ */
+export const HEADERS = Object.freeze({
+  LIMIT:       'X-RateLimit-Limit',
+  REMAINING:   'X-RateLimit-Remaining',
+  RESET:       'X-RateLimit-Reset',
+  RETRY_AFTER: 'Retry-After',
+  POLICY:      'X-RateLimit-Policy',
+})
+
+/**
+ * HTTP status codes used by rate limit responses.
+ */
+export const HTTP_STATUS = Object.freeze({
+  TOO_MANY_REQUESTS: 429,
+  OK:                200,
+})

package/src/constants/store.js

@@ -0,0 +1,20 @@
+/**
+ * Store-related constants shared across MemoryStore and RedisStore.
+ */
+export const STORE_TYPES = Object.freeze({
+  MEMORY: 'memory',
+  REDIS:  'redis',
+})
+
+/**
+ * Redis Lua script keys used for atomic operations.
+ */
+export const REDIS_SCRIPTS = Object.freeze({
+  INCREMENT_WITH_TTL: 'increment_with_ttl',
+  GET_AND_SET:        'get_and_set',
+})
+
+/**
+ * Cleanup interval for MemoryStore expired-entry eviction (ms).
+ */
+export const MEMORY_STORE_CLEANUP_INTERVAL_MS = 30_000

package/src/engine/HeaderWriter.js

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Writes standard rate limit headers onto HTTP responses.
+ */
+
+import { HEADERS, HTTP_STATUS } from '../constants/headers.js'
+import { createLogger }         from '../logger/LoggerFactory.js'
+
+const logger = createLogger('HeaderWriter')
+
+export class HeaderWriter {
+  /**
+   * Writes X-RateLimit-* headers and optionally Retry-After onto a response object.
+   * Works with any response that exposes a setHeader(name, value) method.
+   *
+   * @param {Object}                                      res     - Framework response object.
+   * @param {import('../types/index.js').RateLimitResult} result
+   */
+  write(res, result) {
+    try {
+      res.setHeader(HEADERS.LIMIT,     String(result.limit))
+      res.setHeader(HEADERS.REMAINING, String(result.remaining))
+      res.setHeader(HEADERS.RESET,     String(Math.floor(result.resetAt.getTime() / 1000)))
+
+      if (!result.allowed && result.retryAfter !== undefined) {
+        res.setHeader(HEADERS.RETRY_AFTER, String(result.retryAfter))
+      }
+    } catch (err) {
+      logger.warn('Failed to write rate limit headers', { error: err.message })
+    }
+  }
+
+  /**
+   * Sends a 429 Too Many Requests response with a JSON body.
+   * Works with Express and Fastify response objects.
+   *
+   * @param {Object}                                      res
+   * @param {import('../types/index.js').RateLimitResult} result
+   */
+  sendBlocked(res, result) {
+    this.write(res, result)
+
+    const body = JSON.stringify({
+      error:      'Too Many Requests',
+      retryAfter: result.retryAfter,
+      resetAt:    result.resetAt.toISOString(),
+    })
+
+    if (typeof res.status === 'function') {
+      res.status(HTTP_STATUS.TOO_MANY_REQUESTS).send(body)
+    } else {
+      res.statusCode = HTTP_STATUS.TOO_MANY_REQUESTS
+      res.setHeader('Content-Type', 'application/json')
+      res.end(body)
+    }
+  }
+}

package/src/engine/KeyResolver.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Resolves a rate limit key from a request context.
+ * Validates the resolved key before returning it.
+ */
+
+import { ErrorFactory } from '../errors/ErrorFactory.js'
+import { DEFAULTS }     from '../constants/defaults.js'
+import { createLogger } from '../logger/LoggerFactory.js'
+
+const logger = createLogger('KeyResolver')
+
+export class KeyResolver {
+  /**
+   * @param {import('../types/index.js').KeyResolverFn} resolverFn
+   * @param {string} [prefix]
+   */
+  constructor(resolverFn, prefix = DEFAULTS.KEY_PREFIX) {
+    if (typeof resolverFn !== 'function') {
+      throw ErrorFactory.missingField('keyBy', { reason: 'keyBy must be a function' })
+    }
+    this._resolverFn = resolverFn
+    this._prefix     = prefix
+  }
+
+  /**
+   * Resolves and prefixes the key for a given request context.
+   *
+   * @param {import('../types/index.js').RequestContext} context
+   * @returns {Promise<string>}
+   */
+  async resolve(context) {
+    const raw = await this._resolverFn(context)
+
+    if (!raw || typeof raw !== 'string' || raw.trim().length === 0) {
+      logger.warn('Key resolver returned empty key, falling back to IP', { context })
+      return `${this._prefix}${context.ip ?? 'unknown'}`
+    }
+
+    return `${this._prefix}${raw}`
+  }
+}