@wxn0brp/falcon-frame-plugin 0.0.2 → 0.0.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 wxn0brP
+Copyright (c) 2026 wxn0brP
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/plugins/rateLimit.d.ts

@@ -1,6 +1,73 @@
+import { FFRequest } from "@wxn0brp/falcon-frame";
 import { Plugin } from "../types.js";
 export interface RateLimitRecord {
     count: number;
-    lastRequest: number;
+    windowStart: number;
 }
-export declare function createRateLimiterPlugin(maxRequests: number, windowMs: number): Plugin;
+export interface RateLimiterContext {
+    id: string;
+    retryAfter: number;
+    remainingRequests: number;
+    record: RateLimitRecord;
+}
+export interface RateLimiterOptions {
+    /**
+     * Maximum number of requests allowed per window.
+     */
+    maxRequests: number;
+    /**
+     * Window duration in milliseconds.
+     */
+    windowMs: number;
+    /**
+     * Callback triggered when the rate limit is exceeded.
+     * Gives full control over the response.
+     *
+     * @param req - HTTP request object.
+     * @param res - HTTP response object.
+     * @param ctx - Context object containing limit info (IP, retryAfter, remainingRequests, etc.).
+     */
+    onLimitReached?: (req: any, res: any, ctx: RateLimiterContext) => void;
+    /**
+     * Disable the automatic cleanup interval.
+     * Default: false.
+     */
+    disableCleanup?: boolean;
+    /**
+     * Shared Map instance to use instead of a private one.
+     * Useful if multiple limiters need to share state.
+     */
+    sharedMap?: Map<string, RateLimitRecord>;
+    /**
+     * Function to generate a unique key for each request.
+     * Default: uses the IP address of the request.
+     */
+    id?: (req: FFRequest) => string | Promise<string>;
+}
+/**
+ * Creates a rate limiter plugin for HTTP requests based on IP.
+ *
+ * Uses a simple "fixed window counter" algorithm and can optionally
+ * share the internal Map or disable cleanup interval.
+ *
+ * @example
+ * const sharedMap = new Map();
+ * const rateLimiter = createRateLimiterPlugin({
+ *   maxRequests: 5,
+ *   windowMs: 60_000,
+ *   sharedMap,
+ *   onLimitReached: (req, res, ctx) => {
+ *     res.statusCode = 429;
+ *     res.json({
+ *       message: "Sorry, too many requests!",
+ *       retryAfter: ctx.retryAfter,
+ *       remaining: ctx.remainingRequests,
+ *       ip: ctx.ip,
+ *     });
+ *   },
+ * });
+ *
+ * @param {RateLimiterOptions} options - Rate limiter configuration.
+ * @returns {Plugin} Middleware plugin compatible with your system.
+ */
+export declare function createRateLimiterPlugin(opts: RateLimiterOptions): Plugin;

package/dist/plugins/rateLimit.js

