@wxn0brp/falcon-frame-plugin 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,106 @@
+# FalconFrame Plugin System
+
+A flexible plugin system for the **FalconFrame** framework, allowing developers to register, sort, and execute plugins in a specific order based on dependencies.
+
+## Overview
+
+The **FalconFrame Plugin System** provides a robust way to manage plugins for FalconFrame applications. It supports dependency management using `before` and `after` constraints, ensuring that plugins are executed in the correct order. The system uses a **topological sort** algorithm to handle complex dependency chains and detect circular dependencies.
+
+## Installation
+
+```bash
+npm install @wxn0brp/falcon-frame-plugin
+# and FalconFrame if not already installed
+npm install @wxn0brp/falcon-frame 
+```
+
+## Features
+
+* **Plugin Registration** – Register plugins with optional dependency constraints.
+* **Dependency Management** – Specify `before` and `after` relationships between plugins.
+* **Automatic Sorting** – Plugins are automatically ordered based on dependencies.
+* **Circular Dependency Detection** – Throws errors when circular dependencies are detected.
+* **Route Handler Integration** – Seamless integration with FalconFrame's routing system.
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { PluginSystem } from "@wxn0brp/falcon-frame-plugin";
+import { FalconFrame } from "@wxn0brp/falcon-frame";
+
+const app = new FalconFrame();
+const pluginSystem = new PluginSystem();
+
+// Register a plugin
+pluginSystem.register({
+  	id: "my-plugin",
+  	process: (req, res, next) => {
+  	  	console.log("Executing my plugin");
+  	  	next();
+  	}
+});
+
+// Register multiple plugins
+app.use(pluginSystem);
+```
+
+### Plugin with Dependencies
+
+```typescript
+pluginSystem.register({
+  	id: "auth-plugin",
+  	process: (req, res, next) => {
+  	  	// Authentication logic
+  	  	next();
+  	},
+  	before: "data-plugin"  // Runs before "data-plugin"
+});
+
+pluginSystem.register({
+  id: "data-plugin",
+  	process: (req, res, next) => {
+  	  	// Data processing logic
+  	  	next();
+  	},
+  	after: "auth-plugin"   // Runs after "auth-plugin"
+});
+```
+
+## Plugin Interface
+
+```typescript
+interface Plugin {
+  	id: string;                 // Unique identifier for the plugin
+  	process: RouteHandler;      // Function executed when the plugin runs
+  	before?: string | string[]; // Plugin(s) that should run after this one
+  	after?: string | string[];  // Plugin(s) that should run before this one
+}
+```
+
+## API
+
+### `PluginSystem.register(plugin: Plugin, opts?: PSOpts)`
+
+Registers a plugin with the system. If `opts.after` or `opts.before` are provided, they will define the execution order. Plugins are re-sorted automatically after registration.
+
+### `PluginSystem.getRouteHandler(): RouteHandler`
+
+Returns a **RouteHandler** that executes all registered plugins in the correct order. It will sort the plugins if they haven’t been sorted yet, then execute them recursively.
+
+## Sorting Algorithm
+
+The system uses a **topological sort** to:
+
+* Detect circular dependencies and throw errors
+* Ensure correct execution order based on dependencies
+* Prevent duplicate plugin IDs
+
+## Contributing
+
+Contributions are welcome! Please open an issue or pull request for bug reports, feature requests, or improvements.
+
+## License
+
+MIT License – see the [LICENSE](LICENSE) file for details.

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,39 @@
 {
-	"name": "@wxn0brp/falcon-frame-plugin",
-	"version": "0.0.1",
-	"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.3",
+  "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",
+  "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"
+    }
+  }
 }

package/dist/test.d.ts

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