web-gatekeeper-js 1.0.0

package/README.md

@@ -0,0 +1,486 @@
+# gatekeeper-js
+
+A high-performance, Redis-powered rate limiter and throttler for Node.js applications.  
+Built for distributed systems, horizontally scalable architectures, and high concurrency environments.
+
+Supports:
+
+- Sliding Window Counter rate limiting
+- Token Bucket throttling
+- Atomic operations using Lua scripts
+- Distributed environments using Redis
+- Zero race conditions
+- High concurrency handling
+- Express, Fastify, NestJS, Koa, and custom Node.js servers
+
+---
+
+# Features
+
+- ⚡ Extremely fast Redis-based implementation
+- 🔒 Atomic operations using Redis Lua scripts
+- 🌐 Works across multiple servers/instances
+- 📈 Horizontally scalable
+- 🧠 Supports burst traffic handling
+- 🚫 Prevents race conditions in concurrent environments
+- 🪶 Lightweight and dependency minimal
+- 🔧 Fully configurable
+- 🧵 Safe under heavy parallel requests
+- ♻️ Reusable Redis connections
+- 📦 TypeScript support
+
+---
+
+# Why Redis?
+
+Traditional in-memory rate limiters work only on a single server instance.
+
+That becomes a problem when your application is deployed across:
+
+- Multiple containers
+- Multiple Node.js processes
+- Kubernetes clusters
+- Load balanced servers
+- Microservices
+
+Redis acts as a centralized shared datastore, allowing every instance of your application to enforce the same limits consistently.
+
+This package uses Redis for:
+
+- Shared state management
+- Atomic counters
+- Distributed synchronization
+- Fast in-memory performance
+
+---
+
+# Why Lua Scripts?
+
+Redis commands executed separately can lead to race conditions.
+
+Example problem:
+
+Two requests arrive simultaneously.
+
+Both requests:
+
+1. Read current token count
+2. Both think tokens are available
+3. Both consume tokens
+4. Limit gets bypassed
+
+This package avoids that entirely using Redis Lua scripts.
+
+Lua scripts run atomically inside Redis, meaning:
+
+- No other Redis command can interrupt execution
+- Read + update operations happen together
+- Concurrent requests remain safe
+- No locks are required
+
+This guarantees correctness even under massive traffic spikes.
+
+---
+
+# Algorithms Used
+
+## Sliding Window Counter (Rate Limiter)
+
+Used by `RateLimiter`.
+
+Tracks requests within a moving time window.
+
+Example:
+
+- Limit: `100 requests`
+- Window: `60 seconds`
+
+The limiter continuously tracks requests within the last 60 seconds instead of resetting abruptly like fixed window algorithms.
+
+### Benefits
+
+- Smoother limiting
+- More accurate than fixed windows
+- Prevents sudden request bursts at window boundaries
+- Better user experience
+
+---
+
+## Token Bucket (Throttler)
+
+Used by `Throttler`.
+
+Tokens refill gradually over time.
+
+Example:
+
+- Bucket size: `10`
+- Refill rate: `2 tokens/sec`
+
+If the bucket has tokens available, requests are allowed immediately.
+
+If not:
+
+- Requests are delayed/rejected
+- Burst traffic is controlled gracefully
+
+### Benefits
+
+- Handles traffic spikes efficiently
+- Allows short bursts
+- Smooth request flow
+- Ideal for APIs and real-time systems
+
+---
+
+# Installation
+
+```bash
+npm install gatekeeper-js ioredis
+```
+
+---
+
+# Quick Start
+
+## Rate Limiter Example
+
+```js
+import { RateLimiter } from 'gatekeeper-js'
+import Redis from 'ioredis'
+
+const redis = new Redis()
+
+const limiter = new RateLimiter({
+  redisClient : redis,
+  windowSize  : 60000,
+  limit       : 100,
+  maxToken    : 10,
+  refillRate  : 2
+})
+
+app.use(async (req, res, next) => {
+  const result = await limiter.consume(req.ip)
+
+  if (!result.allowed) {
+    return res.status(429).json({
+      error: result.reason
+    })
+  }
+
+  next()
+})
+```
+
+---
+
+## Throttler Example
+
+```js
+import { Throttler } from 'gatekeeper-js'
+import Redis from 'ioredis'
+
+const redis = new Redis()
+
+const throttler = new Throttler({
+  redisClient : redis,
+  refillRate  : 2,
+  maxWait     : 5000
+})
+
+app.use(async (req, res, next) => {
+  const result = await throttler.consume(req.ip)
+
+  if (!result.allowed) {
+    return res.status(429).json({
+      error: 'Too Many Requests'
+    })
+  }
+
+  next()
+})
+```
+
+---
+
+# API
+
+# RateLimiter
+
+## Constructor
+
+```js
+new RateLimiter(options)
+```
+
+## Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| redisClient | Redis | Yes | ioredis client instance |
+| windowSize | number | Yes | Time window in milliseconds |
+| limit | number | Yes | Maximum requests allowed per window |
+| maxToken | number | No | Maximum burst capacity |
+| refillRate | number | No | Token refill rate per second |
+
+---
+
+## consume(key)
+
+Consumes one request for a given identifier.
+
+```js
+const result = await limiter.consume('user-id')
+```
+
+## Response
+
+```js
+{
+  allowed: true,
+  remaining: 42,
+  resetTime: 1716200000000
+}
+```
+
+## Response Fields
+
+| Field | Description |
+|---|---|
+| allowed | Whether request is allowed |
+| remaining | Remaining requests/tokens |
+| resetTime | Unix timestamp when limit resets |
+| reason | Rejection reason if blocked |
+
+---
+
+# Throttler
+
+## Constructor
+
+```js
+new Throttler(options)
+```
+
+## Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| redisClient | Redis | Yes | ioredis client instance |
+| refillRate | number | Yes | Tokens added per second |
+| maxWait | number | No | Maximum wait time before rejection |
+
+---
+
+## consume(key)
+
+```js
+const result = await throttler.consume('user-id')
+```
+
+## Response
+
+```js
+{
+  allowed: true,
+  retryAfter: 0
+}
+```
+
+---
+
+# Scalability
+
+This package is designed for distributed systems.
+
+Because Redis stores the state centrally:
+
+- Multiple Node.js instances share the same limits
+- Limits remain consistent across deployments
+- Works seamlessly behind load balancers
+- Suitable for microservices and Kubernetes
+
+Example architecture:
+
+```text
+Client Requests
+       ↓
+Load Balancer
+       ↓
+ ┌─────────────┐
+ │ Node App 1  │
+ ├─────────────┤
+ │ Node App 2  │
+ ├─────────────┤
+ │ Node App 3  │
+ └─────────────┘
+       ↓
+     Redis
+```
+
+All application instances communicate with the same Redis server.
+
+---
+
+# Concurrency Safety
+
+This package is safe under heavy concurrent traffic.
+
+Redis Lua scripts ensure:
+
+- Atomic execution
+- No partial updates
+- No inconsistent counters
+- No race conditions
+
+Even if thousands of requests arrive simultaneously, limits remain accurate.
+
+---
+
+# Performance
+
+Redis operations are extremely fast because Redis stores data in memory.
+
+The package is optimized to:
+
+- Minimize Redis calls
+- Use atomic Lua execution
+- Reduce network overhead
+- Handle high throughput efficiently
+
+Suitable for:
+
+- Public APIs
+- Authentication systems
+- Login protection
+- Payment APIs
+- WebSocket gateways
+- Real-time applications
+
+---
+
+# Redis Compatibility
+
+Compatible with:
+
+- Redis 6+
+- Redis 7+
+- Redis Cluster
+- Redis Cloud providers
+
+---
+
+# Framework Support
+
+Works with any Node.js framework:
+
+- Express
+- Fastify
+- NestJS
+- Koa
+- Hono
+- Native HTTP servers
+
+---
+
+# Error Handling
+
+Example:
+
+```js
+try {
+  const result = await limiter.consume(req.ip)
+
+  if (!result.allowed) {
+    return res.status(429).json({
+      error: result.reason
+    })
+  }
+
+  next()
+} catch (error) {
+  console.error(error)
+
+  return res.status(500).json({
+    error: 'Internal Server Error'
+  })
+}
+```
+
+---
+
+# Best Practices
+
+## Use Stable Keys
+
+Good examples:
+
+```js
+req.ip
+user.id
+apiKey
+```
+
+Avoid random or frequently changing keys.
+
+---
+
+## Reuse Redis Connections
+
+Create one shared Redis client instance and reuse it across the application.
+
+```js
+const redis = new Redis()
+```
+
+---
+
+## Configure Reasonable Limits
+
+| Use Case | Suggested Limit |
+|---|---|
+| Login API | 5 requests/min |
+| Public API | 100 requests/min |
+| OTP Verification | 3 requests/5 min |
+
+---
+
+# License
+
+ISC License
+
+Permission to use, modify, and distribute this software for any purpose with or without fee is hereby granted.
+
+See the `LICENSE` file for full details.
+
+---
+
+# Contributing
+
+Contributions are welcome.
+
+Feel free to:
+
+- Open issues
+- Suggest improvements
+- Submit pull requests
+
+---
+
+# Roadmap
+
+Planned features:
+
+- Redis Cluster optimizations
+- Sliding log algorithm
+- Fixed window limiter
+- Rate limit headers
+- Automatic retries
+- Memory fallback store
+- Metrics integration
+
+---
+
+# Author
+
+Built for modern distributed Node.js applications using Redis and Lua for correctness, scalability, and performance.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "web-gatekeeper-js",
+  "version": "1.0.0",
+  "description": "Redis based rate limiter and throttler using sliding window and token bucket algorithms",
+  "main": "src/index.js",
+  "type": "module",
+  "keywords": [
+    "rate-limiter",
+    "throttler",
+    "redis",
+    "sliding-window",
+    "token-bucket",
+    "express",
+    "nodejs"
+  ],
+  "author": "Naveen Kushwaha",
+  "license": "ISC",
+  "peerDependencies": {
+    "ioredis": "^5.10.1"
+  },
+  "devDependencies": {
+    "ioredis": "^5.10.1"
+  }
+}

