@asenajs/ergenecore 1.0.0

package/dist/lib/middlewares/RateLimiterMiddleware.d.ts

@@ -0,0 +1,330 @@
+/**
+ * Rate Limiter Middleware for Ergenecore
+ *
+ * Implements Token Bucket algorithm for rate limiting:
+ * - Token bucket per client (identified by IP or custom key)
+ * - Configurable capacity and refill rate
+ * - Instance-based storage (each middleware instance has its own buckets)
+ * - Zero external dependencies (uses Bun's native APIs)
+ * - Asena DI container compatible
+ *
+ * @module defaults/RateLimiterMiddleware
+ *
+ * **Usage in Asena Application:**
+ * ```typescript
+ * import { Middleware } from '@asenajs/asena/server';
+ * import { RateLimiterMiddleware } from '@asenajs/ergenecore';
+ *
+ * // Create custom rate limiter for your needs
+ * @Middleware()
+ * export class ApiRateLimiter extends RateLimiterMiddleware {
+ *   constructor() {
+ *     super({
+ *       capacity: 100,
+ *       refillRate: 100 / 60, // 100 requests per minute
+ *     });
+ *   }
+ * }
+ *
+ * // Use in controller (class reference, not instance)
+ * @Controller({ middlewares: [ApiRateLimiter] })
+ * export class ApiController { ... }
+ *
+ * // Or use on specific route
+ * @Middleware()
+ * export class StrictRateLimiter extends RateLimiterMiddleware {
+ *   constructor() {
+ *     super({
+ *       capacity: 5,
+ *       refillRate: 5 / 60, // 5 requests per minute
+ *       message: 'Too many login attempts. Please try again later.',
+ *     });
+ *   }
+ * }
+ *
+ * @Post({ path: '/login', middlewares: [StrictRateLimiter] })
+ * public login() { ... }
+ * ```
+ */
+import type { Context } from '../ErgenecoreContextWrapper';
+import { MiddlewareService } from '../defaults/MiddlewareService';
+/**
+ * Token bucket for a single client
+ */
+interface Bucket {
+    /**
+     * Current number of tokens available
+     */
+    tokens: number;
+    /**
+     * Last refill timestamp (milliseconds)
+     */
+    lastRefill: number;
+}
+/**
+ * Rate limiter configuration options
+ */
+export interface RateLimiterOptions {
+    /**
+     * Maximum token capacity (burst size)
+     *
+     * This defines how many requests can be made in a burst.
+     * Example: capacity = 100 means 100 requests can be made instantly if bucket is full.
+     *
+     * @default 100
+     */
+    capacity?: number;
+    /**
+     * Token refill rate (tokens per second)
+     *
+     * This defines the sustained request rate.
+     * Example: refillRate = 10 means 10 requests per second sustained rate.
+     *
+     * Common patterns:
+     * - 10 req/s → refillRate: 10
+     * - 100 req/min → refillRate: 100/60 ≈ 1.67
+     * - 1000 req/hour → refillRate: 1000/3600 ≈ 0.28
+     *
+     * @default 10
+     */
+    refillRate?: number;
+    /**
+     * Custom key generator function
+     *
+     * By default, uses IP address from X-Forwarded-For header or remote address.
+     * You can customize this to use user ID, API key, or any other identifier.
+     *
+     * @default (ctx) => ctx.req.headers.get('x-forwarded-for') || 'unknown'
+     *
+     * @example
+     * ```typescript
+     * // Rate limit by user ID
+     * keyGenerator: (ctx) => ctx.state.user?.id || 'anonymous'
+     *
+     * // Rate limit by API key
+     * keyGenerator: (ctx) => ctx.req.headers.get('x-api-key') || 'unknown'
+     * ```
+     */
+    keyGenerator?: (context: Context) => string;
+    /**
+     * Custom message for rate limit exceeded response
+     *
+     * @default 'Rate limit exceeded. Please try again later.'
+     */
+    message?: string;
+    /**
+     * HTTP status code for rate limit exceeded response
+     *
+     * @default 429
+     */
+    statusCode?: number;
+    /**
+     * Token cost per request
+     *
+     * Advanced feature: Different endpoints can cost different amounts of tokens.
+     *
+     * @default 1
+     *
+     * @example
+     * ```typescript
+     * // Expensive operations cost more tokens
+     * cost: (ctx) => ctx.req.url.includes('/search') ? 5 : 1
+     * ```
+     */
+    cost?: number | ((context: Context) => number);
+    /**
+     * Skip rate limiting based on context
+     *
+     * Useful for whitelisting certain IPs, paths, or authenticated users.
+     *
+     * @default undefined
+     *
+     * @example
+     * ```typescript
+     * // Skip rate limiting for health check
+     * skip: (ctx) => ctx.req.url === '/health'
+     *
+     * // Skip for admin users
+     * skip: (ctx) => ctx.state.user?.role === 'admin'
+     * ```
+     */
+    skip?: (context: Context) => boolean;
+    /**
+     * Bucket cleanup interval in milliseconds
+     *
+     * Periodically removes inactive buckets to prevent memory leaks.
+     * Set to 0 to disable automatic cleanup.
+     *
+     * @default 60000 (1 minute)
+     */
+    cleanupInterval?: number;
+    /**
+     * Bucket TTL (time to live) in milliseconds
+     *
+     * Buckets that haven't been accessed for this duration will be removed during cleanup.
+     *
+     * @default 600000 (10 minutes)
+     */
+    bucketTTL?: number;
+}
+/**
+ * Rate Limiter Middleware
+ *
+ * Implements Token Bucket algorithm for controlling request rate.
+ * Each middleware instance maintains its own bucket storage (instance-based strategy).
+ *
+ * **Token Bucket Algorithm:**
+ * 1. Each client has a bucket with a maximum capacity of tokens
+ * 2. Tokens refill at a constant rate (refillRate per second)
+ * 3. Each request consumes tokens (default: 1 token)
+ * 4. If bucket has insufficient tokens → 429 Too Many Requests
+ * 5. Bucket capacity never exceeds maximum (tokens don't accumulate indefinitely)
+ *
+ * **Performance Optimizations:**
+ * - O(1) bucket lookup (Map)
+ * - O(1) token calculation (pure math, no arrays)
+ * - Lazy token refill (calculated on-demand, not via setInterval)
+ * - Memory-efficient bucket structure (2 numbers per client)
+ * - Automatic cleanup of inactive buckets
+ *
+ * **Instance-based Strategy:**
+ * Each RateLimiterMiddleware instance has its own bucket Map.
+ * This enables route-specific rate limiting:
+ * - GlobalRateLimiter → 1000 req/min for all routes
+ * - ApiRateLimiter → 100 req/min for /api/* routes
+ * - StrictRateLimiter → 5 req/min for /login route
+ *
+ * @example
+ * ```typescript
+ * // Global rate limiter (1000 req/min)
+ * @Middleware()
+ * export class GlobalRateLimiter extends RateLimiterMiddleware {
+ *   constructor() {
+ *     super({ capacity: 1000, refillRate: 1000/60 });
+ *   }
+ * }
+ *
+ * // Strict rate limiter for auth endpoints (5 req/min)
+ * @Middleware()
+ * export class StrictRateLimiter extends RateLimiterMiddleware {
+ *   constructor() {
+ *     super({ capacity: 5, refillRate: 5/60 });
+ *   }
+ * }
+ * ```
+ */
+export declare class RateLimiterMiddleware extends MiddlewareService {
+    /**
+     * Instance-specific bucket storage
+     * Key: Client identifier (IP, user ID, etc.)
+     * Value: Token bucket state
+     */
+    private readonly buckets;
+    /**
+     * Maximum token capacity
+     */
+    private readonly capacity;
+    /**
+     * Token refill rate (tokens per second)
+     */
+    private readonly refillRate;
+    /**
+     * Client key generator function
+     */
+    private readonly keyGenerator;
+    /**
+     * Rate limit exceeded message
+     */
+    private readonly message;
+    /**
+     * Rate limit exceeded status code
+     */
+    private readonly statusCode;
+    /**
+     * Token cost per request
+     */
+    private readonly cost;
+    /**
+     * Skip predicate function
+     */
+    private readonly skip?;
+    /**
+     * Cleanup interval timer ID
+     */
+    private cleanupTimer?;
+    /**
+     * Bucket TTL in milliseconds
+     */
+    private readonly bucketTTL;
+    /**
+     * Creates a new rate limiter middleware instance
+     *
+     * @param options - Rate limiter configuration options
+     *
+     * @example
+     * ```typescript
+     * @Middleware()
+     * export class CustomRateLimiter extends RateLimiterMiddleware {
+     *   constructor() {
+     *     super({
+     *       capacity: 100,
+     *       refillRate: 10,
+     *       keyGenerator: (ctx) => ctx.state.user?.id || 'anonymous',
+     *       message: 'Çok fazla istek gönderdiniz. Lütfen bekleyin.',
+     *       skip: (ctx) => ctx.req.url === '/health'
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    constructor(options?: RateLimiterOptions);
+    /**
+     * Rate limiter middleware handler
+     *
+     * Execution flow:
+     * 1. Check if request should be skipped
+     * 2. Generate client key (IP, user ID, etc.)
+     * 3. Get or create bucket for client
+     * 4. Refill tokens based on elapsed time
+     * 5. Check if sufficient tokens available
+     * 6. Consume tokens and continue, or return 429
+     *
+     * @param context - Ergenecore context wrapper
+     * @param next - Function to call next middleware or handler
+     * @returns Response for rate limited requests, or result of next() for allowed requests
+     */
+    handle(context: Context, next: () => Promise<void>): Promise<any>;
+    /**
+     * Cleanup resources (stop cleanup timer)
+     *
+     * Call this when shutting down the application.
+     */
+    destroy(): void;
+    /**
+     * Get current bucket state for a client (for testing/debugging)
+     *
+     * @param key - Client identifier
+     * @returns Bucket state or undefined
+     */
+    getBucketState(key: string): Bucket | undefined;
+    /**
+     * Clear all buckets (for testing)
+     */
+    clearBuckets(): void;
+    /**
+     * Default key generator - uses X-Forwarded-For or falls back to 'unknown'
+     *
+     * @param context - Ergenecore context
+     * @returns Client identifier
+     */
+    private defaultKeyGenerator;
+    /**
+     * Setup automatic cleanup of inactive buckets
+     *
+     * Prevents memory leaks by removing buckets that haven't been accessed recently.
+     *
+     * @param interval - Cleanup interval in milliseconds
+     */
+    private setupCleanup;
+}
+export {};

