ratelimit-engine 0.0.0-stage → 1.0.1

package/src/engine/RateLimiter.js

@@ -0,0 +1,145 @@
+/**
+ * @fileoverview Core rate limiter engine.
+ * Orchestrates algorithm, store, key resolution, header writing, and hooks.
+ * This class has no knowledge of HTTP frameworks — adapters handle that.
+ */
+
+import { BaseAlgorithm } from '../algorithms/BaseAlgorithm.js'
+import { BaseStore }     from '../stores/BaseStore.js'
+import { KeyResolver }   from './KeyResolver.js'
+import { HeaderWriter }  from './HeaderWriter.js'
+import { ErrorFactory }  from '../errors/ErrorFactory.js'
+import { DEFAULTS }      from '../constants/defaults.js'
+import { createLogger, wrapExternalLogger } from '../logger/LoggerFactory.js'
+
+export class RateLimiter {
+  /**
+   * @param {import('../types/index.js').LimiterConfig} config
+   */
+  constructor(config) {
+    this._validateConfig(config)
+
+    this._algorithm   = config.algorithm
+    this._store       = config.store
+    this._keyResolver = new KeyResolver(config.keyBy)
+    this._headerWriter = new HeaderWriter()
+    this._failOpen    = config.failOpen ?? DEFAULTS.FAIL_OPEN
+    this._onBlocked   = config.onBlocked ?? null
+    this._onAllowed   = config.onAllowed ?? null
+    this._logger      = config.logger
+      ? wrapExternalLogger(config.logger)
+      : createLogger('RateLimiter')
+  }
+
+  /**
+   * Core check — resolves key, runs algorithm, fires hooks.
+   * Call this directly for framework-agnostic usage.
+   *
+   * @param {import('../types/index.js').RequestContext} context
+   * @returns {Promise<import('../types/index.js').RateLimitResult>}
+   */
+  async check(context) {
+    let key
+
+    try {
+      key = await this._keyResolver.resolve(context)
+    } catch (err) {
+      this._logger.error('Key resolution failed', { error: err.message })
+      return this._failOpenResult()
+    }
+
+    let result
+
+    try {
+      result = await this._algorithm.check(key, this._store)
+    } catch (err) {
+      this._logger.error('Algorithm check failed', { key, error: err.message })
+
+      if (this._failOpen) {
+        return this._failOpenResult()
+      }
+
+      throw ErrorFactory.storeUnavailable(err, { key })
+    }
+
+    if (result.allowed) {
+      this._onAllowed?.(context, result)
+      this._logger.debug('Request allowed', { key, remaining: result.remaining })
+    } else {
+      this._onBlocked?.(context, result)
+      this._logger.info('Request blocked', {
+        key,
+        retryAfter: result.retryAfter,
+        resetAt:    result.resetAt.toISOString(),
+      })
+    }
+
+    return result
+  }
+
+  /**
+   * Resets the rate limit state for the given context.
+   *
+   * @param {import('../types/index.js').RequestContext} context
+   * @returns {Promise<void>}
+   */
+  async reset(context) {
+    const key = await this._keyResolver.resolve(context)
+    await this._algorithm.reset(key, this._store)
+    this._logger.info('Rate limit reset', { key })
+  }
+
+  /**
+   * Returns the HeaderWriter so adapters can write headers.
+   *
+   * @returns {HeaderWriter}
+   */
+  getHeaderWriter() {
+    return this._headerWriter
+  }
+
+  /**
+   * Releases store resources.
+   *
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    await this._store.destroy()
+    this._logger.info('RateLimiter destroyed')
+  }
+
+  /**
+   * Validates required config fields and their types.
+   *
+   * @param {import('../types/index.js').LimiterConfig} config
+   */
+  _validateConfig(config) {
+    if (!config) {
+      throw ErrorFactory.missingField('config')
+    }
+    if (!(config.algorithm instanceof BaseAlgorithm)) {
+      throw ErrorFactory.invalidAlgorithm()
+    }
+    if (!(config.store instanceof BaseStore)) {
+      throw ErrorFactory.invalidStore()
+    }
+    if (typeof config.keyBy !== 'function') {
+      throw ErrorFactory.missingField('keyBy')
+    }
+  }
+
+  /**
+   * Fail-open result — allows the request when the store/algorithm is unavailable.
+   *
+   * @returns {import('../types/index.js').RateLimitResult}
+   */
+  _failOpenResult() {
+    this._logger.warn('Fail-open: allowing request due to internal error')
+    return {
+      allowed:   true,
+      limit:     0,
+      remaining: 0,
+      resetAt:   new Date(),
+    }
+  }
+}

