ratelimit-engine 1.0.1 → 1.1.0

package/bin/cli.js

@@ -1,13 +1,26 @@
 #!/usr/bin/env node
 /**
  * ratelimit-engine CLI
- * Setup wizard — generates ratelimit.config.js for your project.
- * Usage: npx ratelimit-engine
+ * Usage:
+ *   npx ratelimit-engine             — setup wizard
+ *   npx ratelimit-engine dashboard   — live 10ms dashboard
  */
 
 import * as readline from 'readline'
 import * as fs from 'fs'
 import * as path from 'path'
+import { createRequire } from 'module'
+import { fileURLToPath }  from 'url'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+
+// ── Route subcommands ─────────────────────────────────────────────
+const subcommand = process.argv[2]
+if (subcommand === 'dashboard') {
+  // Dynamically import and run the dashboard
+  await import(new URL('./dashboard.js', import.meta.url))
+  process.exit(0)
+}
 
 // ── ANSI colours ──────────────────────────────────────────────────
 const C = {
@@ -138,7 +151,7 @@ function algoArgs(key, config) {
   }
 }
 
-function generateConfig({ algoKey, algoConfig, storeKey, frameworkKey, keyStrategyKey }) {
+function generateConfig({ algoKey, algoConfig, storeKey, frameworkKey, keyStrategyKey, failOpen = true, customOnBlocked = null }) {
   const isRedis     = storeKey === 'RedisStore'
   const isComposite = algoKey === 'Composite'
 
@@ -146,7 +159,7 @@ function generateConfig({ algoKey, algoConfig, storeKey, frameworkKey, keyStrate
     ? [algoKey, algoConfig.primary.key, algoConfig.secondary.key]
     : [algoKey]
 
-  const allImports = [...new Set([...imports, storeKey, keyStrategyKey])]
+  const allImports = [...new Set(['createLimiter', ...imports, storeKey, keyStrategyKey])]
 
   const redisImport  = isRedis ? `\nimport Redis from 'ioredis'` : ''
   const redisClient  = isRedis ? `\nconst redis = new Redis() // configure your Redis connection\n` : ''
@@ -203,15 +216,19 @@ if (!result.allowed) {
       break
   }
 
+  const onBlockedMsg = customOnBlocked
+    ? `console.warn(\`${customOnBlocked}\`)`
+    : `console.warn(\`[RATE LIMIT] \${ctx.ip} blocked — retry in \${result.retryAfter}s\`)`
+
   return `import { ${allImports.join(', ')}${compositeImport} } from 'ratelimit-engine'${redisImport}
 ${redisClient}
 const limiter = createLimiter({
   algorithm: ${algoInit},
   store:     ${storeInit},
   keyBy:     ${keyStrategyKey},
-  failOpen:  true,
+  failOpen:  ${failOpen},
   onBlocked: (ctx, result) => {
-    console.warn(\`[RATE LIMIT] \${ctx.ip} blocked — retry in \${result.retryAfter}s\`)
+    ${onBlockedMsg}
   },
 })
 
@@ -252,6 +269,17 @@ async function main() {
   console.log(`\n  ${bold('Step 4 — How should requests be keyed?')}\n`)
   const keyStrategy = await askChoice(KEY_STRATEGIES)
 
+  // Step 5 — Custom overrides
+  console.log(`\n  ${bold('Step 5 — Custom options')} ${dim('(press Enter to skip each)')}`)
+  console.log(`  ${dim('Override any value before the file is written.\n')}`)
+
+  const outputFile = await ask(`  Output filename ${dim('[ratelimit.config.js]')}: `)
+  const fileName   = outputFile || 'ratelimit.config.js'
+
+  const customOnBlocked = await ask(`  onBlocked message ${dim('[Rate limit exceeded, retry in {n}s]')}: `)
+  const failOpenRaw     = await ask(`  failOpen — allow requests when store is down? ${dim('[yes]')}: `)
+  const failOpen        = failOpenRaw.toLowerCase() === 'no' ? false : true
+
   // Generate
   const code = generateConfig({
     algoKey:        algo.key,
@@ -259,21 +287,23 @@ async function main() {
     storeKey:       store.key,
     frameworkKey:   framework.key,
     keyStrategyKey: keyStrategy.key,
+    failOpen,
+    customOnBlocked: customOnBlocked || null,
   })
 
   // Write file
-  const outPath = path.join(process.cwd(), 'ratelimit.config.js')
+  const outPath = path.join(process.cwd(), fileName)
   fs.writeFileSync(outPath, code, 'utf8')
 
   // Output
   console.log(`\n  ${dim('─────────────────────────────────────────────')}`)
-  console.log(`  ${green(bold('✅ Done!'))} Generated ${bold('ratelimit.config.js')}\n`)
+  console.log(`  ${green(bold('✅ Done!'))} Generated ${bold(fileName)}\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(`     ${dim(`import { limiter } from './${fileName}'`)}`)
   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:`)

package/bin/dashboard.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Live dashboard entry point.
+ * Starts a demo server with rate limiting wired to the DashboardCollector,
+ * then renders the terminal UI at 10ms intervals.
+ *
+ * Usage: npx ratelimit-engine dashboard
+ */
+
+import { DashboardCollector } from '../src/dashboard/DashboardCollector.js'
+import { DashboardRenderer }  from '../src/dashboard/DashboardRenderer.js'
+import { createLimiter }      from '../src/engine/createLimiter.js'
+import { TokenBucket }        from '../src/algorithms/TokenBucket.js'
+import { FixedWindow }        from '../src/algorithms/FixedWindow.js'
+import { SlidingWindow }      from '../src/algorithms/SlidingWindow.js'
+import { MemoryStore }        from '../src/stores/MemoryStore.js'
+import { byIP }               from '../src/resolvers/byIP.js'
+
+const REFRESH_MS  = 10
+const DEMO_IPS    = ['192.168.1.1', '10.0.0.5', '172.16.0.3', '127.0.0.1']
+const DEMO_PATHS  = ['/api/hello', '/api/login', '/api/search', '/api/admin/data']
+const DEMO_METHOD = ['GET', 'POST', 'GET', 'DELETE']
+
+// ── Collector + Renderer ──────────────────────────────────────────
+const collector = new DashboardCollector()
+const renderer  = new DashboardRenderer()
+
+// ── Demo limiter (Token Bucket: burst 5, refill 2/sec) ───────────
+const limiter = createLimiter({
+  algorithm: new TokenBucket({ capacity: 5, refillRate: 2 }),
+  store:     new MemoryStore(),
+  keyBy:     byIP,
+  failOpen:  true,
+  onAllowed: (ctx, result) => collector.recordAllowed(ctx),
+  onBlocked: (ctx, result) => collector.recordBlocked(ctx, result),
+})
+
+// ── Simulate traffic — random bursts every 10–80ms ────────────────
+function simulateRequest() {
+  const idx    = Math.floor(Math.random() * DEMO_IPS.length)
+  const ip     = DEMO_IPS[idx]
+  const path   = DEMO_PATHS[idx]
+  const method = DEMO_METHOD[idx]
+
+  limiter.check({ ip, path, method, user: null })
+
+  // Schedule next request with variable interval to create burst patterns
+  const nextIn = Math.random() < 0.3
+    ? Math.floor(Math.random() * 5)    // burst: 0–5ms
+    : Math.floor(Math.random() * 80)   // normal: 0–80ms
+  setTimeout(simulateRequest, nextIn)
+}
+
+// ── Flush bucket every 10ms ───────────────────────────────────────
+const flushInterval = setInterval(() => collector.flush(), REFRESH_MS)
+
+// ── Render loop every 10ms ────────────────────────────────────────
+let paused = false
+const renderInterval = setInterval(() => {
+  if (!paused) renderer.render(collector.snapshot())
+}, REFRESH_MS)
+
+// ── Keyboard input ────────────────────────────────────────────────
+if (process.stdin.isTTY) {
+  process.stdin.setRawMode(true)
+}
+process.stdin.resume()
+process.stdin.setEncoding('utf8')
+
+process.stdin.on('data', (key) => {
+  if (key === 'q' || key === '\u0003') {
+    cleanup()
+  } else if (key === 'r') {
+    collector.reset()
+  } else if (key === 'p') {
+    paused = !paused
+    renderer.paused = paused
+  }
+})
+
+function cleanup() {
+  clearInterval(flushInterval)
+  clearInterval(renderInterval)
+  renderer.cleanup()
+  limiter.destroy()
+  process.exit(0)
+}
+
+process.on('SIGINT', cleanup)
+process.on('SIGTERM', cleanup)
+
+// ── Start ─────────────────────────────────────────────────────────
+simulateRequest()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ratelimit-engine",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Enterprise-grade, algorithm-pluggable rate limiting engine for Node.js",
   "main": "src/index.js",
   "type": "module",
@@ -35,7 +35,8 @@
     "LICENSE"
   ],
   "bin": {
-    "ratelimit-engine": "./bin/cli.js"
+    "ratelimit-engine": "./bin/cli.js",
+    "ratelimit-dashboard": "./bin/dashboard.js"
   },
   "author": "Abhinav710 <kumarabhinav5693@gmail.com>",
   "license": "MIT",

package/src/dashboard/DashboardCollector.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview In-process event collector for the live dashboard.
+ * Receives allowed/blocked events from RateLimiter hooks and
+ * maintains a rolling 10ms-bucketed time series.
+ */
+
+import { EventEmitter } from 'events'
+
+const BUCKET_MS   = 10   // resolution: one bucket per 10ms
+const HISTORY     = 200  // keep last 200 buckets (2 seconds of sparkline)
+const TOP_IPS     = 8    // max IPs shown in top-IPs panel
+const FEED_SIZE   = 12   // max rows in live feed
+
+export class DashboardCollector extends EventEmitter {
+  constructor() {
+    super()
+    this._buckets   = []   // rolling array of { ts, allowed, blocked }
+    this._ipMap     = new Map()   // ip → { allowed, blocked, lastSeen }
+    this._feed      = []          // last N events
+    this._startedAt = Date.now()
+    this._current   = this._newBucket()
+  }
+
+  /** Called by onAllowed hook */
+  recordAllowed(context) {
+    this._current.allowed++
+    this._trackIP(context, true)
+    this._pushFeed({ allowed: true, context, ts: Date.now() })
+    this.emit('tick')
+  }
+
+  /** Called by onBlocked hook */
+  recordBlocked(context, result) {
+    this._current.blocked++
+    this._trackIP(context, false)
+    this._pushFeed({ allowed: false, context, result, ts: Date.now() })
+    this.emit('tick')
+  }
+
+  /** Flush current bucket and start a new one — called every 10ms */
+  flush() {
+    this._buckets.push(this._current)
+    if (this._buckets.length > HISTORY) this._buckets.shift()
+    this._current = this._newBucket()
+  }
+
+  /** Snapshot for the renderer */
+  snapshot() {
+    const buckets  = [...this._buckets, this._current]
+    const last     = buckets.slice(-20)   // last 200ms window
+
+    const totalAllowed  = last.reduce((s, b) => s + b.allowed, 0)
+    const totalBlocked  = last.reduce((s, b) => s + b.blocked, 0)
+    const total         = totalAllowed + totalBlocked
+
+    const topIPs = [...this._ipMap.entries()]
+      .map(([ip, v]) => ({ ip, ...v }))
+      .sort((a, b) => (b.allowed + b.blocked) - (a.allowed + a.blocked))
+      .slice(0, TOP_IPS)
+
+    return {
+      uptime:    Date.now() - this._startedAt,
+      total,
+      allowed:   totalAllowed,
+      blocked:   totalBlocked,
+      sparkline: buckets.map((b) => b.allowed + b.blocked),
+      topIPs,
+      feed:      [...this._feed],
+    }
+  }
+
+  reset() {
+    this._buckets  = []
+    this._ipMap    = new Map()
+    this._feed     = []
+    this._current  = this._newBucket()
+    this._startedAt = Date.now()
+  }
+
+  _newBucket() {
+    return { ts: Date.now(), allowed: 0, blocked: 0 }
+  }
+
+  _trackIP(context, allowed) {
+    const ip = context?.ip ?? 'unknown'
+    const entry = this._ipMap.get(ip) ?? { allowed: 0, blocked: 0, lastSeen: 0 }
+    if (allowed) entry.allowed++
+    else entry.blocked++
+    entry.lastSeen = Date.now()
+    this._ipMap.set(ip, entry)
+  }
+
+  _pushFeed(event) {
+    this._feed.unshift(event)
+    if (this._feed.length > FEED_SIZE) this._feed.pop()
+  }
+}

package/src/dashboard/DashboardRenderer.js

@@ -0,0 +1,186 @@
+/**
+ * @fileoverview Terminal renderer for the live dashboard.
+ * Uses ANSI escape codes only — zero dependencies.
+ * Redraws the full screen every 10ms via process.stdout.write.
+ */
+
+// ── ANSI helpers ──────────────────────────────────────────────────
+const ESC   = '\x1b['
+const CLEAR = '\x1b[2J\x1b[H'   // clear screen + move cursor to top
+const HIDE  = '\x1b[?25l'       // hide cursor
+const SHOW  = '\x1b[?25h'       // show cursor
+
+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',
+  white:   '\x1b[37m',
+  bgRed:   '\x1b[41m',
+  bgGreen: '\x1b[42m',
+}
+
+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 yellow  = (s) => `${C.yellow}${s}${C.reset}`
+const cyan    = (s) => `${C.cyan}${s}${C.reset}`
+const magenta = (s) => `${C.magenta}${s}${C.reset}`
+
+// ── Sparkline ─────────────────────────────────────────────────────
+const SPARK_CHARS = ' ▁▂▃▄▅▆▇█'
+
+function sparkline(values, width = 50) {
+  const slice = values.slice(-width)
+  const max   = Math.max(...slice, 1)
+  return slice
+    .map((v) => {
+      const idx = Math.round((v / max) * (SPARK_CHARS.length - 1))
+      return SPARK_CHARS[idx]
+    })
+    .join('')
+    .padStart(width)
+}
+
+// ── Bar ───────────────────────────────────────────────────────────
+function bar(value, max, width = 30, color = green) {
+  const filled = max > 0 ? Math.round((value / max) * width) : 0
+  const empty  = width - filled
+  return color('█'.repeat(filled)) + dim('░'.repeat(empty))
+}
+
+// ── Format helpers ────────────────────────────────────────────────
+function fmtUptime(ms) {
+  const s = Math.floor(ms / 1000)
+  const m = Math.floor(s / 60)
+  const h = Math.floor(m / 60)
+  return [
+    String(h).padStart(2, '0'),
+    String(m % 60).padStart(2, '0'),
+    String(s % 60).padStart(2, '0'),
+  ].join(':')
+}
+
+function fmtTime(ts) {
+  return new Date(ts).toISOString().slice(11, 23)  // HH:MM:SS.mmm
+}
+
+function pad(s, n) {
+  return String(s).slice(0, n).padEnd(n)
+}
+
+// ── Box drawing ───────────────────────────────────────────────────
+const W = 62   // inner box width
+
+function boxTop(title) {
+  const t = title ? ` ${title} ` : ''
+  const dashes = '─'.repeat(W - t.length)
+  return `  ┌─${t}${dashes}┐`
+}
+
+function boxRow(content) {
+  const raw   = content.replace(/\x1b\[[0-9;]*m/g, '')  // strip ANSI for length
+  const pad   = W - raw.length
+  return `  │ ${content}${' '.repeat(Math.max(0, pad - 1))}│`
+}
+
+function boxBot() {
+  return `  └${'─'.repeat(W + 1)}┘`
+}
+
+// ── Main renderer ─────────────────────────────────────────────────
+export class DashboardRenderer {
+  constructor({ paused = false } = {}) {
+    this.paused = paused
+  }
+
+  render(snapshot) {
+    const { uptime, total, allowed, blocked, sparkline: spark, topIPs, feed } = snapshot
+    const blockPct = total > 0 ? ((blocked / total) * 100).toFixed(1) : '0.0'
+    const maxBar   = Math.max(total, 1)
+    const lines    = []
+
+    // ── Header ────────────────────────────────────────────────────
+    lines.push('')
+    lines.push(
+      `  ${bold(cyan('⚡ ratelimit-engine'))}  ${dim('Live Dashboard')}` +
+      `${' '.repeat(18)}${dim('Refresh: 10ms')}  ${this.paused ? yellow(bold('[PAUSED]')) : ''}`
+    )
+    lines.push(`  ${dim('─'.repeat(W + 2))}`)
+    lines.push(
+      `  Uptime: ${bold(fmtUptime(uptime))}` +
+      `${' '.repeat(10)}Window: last 200ms` +
+      `${' '.repeat(8)}${blocked > allowed ? red('⚠ HIGH BLOCK RATE') : green('● healthy')}`
+    )
+    lines.push('')
+
+    // ── Traffic panel ─────────────────────────────────────────────
+    lines.push(boxTop('Traffic — per 10ms bucket'))
+    lines.push(boxRow(`${pad('Total',    9)} ${bar(total,   maxBar, 28, cyan)}   ${bold(pad(total,   5))} req`))
+    lines.push(boxRow(`${pad('Allowed',  9)} ${bar(allowed, maxBar, 28, green)}   ${bold(green(pad(allowed, 5)))} req`))
+    lines.push(boxRow(`${pad('Blocked',  9)} ${bar(blocked, maxBar, 28, red)}   ${bold(red(pad(blocked, 5)))} req  ${dim(`${blockPct}%`)}`))
+    lines.push(boxBot())
+    lines.push('')
+
+    // ── Sparkline panel ───────────────────────────────────────────
+    lines.push(boxTop('Sparkline — last 2s (200 buckets × 10ms)'))
+    lines.push(boxRow(cyan(sparkline(spark, W - 2))))
+    lines.push(boxBot())
+    lines.push('')
+
+    // ── Top IPs ───────────────────────────────────────────────────
+    lines.push(boxTop('Top IPs'))
+    if (topIPs.length === 0) {
+      lines.push(boxRow(dim('No traffic yet...')))
+    } else {
+      for (const entry of topIPs) {
+        const ipTotal  = entry.allowed + entry.blocked
+        const label    = entry.blocked > entry.allowed
+          ? red('🔴 high block')
+          : green('🟢 normal   ')
+        const ipBar    = bar(entry.blocked, Math.max(ipTotal, 1), 12, red)
+        lines.push(boxRow(
+          `${pad(entry.ip, 16)}  ` +
+          `${pad(ipTotal, 5)} req  ` +
+          `${red(pad(entry.blocked, 4))} blocked  ` +
+          `${ipBar}  ${label}`
+        ))
+      }
+    }
+    lines.push(boxBot())
+    lines.push('')
+
+    // ── Live feed ─────────────────────────────────────────────────
+    lines.push(boxTop('Live Feed'))
+    if (feed.length === 0) {
+      lines.push(boxRow(dim('Waiting for requests...')))
+    } else {
+      for (const ev of feed) {
+        const status  = ev.allowed ? green('✅ ALLOWED') : red('❌ BLOCKED')
+        const ip      = pad(ev.context?.ip ?? 'unknown', 15)
+        const method  = pad(ev.context?.method ?? 'GET', 6)
+        const path    = pad(ev.context?.path ?? '/', 20)
+        const time    = dim(fmtTime(ev.ts))
+        lines.push(boxRow(`${time}  ${status}  ${ip} ${method} ${path}`))
+      }
+    }
+    lines.push(boxBot())
+    lines.push('')
+
+    // ── Footer ────────────────────────────────────────────────────
+    lines.push(`  ${dim('[q]')} quit   ${dim('[r]')} reset counters   ${dim('[p]')} pause/resume`)
+    lines.push('')
+
+    process.stdout.write(HIDE + CLEAR + lines.join('\n'))
+  }
+
+  cleanup() {
+    process.stdout.write(SHOW + '\n')
+  }
+}