package/dist/lib/middlewares/RateLimiterMiddleware.js

@@ -0,0 +1,300 @@
+/**
+ * Rate Limiter Middleware for Ergenecore
+ *
+ * Implements Token Bucket algorithm for rate limiting:
+ * - Token bucket per client (identified by IP or custom key)
+ * - Configurable capacity and refill rate
+ * - Instance-based storage (each middleware instance has its own buckets)
+ * - Zero external dependencies (uses Bun's native APIs)
+ * - Asena DI container compatible
+ *
+ * @module defaults/RateLimiterMiddleware
+ *
+ * **Usage in Asena Application:**
+ * ```typescript
+ * import { Middleware } from '@asenajs/asena/server';
+ * import { RateLimiterMiddleware } from '@asenajs/ergenecore';
+ *
+ * // Create custom rate limiter for your needs
+ * @Middleware()
+ * export class ApiRateLimiter extends RateLimiterMiddleware {
+ *   constructor() {
+ *     super({
+ *       capacity: 100,
+ *       refillRate: 100 / 60, // 100 requests per minute
+ *     });
+ *   }
+ * }
+ *
+ * // Use in controller (class reference, not instance)
+ * @Controller({ middlewares: [ApiRateLimiter] })
+ * export class ApiController { ... }
+ *
+ * // Or use on specific route
+ * @Middleware()
+ * export class StrictRateLimiter extends RateLimiterMiddleware {
+ *   constructor() {
+ *     super({
+ *       capacity: 5,
+ *       refillRate: 5 / 60, // 5 requests per minute
+ *       message: 'Too many login attempts. Please try again later.',
+ *     });
+ *   }
+ * }
+ *
+ * @Post({ path: '/login', middlewares: [StrictRateLimiter] })
+ * public login() { ... }
+ * ```
+ */
+import { MiddlewareService } from '../defaults/MiddlewareService';
+/**
+ * Rate Limiter Middleware
+ *
+ * Implements Token Bucket algorithm for controlling request rate.
+ * Each middleware instance maintains its own bucket storage (instance-based strategy).
+ *
+ * **Token Bucket Algorithm:**
+ * 1. Each client has a bucket with a maximum capacity of tokens
+ * 2. Tokens refill at a constant rate (refillRate per second)
+ * 3. Each request consumes tokens (default: 1 token)
+ * 4. If bucket has insufficient tokens → 429 Too Many Requests
+ * 5. Bucket capacity never exceeds maximum (tokens don't accumulate indefinitely)
+ *
+ * **Performance Optimizations:**
+ * - O(1) bucket lookup (Map)
+ * - O(1) token calculation (pure math, no arrays)
+ * - Lazy token refill (calculated on-demand, not via setInterval)
+ * - Memory-efficient bucket structure (2 numbers per client)
+ * - Automatic cleanup of inactive buckets
+ *
+ * **Instance-based Strategy:**
+ * Each RateLimiterMiddleware instance has its own bucket Map.
+ * This enables route-specific rate limiting:
+ * - GlobalRateLimiter → 1000 req/min for all routes
+ * - ApiRateLimiter → 100 req/min for /api/* routes
+ * - StrictRateLimiter → 5 req/min for /login route
+ *
+ * @example
+ * ```typescript
+ * // Global rate limiter (1000 req/min)
+ * @Middleware()
+ * export class GlobalRateLimiter extends RateLimiterMiddleware {
+ *   constructor() {
+ *     super({ capacity: 1000, refillRate: 1000/60 });
+ *   }
+ * }
+ *
+ * // Strict rate limiter for auth endpoints (5 req/min)
+ * @Middleware()
+ * export class StrictRateLimiter extends RateLimiterMiddleware {
+ *   constructor() {
+ *     super({ capacity: 5, refillRate: 5/60 });
+ *   }
+ * }
+ * ```
+ */
+export class RateLimiterMiddleware extends MiddlewareService {
+    /**
+     * Instance-specific bucket storage
+     * Key: Client identifier (IP, user ID, etc.)
+     * Value: Token bucket state
+     */
+    buckets = new Map();
+    /**
+     * Maximum token capacity
+     */
+    capacity;
+    /**
+     * Token refill rate (tokens per second)
+     */
+    refillRate;
+    /**
+     * Client key generator function
+     */
+    keyGenerator;
+    /**
+     * Rate limit exceeded message
+     */
+    message;
+    /**
+     * Rate limit exceeded status code
+     */
+    statusCode;
+    /**
+     * Token cost per request
+     */
+    cost;
+    /**
+     * Skip predicate function
+     */
+    skip;
+    /**
+     * Cleanup interval timer ID
+     */
+    cleanupTimer;
+    /**
+     * Bucket TTL in milliseconds
+     */
+    bucketTTL;
+    /**
+     * Creates a new rate limiter middleware instance
+     *
+     * @param options - Rate limiter configuration options
+     *
+     * @example
+     * ```typescript
+     * @Middleware()
+     * export class CustomRateLimiter extends RateLimiterMiddleware {
+     *   constructor() {
+     *     super({
+     *       capacity: 100,
+     *       refillRate: 10,
+     *       keyGenerator: (ctx) => ctx.state.user?.id || 'anonymous',
+     *       message: 'Çok fazla istek gönderdiniz. Lütfen bekleyin.',
+     *       skip: (ctx) => ctx.req.url === '/health'
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    constructor(options = {}) {
+        super();
+        // Pre-process and store configuration
+        this.capacity = options.capacity ?? 100;
+        this.refillRate = options.refillRate ?? 10;
+        this.keyGenerator = options.keyGenerator ?? this.defaultKeyGenerator;
+        this.message = options.message ?? 'Rate limit exceeded. Please try again later.';
+        this.statusCode = options.statusCode ?? 429;
+        this.cost = options.cost ?? 1;
+        this.skip = options.skip;
+        this.bucketTTL = options.bucketTTL ?? 600000; // 10 minutes
+        // Setup automatic cleanup
+        const cleanupInterval = options.cleanupInterval ?? 60000; // 1 minute
+        if (cleanupInterval > 0) {
+            this.setupCleanup(cleanupInterval);
+        }
+    }
+    /**
+     * Rate limiter middleware handler
+     *
+     * Execution flow:
+     * 1. Check if request should be skipped
+     * 2. Generate client key (IP, user ID, etc.)
+     * 3. Get or create bucket for client
+     * 4. Refill tokens based on elapsed time
+     * 5. Check if sufficient tokens available
+     * 6. Consume tokens and continue, or return 429
+     *
+     * @param context - Ergenecore context wrapper
+     * @param next - Function to call next middleware or handler
+     * @returns Response for rate limited requests, or result of next() for allowed requests
+     */
+    async handle(context, next) {
+        // Check skip predicate
+        if (this.skip && this.skip(context)) {
+            return await next();
+        }
+        // Generate client key
+        const key = this.keyGenerator(context);
+        // Get or create bucket
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = {
+                tokens: this.capacity,
+                lastRefill: Date.now(),
+            };
+            this.buckets.set(key, bucket);
+        }
+        // Refill tokens based on elapsed time
+        const now = Date.now();
+        const elapsedSeconds = (now - bucket.lastRefill) / 1000;
+        const tokensToAdd = elapsedSeconds * this.refillRate;
+        // Update bucket state
+        bucket.tokens = Math.min(bucket.tokens + tokensToAdd, this.capacity);
+        bucket.lastRefill = now;
+        // Calculate cost for this request
+        const requestCost = typeof this.cost === 'function' ? this.cost(context) : this.cost;
+        // Check if sufficient tokens available
+        if (bucket.tokens < requestCost) {
+            // Rate limit exceeded
+            const retryAfter = Math.ceil((requestCost - bucket.tokens) / this.refillRate);
+            return new Response(this.message, {
+                status: this.statusCode,
+                headers: {
+                    'Retry-After': String(retryAfter),
+                    'X-RateLimit-Limit': String(Math.floor(this.refillRate * 60)), // Requests per minute
+                    'X-RateLimit-Remaining': String(Math.floor(bucket.tokens)),
+                    'X-RateLimit-Reset': String(Math.floor(bucket.lastRefill / 1000 + retryAfter)),
+                },
+            });
+        }
+        // Consume tokens
+        bucket.tokens -= requestCost;
+        // Set rate limit headers
+        context.setResponseHeader('X-RateLimit-Limit', String(Math.floor(this.refillRate * 60)));
+        context.setResponseHeader('X-RateLimit-Remaining', String(Math.floor(bucket.tokens)));
+        context.setResponseHeader('X-RateLimit-Reset', String(Math.floor(bucket.lastRefill / 1000 + 60)));
+        // Continue to next middleware/handler
+        return await next();
+    }
+    /**
+     * Cleanup resources (stop cleanup timer)
+     *
+     * Call this when shutting down the application.
+     */
+    destroy() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+        }
+    }
+    /**
+     * Get current bucket state for a client (for testing/debugging)
+     *
+     * @param key - Client identifier
+     * @returns Bucket state or undefined
+     */
+    getBucketState(key) {
+        return this.buckets.get(key);
+    }
+    /**
+     * Clear all buckets (for testing)
+     */
+    clearBuckets() {
+        this.buckets.clear();
+    }
+    /**
+     * Default key generator - uses X-Forwarded-For or falls back to 'unknown'
+     *
+     * @param context - Ergenecore context
+     * @returns Client identifier
+     */
+    defaultKeyGenerator(context) {
+        return context.req.headers.get('x-forwarded-for') || context.req.headers.get('cf-connecting-ip') || 'unknown';
+    }
+    /**
+     * Setup automatic cleanup of inactive buckets
+     *
+     * Prevents memory leaks by removing buckets that haven't been accessed recently.
+     *
+     * @param interval - Cleanup interval in milliseconds
+     */
+    setupCleanup(interval) {
+        this.cleanupTimer = setInterval(() => {
+            const now = Date.now();
+            const keysToDelete = [];
+            // Find inactive buckets
+            for (const [key, bucket] of this.buckets.entries()) {
+                if (now - bucket.lastRefill > this.bucketTTL) {
+                    keysToDelete.push(key);
+                }
+            }
+            // Remove inactive buckets
+            for (const key of keysToDelete) {
+                this.buckets.delete(key);
+            }
+        }, interval);
+        // Unref timer to allow process to exit
+        this.cleanupTimer.unref();
+    }
+}
+//# sourceMappingURL=RateLimiterMiddleware.js.map