package/src/RateLimiter.js

@@ -0,0 +1,94 @@
+import { slidingWindowScript } from "./scripts/slidingWindow.lua";
+import { tokenBucket } from "./scripts/tokenBucket.lua";
+import { RedisStore } from "./store/RedisStore";
+
+export class RateLimiter {
+  #store;
+  #windowSize;
+  #limit;
+  #maxToken;
+  #refillRate;
+
+  constructor({ redisClient, windowSize, limit, maxToken, refillRate }) {
+    if (!redisClient) throw new Error("redisClient is required");
+    if (!windowSize) throw new Error("windowSize is required");
+    if (!limit) throw new Error("limit is required");
+    if (!maxToken) throw new Error("maxToken is required");
+    if (!refillRate) throw new Error("refillRate is required");
+
+    this.#store = new RedisStore(redisClient);
+    this.#windowSize = windowSize;
+    this.#limit = limit;
+    this.#maxToken = maxToken;
+    this.#refillRate = refillRate;
+  }
+
+  async consume(identifier){
+    const now = Date.now()
+
+    const slidingResult = await this.#runSlidingWindow(identifier, now)
+    if(!slidingResult.allowed){
+        return {
+            allowed: false,
+            reason: 'rate_limit_exceeded',
+            resetAfter: slidingResult.resetAfter
+        }
+    }
+
+    const bucketResult = await this.#runTokenBucket(identifier, now)
+    if(!bucketResult.allowed){
+        return {
+            allowed: false,
+            reason: 'burst_limit_exceeded',
+            retryAfter: bucketResult.retryAfter
+        }
+    }
+
+    return {
+      allowed         : true,
+      remaining       : slidingResult.remaining,
+      tokensRemaining : bucketResult.tokensLeft
+    }
+  }
+
+  async #runSlidingWindow(identifier,now){
+    const key = `rl:sliding:${identifier}`
+    const ttl = Math.ceil((this.#windowSize / 1000) * 2)
+
+    const result = await this.#store.evalScript(
+        slidingWindowScript,
+        key,
+        this.#windowSize,
+        this.#limit,
+        now,
+        ttl
+    )
+
+    return {
+        allowed : result[0] === 1,
+        current : result[1],
+        remaining : result[2],
+        resetAfter: result[3]
+    }
+  }
+
+  async #runTokenBucket(identifier, now) {
+    const key = `rl:bucket:${identifier}`
+    const ttl = Math.max(Math.ceil(this.#maxToken / this.#refillRate) * 2, 60)
+
+    const result = await this.#store.evalScript(
+      tokenBucketScript,
+      key,
+      now,                
+      this.#maxToken,     
+      this.#refillRate,   
+      ttl                 
+    )
+
+    return {
+      allowed    : result[0] === 1,
+      tokensLeft : result[1],
+      retryAfter : result[2]
+    }
+  }  
+}

