ratelimit-engine 0.0.0-stage → 1.0.1

package/bin/cli.js

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+/**
+ * ratelimit-engine CLI
+ * Setup wizard — generates ratelimit.config.js for your project.
+ * Usage: npx ratelimit-engine
+ */
+
+import * as readline from 'readline'
+import * as fs from 'fs'
+import * as path from 'path'
+
+// ── ANSI colours ──────────────────────────────────────────────────
+const C = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  green:   '\x1b[32m',
+  red:     '\x1b[31m',
+  yellow:  '\x1b[33m',
+  cyan:    '\x1b[36m',
+  magenta: '\x1b[35m',
+  blue:    '\x1b[34m',
+}
+
+const bold    = (s) => `${C.bold}${s}${C.reset}`
+const dim     = (s) => `${C.dim}${s}${C.reset}`
+const green   = (s) => `${C.green}${s}${C.reset}`
+const cyan    = (s) => `${C.cyan}${s}${C.reset}`
+const yellow  = (s) => `${C.yellow}${s}${C.reset}`
+const magenta = (s) => `${C.magenta}${s}${C.reset}`
+const blue    = (s) => `${C.blue}${s}${C.reset}`
+
+// ── Readline helpers ──────────────────────────────────────────────
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+
+function ask(question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(answer.trim()))
+  })
+}
+
+async function askNumber(label, defaultVal) {
+  const raw = await ask(`  ${label} ${dim(`[${defaultVal}]`)}: `)
+  const num = parseInt(raw, 10)
+  return isNaN(num) || num <= 0 ? defaultVal : num
+}
+
+async function askChoice(choices) {
+  choices.forEach((c, i) => {
+    console.log(`  ${bold(cyan(String(i + 1)))}. ${bold(c.label.padEnd(18))} ${dim(c.desc)}`)
+  })
+  const raw = await ask(`\n  Pick [1-${choices.length}]: `)
+  const idx = parseInt(raw, 10) - 1
+  if (isNaN(idx) || idx < 0 || idx >= choices.length) return choices[0]
+  return choices[idx]
+}
+
+// ── Algorithm definitions ─────────────────────────────────────────
+const ALGORITHMS = [
+  { key: 'TokenBucket',   label: 'Token Bucket',   desc: 'Burst-friendly — refills tokens over time' },
+  { key: 'FixedWindow',   label: 'Fixed Window',   desc: 'Simple counter per time window' },
+  { key: 'SlidingWindow', label: 'Sliding Window', desc: 'Smooth rolling window, no boundary spikes' },
+  { key: 'LeakyBucket',   label: 'Leaky Bucket',   desc: 'Strict output rate, drops excess' },
+  { key: 'Composite',     label: 'Composite',      desc: 'Combine two algorithms (ALL / ANY)' },
+]
+
+const STORES = [
+  { key: 'MemoryStore', label: 'Memory',  desc: 'In-process store — single instance' },
+  { key: 'RedisStore',  label: 'Redis',   desc: 'Distributed store — multi-instance / clustered' },
+]
+
+const FRAMEWORKS = [
+  { key: 'express',  label: 'Express',  desc: 'app.use(limiter.express())' },
+  { key: 'fastify',  label: 'Fastify',  desc: 'fastify.addHook("onRequest", limiter.fastify())' },
+  { key: 'manual',   label: 'Manual',   desc: 'limiter.check(ctx) — any framework' },
+]
+
+const KEY_STRATEGIES = [
+  { key: 'byIP',               label: 'By IP',         desc: 'One counter per client IP (default)' },
+  { key: 'byUser',             label: 'By User',        desc: 'One counter per authenticated user' },
+  { key: 'byRoute',            label: 'By Route',       desc: 'One counter per URL path' },
+  { key: 'compositeResolver',  label: 'IP + Route',     desc: 'Separate counter per IP+route combination' },
+]
+
+// ── Config collectors ─────────────────────────────────────────────
+async function collectAlgoConfig(key) {
+  switch (key) {
+    case 'TokenBucket': {
+      const capacity   = await askNumber('Token bucket capacity (burst size)', 100)
+      const refillRate = await askNumber('Refill rate (tokens/sec)', 10)
+      return { capacity, refillRate }
+    }
+    case 'FixedWindow':
+    case 'SlidingWindow': {
+      const limit    = await askNumber('Max requests per window', 100)
+      const windowMs = (await askNumber('Window size (seconds)', 60)) * 1000
+      return { limit, windowMs }
+    }
+    case 'LeakyBucket': {
+      const capacity = await askNumber('Queue capacity (max queued requests)', 100)
+      const leakRate = await askNumber('Leak rate (requests/sec)', 10)
+      return { capacity, leakRate }
+    }
+    case 'Composite': {
+      console.log(`\n  ${bold('Primary algorithm:')}\n`)
+      const primary = await askChoice(ALGORITHMS.filter((a) => a.key !== 'Composite'))
+      const primaryConfig = await collectAlgoConfig(primary.key)
+
+      console.log(`\n  ${bold('Secondary algorithm:')}\n`)
+      const secondary = await askChoice(ALGORITHMS.filter((a) => a.key !== 'Composite'))
+      const secondaryConfig = await collectAlgoConfig(secondary.key)
+
+      console.log(`\n  ${bold('Composite mode:')}\n`)
+      const mode = await askChoice([
+        { key: 'ALL', label: 'ALL', desc: 'Both algorithms must allow the request' },
+        { key: 'ANY', label: 'ANY', desc: 'At least one algorithm must allow the request' },
+      ])
+
+      return { primary: { key: primary.key, config: primaryConfig }, secondary: { key: secondary.key, config: secondaryConfig }, mode: mode.key }
+    }
+    default:
+      return {}
+  }
+}
+
+// ── Code generators ───────────────────────────────────────────────
+function algoArgs(key, config) {
+  switch (key) {
+    case 'TokenBucket':
+      return `{ capacity: ${config.capacity}, refillRate: ${config.refillRate} }`
+    case 'FixedWindow':
+    case 'SlidingWindow':
+      return `{ limit: ${config.limit}, windowMs: ${config.windowMs} }`
+    case 'LeakyBucket':
+      return `{ capacity: ${config.capacity}, leakRate: ${config.leakRate} }`
+    default:
+      return '{}'
+  }
+}
+
+function generateConfig({ algoKey, algoConfig, storeKey, frameworkKey, keyStrategyKey }) {
+  const isRedis     = storeKey === 'RedisStore'
+  const isComposite = algoKey === 'Composite'
+
+  const imports = isComposite
+    ? [algoKey, algoConfig.primary.key, algoConfig.secondary.key]
+    : [algoKey]
+
+  const allImports = [...new Set([...imports, storeKey, keyStrategyKey])]
+
+  const redisImport  = isRedis ? `\nimport Redis from 'ioredis'` : ''
+  const redisClient  = isRedis ? `\nconst redis = new Redis() // configure your Redis connection\n` : ''
+  const storeInit    = isRedis
+    ? `new RedisStore({ client: redis })`
+    : `new MemoryStore()`
+
+  let algoInit
+  if (isComposite) {
+    const { primary, secondary, mode } = algoConfig
+    algoInit = `new Composite({
+  algorithms: [
+    new ${primary.key}(${algoArgs(primary.key, primary.config)}),
+    new ${secondary.key}(${algoArgs(secondary.key, secondary.config)}),
+  ],
+  mode: COMPOSITE_MODES.${mode},
+})`
+  } else {
+    algoInit = `new ${algoKey}(${algoArgs(algoKey, algoConfig)})`
+  }
+
+  const compositeImport = isComposite ? `, COMPOSITE_MODES` : ''
+
+  let frameworkUsage
+  switch (frameworkKey) {
+    case 'express':
+      frameworkUsage = `// Express — apply globally
+app.use(limiter.express())
+
+// or per-route
+app.get('/api/resource', limiter.express(), handler)`
+      break
+    case 'fastify':
+      frameworkUsage = `// Fastify — apply globally
+fastify.addHook('onRequest', limiter.fastify())
+
+// or per-route
+fastify.get('/api/resource', { onRequest: limiter.fastify() }, handler)`
+      break
+    case 'manual':
+      frameworkUsage = `// Manual — any framework
+const result = await limiter.check({
+  ip:   req.ip,
+  path: req.path,
+  user: req.user?.id, // optional
+})
+
+if (!result.allowed) {
+  return res.status(429).json({
+    error:      'Too Many Requests',
+    retryAfter: result.retryAfter,
+  })
+}`
+      break
+  }
+
+  return `import { ${allImports.join(', ')}${compositeImport} } from 'ratelimit-engine'${redisImport}
+${redisClient}
+const limiter = createLimiter({
+  algorithm: ${algoInit},
+  store:     ${storeInit},
+  keyBy:     ${keyStrategyKey},
+  failOpen:  true,
+  onBlocked: (ctx, result) => {
+    console.warn(\`[RATE LIMIT] \${ctx.ip} blocked — retry in \${result.retryAfter}s\`)
+  },
+})
+
+${frameworkUsage}
+
+export { limiter }
+`
+}
+
+// ── Main ──────────────────────────────────────────────────────────
+async function main() {
+  console.clear()
+  console.log(`
+  ${bold(cyan('⚡ ratelimit-engine'))} ${dim('— Setup Wizard')}
+  ${dim('─────────────────────────────────────────────')}
+  ${dim('Generates a ready-to-use ratelimit.config.js')}
+  ${dim('for your project in the current directory.')}
+  `)
+
+  // Step 1 — Algorithm
+  console.log(`  ${bold('Step 1 — Choose an algorithm:')}\n`)
+  const algo = await askChoice(ALGORITHMS)
+  console.log()
+  const algoConfig = await collectAlgoConfig(algo.key)
+
+  // Step 2 — Store
+  console.log(`\n  ${bold('Step 2 — Choose a store:')}\n`)
+  const store = await askChoice(STORES)
+  if (store.key === 'RedisStore') {
+    console.log(`\n  ${yellow('Note:')} Make sure ${bold('ioredis')} is installed: ${dim('npm install ioredis')}`)
+  }
+
+  // Step 3 — Framework
+  console.log(`\n  ${bold('Step 3 — Choose your framework:')}\n`)
+  const framework = await askChoice(FRAMEWORKS)
+
+  // Step 4 — Key strategy
+  console.log(`\n  ${bold('Step 4 — How should requests be keyed?')}\n`)
+  const keyStrategy = await askChoice(KEY_STRATEGIES)
+
+  // Generate
+  const code = generateConfig({
+    algoKey:        algo.key,
+    algoConfig,
+    storeKey:       store.key,
+    frameworkKey:   framework.key,
+    keyStrategyKey: keyStrategy.key,
+  })
+
+  // Write file
+  const outPath = path.join(process.cwd(), 'ratelimit.config.js')
+  fs.writeFileSync(outPath, code, 'utf8')
+
+  // Output
+  console.log(`\n  ${dim('─────────────────────────────────────────────')}`)
+  console.log(`  ${green(bold('✅ Done!'))} Generated ${bold('ratelimit.config.js')}\n`)
+  console.log(`  ${dim('─────────────────────────────────────────────')}`)
+  console.log(`\n${code}`)
+  console.log(`  ${dim('─────────────────────────────────────────────')}`)
+  console.log(`\n  ${bold('Next steps:')}\n`)
+  console.log(`  ${cyan('1.')} Import the config into your app:`)
+  console.log(`     ${dim("import { limiter } from './ratelimit.config.js'")}`)
+  console.log(`\n  ${cyan('2.')} Wire it up — the usage snippet is inside the generated file.`)
+  if (store.key === 'RedisStore') {
+    console.log(`\n  ${cyan('3.')} Install ioredis if not already:`)
+    console.log(`     ${dim('npm install ioredis')}`)
+  }
+  console.log()
+
+  rl.close()
+}
+
+main().catch((err) => {
+  console.error(`\nError: ${err.message}`)
+  rl.close()
+  process.exit(1)
+})

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "ratelimit-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Enterprise-grade, algorithm-pluggable rate limiting engine for Node.js",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix"
+  },
+  "keywords": [
+    "rate-limit",
+    "rate-limiter",
+    "throttle",
+    "token-bucket",
+    "sliding-window",
+    "fixed-window",
+    "leaky-bucket",
+    "redis",
+    "express",
+    "fastify",
+    "enterprise",
+    "middleware"
+  ],
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "ratelimit-engine": "./bin/cli.js"
+  },
+  "author": "Abhinav710 <kumarabhinav5693@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^1.0.0",
+    "eslint": "^8.57.0",
+    "vitest": "^1.0.0"
+  },
+  "peerDependencies": {
+    "ioredis": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
+  }
+}