package/src/engine/createLimiter.js

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Convenience factory — wraps RateLimiter construction
+ * and wires Express/Fastify adapters so consumers get a single entry point.
+ */
+
+import { RateLimiter }    from './RateLimiter.js'
+import { ExpressAdapter } from '../adapters/ExpressAdapter.js'
+import { FastifyAdapter } from '../adapters/FastifyAdapter.js'
+
+/**
+ * Creates a configured RateLimiter and returns it with
+ * pre-built adapter helpers for Express and Fastify.
+ *
+ * @param {import('../types/index.js').LimiterConfig} config
+ * @returns {{
+ *   limiter:  RateLimiter,
+ *   express:  () => Function,
+ *   fastify:  () => Function,
+ *   check:    (context: import('../types/index.js').RequestContext) => Promise<import('../types/index.js').RateLimitResult>,
+ *   reset:    (context: import('../types/index.js').RequestContext) => Promise<void>,
+ *   destroy:  () => Promise<void>,
+ * }}
+ */
+export function createLimiter(config) {
+  const limiter         = new RateLimiter(config)
+  const expressAdapter  = new ExpressAdapter(limiter)
+  const fastifyAdapter  = new FastifyAdapter(limiter)
+
+  return {
+    limiter,
+    express: () => expressAdapter.middleware(),
+    fastify: () => fastifyAdapter.middleware(),
+    check:   (context) => limiter.check(context),
+    reset:   (context) => limiter.reset(context),
+    destroy: ()        => limiter.destroy(),
+  }
+}

package/src/errors/ConfigurationError.js

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Error class for configuration validation failures.
+ */
+
+import { RateLimitError } from './RateLimitError.js'
+
+/**
+ * Thrown when createLimiter() or an algorithm/store receives invalid config.
+ */
+export class ConfigurationError extends RateLimitError {
+  /**
+   * @param {string} message
+   * @param {string} code
+   * @param {Object} [meta]
+   */
+  constructor(message, code, meta = {}) {
+    super(message, code, meta)
+    this.name = 'ConfigurationError'
+  }
+}

