ratelimit-engine 0.0.0-stage → 1.0.0

package/bin/cli.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+/**
+ * ratelimit-engine CLI
+ * Interactive wizard to simulate any built-in algorithm.
+ * Usage: npx ratelimit-engine simulate
+ */
+
+import * as readline from 'readline'
+import { FixedWindow }   from '../src/algorithms/FixedWindow.js'
+import { SlidingWindow } from '../src/algorithms/SlidingWindow.js'
+import { TokenBucket }   from '../src/algorithms/TokenBucket.js'
+import { LeakyBucket }   from '../src/algorithms/LeakyBucket.js'
+import { Composite }     from '../src/algorithms/Composite.js'
+import { MemoryStore }   from '../src/stores/MemoryStore.js'
+import { COMPOSITE_MODES } from '../src/constants/algorithms.js'
+
+// ── 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',
+  white:   '\x1b[37m',
+  bgDark:  '\x1b[48;5;235m',
+}
+
+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 red     = (s) => `${C.red}${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}`
+
+// ── Readline helper ───────────────────────────────────────────────
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+
+function ask(question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(answer.trim()))
+  })
+}
+
+function askNumber(question, defaultVal) {
+  return new Promise(async (resolve) => {
+    const raw = await ask(`${question} ${dim(`[${defaultVal}]`)}: `)
+    const num = parseInt(raw, 10)
+    resolve(isNaN(num) || num <= 0 ? defaultVal : num)
+  })
+}
+
+// ── Algorithm menu ────────────────────────────────────────────────
+const ALGORITHMS = [
+  {
+    key:   'token-bucket',
+    label: 'Token Bucket',
+    desc:  'Burst-friendly — refills tokens over time',
+    color: cyan,
+  },
+  {
+    key:   'fixed-window',
+    label: 'Fixed Window',
+    desc:  'Simple counter per time window',
+    color: green,
+  },
+  {
+    key:   'sliding-window',
+    label: 'Sliding Window',
+    desc:  'Smooth rolling window, no boundary spikes',
+    color: yellow,
+  },
+  {
+    key:   'leaky-bucket',
+    label: 'Leaky Bucket',
+    desc:  'Strict output rate, drops excess',
+    color: magenta,
+  },
+  {
+    key:   'composite',
+    label: 'Composite',
+    desc:  'Combine two algorithms (ALL / ANY)',
+    color: (s) => `\x1b[35m${s}${C.reset}`,
+  },
+]
+
+// ── Build algorithm from user input ──────────────────────────────
+async function buildAlgorithm(key) {
+  switch (key) {
+    case 'token-bucket': {
+      const capacity   = await askNumber('  Bucket capacity (max tokens)', 10)
+      const refillRate = await askNumber('  Refill rate (tokens/sec)', 2)
+      return new TokenBucket({ capacity, refillRate })
+    }
+    case 'fixed-window': {
+      const limit    = await askNumber('  Max requests', 10)
+      const windowMs = (await askNumber('  Window (seconds)', 60)) * 1000
+      return new FixedWindow({ limit, windowMs })
+    }
+    case 'sliding-window': {
+      const limit    = await askNumber('  Max requests', 10)
+      const windowMs = (await askNumber('  Window (seconds)', 60)) * 1000
+      return new SlidingWindow({ limit, windowMs })
+    }
+    case 'leaky-bucket': {
+      const capacity = await askNumber('  Bucket capacity (queue depth)', 10)
+      const leakRate = await askNumber('  Leak rate (requests/sec)', 2)
+      return new LeakyBucket({ capacity, leakRate })
+    }
+    case 'composite': {
+      console.log(`\n  ${bold('Primary algorithm:')}`)
+      const primaryKey  = await pickAlgorithm(ALGORITHMS.filter((a) => a.key !== 'composite'))
+      const primary     = await buildAlgorithm(primaryKey)
+
+      console.log(`\n  ${bold('Secondary algorithm:')}`)
+      const secondaryKey = await pickAlgorithm(ALGORITHMS.filter((a) => a.key !== 'composite'))
+      const secondary    = await buildAlgorithm(secondaryKey)
+
+      const modeRaw = await ask(`\n  Mode — ${cyan('1')} ALL (both must pass) / ${yellow('2')} ANY (one must pass) [1]: `)
+      const mode    = modeRaw === '2' ? COMPOSITE_MODES.ANY : COMPOSITE_MODES.ALL
+
+      return new Composite({ algorithms: [primary, secondary], mode })
+    }
+    default:
+      return new FixedWindow()
+  }
+}
+
+async function pickAlgorithm(list = ALGORITHMS) {
+  list.forEach((a, i) => {
+    console.log(`  ${bold(cyan(String(i + 1)))}. ${bold(a.label.padEnd(18))} ${dim(a.desc)}`)
+  })
+
+  const raw = await ask(`\n  Pick [1-${list.length}]: `)
+  const idx = parseInt(raw, 10) - 1
+
+  if (isNaN(idx) || idx < 0 || idx >= list.length) {
+    console.log(dim('  Invalid choice — defaulting to Token Bucket'))
+    return 'token-bucket'
+  }
+
+  return list[idx].key
+}
+
+// ── Table renderer ────────────────────────────────────────────────
+function renderTable(rows) {
+  const cols = [
+    { key: 'req',        label: 'Req',        width: 5  },
+    { key: 'time',       label: 'Time (ms)',  width: 10 },
+    { key: 'allowed',    label: 'Allowed',    width: 10 },
+    { key: 'remaining',  label: 'Remaining',  width: 11 },
+    { key: 'retryAfter', label: 'Retry (s)',  width: 10 },
+    { key: 'resetAt',    label: 'Resets At',  width: 12 },
+  ]
+
+  const divider = '+' + cols.map((c) => '-'.repeat(c.width + 2)).join('+') + '+'
+  const header  = '|' + cols.map((c) => ` ${bold(c.label.padEnd(c.width))} `).join('|') + '|'
+
+  console.log('\n' + divider)
+  console.log(header)
+  console.log(divider)
+
+  for (const row of rows) {
+    const allowed = row.allowed
+      ? green('✅ yes'.padEnd(10))
+      : red('❌ no'.padEnd(10))
+
+    const line = '|' + [
+      ` ${String(row.req).padEnd(cols[0].width)} `,
+      ` ${String(row.time).padEnd(cols[1].width)} `,
+      ` ${allowed} `,
+      ` ${String(row.remaining).padEnd(cols[3].width)} `,
+      ` ${String(row.retryAfter ?? '—').padEnd(cols[4].width)} `,
+      ` ${String(row.resetAt).padEnd(cols[5].width)} `,
+    ].join('|') + '|'
+
+    console.log(line)
+  }
+
+  console.log(divider)
+}
+
+// ── Summary ───────────────────────────────────────────────────────
+function renderSummary(rows) {
+  const allowed   = rows.filter((r) => r.allowed).length
+  const blocked   = rows.filter((r) => !r.allowed).length
+  const avgRemain = (rows.reduce((s, r) => s + r.remaining, 0) / rows.length).toFixed(1)
+
+  console.log(`
+  ${bold('Summary')}
+  ───────────────────────────────
+  Total requests : ${bold(String(rows.length))}
+  Allowed        : ${green(bold(String(allowed)))}
+  Blocked        : ${red(bold(String(blocked)))}
+  Avg remaining  : ${cyan(avgRemain)}
+  `)
+}
+
+// ── Sleep helper ──────────────────────────────────────────────────
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+// ── Main ──────────────────────────────────────────────────────────
+async function main() {
+  console.clear()
+  console.log(`
+  ${bold(cyan('⚡ ratelimit-engine'))} ${dim('— Algorithm Simulator')}
+  ${dim('─────────────────────────────────────────')}
+  `)
+
+  console.log(`  ${bold('Select algorithm:')}\n`)
+  const algoKey  = await pickAlgorithm()
+  const algo     = await buildAlgorithm(algoKey)
+  const requests = await askNumber('\nSimulate how many requests?', 15)
+  const delayMs  = await askNumber('Delay between requests (ms)?', 100)
+
+  console.log(`\n  ${dim('Running simulation...')}\n`)
+
+  const store = new MemoryStore()
+  const rows  = []
+  const key   = 'cli:simulate'
+  const start = Date.now()
+
+  for (let i = 1; i <= requests; i++) {
+    const result = await algo.check(key, store)
+    const elapsed = Date.now() - start
+
+    rows.push({
+      req:        i,
+      time:       elapsed,
+      allowed:    result.allowed,
+      remaining:  result.remaining,
+      retryAfter: result.retryAfter !== undefined ? result.retryAfter : '—',
+      resetAt:    result.resetAt.toTimeString().slice(0, 8),
+    })
+
+    if (i < requests) {
+      await sleep(delayMs)
+    }
+  }
+
+  await store.destroy()
+  renderTable(rows)
+  renderSummary(rows)
+
+  const again = await ask('  Run another simulation? (y/n) [n]: ')
+  if (again.toLowerCase() === 'y') {
+    await main()
+  } else {
+    console.log(`\n  ${dim('Goodbye.')}\n`)
+    rl.close()
+  }
+}
+
+main().catch((err) => {
+  console.error(red(`\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.0",
+  "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 })
+  }
+}