redis-distributed-rate-limiter 1.0.0

package/README.md

@@ -0,0 +1,135 @@
+# redis-distributed-rate-limiter
+
+A high-performance, ultra-low-latency distributed rate-limiting middleware for Express.js applications. Built with atomic Redis Lua scripting to prevent race conditions across horizontally scaled infrastructure, featuring a decoupled asynchronous telemetry hook for real-time traffic observability.
+
+[![TypeScript Supported](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+## 🏗️ Core Architecture
+
+This library isolates the critical path of API request evaluation from the secondary collection of analytical telemetry data. By executing a Rolling Sliding Window algorithm atomically within a single Redis thread, the middleware maintains a sub-3ms latency overhead while providing rich hooks to stream analytics to downstream systems like Apache Kafka, RabbitMQ, or managed logging databases.
+
+* **Distributed Synchronization:** State is centralized in Redis, allowing multiple stateless API gateway instances to scale out horizontally while maintaining shared rate-limit quotas.
+* **Atomic Sliding Window:** Uses custom Lua scripting (`ZREMRANGEBYSCORE` + `ZADD` + `ZCARD`) to guarantee thread safety and prevent window-boundary traffic exploitation.
+* **Non-Blocking Telemetry Pipelines:** Exposes a clean event-driven interface that offloads log recording out of the main request-response lifecycle loop using `process.nextTick()`.
+* **Resilient Fail-Open Design:** Automatically logs internal exceptions and fails open, preventing cache cluster outages from crashing customer-facing API nodes.
+
+---
+
+## ⚙️ Installation
+
+Install the package via the npm registry:
+
+```bash
+npm install redis-distributed-rate-limiter
+
+```
+
+### Peer Dependencies
+
+Ensure you have the official Redis client installed and running in your root application environment:
+
+```bash
+npm install redis
+
+```
+
+---
+
+## 🚀 Quick Start (TypeScript / JavaScript)
+
+Initialize the middleware by passing your pre-configured Redis client wrapper and setting up your threshold definitions:
+
+```typescript
+import express from 'express';
+import { createClient } from 'redis';
+import { distributedRateLimiter, TelemetryLog } from 'redis-distributed-rate-limiter';
+
+const app = express();
+
+// 1. Initialize your centralized Redis client connection
+const redisClient = createClient({ url: 'redis://localhost:6379' });
+redisClient.connect().then(() => console.log('Redis connected successfully'));
+
+// 2. Configure the Distributed Rate Limiter Middleware
+const limiter = distributedRateLimiter({
+  redisClient: redisClient,
+  windowInMs: 60000,   // 1 Minute moving sliding window
+  maxRequests: 10,     // Allow up to 10 requests per window
+  
+  // Custom non-blocking callback hook for async logging infrastructure
+  onLog: (logData: TelemetryLog) => {
+    // Example: Stream log payloads asynchronously to an Apache Kafka Producer,
+    // a microservice logger, or push to an analytics queue.
+    console.log(`[Telemetry Ingress] IP: ${logData.ip} | Status: ${logData.status} | Hits: ${logData.currentCount}`);
+  }
+});
+
+// 3. Apply the middleware cluster globally or to explicit routes
+app.use(limiter);
+
+app.get('/api/v1/resource', (req, res) => {
+  res.json({ success: true, message: "Welcome to the secure gateway." });
+});
+
+// Note: If running behind reverse proxies (AWS ALB, Nginx, Cloudflare, Vercel)
+app.set('trust proxy', true);
+
+app.listen(3000, () => console.log('API Gateway active on port 3000'));
+
+```
+
+---
+
+## 🎛️ Configuration Reference
+
+The `distributedRateLimiter` initialization constructor accepts the following structured parameters:
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `redisClient` | `any` | **Yes** | An open, active v4 instance connection to your Redis deployment server. |
+| `windowInMs` | `number` | **Yes** | Moving time framework window tracked in milliseconds (e.g., `60000` for 1 minute). |
+| `maxRequests` | `number` | **Yes** | Total allowed operations inside the specific time frame constraint bounds. |
+| `keyGenerator` | `(req) => string` | No | Overrides default key tracking logic. Allows tracking limits using authorization tokens, API keys, or User IDs instead of plain IP routing. |
+| `onLog` | `(log: TelemetryLog) => void` | No | Callback hook firing asynchronously upon execution completion. Passes complete log payload packages. |
+
+---
+
+## 📊 Telemetry Log Payload Schema
+
+The `onLog` event emitter passes an immutable `TelemetryLog` object containing downstream performance values:
+
+```typescript
+interface TelemetryLog {
+  ip: string;           // Remote user origin IP or mapped proxy client
+  path: string;         // Visited API node endpoint URL string
+  method: string;       // Executed HTTP request method verb (GET, POST, etc.)
+  status: 'ALLOWED' | 'BLOCKED'; // Resolution status string output
+  timestamp: number;    // POSIX timestamp tracking exact request ingress time
+  currentCount: number; // Active tracking window hit state returned from Redis
+}
+
+```
+
+---
+
+## 🛡️ Response Headers
+
+Successful operations return standard rate limit metadata embedded securely inside response headers:
+
+```http
+X-RateLimit-Limit: 10
+X-RateLimit-Remaining: 9
+X-RateLimit-Reset: 2026-07-05T11:04:48.201Z
+
+```
+
+When thresholds are broken, the middleware automatically rejects traffic with an explicit `429 Too Many Requests` status payload:
+
+```json
+{
+  "status": 429,
+  "error": "Too Many Requests",
+  "message": "Rate limit exceeded. Please try again in 60 seconds."
+}
+
+```

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { Request, Response, NextFunction } from 'express';
+import { LimiterConfig } from './types';
+export declare function distributedRateLimiter(config: LimiterConfig): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,IAO5C,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,OAAO,CAAC,IAAI,CAAC,CA6D9E"}

package/dist/index.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.distributedRateLimiter = distributedRateLimiter;
+const luaScript_1 = require("./luaScript");
+function distributedRateLimiter(config) {
+    const { redisClient, windowInMs, maxRequests, onLog } = config;
+    // Default key generator uses the client's IP address
+    const defaultKeyGen = (req) => `ratelimit:${req.ip || req.socket.remoteAddress}`;
+    const getKey = config.keyGenerator || defaultKeyGen;
+    return async (req, res, next) => {
+        // cast to any to avoid strict Request type incompatibilities across express versions
+        const key = getKey(req);
+        const now = Date.now();
+        try {
+            // Execute the atomic Lua script in Redis
+            // eval(script, numKeys, keys, args)
+            const result = await redisClient.eval(luaScript_1.SLIDING_WINDOW_LUA, {
+                keys: [key],
+                arguments: [now.toString(), windowInMs.toString(), maxRequests.toString()]
+            });
+            const [isAllowed, currentCount] = result;
+            const remaining = Math.max(0, maxRequests - currentCount);
+            // Set standard rate-limiting headers
+            res.setHeader('X-RateLimit-Limit', maxRequests);
+            res.setHeader('X-RateLimit-Remaining', remaining);
+            res.setHeader('X-RateLimit-Reset', new Date(now + windowInMs).toISOString());
+            if (isAllowed === 1) {
+                // Trigger telemetry asynchronously without pausing the application cycle
+                if (onLog) {
+                    process.nextTick(() => onLog({
+                        ip: req.ip || 'unknown',
+                        path: req.path,
+                        method: req.method,
+                        status: 'ALLOWED',
+                        timestamp: now,
+                        currentCount
+                    }));
+                }
+                return next();
+            }
+            else {
+                // Block the request if the threshold is breached
+                if (onLog) {
+                    process.nextTick(() => onLog({
+                        ip: req.ip || 'unknown',
+                        path: req.path,
+                        method: req.method,
+                        status: 'BLOCKED',
+                        timestamp: now,
+                        currentCount
+                    }));
+                }
+                res.status(429).json({
+                    status: 429,
+                    error: 'Too Many Requests',
+                    message: `Rate limit exceeded. Please try again in ${Math.ceil(windowInMs / 1000)} seconds.`
+                });
+                return;
+            }
+        }
+        catch (error) {
+            // Fail-open strategy: If Redis fails, log the error and allow the traffic to pass
+            // so your security tool doesn't accidentally cause a total app outage.
+            console.error('Rate Limiter Internal Error:', error);
+            return next();
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/luaScript.d.ts

@@ -0,0 +1,2 @@
+export declare const SLIDING_WINDOW_LUA = "\n  local key = KEYS[1]\n  local now = tonumber(ARGV[1])\n  local window = tonumber(ARGV[2])\n  local limit = tonumber(ARGV[3])\n  \n  local clearBefore = now - window\n  \n  -- 1. Remove timestamps older than the current sliding window boundary\n  redis.call('ZREMRANGEBYSCORE', key, '-inf', clearBefore)\n  \n  -- 2. Count how many requests are left in the current window\n  local currentRequests = redis.call('ZCARD', key)\n  \n  -- 3. If below the limit, allow the request and log the current timestamp\n  if currentRequests < limit then\n    redis.call('ZADD', key, now, now)\n    -- Set an expiry on the key so it cleans itself up if the user stops sending requests\n    redis.call('EXPIRE', key, math.ceil(window / 1000))\n    return {1, currentRequests + 1} -- [Allowed = true, New Count]\n  else\n    return {0, currentRequests}     -- [Allowed = false, Current Count]\n  end\n";
+//# sourceMappingURL=luaScript.d.ts.map

package/dist/luaScript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"luaScript.d.ts","sourceRoot":"","sources":["../src/luaScript.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,23BAuB9B,CAAC"}

package/dist/luaScript.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SLIDING_WINDOW_LUA = void 0;
+exports.SLIDING_WINDOW_LUA = `
+  local key = KEYS[1]
+  local now = tonumber(ARGV[1])
+  local window = tonumber(ARGV[2])
+  local limit = tonumber(ARGV[3])
+  
+  local clearBefore = now - window
+  
+  -- 1. Remove timestamps older than the current sliding window boundary
+  redis.call('ZREMRANGEBYSCORE', key, '-inf', clearBefore)
+  
+  -- 2. Count how many requests are left in the current window
+  local currentRequests = redis.call('ZCARD', key)
+  
+  -- 3. If below the limit, allow the request and log the current timestamp
+  if currentRequests < limit then
+    redis.call('ZADD', key, now, now)
+    -- Set an expiry on the key so it cleans itself up if the user stops sending requests
+    redis.call('EXPIRE', key, math.ceil(window / 1000))
+    return {1, currentRequests + 1} -- [Allowed = true, New Count]
+  else
+    return {0, currentRequests}     -- [Allowed = false, Current Count]
+  end
+`;
+//# sourceMappingURL=luaScript.js.map

package/dist/luaScript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"luaScript.js","sourceRoot":"","sources":["../src/luaScript.ts"],"names":[],"mappings":";;;AAAa,QAAA,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;CAuBjC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+export interface TelemetryLog {
+    ip: string;
+    path: string;
+    method: string;
+    status: 'ALLOWED' | 'BLOCKED';
+    timestamp: number;
+    currentCount: number;
+}
+export interface LimiterConfig {
+    redisClient: any;
+    windowInMs: number;
+    maxRequests: number;
+    keyGenerator?: (req: Request) => string;
+    onLog?: (log: TelemetryLog) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,GAAG,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACxC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,IAAI,CAAC;CACrC"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "redis-distributed-rate-limiter",
+  "version": "1.0.0",
+  "description": "High-performance distributed rate-limiting middleware for Express using atomic Redis Lua scripting and non-blocking telemetry hooks.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "redis",
+    "rate-limiter",
+    "distributed",
+    "express",
+    "middleware",
+    "lua",
+    "sliding-window",
+    "telemetry",
+    "api-security"
+  ],
+  "author": "Rohit Verma",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "redis": "^4.0.0"
+  }
+}