redis-lua-rate-limiter 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# redis-lua-rate-limiter
+
+Distributed, atomic, token-bucket rate limiter for Node.js powered by Redis Lua scripts.
+
+## Why?
+
+Most Express rate limiters break in distributed systems.
+This one keeps the logic inside Redis using Lua for atomic safety.
+
+## Install
+
+```bash
+npm i redis-lua-rate-limiter
+```
+
+## Usage
+
+```ts
+import express from "express";
+import { createRateLimiter } from "redis-lua-rate-limiter";
+
+const limiter = await createRateLimiter({
+  redisUrl: "redis://localhost:6379",
+  default: { capacity: 10, refillRate: 5 },
+  headers: true,
+});
+
+app.use(limiter.middleware());
+```
+
+## Features
+
+- Token bucket algorithm
+- Redis Lua atomic execution
+- Per API key / IP limiting
+- Per route limits
+- Rate limit headers
+- Works across multiple Node servers
+
+## Benchmark
+
+```
+$ npx autocannon -c 1000 -d 15 http://localhost:3000
+Running 15s test @ http://localhost:3000
+```
+
+Tested with 1000 connections using autocannon
+
+```
+┌─────────┬────────┬────────┬────────┬────────┬───────────┬──────────┬────────┐
+│ Stat    │ 2.5%   │ 50%    │ 97.5%  │ 99%    │ Avg       │ Stdev
+    │ Max    │
+├─────────┼────────┼────────┼────────┼────────┼───────────┼──────────┼────────┤
+│ Latency │ 203 ms │ 214 ms │ 253 ms │ 481 ms │ 220.74 ms │ 41.38 ms │ 759 ms │
+└─────────┴────────┴────────┴────────┴────────┴───────────┴──────────┴────────┘
+┌───────────┬────────┬────────┬─────────┬─────────┬─────────┬────────┬────────┐
+│ Stat      │ 1%     │ 2.5%   │ 50%     │ 97.5%   │ Avg     │ Stdev  │ Min    │
+├───────────┼────────┼────────┼─────────┼─────────┼─────────┼────────┼────────┤
+│ Req/Sec   │ 2,739  │ 2,739  │ 4,595   │ 5,003   │ 4,516.4 │ 558.22 │ 2,739  │
+├───────────┼────────┼────────┼─────────┼─────────┼─────────┼────────┼────────┤
+│ Bytes/Sec │ 898 kB │ 898 kB │ 1.51 MB │ 1.64 MB │ 1.48 MB │ 183 kB │ 897 kB │
+└───────────┴────────┴────────┴─────────┴─────────┴─────────┴────────┴────────┘
+```
+Req/Bytes counts sampled once per second.
+# of samples: 15
+```
+160 2xx responses, 67579 non 2xx responses
+69k requests in 15.22s, 22.2 MB read
+
+```
+
+Shows strict enforcement without race conditions.
+
+## Docker
+
+```bash
+docker compose up
+```

package/dist/core/lua.d.ts

@@ -0,0 +1,2 @@
+import { Redis } from "ioredis";
+export declare function loadLua(redis: Redis): Promise<unknown>;

package/dist/core/lua.js

@@ -0,0 +1,15 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadLua = loadLua;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+async function loadLua(redis) {
+    const luaPath = path_1.default.join(__dirname, "..", "..", "lua", "token_bucket.lua");
+    const script = fs_1.default.readFileSync(luaPath, "utf8");
+    const sha = await redis.script("LOAD", script);
+    return sha;
+}
+//# sourceMappingURL=lua.js.map

package/dist/core/lua.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lua.js","sourceRoot":"","sources":["../../src/core/lua.ts"],"names":[],"mappings":";;;;;AAIA,0BAKC;AATD,4CAAoB;AACpB,gDAAwB;AAGjB,KAAK,UAAU,OAAO,CAAC,KAAY;IACxC,MAAM,OAAO,GAAG,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,kBAAkB,CAAC,CAAC;IAC5E,MAAM,MAAM,GAAG,YAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/core/redis.d.ts

@@ -0,0 +1,2 @@
+import Redis from "ioredis";
+export declare function createRedisClient(redisUrl: string): Redis;

package/dist/core/redis.js

