@kanjijs/throttler 0.2.0-beta.1

package/README.md

@@ -0,0 +1,59 @@
+# @kanjijs/throttler
+
+Rate limiting module for the Kanjijs Framework. Protects your application from brute-force attacks and abuse.
+
+## Installation
+
+```bash
+bun add @kanjijs/throttler
+```
+
+## Usage
+
+### 1. Global Configuration
+
+Register the module in your root `AppModule`. This will apply the limit to **ALL** routes by default.
+
+```typescript
+import { Module } from "@kanjijs/core";
+import { ThrottlerModule } from "@kanjijs/throttler";
+
+@Module({
+  imports: [
+    ThrottlerModule.forRoot({
+      limit: 10,   // Max requests
+      ttl: 60      // Time window in seconds
+    })
+  ]
+})
+export class AppModule {}
+```
+
+### 2. Customizing Specific Routes
+
+Use the `@Throttle` decorator to override the global settings for specific methods or controllers.
+
+```typescript
+import { Controller, Get } from "@kanjijs/core";
+import { Throttle } from "@kanjijs/throttler";
+
+@Controller("/files")
+export class FileController {
+
+  @Get("/download")
+  @Throttle({ limit: 3, ttl: 3600 }) // Stricter limit: 3 downloads per hour
+  downloadFile() {
+    return "File content...";
+  }
+}
+```
+
+## Features
+
+- **Global Protection**: Acts as a Global Middleware automatically registered via `KanjijsAdapter`.
+- **Headers**: Automatically adds standard rate limit headers:
+  - `X-RateLimit-Limit`
+  - `X-RateLimit-Remaining`
+  - `X-RateLimit-Reset`
+  - `Retry-After` (on 429)
+- **Storage**: Currently supports In-Memory storage. Redis support coming soon.

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@kanjijs/throttler",
+  "version": "0.2.0-beta.1",
+  "type": "module",
+  "main": "./src/index.ts",
+  "dependencies": {
+    "@kanjijs/core": "workspace:*",
+    "hono": "^4.0.0",
+    "reflect-metadata": "^0.2.0"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+console.log("Throttler Package Loaded");
+export * from "./throttler.module";
+export * from "./throttler.service";
+export * from "./throttler.decorator";
+export * from "./throttler.storage";
+export * from "./throttler.guard";

package/src/throttler.decorator.ts

@@ -0,0 +1,27 @@
+import { Use, KanjijsIoC } from "@kanjijs/core";
+import { type Context, type Next } from "hono";
+import { ThrottlerService } from "./throttler.service";
+
+export interface ThrottlerOptions {
+  limit: number;
+  ttl: number; // seconds
+}
+
+export function Throttle(options: ThrottlerOptions) {
+  return Use(async (c: Context, next: Next) => {
+    // Resolve singleton
+    const throttler = KanjijsIoC.resolve(ThrottlerService);
+    
+    if (throttler) {
+      // Use specific options from decorator
+      const allowed = await throttler.handleRequest(c, options.limit, options.ttl);
+      if (!allowed) return; // Blocked (handleRequest sets status/body)
+    } else {
+        // Fallback or warning? If module is not imported, throttler service won't exist.
+        // It's safe to just next() or warn.
+        console.warn("@Throttle used but ThrottlerModule not imported/provided.");
+    }
+    
+    await next();
+  });
+}

package/src/throttler.guard.ts

@@ -0,0 +1,85 @@
+import { Inject, Injectable, GLOBAL_MIDDLEWARE_TOKEN } from "@kanjijs/core";
+import { type Context, type Next } from "hono";
+import { ThrottlerInMemoryStorage, type ThrottlerStorage } from "./throttler.storage";
+import { THROTTLER_LIMIT, THROTTLER_TTL } from "./throttler.decorator";
+
+export interface ThrottlerModuleOptions {
+  limit?: number;
+  ttl?: number;
+  storage?: ThrottlerStorage;
+}
+
+export const THROTTLER_OPTIONS = "THROTTLER_OPTIONS";
+
+@Injectable()
+export class ThrottlerGuard {
+  private storage: ThrottlerStorage;
+  private defaultLimit: number;
+  private defaultTtl: number;
+
+  constructor(@Inject(THROTTLER_OPTIONS) private options: ThrottlerModuleOptions) {
+    this.storage = options.storage || new ThrottlerInMemoryStorage();
+    this.defaultLimit = options.limit || 10;
+    this.defaultTtl = options.ttl || 60;
+  }
+
+  // This will be registered as a Global Middleware in KanjijsAdapter if provided
+  async handle(c: Context, next: Next) {
+    // 1. Identify Client (IP)
+    // Hono "conn" info or header
+    /* 
+       NOTE: In Bun/Hono, getting IP can be platform specific.
+       We will trust X-Forwarded-For or use a fallback.
+    */
+    const ip = c.req.header("x-forwarded-for") || "unknown";
+    const key = `throttler:${ip}:${c.req.path}`; // Limit by IP + Path (or just IP?) -> Usually just IP for global
+
+    // 2. Resolve Metadata (Limit/TTL)
+    // KanjijsAdapter doesn't expose the "Current Handler" to global middleware easily yet in the context.
+    // LIMITATION: Global Middleware runs BEFORE routing in Hono standard app.use('*').
+    // To support @Throttle decorators, we need to run THIS check inside the route handler wrapper OR 
+    // we need to access the route handler metadata here.
+    
+    // CURRENT STRATEGY: 
+    // Global Config applies to ALL routes globally (Middleware style).
+    // @Throttle decorator support requires Per-Route logic.
+    // Since KanjijsAdapter registers routes, we should probably implement this as a specific middleware wrapper there,
+    // OR we rely on Hono context to pass handler info? No standard way.
+    
+    // REVISED PLAN:
+    // We will implement `ThrottlerGuard` but we cannot easily use it as a simple `app.use('*')` 
+    // IF we want to support @Throttle decorators overriding it properly *per route* efficiently without finding the route match twice.
+    
+    // HOWEVER, for MVP:
+    // 1. Global Throttling: Runs on `*`, uses default limit.
+    // 2. Decorator Throttling: The adapter needs to know about it.
+    
+    // BUT the user asked for: "rate limit haz que tambien se pueda configurar desde main y no solo usando el decorador"
+    
+    // Let's stick to the plan:
+    // If we use Global Middleware, we enforce global limit.
+    // If we want specific limits, we need `KanjijsAdapter` to help us OR we attach `ThrottlerGuard` to the route in the Adapter.
+    
+    // DECISION: 
+    // This `handle` method will apply the DEFAULT global limit if installed globally.
+    // For Decorator support, `KanjijsAdapter` needs to look for `@Throttle` metadata and add THIS middleware (configured differently) to that route.
+    
+    const limit = this.defaultLimit;
+    const ttl = this.defaultTtl;
+
+    const { total, timeToExpire } = await this.storage.increment(key, ttl);
+
+    if (total > limit) {
+      return c.text(`Too Many Requests`, 429, {
+        "Retry-After": timeToExpire.toString()
+      });
+    }
+
+    // Headers
+    c.header("X-RateLimit-Limit", limit.toString());
+    c.header("X-RateLimit-Remaining", Math.max(0, limit - total).toString());
+    c.header("X-RateLimit-Reset", timeToExpire.toString());
+
+    await next();
+  }
+}

package/src/throttler.module.ts

@@ -0,0 +1,36 @@
+import { Module, GLOBAL_MIDDLEWARE_TOKEN, KanjijsIoC } from "@kanjijs/core";
+import type { Context, Next } from "hono";
+import { ThrottlerService, THROTTLER_OPTIONS, type ThrottlerModuleOptions } from "./throttler.service";
+
+@Module({})
+export class ThrottlerModule {
+  static forRoot(options: ThrottlerModuleOptions) {
+    return {
+      module: ThrottlerModule,
+      providers: [
+        {
+          provide: THROTTLER_OPTIONS,
+          useValue: options,
+        },
+        ThrottlerService,
+        {
+          provide: GLOBAL_MIDDLEWARE_TOKEN,
+          useValue: async (c: Context, next: Next) => {
+             // console.log("Throttler Middleware Executing via Global Token");
+             const throttler = KanjijsIoC.resolve(ThrottlerService);
+             if (throttler) {
+                 const { limit, ttl } = throttler.getGlobalOptions();
+                 const allowed = await throttler.handleRequest(c, limit, ttl);
+                 if (!allowed) {
+                    c.header("Retry-After", ttl.toString());
+                    return c.text("Too Many Requests", 429);
+                 }
+             }
+             await next();
+          }
+        }
+      ],
+      exports: [ThrottlerService],
+    };
+  }
+}

package/src/throttler.service.ts

@@ -0,0 +1,50 @@
+import { Inject, Injectable } from "@kanjijs/core";
+import { type Context } from "hono";
+import { ThrottlerInMemoryStorage, type ThrottlerStorage } from "./throttler.storage";
+
+export interface ThrottlerModuleOptions {
+  limit?: number;
+  ttl?: number;
+  storage?: ThrottlerStorage;
+}
+
+export const THROTTLER_OPTIONS = "THROTTLER_OPTIONS";
+
+@Injectable()
+export class ThrottlerService {
+  private storage: ThrottlerStorage;
+  private defaultLimit: number;
+  private defaultTtl: number;
+
+  constructor(@Inject(THROTTLER_OPTIONS) private options: ThrottlerModuleOptions) {
+    this.storage = options.storage || new ThrottlerInMemoryStorage();
+    this.defaultLimit = options.limit || 10;
+    this.defaultTtl = options.ttl || 60;
+  }
+
+  getGlobalOptions() {
+    return { limit: this.defaultLimit, ttl: this.defaultTtl };
+  }
+
+  async handleRequest(c: Context, limit: number, ttl: number): Promise<boolean> {
+    const ip = c.req.header("x-forwarded-for") || "unknown";
+    const path = c.req.path;
+    const key = `throttler:${ip}:${path}`; 
+
+    const { total, timeToExpire } = await this.storage.increment(key, ttl);
+
+    // Headers
+    c.header("X-RateLimit-Limit", limit.toString());
+    c.header("X-RateLimit-Remaining", Math.max(0, limit - total).toString());
+    c.header("X-RateLimit-Reset", timeToExpire.toString());
+
+    if (total > limit) {
+      c.status(429);
+      c.header("Retry-After", timeToExpire.toString());
+      c.text(`Too Many Requests`); // Body
+      return false; // Blocks request
+    }
+
+    return true; // Allowed
+  }
+}

package/src/throttler.storage.ts

@@ -0,0 +1,22 @@
+export interface ThrottlerStorage {
+  increment(key: string, ttl: number): Promise<{ total: number; timeToExpire: number }>;
+}
+
+export class ThrottlerInMemoryStorage implements ThrottlerStorage {
+  private storage = new Map<string, { total: number; expiresAt: number }>();
+
+  async increment(key: string, ttl: number): Promise<{ total: number; timeToExpire: number }> {
+    const now = Date.now();
+    const record = this.storage.get(key);
+
+    if (!record || record.expiresAt < now) {
+      const expiresAt = now + ttl * 1000;
+      this.storage.set(key, { total: 1, expiresAt });
+      return { total: 1, timeToExpire: ttl };
+    }
+
+    record.total++;
+    const timeToExpire = Math.ceil((record.expiresAt - now) / 1000);
+    return { total: record.total, timeToExpire: Math.max(0, timeToExpire) };
+  }
+}