sliding-window-counter-rate-limiter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shubham Kakade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,339 @@
+# Sliding Window Counter Rate Limiter
+
+A production-ready **Sliding Window Counter rate limiter** for Express applications using **Redis and Lua**.
+
+It provides atomic rate limiting, configurable client identification, rate-limit headers, Redis failure strategies, and automatic Redis reconnection support.
+
+## Features
+
+- Sliding Window Counter algorithm
+- Redis-backed distributed rate limiting
+- Atomic Redis + Lua execution
+- Express middleware
+- Custom client/key identification
+- Configurable rate limits
+- Configurable Redis key prefix
+- `fail-open` and `fail-closed` Redis strategies
+- Rate-limit response headers
+- `Retry-After` header for blocked requests
+- Input configuration validation
+- Concurrent request safety
+
+## Installation
+
+```bash
+npm install sliding-window-counter-rate-limiter redis
+```
+
+## Requirements
+
+- Node.js 18+
+- Redis 6+
+- Express 4+ or 5+
+
+## Basic Usage
+
+```js
+const express = require("express");
+const { createClient } = require("redis");
+
+const { rateLimiter } = require("sliding-window-counter-rate-limiter");
+
+const app = express();
+
+const redis = createClient({
+  url: "redis://localhost:6379",
+});
+
+redis.on("error", (error) => {
+  console.error("Redis error:", error);
+});
+
+redis.connect();
+
+const limiter = rateLimiter({
+  redis,
+  limit: 100,
+  windowMs: 60_000,
+});
+
+app.use(limiter);
+
+app.get("/", (req, res) => {
+  res.json({
+    success: true,
+    message: "Request allowed",
+  });
+});
+
+app.listen(3000, () => {
+  console.log("Server running on port 3000");
+});
+```
+
+The above configuration allows:
+
+```text
+100 requests
+per 60 seconds
+per client IP
+```
+
+The default client identifier is:
+
+```js
+(req) => req.ip;
+```
+
+## Custom Client Identification
+
+You can define how clients should be identified using `keyGenerator`.
+
+### User ID
+
+```js
+const limiter = rateLimiter({
+  redis,
+  limit: 100,
+  windowMs: 60_000,
+
+  keyGenerator: (req) => req.user.id,
+});
+```
+
+### API Key
+
+```js
+const limiter = rateLimiter({
+  redis,
+  limit: 1000,
+  windowMs: 60_000,
+
+  keyGenerator: (req) => req.headers["x-api-key"],
+});
+```
+
+### IP Address
+
+This is the default:
+
+```js
+const limiter = rateLimiter({
+  redis,
+  limit: 100,
+  windowMs: 60_000,
+
+  keyGenerator: (req) => req.ip,
+});
+```
+
+If your application is behind a reverse proxy, configure Express `trust proxy` appropriately so `req.ip` represents the intended client.
+
+## Configuration
+
+| Option               | Type         | Default         | Description                       |
+| -------------------- | ------------ | --------------- | --------------------------------- |
+| `redis`              | Redis client | Required        | Redis client instance             |
+| `limit`              | number       | Required        | Maximum requests allowed          |
+| `windowMs`           | number       | Required        | Rate-limit window in milliseconds |
+| `keyGenerator`       | function     | `req => req.ip` | Generates the client identifier   |
+| `keyPrefix`          | string       | `"rate-limit"`  | Redis key namespace               |
+| `redisErrorStrategy` | string       | `"fail-open"`   | Redis failure behavior            |
+
+### Example
+
+```js
+const limiter = rateLimiter({
+  redis,
+  limit: 100,
+  windowMs: 60_000,
+  keyGenerator: (req) => req.user.id,
+  keyPrefix: "my-api",
+  redisErrorStrategy: "fail-closed",
+});
+```
+
+## Redis Error Strategies
+
+### `fail-open`
+
+```js
+redisErrorStrategy: "fail-open";
+```
+
+If Redis becomes unavailable, the request continues to the application:
+
+```text
+Request
+   ↓
+Rate limiter
+   ↓
+Redis unavailable
+   ↓
+next()
+   ↓
+Application
+```
+
+This prioritizes application availability over strict rate limiting.
+
+### `fail-closed`
+
+```js
+redisErrorStrategy: "fail-closed";
+```
+
+If Redis becomes unavailable, the middleware returns:
+
+```http
+503 Service Unavailable
+```
+
+```json
+{
+  "success": false,
+  "message": "Rate limiter temporarily unavailable"
+}
+```
+
+This prioritizes strict rate-limit enforcement.
+
+## Rate-Limit Headers
+
+Successful requests include:
+
+```http
+RateLimit-Limit: 100
+RateLimit-Remaining: 99
+RateLimit-Reset: 42
+```
+
+When the rate limit is exceeded:
+
+```http
+HTTP/1.1 429 Too Many Requests
+Retry-After: 42
+```
+
+Response:
+
+```json
+{
+  "success": false,
+  "message": "Too many requests"
+}
+```
+
+## How Sliding Window Counter Works
+
+The algorithm divides time into fixed windows.
+
+For example, with a 60-second window:
+
+```text
+Previous Window              Current Window
+───────────────────          ───────────────────
+       60 seconds                    60 seconds
+```
+
+Instead of completely ignoring the previous window, the algorithm gives it a decreasing weight.
+
+The estimated request count is:
+
+```text
+estimatedCount =
+    previousCount × (1 - progress)
+    + currentCount
+```
+
+Where:
+
+```text
+progress =
+    elapsedTime / windowSize
+```
+
+Example:
+
+```text
+Limit = 10
+
+Previous window = 6 requests
+Current window = 2 requests
+
+50% of current window has elapsed
+
+Previous contribution:
+6 × (1 - 0.5)
+= 3
+
+Estimated count:
+3 + 2
+= 5
+```
+
+The request is allowed because:
+
+```text
+5 < 10
+```
+
+The Redis Lua script performs the calculation and counter update atomically.
+
+## Why Redis + Lua?
+
+The rate limiter performs multiple operations:
+
+```text
+Read current counter
+Read previous counter
+Calculate weighted count
+Check limit
+Increment counter
+Set expiration
+```
+
+These operations need to behave atomically when many requests arrive concurrently.
+
+Redis executes the Lua script atomically, preventing race conditions such as multiple concurrent requests all observing the same counter value before incrementing it.
+
+## Redis Key Structure
+
+Keys follow this structure:
+
+```text
+{keyPrefix}:{clientKey}:{windowStart}
+```
+
+Example:
+
+```text
+rate-limit:user-123:1757750400000
+```
+
+Previous and current windows use separate Redis keys.
+
+## Testing
+
+Run the test suite with:
+
+```bash
+npm test
+```
+
+The project includes tests for:
+
+- Basic rate limiting
+- Window expiration
+- Sliding-window behavior
+- Previous-window weighting
+- Concurrent requests
+- Client isolation
+- Redis failure handling
+- Rate-limit headers
+- Configuration validation
+- Public package API
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "sliding-window-counter-rate-limiter",
+  "version": "1.0.0",
+  "description": "Production-ready Sliding Window Counter rate limiter for Express using Redis and Lua",
+  "license": "MIT",
+  "author": "Shubham Kakade",
+  "type": "commonjs",
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "keywords": [
+    "rate-limit",
+    "rate-limiter",
+    "express",
+    "redis",
+    "sliding-window",
+    "sliding-window-counter",
+    "middleware",
+    "api",
+    "backend"
+  ],
+  "dependencies": {
+    "redis": "^6.2.1"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.js

@@ -0,0 +1,5 @@
+const rateLimiter = require("./middleware");
+
+module.exports = {
+  rateLimiter,
+};

package/src/limiter.js

@@ -0,0 +1,46 @@
+async function checkRateLimit({
+  redis,
+  script,
+  currentKey,
+  previousKey,
+  limit,
+  windowMs,
+  now,
+  currentWindowStart,
+}) {
+  const result = await redis.eval(script, {
+    keys: [
+      currentKey,
+      previousKey,
+    ],
+
+    arguments: [
+      String(limit),
+      String(windowMs),
+      String(now),
+      String(currentWindowStart),
+    ],
+  });
+
+  const [
+    allowed,
+    currentCount,
+    previousCount,
+    estimatedCount,
+    remaining,
+    resetMs,
+  ] = result;
+
+  return {
+    allowed: Boolean(allowed),
+    currentCount,
+    previousCount,
+    estimatedCount,
+    remaining,
+    resetMs,
+  };
+}
+
+module.exports = {
+  checkRateLimit,
+};

package/src/middleware.js

@@ -0,0 +1,99 @@
+const fs = require("fs");
+const path = require("path");
+
+const { checkRateLimit } = require("./limiter");
+
+const { validateOptions } = require("./validate-options");
+
+const luaScript = fs.readFileSync(
+  path.join(__dirname, "redis/script.lua"),
+  "utf8",
+);
+
+function rateLimiter({
+  redis,
+  limit,
+  windowMs,
+  keyGenerator = (req) => req.ip,
+  keyPrefix = "rate-limit",
+  redisErrorStrategy = "fail-open",
+}) {
+  validateOptions({
+    redis,
+    limit,
+    windowMs,
+    keyGenerator,
+    keyPrefix,
+    redisErrorStrategy,
+  });
+
+  return async function (req, res, next) {
+    try {
+      const now = Date.now();
+
+      const currentWindowStart = Math.floor(now / windowMs) * windowMs;
+
+      const previousWindowStart = currentWindowStart - windowMs;
+
+      const clientKey = keyGenerator(req);
+
+      if (typeof clientKey !== "string" || clientKey.trim().length === 0) {
+        throw new Error("keyGenerator must return a non-empty string");
+      }
+
+      const currentKey = `${keyPrefix}:${clientKey}:${currentWindowStart}`;
+
+      const previousKey = `${keyPrefix}:${clientKey}:${previousWindowStart}`;
+
+      const result = await checkRateLimit({
+        redis,
+        script: luaScript,
+        currentKey,
+        previousKey,
+        limit,
+        windowMs,
+        now,
+        currentWindowStart,
+      });
+
+      // Headers
+      res.setHeader("RateLimit-Limit", limit);
+
+      res.setHeader("RateLimit-Remaining", Math.max(0, result.remaining));
+
+      const resetSeconds = Math.ceil(result.resetMs / 1000);
+
+      res.setHeader("RateLimit-Reset", resetSeconds);
+
+      // Reject
+      if (!result.allowed) {
+        res.setHeader("Retry-After", resetSeconds);
+
+        return res.status(429).json({
+          success: false,
+          message: "Too many requests",
+        });
+      }
+
+      // Allow
+      next();
+    } catch (error) {
+      console.error("Rate limiter Redis error:", error);
+
+      if (redisErrorStrategy === "fail-open") {
+        return next();
+      }
+
+      if (redisErrorStrategy === "fail-closed") {
+        return res.status(503).json({
+          success: false,
+          message: "Rate limiter temporarily unavailable",
+        });
+      }
+
+      return next(new Error("Invalid redisErrorStrategy"));
+    }
+  };
+}
+
+module.exports = rateLimiter;

package/src/redis/script.lua

@@ -0,0 +1,75 @@
+local current_key = KEYS[1]
+local previous_key = KEYS[2]
+
+local limit = tonumber(ARGV[1])
+local window_ms = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local current_window_start = tonumber(ARGV[4])
+
+local current_count =
+    tonumber(redis.call("GET", current_key)) or 0
+
+local previous_count =
+    tonumber(redis.call("GET", previous_key)) or 0
+
+local elapsed =
+    now - current_window_start
+
+local progress =
+    elapsed / window_ms
+
+local previous_contribution =
+    previous_count * (1 - progress)
+
+local estimated_count =
+    previous_contribution + current_count
+
+-- Request rejected
+if estimated_count >= limit then
+
+    local remaining =
+        math.max(0, math.floor(limit - estimated_count))
+
+    local reset_ms =
+        window_ms - elapsed
+
+    return {
+        0,
+        current_count,
+        previous_count,
+        math.floor(estimated_count),
+        remaining,
+        reset_ms
+    }
+end
+
+-- Request allowed
+current_count =
+    redis.call("INCR", current_key)
+
+redis.call(
+    "PEXPIRE",
+    current_key,
+    window_ms * 2
+)
+
+local new_estimated_count =
+    estimated_count + 1
+
+local remaining =
+    math.max(
+        0,
+        math.floor(limit - new_estimated_count)
+    )
+
+local reset_ms =
+    window_ms - elapsed
+
+return {
+    1,
+    current_count,
+    previous_count,
+    math.floor(new_estimated_count),
+    remaining,
+    reset_ms
+}

package/src/validate-options.js

@@ -0,0 +1,36 @@
+function validateOptions({
+  redis,
+  limit,
+  windowMs,
+  keyGenerator,
+  keyPrefix,
+  redisErrorStrategy,
+}) {
+  if (!redis) {
+    throw new Error("redis is required");
+  }
+
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw new Error("limit must be a positive integer");
+  }
+
+  if (!Number.isInteger(windowMs) || windowMs <= 0) {
+    throw new Error("windowMs must be a positive integer");
+  }
+
+  if (typeof keyGenerator !== "function") {
+    throw new Error("keyGenerator must be a function");
+  }
+
+  if (typeof keyPrefix !== "string" || keyPrefix.trim().length === 0) {
+    throw new Error("keyPrefix must be a non-empty string");
+  }
+
+  if (!["fail-open", "fail-closed"].includes(redisErrorStrategy)) {
+    throw new Error('redisErrorStrategy must be "fail-open" or "fail-closed"');
+  }
+}
+
+module.exports = {
+  validateOptions,
+};