package/src/Throttler.js

@@ -0,0 +1,55 @@
+// src/Throttler.js
+
+import { throttlerScript } from './scripts/throttler.lua.js'
+import { RedisStore }      from './store/RedisStore.js'
+
+export class Throttler {
+  #store
+  #refillRate
+  #maxWait
+
+  constructor({ redisClient, refillRate, maxWait }) {
+    if (!redisClient) throw new Error('redisClient is required')
+    if (!refillRate)  throw new Error('refillRate is required')
+    if (!maxWait)     throw new Error('maxWait is required')
+
+    this.#store      = new RedisStore(redisClient)
+    this.#refillRate = refillRate
+    this.#maxWait    = maxWait
+  }
+
+  async consume(identifier) {
+    const now = Date.now()
+    const key = `rl:throttler:${identifier}`
+    const ttl = 60
+
+    const result = await this.#store.evalScript(
+      throttlerScript,
+      key,
+      now,               
+      this.#refillRate,  
+      this.#maxWait,     
+      ttl                
+    )
+
+    const allowed  = result[0] === 1
+    const waitTime = result[1]
+
+    if (!allowed) {
+      return {
+        allowed    : false,
+        retryAfter : (waitTime / 1000).toFixed(2) + 's'
+      }
+    }
+
+    if (waitTime > 0) {
+      await this.#delay(waitTime)
+    }
+
+    return { allowed: true, waitTime }
+  }
+
+  #delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms))
+  }
+}

