@roneysilva25/test 1.0.0

package/README.md

@@ -0,0 +1,2 @@
+# rate-limiter
+Implementation of the most common rate limiting algorithms: Fixed Window, Sliding Window, Leaky Bucket, Token Bucket. To be used as middleware for express applications.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@roneysilva25/test",
+  "version": "1.0.0",
+  "description": "Implementation of the most common rate limiting algorithms: Fixed Window, Sliding Window, Leaky Bucket, Token Bucket. To be used as middleware for express applications.",
+  "homepage": "https://github.com/roneysilva25/rate-limiter#readme",
+  "bugs": {
+    "url": "https://github.com/roneysilva25/rate-limiter/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/roneysilva25/rate-limiter.git"
+  },
+  "license": "ISC",
+  "author": "Roney Silva <roney.diego000@gmail.com>  (https://roneysilva25.github.io/portfolio)",
+  "type": "module",
+  "main": "./index.js",
+  "files": ["dist", "src"],
+  "scripts": {
+    "test": "npx jest --watch",
+    "clean": "rm -rf ./dist",
+    "prebuild": "npm run clean",
+    "build": "tsc",
+    "preversion": "npm run build"
+  },
+  "devDependencies": {
+    "@swc/core": "^1.15.11",
+    "@swc/jest": "^0.2.39",
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/algorithms/Algorithm.interface.ts

@@ -0,0 +1,17 @@
+import type { Storage } from "../db/Storage.js";
+import type { PacketPayload } from "./FixedWindow.interfaces.js";
+
+export interface HandleArgs {
+    packetKey: string;
+    forwardCb: (packetInfo: PacketPayload) => void;
+    dropCb:(packetInfo: PacketPayload) => void;
+}
+
+export interface Algorithm {
+    readonly storage: typeof Storage,
+    capacity: number;
+    timeWindowInMs: number;
+    handle: (args: HandleArgs) => void;
+}
+
+export type AlgorithmConstructorArgs = Omit<Algorithm, "handle">;

package/src/algorithms/FixedWindow.interfaces.ts

@@ -0,0 +1,8 @@
+interface PacketPayload {
+    createdAt: number;
+    allowance: number;
+}
+
+export {
+    type PacketPayload,
+}

package/src/algorithms/FixedWindow.ts

@@ -0,0 +1,50 @@
+import { Storage } from "../db/Storage.js";
+import type { PacketPayload } from "./FixedWindow.interfaces.js";
+import type { HandleArgs, Algorithm, AlgorithmConstructorArgs } from "./Algorithm.interface.js";
+
+export class FixedWindow implements Algorithm {
+    capacity: number;
+    timeWindowInMs: number; 
+    storage: typeof Storage;
+
+    constructor({ 
+        capacity,  
+        timeWindowInMs,
+        storage,
+    }: AlgorithmConstructorArgs) {
+        this.capacity = capacity;
+        this.timeWindowInMs = timeWindowInMs;
+        this.storage = storage;
+    }
+
+    handle({ packetKey, forwardCb, dropCb }: HandleArgs) {
+        const existingPacket = this.storage.retrieve<PacketPayload>(packetKey);
+        const currentTime = new Date().getTime();
+
+        if (!existingPacket || currentTime - existingPacket.createdAt >= this.timeWindowInMs) {
+            const createdPacket = this.storage.store<PacketPayload>({
+                key: packetKey,
+                payload: {
+                    createdAt: currentTime,
+                    allowance: this.capacity - 1,
+                },
+            });
+
+            return forwardCb(createdPacket);
+        }
+
+        if (existingPacket.allowance - 1 >= 0) {
+            const updatedPacket = this.storage.store<PacketPayload>({
+                key: packetKey,
+                payload: {
+                    createdAt: existingPacket.createdAt,
+                    allowance: existingPacket.allowance - 1,
+                },
+            });
+
+            return forwardCb(updatedPacket);
+        }
+
+        return dropCb(existingPacket);
+    }
+}

package/src/controllers/RateLimiterController.interfaces.ts

@@ -0,0 +1,34 @@
+import type { PacketPayload } from "../algorithms/FixedWindow.interfaces.js";
+import type { NextFunction, Response, Request, } from "express";
+
+interface LimiterInfo {
+    capacity: number;
+    timeWindowInMs: number;
+}
+
+interface ConfigResponseHeaders {
+    res: Response;
+    packetInfo: PacketPayload;
+    limiterInfo: LimiterInfo;
+}
+
+interface DropArgs {
+    req: Request;
+    res: Response;
+    packetInfo: PacketPayload;
+    limiterInfo: LimiterInfo;
+}
+
+interface ForwardArgs {
+    req: Request;
+    res: Response;
+    next: NextFunction;
+    packetInfo: PacketPayload;
+    limiterInfo: LimiterInfo;
+}
+
+export type {
+    ConfigResponseHeaders,
+    DropArgs,
+    ForwardArgs,
+}

package/src/controllers/RateLimiterController.ts

@@ -0,0 +1,20 @@
+import type { ConfigResponseHeaders, DropArgs, ForwardArgs } from "./RateLimiterController.interfaces.js";
+
+export class RateLimiterController {
+    private configResponseHeaders({ limiterInfo, packetInfo, res  }: ConfigResponseHeaders) {
+        const resetsIn = limiterInfo.timeWindowInMs + packetInfo.createdAt - new Date().getTime();
+        res.setHeader("X-RateLimit-Limit", limiterInfo.capacity);
+        res.setHeader("X-RateLimit-Remaining", packetInfo.allowance);
+        res.setHeader("X-RateLimit-Reset", resetsIn);
+    }
+
+    public drop({ res, req, packetInfo, limiterInfo }: DropArgs) {
+        this.configResponseHeaders({ res, limiterInfo, packetInfo });
+        return res.status(429).send();
+    }
+
+    public forward({ req, res, next, packetInfo, limiterInfo }: ForwardArgs) {
+        this.configResponseHeaders({ res, limiterInfo, packetInfo });
+        next();
+    }
+}

package/src/db/Storage.interfaces.ts

@@ -0,0 +1,8 @@
+interface StoreArgs<Payload> {
+    key: string;
+    payload: Payload;
+}
+
+export {
+    type StoreArgs,
+}

package/src/db/Storage.ts

@@ -0,0 +1,26 @@
+import type { StoreArgs } from "./Storage.interfaces.js";
+
+export class Storage {
+    private static instance: Storage;
+    private storage: Map<string, any>;
+
+    private constructor() {
+        this.storage = new Map();
+    }
+
+    private static getInstance(): Storage {
+        if (!this.instance) {
+            this.instance = new Storage();
+        }
+
+        return this.instance;
+    }
+
+    public static store<Payload>({ key, payload }: StoreArgs<Payload>): Payload {
+        return this.getInstance().storage.set(key, payload).get(key);
+    }
+
+    public static retrieve<Payload>(key: string): Payload | undefined {
+        return this.getInstance().storage.get(key);
+    }
+}

package/src/factories/AlgorithmFactory.interfaces.ts

@@ -0,0 +1,17 @@
+import type { Algorithm, AlgorithmConstructorArgs } from "../algorithms/Algorithm.interface.js";
+
+type Algorithms = "fixed_window";
+
+interface GetArgs {
+    algorithm: Algorithms;
+    config: AlgorithmConstructorArgs;
+}
+
+interface IAlgorithmFactory {
+    get(args: GetArgs): Algorithm; 
+}
+
+export {
+    type IAlgorithmFactory,
+    type GetArgs,
+}

package/src/factories/AlgorithmFactory.ts

@@ -0,0 +1,14 @@
+import { FixedWindow } from "../algorithms/FixedWindow.js";
+import type { Algorithm } from "../algorithms/Algorithm.interface.js";
+import type { GetArgs, IAlgorithmFactory } from "./AlgorithmFactory.interfaces.js";
+
+export class AlgorithmFactory implements IAlgorithmFactory {
+    public get({ algorithm, config }: GetArgs): Algorithm {    
+        switch (algorithm) {
+            case "fixed_window":
+                return new FixedWindow(config);
+            default:
+                throw new Error(`Unknown algorithm: ${algorithm}.`);
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+import type { NextFunction, Request, Response } from "express";
+import { Storage } from "./db/Storage.js";
+import { RateLimiterController } from "./controllers/RateLimiterController.js";
+import { AlgorithmFactory } from "./factories/AlgorithmFactory.js";
+import type { RateLimiterArgs } from "./interfaces.js";
+
+function validateIP(req: Request, res: Response) {
+    if (!req.ip) {
+        return res.status(400).send("Invalid IP Address.");
+    }
+}
+
+function rateLimiter({
+    algorithm,
+    capacity,
+    timeWindowInMs,
+    storage = Storage
+}: RateLimiterArgs) {
+    const controller = new RateLimiterController(); 
+    const algFactory = new AlgorithmFactory().get({
+        algorithm,
+        config: {
+            timeWindowInMs,
+            storage,
+            capacity,
+        },
+    });
+    
+    return {
+        limit(req: Request, res: Response, next: NextFunction) {
+            validateIP(req, res);
+
+            return algFactory.handle({
+                packetKey: req.ip as string,
+                dropCb: (packetInfo) => controller.drop({
+                    req,
+                    res,
+                    packetInfo,
+                    limiterInfo: {
+                        capacity,
+                        timeWindowInMs,
+                    },
+                }),
+                forwardCb: (packetInfo) => controller.forward({
+                    req,
+                    res,
+                    next,
+                    packetInfo,
+                    limiterInfo: {
+                        capacity,
+                        timeWindowInMs,
+                    },
+                }),
+            });
+        }
+    }
+}
+
+export {
+    rateLimiter,
+}

package/src/interfaces.ts

@@ -0,0 +1,12 @@
+import type { Storage } from "./db/Storage.js";
+
+interface RateLimiterArgs {
+    algorithm: "fixed_window";
+    capacity: number;
+    timeWindowInMs: number;
+    storage?: typeof Storage;
+}
+
+export type {
+    RateLimiterArgs
+}

package/src/test/FixedWindow.test.ts

@@ -0,0 +1,121 @@
+import { FixedWindow } from "../algorithms/FixedWindow.js";
+
+describe("FixedWindow", () => {
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    const mockGetTime = jest.fn();
+    const mockStore = jest.fn();
+    const mockRetrieve = jest.fn();
+    const mockStorage = {
+        store: mockStore,
+        retrieve: mockRetrieve, 
+    }
+    const mockDropCb = jest.fn();
+    const mockForwardCb = jest.fn();
+
+    const fixedWindowArgs = {
+        capacity: 200,
+        timeWindowInMs: 1000*60*2,
+        storage: mockStorage,
+    }
+
+    //@ts-ignore
+    const fixedWindow = new FixedWindow(fixedWindowArgs);
+
+    jest.spyOn(Date.prototype, "getTime").mockImplementation(mockGetTime);
+
+    it("should create a packet with maximum allowance, the current timestamp and call forwardCb, all if the packet does not exist yet ", () => {
+        const createdPacket = {
+            key: "packetKey",
+            payload: {
+                createdAt: 1,
+                allowance: fixedWindowArgs.capacity - 1, 
+            },
+        }
+
+        mockGetTime.mockReturnValueOnce(1);
+        mockRetrieve.mockReturnValueOnce(undefined);
+        mockStore.mockReturnValueOnce(createdPacket);
+
+        fixedWindow.handle({ 
+            packetKey: "packetKey",  
+            dropCb: mockDropCb,
+            forwardCb: mockForwardCb,
+        });
+
+        expect(mockStore).toHaveBeenCalledWith(createdPacket);
+        expect(mockForwardCb).toHaveBeenCalledWith(createdPacket);
+    });
+
+    it("should update an existing packet with reset allowance and timestamp, and call forwardCb if the time window has passed", () => {
+        const resetAllowance = fixedWindowArgs.capacity - 1
+        const updatedPacket = {
+            createdAt: fixedWindowArgs.timeWindowInMs,
+            allowance: resetAllowance,
+        };
+        const currentTimestamp = fixedWindowArgs.timeWindowInMs;
+
+        mockGetTime.mockReturnValueOnce(currentTimestamp);
+        mockRetrieve.mockReturnValueOnce({
+            createdAt: 0,
+            allowance: 10,
+        });
+        mockStore.mockReturnValueOnce(updatedPacket);
+
+        fixedWindow.handle({ 
+            packetKey: "packetKey",  
+            dropCb: mockDropCb,
+            forwardCb: mockForwardCb,
+        });
+
+        expect(mockForwardCb).toHaveBeenCalledWith(updatedPacket);
+    });
+
+    it("should update an existing packet, decreasing its allowance by 1 and keeping the same createdAt timestamp, when the allowance has not reached 0 (zero)", () => {
+        const foundPacket = {
+            createdAt: 10,
+            allowance: 4,
+        }
+
+        const updatedPacket = {
+            createdAt: foundPacket.createdAt,
+            allowance: 3,
+        }
+
+        mockGetTime.mockReturnValueOnce(foundPacket.createdAt + 1);
+        mockRetrieve.mockReturnValueOnce(foundPacket);
+        mockStore.mockReturnValueOnce(updatedPacket);
+
+        fixedWindow.handle({ 
+            packetKey: "packetKey",  
+            dropCb: mockDropCb,
+            forwardCb: mockForwardCb,
+        });
+
+        expect(mockStore).toHaveBeenCalledWith({
+            key: "packetKey",
+            payload: updatedPacket,
+        });
+        expect(mockForwardCb).toHaveBeenCalledWith(updatedPacket);
+    });
+
+    it("should call the dropCb when the allowance has already reached zero.", () => {
+        const foundPacket = {
+            createdAt: 10,
+            allowance: 0,
+        };
+
+        mockGetTime.mockReturnValueOnce(foundPacket.createdAt + 10);
+        mockRetrieve.mockReturnValueOnce(foundPacket);
+
+        fixedWindow.handle({ 
+            packetKey: "packetKey",  
+            dropCb: mockDropCb,
+            forwardCb: mockForwardCb,
+        });
+
+        expect(mockDropCb).toHaveBeenCalledWith(foundPacket);
+    });
+});