package/src/errors/ErrorFactory.js

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Central factory for creating all engine errors.
+ * No other file should call `new XyzError(...)` directly —
+ * always go through ErrorFactory so error shape stays consistent.
+ */
+
+import { ConfigurationError } from './ConfigurationError.js'
+import { StoreError }         from './StoreError.js'
+import { RateLimitError }     from './RateLimitError.js'
+import { ERROR_CODES, ERROR_MESSAGES } from '../constants/errors.js'
+
+/**
+ * @param {string} field   - Name of the missing config field.
+ * @param {Object} [meta]
+ * @returns {ConfigurationError}
+ */
+function missingField(field, meta = {}) {
+  return new ConfigurationError(
+    `${ERROR_MESSAGES[ERROR_CODES.CONFIGURATION_MISSING_FIELD]}: '${field}'`,
+    ERROR_CODES.CONFIGURATION_MISSING_FIELD,
+    { field, ...meta },
+  )
+}
+
+/**
+ * @param {string} field   - Name of the invalid config field.
+ * @param {*}      value   - The value that was rejected.
+ * @param {string} reason  - Why it is invalid.
+ * @param {Object} [meta]
+ * @returns {ConfigurationError}
+ */
+function invalidValue(field, value, reason, meta = {}) {
+  return new ConfigurationError(
+    `${ERROR_MESSAGES[ERROR_CODES.CONFIGURATION_INVALID_VALUE]}: '${field}' — ${reason}`,
+    ERROR_CODES.CONFIGURATION_INVALID_VALUE,
+    { field, value, reason, ...meta },
+  )
+}
+
+/**
+ * @param {Object} [meta]
+ * @returns {ConfigurationError}
+ */
+function invalidAlgorithm(meta = {}) {
+  return new ConfigurationError(
+    ERROR_MESSAGES[ERROR_CODES.CONFIGURATION_INVALID_ALGO],
+    ERROR_CODES.CONFIGURATION_INVALID_ALGO,
+    meta,
+  )
+}
+
+/**
+ * @param {Object} [meta]
+ * @returns {ConfigurationError}
+ */
+function invalidStore(meta = {}) {
+  return new ConfigurationError(
+    ERROR_MESSAGES[ERROR_CODES.CONFIGURATION_INVALID_STORE],
+    ERROR_CODES.CONFIGURATION_INVALID_STORE,
+    meta,
+  )
+}
+
+/**
+ * @param {string} operation  - 'read' | 'write'.
+ * @param {Error}  cause      - Underlying error from the store.
+ * @param {Object} [meta]
+ * @returns {StoreError}
+ */
+function storeOperationFailed(operation, cause, meta = {}) {
+  const code = operation === 'read'
+    ? ERROR_CODES.STORE_READ_FAILED
+    : ERROR_CODES.STORE_WRITE_FAILED
+
+  return new StoreError(
+    `${ERROR_MESSAGES[code]}: ${cause.message}`,
+    code,
+    { operation, cause: cause.message, ...meta },
+  )
+}
+
+/**
+ * @param {Error}  cause
+ * @param {Object} [meta]
+ * @returns {StoreError}
+ */
+function storeUnavailable(cause, meta = {}) {
+  return new StoreError(
+    `${ERROR_MESSAGES[ERROR_CODES.STORE_UNAVAILABLE]}: ${cause.message}`,
+    ERROR_CODES.STORE_UNAVAILABLE,
+    { cause: cause.message, ...meta },
+  )
+}
+
+/**
+ * @param {string} key
+ * @param {import('../types/index.js').RateLimitResult} result
+ * @param {Object} [meta]
+ * @returns {RateLimitError}
+ */
+function rateLimitExceeded(key, result, meta = {}) {
+  return new RateLimitError(
+    ERROR_MESSAGES[ERROR_CODES.RATE_LIMIT_EXCEEDED],
+    ERROR_CODES.RATE_LIMIT_EXCEEDED,
+    { key, remaining: result.remaining, resetAt: result.resetAt, ...meta },
+  )
+}
+
+export const ErrorFactory = Object.freeze({
+  missingField,
+  invalidValue,
+  invalidAlgorithm,
+  invalidStore,
+  storeOperationFailed,
+  storeUnavailable,
+  rateLimitExceeded,
+})

package/src/errors/RateLimitError.js

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Base error class for all ratelimit-engine errors.
+ */
+
+/**
+ * Base error class. All engine errors extend this.
+ * Carries a machine-readable code alongside the human message.
+ */
+export class RateLimitError extends Error {
+  /**
+   * @param {string} message  - Human-readable description.
+   * @param {string} code     - Machine-readable error code from ERROR_CODES.
+   * @param {Object} [meta]   - Optional extra context (key, config field, etc.).
+   */
+  constructor(message, code, meta = {}) {
+    super(message)
+    this.name   = 'RateLimitError'
+    this.code   = code
+    this.meta   = meta
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor)
+    }
+  }
+}

package/src/errors/StoreError.js

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Error class for store-layer failures.
+ */
+
+import { RateLimitError } from './RateLimitError.js'
+
+/**
+ * Thrown when a store operation (read, write, connect) fails.
+ */
+export class StoreError extends RateLimitError {
+  /**
+   * @param {string} message
+   * @param {string} code
+   * @param {Object} [meta]
+   */
+  constructor(message, code, meta = {}) {
+    super(message, code, meta)
+    this.name = 'StoreError'
+  }
+}