package/dist/lib/middlewares/RateLimiterMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimiterMiddleware.js","sourceRoot":"","sources":["../../../lib/middlewares/RateLimiterMiddleware.ts"],"names":[],"mappings":"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"}

package/dist/lib/types/Handler.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Ergenecore handler type definitions
+ *
+ * Type aliases for route handlers and other function signatures
+ * specific to the Ergenecore adapter.
+ *
+ * @module types/Handler
+ */
+import type { Context } from '../ErgenecoreContextWrapper';
+/**
+ * Ergenecore route handler function
+ *
+ * Asynchronous function that receives an ErgenecoreContextWrapper
+ * and returns a Response or JSON-serializable data.
+ *
+ * @param ctx - Ergenecore context wrapper (ErgenecoreContextWrapper)
+ * @returns Response object or JSON-serializable data
+ *
+ * @example
+ * ```typescript
+ * const handler: ErgenecoreHandler = async (ctx) => {
+ *   const id = ctx.getParam('id');
+ *   const user = await db.users.findById(id);
+ *   return ctx.send(user);
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const handler: ErgenecoreHandler = async (ctx) => {
+ *   // Return Response directly
+ *   return new Response('Hello World', {
+ *     status: 200,
+ *     headers: { 'Content-Type': 'text/plain' }
+ *   });
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const handler: ErgenecoreHandler = async (ctx) => {
+ *   // Return JSON-serializable data
+ *   return { message: 'Success', data: { id: 123 } };
+ * };
+ * ```
+ */
+export type ErgenecoreHandler = (ctx: Context) => Promise<Response | any>;
+/**
+ * Ergenecore middleware next function
+ *
+ * Asynchronous function called within middleware to proceed
+ * to the next middleware in the chain or the route handler.
+ *
+ * @returns Promise that resolves when the next middleware/handler completes
+ *
+ * @example
+ * ```typescript
+ * const middleware = async (ctx: Context, next: ErgenecoreNext) => {
+ *   console.log('Before handler');
+ *   await next();
+ *   console.log('After handler');
+ * };
+ * ```
+ */
+export type ErgenecoreNext = () => Promise<void>;