package/src/algorithms/SlidingWindowCounter.js

@@ -0,0 +1,29 @@
+export  const slidingWindow = async (req, res, next) => {
+  const userId     = req.ip
+  const windowSize = 60000
+  const limit      = 5
+  const now        = Date.now()
+  const ttl        = (windowSize / 1000) * 2   
+
+const result = await redisClient.eval(
+    slidingWindowScript,
+    1,                                    
+    `rl:Sliding:user:${userId}`,          
+    windowSize,                           
+    limit,                                
+    now,                                  
+    ttl                                   
+  )
+
+  console.log({
+    allowed       : result[0] === 1,
+    currentCount  : result[1],
+    remaining     : result[2]
+  })
+
+  if (result[0] === 0) {
+    return res.status(429).json({ message: "Too Many Requests" })
+  }
+
+  return next()
+}

package/src/algorithms/TokenBucket.js

@@ -0,0 +1,32 @@
+export const tokenBucket = async (req, res, next) => {
+  const userId     = req.ip
+  const maxToken   = 5
+  const refillRate = 0.5
+  const now        = Date.now()
+  const ttl        = Math.max(Math.ceil(maxToken / refillRate) * 2, 60)
+
+  const result = await redisClient.eval(
+    tokenBucketScript,
+    1,                                      
+    `rl:tokenBucket:user:${userId}`,        
+    now,                                   
+    maxToken,                               
+    refillRate,                             
+    ttl                                     
+  )
+
+  console.log({
+    allowed    : result[0] === 1,
+    tokensLeft : result[1],
+    retryAfter : result[2]
+  })
+
+  if (result[0] === 0) {
+    return res.status(429).json({
+      message    : "Too Many Requests",
+      retryAfter : `${result[2]}s`
+    })
+  }
+
+  return next()
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { RateLimiter } from './RateLimiter.js'
+export { Throttler }   from './Throttler.js'

package/src/scripts/slidingWindow.lua.js

@@ -0,0 +1,62 @@
+export const slidingWindowScript = `
+  local key         = KEYS[1]
+  local windowSize  = tonumber(ARGV[1])
+  local limit       = tonumber(ARGV[2])
+  local now         = tonumber(ARGV[3])
+  local ttl         = tonumber(ARGV[4])
+
+  local windowStart = math.floor(now / windowSize) * windowSize
+
+  local storedWindowStart = tonumber(redis.call('HGET', key, 'windowStart')   or 0)
+  local currentCount      = tonumber(redis.call('HGET', key, 'currentCount')  or 0)
+  local previousCount     = tonumber(redis.call('HGET', key, 'previousCount') or 0)
+
+  -- resetAfter calculated once, used in all returns
+  local resetAfter = math.ceil((windowSize - (now - windowStart)) / 1000)
+
+  -- first time user
+  if storedWindowStart == 0 then
+    redis.call('HSET', key,
+      'windowStart',   windowStart,
+      'currentCount',  1,
+      'previousCount', 0
+    )
+    redis.call('EXPIRE', key, ttl)
+    return { 1, 1, limit - 1, resetAfter }   -- ← 4 values
+  end
+
+  local windowsPassed = math.floor((windowStart - storedWindowStart) / windowSize)
+
+  local newPreviousCount = previousCount
+  local newCurrentCount  = currentCount
+
+  if windowsPassed > 1 then
+    newPreviousCount = 0
+    newCurrentCount  = 0
+  elseif windowsPassed == 1 then
+    newPreviousCount = currentCount
+    newCurrentCount  = 0
+  end
+
+  local elapsedTime    = (now - windowStart) / 1000
+  local overlap        = 1 - (elapsedTime / (windowSize / 1000))
+  local effectiveCount = (overlap * newPreviousCount) + newCurrentCount
+
+  -- blocked
+  if effectiveCount >= limit then
+    return { 0, newCurrentCount, 0, resetAfter }   -- ← 4 values
+  end
+
+  -- allowed
+  newCurrentCount = newCurrentCount + 1
+
+  redis.call('HSET', key,
+    'windowStart',   windowStart,
+    'currentCount',  newCurrentCount,
+    'previousCount', newPreviousCount
+  )
+  redis.call('EXPIRE', key, ttl)
+
+  local remaining = math.floor(limit - effectiveCount - 1)
+  return { 1, newCurrentCount, remaining, resetAfter }   -- ← 4 values
+`

package/src/scripts/throttler.lua.js

@@ -0,0 +1,34 @@
+export const throttler = `
+  local key        = KEYS[1]
+  local now        = tonumber(ARGV[1])
+  local refillRate = tonumber(ARGV[2])
+  local maxWait    = tonumber(ARGV[3])
+  local ttl        = tonumber(ARGV[4])
+
+  -- safely read nextAllowedTime
+  local raw             = redis.call('HGET', key, 'nextAllowedTime')
+  local nextAllowedTime = raw and tonumber(raw) or now
+
+  -- calculate wait time
+  local waitTime = nextAllowedTime - now
+
+  -- reject if queue too full
+  if waitTime > maxWait then
+    return { 0, waitTime }
+  end
+
+  -- calculate new nextAllowedTime
+  local newNextAllowedTime
+  if waitTime <= 0 then
+    newNextAllowedTime = now + (1000 / refillRate)
+  else
+    newNextAllowedTime = nextAllowedTime + (1000 / refillRate)
+  end
+
+  -- save and set TTL
+  redis.call('HSET', key, 'nextAllowedTime', newNextAllowedTime)
+  redis.call('EXPIRE', key, ttl)
+
+  -- return allowed + waitTime so Node.js knows how long to delay
+  return { 1, math.max(waitTime, 0) }
+`

package/src/scripts/tokenBucket.lua.js

@@ -0,0 +1,46 @@
+const tokenBucketScript = `
+  local key        = KEYS[1]
+  local now        = tonumber(ARGV[1])
+  local maxToken   = tonumber(ARGV[2])
+  local refillRate = tonumber(ARGV[3])
+  local ttl        = tonumber(ARGV[4])
+
+  -- read stored state (same as your hGetAll)
+  local lastReqTime = tonumber(redis.call('HGET', key, 'time')      or now)
+  local tokenLeft   = tonumber(redis.call('HGET', key, 'tokenLeft') or maxToken)
+
+  -- first time user (same as your empty check)
+  if lastReqTime == nil or tokenLeft == nil then
+    redis.call('HSET', key,
+      'time',      now,
+      'tokenLeft', maxToken - 1
+    )
+    redis.call('EXPIRE', key, ttl)
+    return { 1, maxToken - 1 }
+  end
+
+  -- calculate refill (same as your timeElapsed and updatedToken)
+  local timeElapsed   = (now - lastReqTime) / 1000
+  local updatedToken  = math.min(tokenLeft + (timeElapsed * refillRate), maxToken)
+
+  -- block if not enough tokens (same as your updatedToken < 1)
+  if updatedToken < 1 then
+    redis.call('HSET', key,
+      'time',      now,
+      'tokenLeft', updatedToken
+    )
+    redis.call('EXPIRE', key, ttl)
+
+    local retryAfter = math.ceil((1 - updatedToken) / refillRate)
+    return { 0, 0, retryAfter }
+  end
+
+  -- allow — consume 1 token and save (same as your hSet)
+  redis.call('HSET', key,
+    'time',      now,
+    'tokenLeft', updatedToken - 1
+  )
+  redis.call('EXPIRE', key, ttl)
+
+  return { 1, updatedToken - 1, 0 }
+`

package/src/store/RedisStore.js

@@ -0,0 +1,16 @@
+export class RedisStore {
+  #redis
+
+  constructor(redisClient) {
+    this.#redis = redisClient
+  }
+
+  async evalScript(script, key, ...args) {
+    return await this.#redis.eval(
+      script,
+      1,      
+      key,    
+      ...args 
+    )
+  }
+}