package/src/adapters/BaseAdapter.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Abstract base class for framework adapters.
+ * Adapters extract a RequestContext from the framework's request object
+ * and delegate to the RateLimiter engine.
+ */
+
+import { ErrorFactory } from '../errors/ErrorFactory.js'
+
+export class BaseAdapter {
+  /**
+   * @param {import('../engine/RateLimiter.js').RateLimiter} limiter
+   */
+  constructor(limiter) {
+    if (new.target === BaseAdapter) {
+      throw ErrorFactory.invalidAlgorithm({ reason: 'BaseAdapter cannot be instantiated directly' })
+    }
+    this._limiter = limiter
+  }
+
+  /**
+   * Extracts a RequestContext from the framework's native request object.
+   *
+   * @param {Object} req  - Framework request object.
+   * @returns {import('../types/index.js').RequestContext}
+   */
+  extractContext(_req) {
+    throw new Error('extractContext() must be implemented by subclass')
+  }
+
+  /**
+   * Returns the framework-specific middleware function.
+   *
+   * @returns {Function}
+   */
+  middleware() {
+    throw new Error('middleware() must be implemented by subclass')
+  }
+}

package/src/adapters/ExpressAdapter.js

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Express middleware adapter.
+ */
+
+import { BaseAdapter } from './BaseAdapter.js'
+import { createLogger } from '../logger/LoggerFactory.js'
+
+const logger = createLogger('ExpressAdapter')
+
+export class ExpressAdapter extends BaseAdapter {
+  /**
+   * @param {import('../engine/RateLimiter.js').RateLimiter} limiter
+   */
+  constructor(limiter) {
+    super(limiter)
+  }
+
+  /**
+   * @param {Object} req - Express request.
+   * @returns {import('../types/index.js').RequestContext}
+   */
+  extractContext(req) {
+    return {
+      ip:         req.ip ?? req.socket?.remoteAddress ?? 'unknown',
+      userId:     req.user?.id ?? req.user?.sub ?? undefined,
+      apiKey:     req.headers?.['x-api-key'] ?? undefined,
+      method:     req.method,
+      path:       req.path ?? req.url,
+      headers:    req.headers ?? {},
+      rawRequest: req,
+    }
+  }
+
+  /**
+   * Returns an Express-compatible middleware function.
+   * Writes rate limit headers and sends 429 when blocked.
+   *
+   * @returns {Function} (req, res, next) => void
+   */
+  middleware() {
+    const limiter      = this._limiter
+    const headerWriter = this._limiter.getHeaderWriter()
+
+    return async (req, res, next) => {
+      try {
+        const context = this.extractContext(req)
+        const result  = await limiter.check(context)
+
+        headerWriter.write(res, result)
+
+        if (!result.allowed) {
+          logger.info('Blocking request', { ip: context.ip, path: context.path })
+          headerWriter.sendBlocked(res, result)
+          return
+        }
+
+        next()
+      } catch (err) {
+        logger.error('Unexpected error in Express middleware', { error: err.message })
+        next(err)
+      }
+    }
+  }
+}