@@ -1,23 +1,87 @@
-;
-export function createRateLimiterPlugin(maxRequests, windowMs) {
-    const rateLimitMap = new Map();
+/**
+ * Creates a rate limiter plugin for HTTP requests based on IP.
+ *
+ * Uses a simple "fixed window counter" algorithm and can optionally
+ * share the internal Map or disable cleanup interval.
+ *
+ * @example
+ * const sharedMap = new Map();
+ * const rateLimiter = createRateLimiterPlugin({
+ *   maxRequests: 5,
+ *   windowMs: 60_000,
+ *   sharedMap,
+ *   onLimitReached: (req, res, ctx) => {
+ *     res.statusCode = 429;
+ *     res.json({
+ *       message: "Sorry, too many requests!",
+ *       retryAfter: ctx.retryAfter,
+ *       remaining: ctx.remainingRequests,
+ *       ip: ctx.ip,
+ *     });
+ *   },
+ * });
+ *
+ * @param {RateLimiterOptions} options - Rate limiter configuration.
+ * @returns {Plugin} Middleware plugin compatible with your system.
+ */
+export function createRateLimiterPlugin(opts) {
+    const { maxRequests, windowMs, onLimitReached, disableCleanup = false, sharedMap, } = opts;
+    const rateLimitMap = sharedMap ?? new Map();
+    // Optional automatic cleanup
+    if (!disableCleanup) {
+        const cleanupInterval = setInterval(() => {
+            const now = Date.now();
+            for (const [id, record] of rateLimitMap.entries()) {
+                if (now - record.windowStart > windowMs) {
+                    rateLimitMap.delete(id);
+                }
+            }
+        }, windowMs * 2);
+        cleanupInterval.unref?.();
+    }
     return {
         id: "rateLimiter",
-        process: (req, res, next) => {
-            const ip = req.socket.remoteAddress ?? "unknown";
+        process: async (req, res, next) => {
+            let id;
+            if (opts.id) {
+                id = await opts.id(req);
+            }
+            else {
+                id = req.socket.remoteAddress ?? "unknown";
+            }
             const now = Date.now();
-            const record = rateLimitMap.get(ip);
-            if (!record || now - record.lastRequest > windowMs) {
-                rateLimitMap.set(ip, { count: 1, lastRequest: now });
+            const record = rateLimitMap.get(id);
+            if (!record) {
+                rateLimitMap.set(id, { count: 1, windowStart: now });
+                return next();
+            }
+            const elapsed = now - record.windowStart;
+            // Reset window if it expired
+            if (elapsed > windowMs) {
+                rateLimitMap.set(id, { count: 1, windowStart: now });
                 return next();
             }
+            // Rate limit exceeded
             if (record.count >= maxRequests) {
+                const retryAfter = Math.ceil((windowMs - elapsed) / 1000);
+                const remainingRequests = Math.max(0, maxRequests - record.count);
                 res.statusCode = 429;
+                res.setHeader("Retry-After", retryAfter);
+                const ctx = {
+                    id,
+                    retryAfter,
+                    remainingRequests,
+                    record,
+                };
+                if (onLimitReached)
+                    return onLimitReached(req, res, ctx);
+                // Default plain text response
+                res.setHeader("Content-Type", "text/plain; charset=utf-8");
                 return res.end("Too Many Requests");
             }
+            // Increment count
             record.count++;
-            record.lastRequest = now;
-            rateLimitMap.set(ip, record);
+            rateLimitMap.set(id, record);
             next();
         },
     };

package/package.json

@@ -1,42 +1,43 @@
 {
-	"name": "@wxn0brp/falcon-frame-plugin",
-	"version": "0.0.2",
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
-	"description": "",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/wxn0brP/FalconFrame-plugin.git"
-	},
-	"homepage": "https://github.com/wxn0brP/FalconFrame-plugin",
-	"author": "wxn0brP",
-	"license": "MIT",
-	"type": "module",
-	"scripts": {
-		"build": "tsc && tsc-alias"
-	},
-	"devDependencies": {
-		"@types/bun": "*",
-		"@wxn0brp/falcon-frame": "^0.5.0",
-		"tsc-alias": "*",
-		"typescript": "*"
-	},
-	"peerDependencies": {
-		"@wxn0brp/falcon-frame": ">=0.5.0"
-	},
-	"files": [
-		"dist"
-	],
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js",
-			"default": "./dist/index.js"
-		},
-		"./*": {
-			"types": "./dist/*.d.ts",
-			"import": "./dist/*.js",
-			"default": "./dist/*.js"
-		}
-	}
-}
+  "name": "@wxn0brp/falcon-frame-plugin",
+  "version": "0.0.4",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "description": "Plugin system for FalconFrame",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wxn0brP/FalconFrame-plugin.git"
+  },
+  "homepage": "https://github.com/wxn0brP/FalconFrame-plugin",
+  "author": "wxn0brP",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "falcon-frame",
+    "plugin"
+  ],
+  "devDependencies": {
+    "@types/bun": "*",
+    "@wxn0brp/falcon-frame": "^0.7.0",
+    "tsc-alias": "*",
+    "typescript": "*"
+  },
+  "peerDependencies": {
+    "@wxn0brp/falcon-frame": ">=0.7.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  }
+}

package/dist/test.d.ts

@@ -1 +0,0 @@
-export {};