package/src/index.js

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Public API surface for ratelimit-engine.
+ * Everything a consumer needs is exported from here.
+ * Internal implementation details are not re-exported.
+ */
+
+// Engine
+export { RateLimiter }      from './engine/RateLimiter.js'
+
+// Factory (convenience wrapper)
+export { createLimiter }    from './engine/createLimiter.js'
+
+// Algorithms
+export { BaseAlgorithm }    from './algorithms/BaseAlgorithm.js'
+export { FixedWindow }      from './algorithms/FixedWindow.js'
+export { SlidingWindow }    from './algorithms/SlidingWindow.js'
+export { TokenBucket }      from './algorithms/TokenBucket.js'
+export { LeakyBucket }      from './algorithms/LeakyBucket.js'
+export { Composite }        from './algorithms/Composite.js'
+
+// Stores
+export { BaseStore }        from './stores/BaseStore.js'
+export { MemoryStore }      from './stores/MemoryStore.js'
+export { RedisStore }       from './stores/RedisStore.js'
+
+// Adapters
+export { ExpressAdapter }   from './adapters/ExpressAdapter.js'
+export { FastifyAdapter }   from './adapters/FastifyAdapter.js'
+
+// Resolvers
+export { byIP }             from './resolvers/byIP.js'
+export { byUser }           from './resolvers/byUser.js'
+export { byAPIKey }         from './resolvers/byAPIKey.js'
+export { byRoute }          from './resolvers/byRoute.js'
+export { compositeResolver } from './resolvers/composite.js'
+
+// Logger
+export { Logger }           from './logger/Logger.js'
+export { createLogger, wrapExternalLogger } from './logger/LoggerFactory.js'
+
+// Errors
+export { RateLimitError }   from './errors/RateLimitError.js'
+export { StoreError }       from './errors/StoreError.js'
+export { ConfigurationError } from './errors/ConfigurationError.js'
+export { ErrorFactory }     from './errors/ErrorFactory.js'
+
+// Constants (consumers may need these for custom implementations)
+export { ALGORITHM_NAMES, COMPOSITE_MODES } from './constants/algorithms.js'
+export { DEFAULTS }         from './constants/defaults.js'
+export { ERROR_CODES, ERROR_MESSAGES }      from './constants/errors.js'
+export { HEADERS, HTTP_STATUS }             from './constants/headers.js'
+export { STORE_TYPES }      from './constants/store.js'

package/src/logger/Logger.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Structured logger with pluggable transport.
+ * Enterprise teams can inject Winston, Pino, or any compatible logger.
+ */
+
+/**
+ * Log level hierarchy — higher index = more severe.
+ */
+const LOG_LEVELS = Object.freeze({
+  debug: 0,
+  info:  1,
+  warn:  2,
+  error: 3,
+})
+
+/**
+ * Default console transport — used when no custom logger is injected.
+ *
+ * @param {string} level
+ * @param {string} message
+ * @param {Object} context
+ */
+function defaultTransport(level, message, context) {
+  const timestamp = new Date().toISOString()
+  const base = { timestamp, level, message, ...context }
+  const output = JSON.stringify(base)
+
+  if (level === 'error' || level === 'warn') {
+    process.stderr.write(output + '\n')
+  } else {
+    process.stdout.write(output + '\n')
+  }
+}
+
+/**
+ * Structured logger. Each instance carries a fixed context object
+ * that is merged into every log entry it emits.
+ */
+export class Logger {
+  /**
+   * @param {Object}   options
+   * @param {string}   options.name          - Logger name / component label.
+   * @param {string}   [options.level]       - Minimum log level. Default: 'info'.
+   * @param {Object}   [options.context]     - Fixed context merged into every entry.
+   * @param {Function} [options.transport]   - Custom transport fn(level, message, context).
+   */
+  constructor({ name, level = 'info', context = {}, transport = defaultTransport }) {
+    this._name      = name
+    this._minLevel  = LOG_LEVELS[level] ?? LOG_LEVELS.info
+    this._context   = context
+    this._transport = transport
+  }
+
+  /**
+   * Creates a child logger that inherits this logger's context
+   * and merges additional fixed context fields.
+   *
+   * @param {Object} additionalContext
+   * @returns {Logger}
+   */
+  child(additionalContext) {
+    return new Logger({
+      name:      this._name,
+      level:     this._levelName(),
+      context:   { ...this._context, ...additionalContext },
+      transport: this._transport,
+    })
+  }
+
+  /**
+   * @param {string} message
+   * @param {Object} [context]
+   */
+  debug(message, context = {}) {
+    this._log('debug', message, context)
+  }
+
+  /**
+   * @param {string} message
+   * @param {Object} [context]
+   */
+  info(message, context = {}) {
+    this._log('info', message, context)
+  }
+
+  /**
+   * @param {string} message
+   * @param {Object} [context]
+   */
+  warn(message, context = {}) {
+    this._log('warn', message, context)
+  }
+
+  /**
+   * @param {string} message
+   * @param {Object} [context]
+   */
+  error(message, context = {}) {
+    this._log('error', message, context)
+  }
+
+  /**
+   * @param {string} level
+   * @param {string} message
+   * @param {Object} context
+   */
+  _log(level, message, context) {
+    if (LOG_LEVELS[level] < this._minLevel) {
+      return
+    }
+
+    this._transport(level, message, {
+      logger:  this._name,
+      ...this._context,
+      ...context,
+    })
+  }
+
+  /**
+   * @returns {string}
+   */
+  _levelName() {
+    return Object.keys(LOG_LEVELS).find(
+      (k) => LOG_LEVELS[k] === this._minLevel
+    ) ?? 'info'
+  }
+}