package/src/adapters/FastifyAdapter.js

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Fastify hook adapter.
+ */
+
+import { BaseAdapter } from './BaseAdapter.js'
+import { createLogger } from '../logger/LoggerFactory.js'
+import { HTTP_STATUS }  from '../constants/headers.js'
+
+const logger = createLogger('FastifyAdapter')
+
+export class FastifyAdapter extends BaseAdapter {
+  /**
+   * @param {import('../engine/RateLimiter.js').RateLimiter} limiter
+   */
+  constructor(limiter) {
+    super(limiter)
+  }
+
+  /**
+   * @param {Object} req - Fastify request.
+   * @returns {import('../types/index.js').RequestContext}
+   */
+  extractContext(req) {
+    return {
+      ip:         req.ip ?? 'unknown',
+      userId:     req.user?.id ?? req.user?.sub ?? undefined,
+      apiKey:     req.headers?.['x-api-key'] ?? undefined,
+      method:     req.method,
+      path:       req.url,
+      headers:    req.headers ?? {},
+      rawRequest: req,
+    }
+  }
+
+  /**
+   * Returns a Fastify onRequest hook function.
+   *
+   * @returns {Function} async (request, reply) => void
+   */
+  middleware() {
+    const limiter      = this._limiter
+    const headerWriter = this._limiter.getHeaderWriter()
+
+    return async (request, reply) => {
+      try {
+        const context = this.extractContext(request)
+        const result  = await limiter.check(context)
+
+        headerWriter.write(reply.raw, result)
+
+        if (!result.allowed) {
+          logger.info('Blocking request', { ip: context.ip, path: context.path })
+          reply
+            .code(HTTP_STATUS.TOO_MANY_REQUESTS)
+            .send({
+              error:      'Too Many Requests',
+              retryAfter: result.retryAfter,
+              resetAt:    result.resetAt.toISOString(),
+            })
+        }
+      } catch (err) {
+        logger.error('Unexpected error in Fastify hook', { error: err.message })
+        throw err
+      }
+    }
+  }
+}

