reflo 1.0.0

package/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      packages: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+
+      - name: Run semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release
+

package/.releaserc.json

@@ -0,0 +1,12 @@
+{
+  "branches": ["master"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    "@semantic-release/github",
+    "@semantic-release/git"
+  ]
+}
+

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# 1.0.0 (2025-07-06)
+
+
+### Bug Fixes
+
+* updated keywords ([88aca71](https://github.com/theanuragshukla/reflo/commit/88aca7177da6d3aa627e2be07f30cfbfca3ca544))

package/dist/index.cjs

@@ -0,0 +1,126 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  backoffStrategies: () => backoffStrategies,
+  identifierStrategies: () => identifierStrategies,
+  rateLimiter: () => rateLimiter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/redisClient.ts
+var import_ioredis = __toESM(require("ioredis"), 1);
+var DEFAULT_REDIS_URL = process.env.REDIS_URL || "redis://localhost:6379";
+var redis = new import_ioredis.default(DEFAULT_REDIS_URL, {
+  tls: process.env.REDIS_TLS === "true" ? {} : void 0,
+  maxRetriesPerRequest: 0
+});
+redis.on("error", (err) => console.error("Redis error:", err));
+redis.defineCommand("tokenBucket", {
+  numberOfKeys: 1,
+  lua: `local key=KEYS[1]
+  local capacity=tonumber(ARGV[1])
+  local refill_rate=tonumber(ARGV[2])
+  local now=tonumber(ARGV[3])
+  local tokens=tonumber(redis.call("HGET",key,"tokens") or capacity)
+  local last=tonumber(redis.call("HGET",key,"last") or now)
+  local delta=now-last
+  local filled=math.min(capacity, tokens + delta * refill_rate)
+  local allowed = 0
+  if filled >= 1 then allowed = 1; filled = filled - 1 end
+  redis.call("HMSET", key, "tokens", filled, "last", now)
+  redis.call("PEXPIRE", key, math.ceil(capacity/refill_rate))
+  local overuse = allowed == 0 and math.ceil(1 - filled) or 0
+  return {allowed, filled, overuse}`
+});
+
+// src/strategies/identifier.ts
+var identifierStrategies = {
+  byIP: () => (req) => `ip:${req.ip}`,
+  byHeader: (name) => (req) => `hdr:${name}:${req.header(name) || "none"}`
+};
+
+// src/strategies/backoff.ts
+var backoffStrategies = {
+  none: () => 0,
+  fixed: (ms) => () => ms,
+  linear: (base, max = 5e3) => (overuse) => Math.min(max, base * overuse),
+  exponential: (base, max = 5e3) => (overuse) => Math.min(max, base * Math.pow(2, overuse))
+};
+
+// src/utils.ts
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/rateLimiter.ts
+function rateLimiter(config) {
+  const {
+    timeWindowSeconds,
+    requestCount,
+    exceptions = [],
+    allowlist = [],
+    blocklist = [],
+    getIdentifier = identifierStrategies.byIP(),
+    backoffStrategy = backoffStrategies.exponential(200)
+  } = config;
+  return async (req, res, next) => {
+    const userKey = getIdentifier(req);
+    if (blocklist.includes(userKey)) return res.status(403).send("Forbidden");
+    if (allowlist.includes(userKey)) return next();
+    const rule = exceptions.find((ex) => ex.route === req.path);
+    const capacity = rule?.count ?? requestCount;
+    const refillRate = capacity / (timeWindowSeconds * 1e3);
+    try {
+      const [allowed, tokensLeft, overuse] = await redis.tokenBucket(
+        `lim:${userKey}:${req.path}`,
+        capacity,
+        refillRate,
+        Date.now()
+      );
+      res.setHeader("X-RateLimit-Limit", capacity.toString());
+      res.setHeader("X-RateLimit-Remaining", Math.floor(tokensLeft).toString());
+      if (allowed) return next();
+      const wait = backoffStrategy(overuse);
+      await delay(wait);
+      return res.status(429).send(`Too Many Requests \u2014 delayed ${wait}ms`);
+    } catch (err) {
+      console.error("Reflo error:", err);
+      return res.status(503).send("Rate limit service unavailable");
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  backoffStrategies,
+  identifierStrategies,
+  rateLimiter
+});

package/dist/index.d.cts

@@ -0,0 +1,32 @@
+import { Request, Response, NextFunction } from 'express';
+
+interface ExceptionRule {
+    route: string;
+    count: number;
+}
+interface LimiterConfig {
+    timeWindowSeconds: number;
+    requestCount: number;
+    exceptions?: ExceptionRule[];
+    allowlist?: string[];
+    blocklist?: string[];
+    getIdentifier?: (req: Request) => string;
+    backoffStrategy?: (overuse: number) => number;
+}
+type ExpressHandler = (req: Request, res: Response, next: NextFunction) => void;
+
+declare function rateLimiter(config: LimiterConfig): ExpressHandler;
+
+declare const identifierStrategies: {
+    byIP: () => (req: Request) => string;
+    byHeader: (name: string) => (req: Request) => string;
+};
+
+declare const backoffStrategies: {
+    none: () => number;
+    fixed: (ms: number) => () => number;
+    linear: (base: number, max?: number) => (overuse: number) => number;
+    exponential: (base: number, max?: number) => (overuse: number) => number;
+};
+
+export { type ExceptionRule, type ExpressHandler, type LimiterConfig, backoffStrategies, identifierStrategies, rateLimiter };

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { Request, Response, NextFunction } from 'express';
+
+interface ExceptionRule {
+    route: string;
+    count: number;
+}
+interface LimiterConfig {
+    timeWindowSeconds: number;
+    requestCount: number;
+    exceptions?: ExceptionRule[];
+    allowlist?: string[];
+    blocklist?: string[];
+    getIdentifier?: (req: Request) => string;
+    backoffStrategy?: (overuse: number) => number;
+}
+type ExpressHandler = (req: Request, res: Response, next: NextFunction) => void;
+
+declare function rateLimiter(config: LimiterConfig): ExpressHandler;
+
+declare const identifierStrategies: {
+    byIP: () => (req: Request) => string;
+    byHeader: (name: string) => (req: Request) => string;
+};
+
+declare const backoffStrategies: {
+    none: () => number;
+    fixed: (ms: number) => () => number;
+    linear: (base: number, max?: number) => (overuse: number) => number;
+    exponential: (base: number, max?: number) => (overuse: number) => number;
+};
+
+export { type ExceptionRule, type ExpressHandler, type LimiterConfig, backoffStrategies, identifierStrategies, rateLimiter };

package/dist/index.js

@@ -0,0 +1,87 @@
+// src/redisClient.ts
+import Redis from "ioredis";
+var DEFAULT_REDIS_URL = process.env.REDIS_URL || "redis://localhost:6379";
+var redis = new Redis(DEFAULT_REDIS_URL, {
+  tls: process.env.REDIS_TLS === "true" ? {} : void 0,
+  maxRetriesPerRequest: 0
+});
+redis.on("error", (err) => console.error("Redis error:", err));
+redis.defineCommand("tokenBucket", {
+  numberOfKeys: 1,
+  lua: `local key=KEYS[1]
+  local capacity=tonumber(ARGV[1])
+  local refill_rate=tonumber(ARGV[2])
+  local now=tonumber(ARGV[3])
+  local tokens=tonumber(redis.call("HGET",key,"tokens") or capacity)
+  local last=tonumber(redis.call("HGET",key,"last") or now)
+  local delta=now-last
+  local filled=math.min(capacity, tokens + delta * refill_rate)
+  local allowed = 0
+  if filled >= 1 then allowed = 1; filled = filled - 1 end
+  redis.call("HMSET", key, "tokens", filled, "last", now)
+  redis.call("PEXPIRE", key, math.ceil(capacity/refill_rate))
+  local overuse = allowed == 0 and math.ceil(1 - filled) or 0
+  return {allowed, filled, overuse}`
+});
+
+// src/strategies/identifier.ts
+var identifierStrategies = {
+  byIP: () => (req) => `ip:${req.ip}`,
+  byHeader: (name) => (req) => `hdr:${name}:${req.header(name) || "none"}`
+};
+
+// src/strategies/backoff.ts
+var backoffStrategies = {
+  none: () => 0,
+  fixed: (ms) => () => ms,
+  linear: (base, max = 5e3) => (overuse) => Math.min(max, base * overuse),
+  exponential: (base, max = 5e3) => (overuse) => Math.min(max, base * Math.pow(2, overuse))
+};
+
+// src/utils.ts
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/rateLimiter.ts
+function rateLimiter(config) {
+  const {
+    timeWindowSeconds,
+    requestCount,
+    exceptions = [],
+    allowlist = [],
+    blocklist = [],
+    getIdentifier = identifierStrategies.byIP(),
+    backoffStrategy = backoffStrategies.exponential(200)
+  } = config;
+  return async (req, res, next) => {
+    const userKey = getIdentifier(req);
+    if (blocklist.includes(userKey)) return res.status(403).send("Forbidden");
+    if (allowlist.includes(userKey)) return next();
+    const rule = exceptions.find((ex) => ex.route === req.path);
+    const capacity = rule?.count ?? requestCount;
+    const refillRate = capacity / (timeWindowSeconds * 1e3);
+    try {
+      const [allowed, tokensLeft, overuse] = await redis.tokenBucket(
+        `lim:${userKey}:${req.path}`,
+        capacity,
+        refillRate,
+        Date.now()
+      );
+      res.setHeader("X-RateLimit-Limit", capacity.toString());
+      res.setHeader("X-RateLimit-Remaining", Math.floor(tokensLeft).toString());
+      if (allowed) return next();
+      const wait = backoffStrategy(overuse);
+      await delay(wait);
+      return res.status(429).send(`Too Many Requests \u2014 delayed ${wait}ms`);
+    } catch (err) {
+      console.error("Reflo error:", err);
+      return res.status(503).send("Rate limit service unavailable");
+    }
+  };
+}
+export {
+  backoffStrategies,
+  identifierStrategies,
+  rateLimiter
+};

package/jest.config.cjs

@@ -0,0 +1,13 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest/presets/default', // or 'ts-jest/presets/js-with-ts'
+  testEnvironment: 'node',
+  testMatch: ['**/test/**/*.spec.ts'],
+  transform: {
+    '^.+\\.ts$': ['ts-jest', {
+      tsconfig: 'tsconfig.json',
+    }],
+  },
+};
+
+

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "reflo",
+  "version": "1.0.0",
+  "description": "A modular, Redis-backed rate limiting middleware for Express with pluggable strategies and exponential backoff.",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "keywords": [
+    "rate-limiter",
+    "express",
+    "redis",
+    "middleware",
+    "reflo"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theanuragshukla/reflo.git"
+  },
+  "author": "Anurag Shukla(theanuragshukla)",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint .",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "express": "^4.18.0",
+    "ioredis": "^5.0.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.3",
+    "@semantic-release/npm": "^12.0.2",
+    "@types/express": "^4.17.0",
+    "@types/jest": "^29.5.14",
+    "@types/supertest": "^6.0.3",
+    "jest": "^29.7.0",
+    "semantic-release": "^24.2.6",
+    "supertest": "^7.1.1",
+    "ts-jest": "^29.4.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/theanuragshukla/reflo/issues"
+  },
+  "homepage": "https://github.com/theanuragshukla/reflo#readme"
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./rateLimiter";
+export * from "./strategies/identifier";
+export * from "./strategies/backoff";
+export * from "./types";
+

package/src/rateLimiter.ts

@@ -0,0 +1,49 @@
+import type { ExpressHandler, LimiterConfig } from "./types";
+import { redis } from "./redisClient";
+import { identifierStrategies } from "./strategies/identifier";
+import { backoffStrategies } from "./strategies/backoff";
+import { delay } from "./utils";
+
+export function rateLimiter(config: LimiterConfig): ExpressHandler {
+  const {
+    timeWindowSeconds,
+    requestCount,
+    exceptions = [],
+    allowlist = [],
+    blocklist = [],
+    getIdentifier = identifierStrategies.byIP(),
+    backoffStrategy = backoffStrategies.exponential(200),
+  } = config;
+
+  return async (req, res, next) => {
+    const userKey = getIdentifier(req);
+    if (blocklist.includes(userKey)) return res.status(403).send("Forbidden");
+    if (allowlist.includes(userKey)) return next();
+
+    const rule = exceptions.find((ex) => ex.route === req.path);
+    const capacity = rule?.count ?? requestCount;
+    const refillRate = capacity / (timeWindowSeconds * 1000);
+
+    try {
+      const [allowed, tokensLeft, overuse] = (await (redis as any).tokenBucket(
+        `lim:${userKey}:${req.path}`,
+        capacity,
+        refillRate,
+        Date.now(),
+      )) as [0 | 1, number, number];
+
+      res.setHeader("X-RateLimit-Limit", capacity.toString());
+      res.setHeader("X-RateLimit-Remaining", Math.floor(tokensLeft).toString());
+
+      if (allowed) return next();
+
+      const wait = backoffStrategy(overuse);
+      await delay(wait);
+      return res.status(429).send(`Too Many Requests — delayed ${wait}ms`);
+    } catch (err) {
+      console.error("Reflo error:", err);
+      return res.status(503).send("Rate limit service unavailable");
+    }
+  };
+}
+

package/src/redisClient.ts

@@ -0,0 +1,27 @@
+import Redis from "ioredis";
+
+const DEFAULT_REDIS_URL = process.env.REDIS_URL || "redis://localhost:6379";
+export const redis = new Redis(DEFAULT_REDIS_URL, {
+	tls: process.env.REDIS_TLS === "true" ? {} : undefined,
+	maxRetriesPerRequest: 0,
+});
+
+redis.on("error", (err) => console.error("Redis error:", err));
+
+redis.defineCommand("tokenBucket", {
+	numberOfKeys: 1,
+	lua: `local key=KEYS[1]
+  local capacity=tonumber(ARGV[1])
+  local refill_rate=tonumber(ARGV[2])
+  local now=tonumber(ARGV[3])
+  local tokens=tonumber(redis.call("HGET",key,"tokens") or capacity)
+  local last=tonumber(redis.call("HGET",key,"last") or now)
+  local delta=now-last
+  local filled=math.min(capacity, tokens + delta * refill_rate)
+  local allowed = 0
+  if filled >= 1 then allowed = 1; filled = filled - 1 end
+  redis.call("HMSET", key, "tokens", filled, "last", now)
+  redis.call("PEXPIRE", key, math.ceil(capacity/refill_rate))
+  local overuse = allowed == 0 and math.ceil(1 - filled) or 0
+  return {allowed, filled, overuse}`,
+});

package/src/strategies/backoff.ts

@@ -0,0 +1,12 @@
+export const backoffStrategies = {
+	none: () => 0,
+	fixed: (ms: number) => () => ms,
+	linear:
+		(base: number, max = 5000) =>
+		(overuse: number) =>
+			Math.min(max, base * overuse),
+	exponential:
+		(base: number, max = 5000) =>
+		(overuse: number) =>
+			Math.min(max, base * Math.pow(2, overuse)),
+};

package/src/strategies/identifier.ts

@@ -0,0 +1,7 @@
+import type { Request } from "express";
+
+export const identifierStrategies = {
+	byIP: () => (req: Request) => `ip:${req.ip}`,
+	byHeader: (name: string) => (req: Request) =>
+		`hdr:${name}:${req.header(name) || "none"}`,
+};

package/src/strategies/index.ts

@@ -0,0 +1,3 @@
+export * from "./identifier";
+export * from "./backoff";
+

package/src/types.ts

@@ -0,0 +1,22 @@
+import { Request, Response, NextFunction } from "express";
+
+export interface ExceptionRule {
+	route: string;
+	count: number;
+}
+
+export interface LimiterConfig {
+	timeWindowSeconds: number;
+	requestCount: number;
+	exceptions?: ExceptionRule[];
+	allowlist?: string[];
+	blocklist?: string[];
+	getIdentifier?: (req: Request) => string;
+	backoffStrategy?: (overuse: number) => number;
+}
+
+export type ExpressHandler = (
+	req: Request,
+	res: Response,
+	next: NextFunction
+) => void;

package/src/utils.ts

@@ -0,0 +1,8 @@
+export function normalizeIP(ip: string): string {
+  return ip.replace("::ffff:", "").replace("::1", "127.0.0.1");
+}
+
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+

package/test/rateLimiter.spec.ts

@@ -0,0 +1,129 @@
+import express from "express";
+import request from "supertest";
+import { rateLimiter } from "../src/rateLimiter";
+import { identifierStrategies, backoffStrategies } from "../src/strategies";
+import { redis } from "../src/redisClient";
+import { normalizeIP } from "../src/utils";
+
+const createApp = (overrides = {}) => {
+  const app = express();
+  app.use(express.json());
+
+  app.use(
+    rateLimiter({
+      timeWindowSeconds: 1,
+      requestCount: 2,
+      getIdentifier: identifierStrategies.byHeader("x-test-id"),
+      backoffStrategy: backoffStrategies.none,
+      ...overrides,
+    })
+  );
+
+  app.get("/", (req, res) => res.send("ok"));
+  return app;
+};
+
+beforeEach(async () => {
+  await redis.flushall();
+});
+
+afterAll(async () => {
+  await redis.quit();
+});
+
+describe("rateLimiter core behavior", () => {
+  it("allows up to limit then 429", async () => {
+    const app = createApp();
+
+    const req = () => request(app).get("/").set("x-test-id", "core-1");
+
+    await req().expect(200);
+    await req().expect(200);
+    await req().expect(429);
+  });
+
+  it("respects allowlist", async () => {
+    const id = "allow-1";
+    const app = createApp({
+      allowlist: [`hdr:x-test-id:${id}`],
+    });
+
+    const req = () => request(app).get("/").set("x-test-id", id);
+    await req().expect(200);
+    await req().expect(200);
+    await req().expect(200); // still allowed
+  });
+
+  it("respects blocklist", async () => {
+    const id = "block-1";
+    const app = createApp({
+      blocklist: [`hdr:x-test-id:${id}`],
+    });
+
+    const req = () => request(app).get("/").set("x-test-id", id);
+    await req().expect(403);
+  });
+});
+
+describe("identifierStrategies", () => {
+  it("identifies by header", async () => {
+    const app = createApp();
+
+    const req = () => request(app).get("/").set("x-test-id", "hdr-1");
+
+    await req().expect(200);
+    await req().expect(200);
+    await req().expect(429);
+  });
+});
+
+describe("backoffStrategies", () => {
+  const measureDelay = async (reqFn: () => Promise<request.Response>): Promise<number> => {
+    const start = Date.now();
+    await reqFn();
+    return Date.now() - start;
+  };
+
+  it("uses fixed backoff", async () => {
+    const id = "fixed-1";
+    const app = createApp({
+      backoffStrategy: backoffStrategies.fixed(100),
+    });
+
+    const req = () => request(app).get("/").set("x-test-id", id);
+
+    await req();
+    await req();
+    const elapsed = await measureDelay(req);
+    expect(elapsed).toBeGreaterThanOrEqual(90);
+  });
+
+  it("uses linear backoff", async () => {
+    const id = "linear-1";
+    const app = createApp({
+      backoffStrategy: backoffStrategies.linear(50),
+    });
+
+    const req = () => request(app).get("/").set("x-test-id", id);
+
+    await req();
+    await req();
+    const elapsed = await measureDelay(req);
+    expect(elapsed).toBeGreaterThanOrEqual(40);
+  });
+
+  it("uses exponential backoff", async () => {
+    const id = "exp-1";
+    const app = createApp({
+      backoffStrategy: backoffStrategies.exponential(60),
+    });
+
+    const req = () => request(app).get("/").set("x-test-id", id);
+
+    await req();
+    await req();
+    const elapsed = await measureDelay(req);
+    expect(elapsed).toBeGreaterThanOrEqual(60);
+  });
+});
+

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "module": "ESNext",
+    "target": "ES2020",
+    "moduleResolution": "node",
+    "strict": true,
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "baseUrl": "./src",
+    "types": ["node", "jest"]
+  }
+}
+