package/src/logger/LoggerFactory.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Factory that creates named Logger instances.
+ * Supports injecting an enterprise logger (Winston, Pino) as the transport.
+ */
+
+import { Logger } from './Logger.js'
+
+/**
+ * Creates a Logger bound to a component name and optional shared context.
+ *
+ * @param {string}   name               - Component name (e.g. 'MemoryStore', 'TokenBucket').
+ * @param {Object}   [options]
+ * @param {string}   [options.level]    - Minimum log level. Default: 'info'.
+ * @param {Object}   [options.context]  - Fixed context fields merged into every entry.
+ * @param {Function} [options.transport]- Custom transport fn(level, message, context).
+ * @returns {Logger}
+ */
+export function createLogger(name, options = {}) {
+  return new Logger({ name, ...options })
+}
+
+/**
+ * Wraps an external logger (Winston, Pino, etc.) so it satisfies
+ * the Logger interface expected by the engine.
+ * The external logger must expose debug/info/warn/error methods.
+ *
+ * @param {Object} externalLogger
+ * @returns {Logger}
+ */
+export function wrapExternalLogger(externalLogger) {
+  const transport = (level, message, context) => {
+    externalLogger[level]?.(message, context)
+  }
+
+  return new Logger({ name: 'external', transport })
+}

package/src/resolvers/byAPIKey.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Resolves the rate limit key from an API key header.
+ */
+
+/**
+ * @param {import('../types/index.js').RequestContext} context
+ * @returns {string}
+ */
+export function byAPIKey(context) {
+  return `apikey:${context.apiKey ?? context.ip ?? 'unknown'}`
+}

package/src/resolvers/byIP.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Resolves the rate limit key from the client's IP address.
+ */
+
+/**
+ * @param {import('../types/index.js').RequestContext} context
+ * @returns {string}
+ */
+export function byIP(context) {
+  return `ip:${context.ip ?? 'unknown'}`
+}

package/src/resolvers/byRoute.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Resolves the rate limit key from the HTTP method and path.
+ */
+
+/**
+ * @param {import('../types/index.js').RequestContext} context
+ * @returns {string}
+ */
+export function byRoute(context) {
+  const method = context.method ?? 'UNKNOWN'
+  const path   = context.path   ?? '/'
+  return `route:${method}:${path}`
+}

package/src/resolvers/byUser.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Resolves the rate limit key from an authenticated user ID.
+ */
+
+/**
+ * @param {import('../types/index.js').RequestContext} context
+ * @returns {string}
+ */
+export function byUser(context) {
+  return `user:${context.userId ?? context.ip ?? 'unknown'}`
+}

package/src/resolvers/composite.js

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Composite resolver — combines multiple resolvers into one key.
+ * Useful for scoping limits by both user and route simultaneously.
+ */
+
+/**
+ * Creates a resolver that joins the output of multiple resolvers with a separator.
+ *
+ * @param {import('../types/index.js').KeyResolverFn[]} resolvers
+ * @param {string} [separator]
+ * @returns {import('../types/index.js').KeyResolverFn}
+ */
+export function compositeResolver(resolvers, separator = '|') {
+  return async (context) => {
+    const parts = await Promise.all(resolvers.map((fn) => fn(context)))
+    return parts.join(separator)
+  }
+}