package/src/algorithms/BaseAlgorithm.js

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Abstract base class for all rate limit algorithms.
+ * Every algorithm must extend this and implement check() and reset().
+ */
+
+import { ErrorFactory } from '../errors/ErrorFactory.js'
+
+export class BaseAlgorithm {
+  /**
+   * @param {string} name - Algorithm identifier from ALGORITHM_NAMES.
+   */
+  constructor(name) {
+    if (new.target === BaseAlgorithm) {
+      throw ErrorFactory.invalidAlgorithm({ reason: 'BaseAlgorithm cannot be instantiated directly' })
+    }
+    this.name = name
+  }
+
+  /**
+   * Checks whether the given key is within its rate limit.
+   *
+   * @param {string}                                       key
+   * @param {import('../stores/BaseStore.js').BaseStore}   store
+   * @returns {Promise<import('../types/index.js').RateLimitResult>}
+   */
+  async check(_key, _store) {
+    throw new Error('check() must be implemented by subclass')
+  }
+
+  /**
+   * Resets the rate limit state for the given key.
+   *
+   * @param {string}                                       key
+   * @param {import('../stores/BaseStore.js').BaseStore}   store
+   * @returns {Promise<void>}
+   */
+  async reset(_key, _store) {
+    throw new Error('reset() must be implemented by subclass')
+  }
+}