@@ -0,0 +1,11 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRedisClient = createRedisClient;
+const ioredis_1 = __importDefault(require("ioredis"));
+function createRedisClient(redisUrl) {
+    return new ioredis_1.default(redisUrl);
+}
+//# sourceMappingURL=redis.js.map

package/dist/core/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.js","sourceRoot":"","sources":["../../src/core/redis.ts"],"names":[],"mappings":";;;;;AAEA,8CAEC;AAJD,sDAA4B;AAE5B,SAAgB,iBAAiB,CAAC,QAAgB;IAChD,OAAO,IAAI,iBAAK,CAAC,QAAQ,CAAC,CAAC;AAC7B,CAAC"}

package/dist/core/tokenBucket.d.ts

@@ -0,0 +1,2 @@
+import { Redis } from "ioredis";
+export declare function executeTokenBucket(redis: Redis, sha: string, key: string, capacity: number, refillRate: number): Promise<boolean>;

package/dist/core/tokenBucket.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeTokenBucket = executeTokenBucket;
+async function executeTokenBucket(redis, sha, key, capacity, refillRate) {
+    const now = Math.floor(Date.now() / 1000);
+    const allowed = await redis.evalsha(sha, 1, key, capacity, refillRate, now, 1);
+    return allowed === 1;
+}
+//# sourceMappingURL=tokenBucket.js.map

package/dist/core/tokenBucket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenBucket.js","sourceRoot":"","sources":["../../src/core/tokenBucket.ts"],"names":[],"mappings":";;AAEA,gDAoBC;AApBM,KAAK,UAAU,kBAAkB,CACtC,KAAY,EACZ,GAAW,EACX,GAAW,EACX,QAAgB,EAChB,UAAkB;IAElB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAE1C,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,OAAO,CACjC,GAAG,EACH,CAAC,EACD,GAAG,EACH,QAAQ,EACR,UAAU,EACV,GAAG,EACH,CAAC,CACF,CAAC;IAEF,OAAO,OAAO,KAAK,CAAC,CAAC;AACvB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { Request } from "express";
+import { RateLimiterOptions } from "./types";
+export declare function createRateLimiter(options: RateLimiterOptions): Promise<{
+    middleware: () => (req: Request, res: any, next: any) => Promise<any>;
+}>;