package/src/algorithms/Composite.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Composite algorithm.
+ * Combines multiple algorithms with ALL (every must pass) or ANY (one must pass) mode.
+ * Enables multi-policy enforcement — e.g. burst cap AND daily hard limit.
+ */
+
+import { BaseAlgorithm } from './BaseAlgorithm.js'
+import { ErrorFactory }  from '../errors/ErrorFactory.js'
+import { ALGORITHM_NAMES, COMPOSITE_MODES } from '../constants/algorithms.js'
+import { createLogger } from '../logger/LoggerFactory.js'
+
+const logger = createLogger('Composite')
+
+export class Composite extends BaseAlgorithm {
+  /**
+   * @param {Object}   options
+   * @param {BaseAlgorithm[]} options.algorithms - Array of algorithm instances to evaluate.
+   * @param {string}   [options.mode]            - 'ALL' (default) or 'ANY'.
+   */
+  constructor({ algorithms, mode = COMPOSITE_MODES.ALL } = {}) {
+    super(ALGORITHM_NAMES.COMPOSITE)
+
+    if (!Array.isArray(algorithms) || algorithms.length === 0) {
+      throw ErrorFactory.invalidValue('algorithms', algorithms, 'must be a non-empty array of BaseAlgorithm instances')
+    }
+
+    const allValid = algorithms.every((a) => a instanceof BaseAlgorithm)
+    if (!allValid) {
+      throw ErrorFactory.invalidAlgorithm({ reason: 'All composite algorithms must extend BaseAlgorithm' })
+    }
+
+    if (mode !== COMPOSITE_MODES.ALL && mode !== COMPOSITE_MODES.ANY) {
+      throw ErrorFactory.invalidValue('mode', mode, `must be '${COMPOSITE_MODES.ALL}' or '${COMPOSITE_MODES.ANY}'`)
+    }
+
+    this._algorithms = algorithms
+    this._mode       = mode
+  }
+
+  /**
+   * Runs all child algorithms in parallel and combines their results
+   * according to the configured mode.
+   *
+   * @param {string} key
+   * @param {import('../stores/BaseStore.js').BaseStore} store
+   * @returns {Promise<import('../types/index.js').RateLimitResult>}
+   */
+  async check(key, store) {
+    const results = await Promise.all(
+      this._algorithms.map((algo) => algo.check(key, store)),
+    )
+
+    const allowed = this._mode === COMPOSITE_MODES.ALL
+      ? results.every((r) => r.allowed)
+      : results.some((r) => r.allowed)
+
+    // Use the most restrictive result when blocked
+    const blocking   = results.filter((r) => !r.allowed)
+    const strictest  = blocking.length > 0
+      ? blocking.reduce((a, b) => (a.retryAfter ?? 0) > (b.retryAfter ?? 0) ? a : b)
+      : results[0]
+
+    const remaining  = Math.min(...results.map((r) => r.remaining))
+    const limit      = Math.min(...results.map((r) => r.limit))
+    const resetAt    = blocking.length > 0
+      ? new Date(Math.max(...blocking.map((r) => r.resetAt.getTime())))
+      : results[0].resetAt
+
+    logger.debug('Composite check', {
+      key,
+      mode: this._mode,
+      allowed,
+      algorithms: results.map((r, i) => ({
+        name:    this._algorithms[i].name,
+        allowed: r.allowed,
+      })),
+    })
+
+    return {
+      allowed,
+      limit,
+      remaining,
+      resetAt,
+      retryAfter: allowed ? undefined : strictest.retryAfter,
+    }
+  }
+
+  /**
+   * @param {string} key
+   * @param {import('../stores/BaseStore.js').BaseStore} store
+   * @returns {Promise<void>}
+   */
+  async reset(key, store) {
+    await Promise.all(this._algorithms.map((algo) => algo.reset(key, store)))
+    logger.debug('Composite reset', { key })
+  }
+}