package/dist/index.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRateLimiter = createRateLimiter;
+const redis_1 = require("./core/redis");
+const lua_1 = require("./core/lua");
+async function createRateLimiter(options) {
+    const redis = (0, redis_1.createRedisClient)(options.redisUrl);
+    const sha = await (0, lua_1.loadLua)(redis);
+    const keyGen = options.keyGenerator || ((req) => `rate:${req.ip}`);
+    const routes = new Map(Object.entries(options.routes || {}));
+    async function rateLimit(key, config) {
+        const now = Math.floor(Date.now() / 1000);
+        const [allowed, remaining] = (await redis.evalsha(sha, 1, key, config.capacity, config.refillRate, now, 1));
+        return { allowed: allowed === 1, remaining };
+    }
+    function middleware() {
+        return async (req, res, next) => {
+            const routeConfig = routes.get(req.path) || options.default;
+            const key = keyGen(req);
+            const { allowed, remaining } = await rateLimit(key, routeConfig);
+            if (options.headers) {
+                res.setHeader("X-RateLimit-Limit", routeConfig.capacity);
+                res.setHeader("X-RateLimit-Remaining", Math.floor(remaining));
+            }
+            if (!allowed) {
+                return res.status(429).json({
+                    error: "Too Many Requests",
+                });
+            }
+            next();
+        };
+    }
+    return { middleware };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAKA,8CA0DC;AA/DD,wCAAiD;AACjD,oCAAqC;AAI9B,KAAK,UAAU,iBAAiB,CAAC,OAA2B;IACjE,MAAM,KAAK,GAAG,IAAA,yBAAiB,EAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,MAAM,IAAA,aAAO,EAAC,KAAK,CAAC,CAAC;IAEjC,MAAM,MAAM,GACV,OAAO,CAAC,YAAY,IAAI,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,QAAQ,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IAE/D,MAAM,MAAM,GAAG,IAAI,GAAG,CACpB,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CACrC,CAAC;IAEF,KAAK,UAAU,SAAS,CACtB,GAAW,EACX,MAAoB;QAEpB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAE1C,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,OAAO,CAC/C,GAAa,EACb,CAAC,EACD,GAAG,EACH,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,UAAU,EACjB,GAAG,EACH,CAAC,CACF,CAAqB,CAAC;QAEvB,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IAC/C,CAAC;IAED,SAAS,UAAU;QACjB,OAAO,KAAK,EAAE,GAAY,EAAE,GAAQ,EAAE,IAAS,EAAE,EAAE;YACjD,MAAM,WAAW,GACf,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC;YAE1C,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAExB,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,SAAS,CAC5C,GAAG,EACH,WAAW,CACZ,CAAC;YAEF,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACpB,GAAG,CAAC,SAAS,CAAC,mBAAmB,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;gBACzD,GAAG,CAAC,SAAS,CAAC,uBAAuB,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YAChE,CAAC;YAED,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;oBAC1B,KAAK,EAAE,mBAAmB;iBAC3B,CAAC,CAAC;YACL,CAAC;YAED,IAAI,EAAE,CAAC;QACT,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,CAAC;AACxB,CAAC"}

package/dist/middleware/express.d.ts

@@ -0,0 +1,2 @@
+import { Request, Response, NextFunction } from "express";
+export declare function createExpressMiddleware(rateLimitFn: (key: string) => Promise<boolean>): (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;

package/dist/middleware/express.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createExpressMiddleware = createExpressMiddleware;
+function createExpressMiddleware(rateLimitFn) {
+    return async (req, res, next) => {
+        const key = `rate:${req.ip}`;
+        const allowed = await rateLimitFn(key);
+        if (!allowed) {
+            return res.status(429).json({ error: "Too Many Requests" });
+        }
+        next();
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/middleware/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../src/middleware/express.ts"],"names":[],"mappings":";;AAEA,0DAYC;AAZD,SAAgB,uBAAuB,CAAC,WAA8C;IACpF,OAAO,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QAC/D,MAAM,GAAG,GAAG,QAAQ,GAAG,CAAC,EAAE,EAAE,CAAC;QAE7B,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;QAEvC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,CAAC;QAC9D,CAAC;QAED,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+import { Request } from "express";
+export type BucketConfig = {
+    capacity: number;
+    refillRate: number;
+};
+export type RateLimiterOptions = {
+    redisUrl: string;
+    default: BucketConfig;
+    routes?: Record<string, BucketConfig>;
+    keyGenerator?: (req: Request) => string;
+    headers?: boolean;
+};

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/lua/token_bucket.lua

@@ -0,0 +1,30 @@
+local key = KEYS[1]
+
+local capacity = tonumber(ARGV[1])
+local refill_rate = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local requested = tonumber(ARGV[4])
+
+local data = redis.call("HMGET", key, "tokens", "timestamp")
+local tokens = tonumber(data[1])
+local timestamp = tonumber(data[2])
+
+if tokens == nil then
+    tokens = capacity
+    timestamp = now
+end
+
+local delta = math.max(0, now - timestamp)
+local refill = delta * refill_rate
+tokens = math.min(capacity, tokens + refill)
+
+local allowed = tokens >= requested
+
+if allowed then
+    tokens = tokens - requested
+end
+
+redis.call("HMSET", key, "tokens", tokens, "timestamp", now)
+redis.call("EXPIRE", key, 3600)
+
+return { allowed and 1 or 0, tokens }

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "redis-lua-rate-limiter",
+  "version": "1.0.0",
+  "description": "Distributed token-bucket rate limiter using Redis Lua scripts for Node.js/Express",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "lua"],
+
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node-dev example/express-app.ts"
+  },
+  "keywords": [
+    "rate-limiter",
+    "redis",
+    "lua",
+    "token-bucket",
+    "express",
+    "distributed"
+  ],
+  "author": "shubhankar kumar singh",
+  "license": "MIT",
+  "dependencies": {
+    
+    "ioredis": "^5.9.2"
+  },
+  "peerDependencies": {
+    "express": "^4 || ^5"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.2.1",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.9.3"
+  }
+}