@asenajs/hono-adapter 1.1.0 → 1.2.0

package/dist/lib/middlewares/CorsMiddleware.js

@@ -0,0 +1,169 @@
+/**
+ * CORS Middleware for Hono Adapter
+ *
+ * Handles Cross-Origin Resource Sharing (CORS) by:
+ * - Setting appropriate CORS headers on responses
+ * - Handling preflight OPTIONS requests
+ * - Supporting origin validation
+ * - Uses Hono's native header system
+ *
+ * @module defaults/CorsMiddleware
+ *
+ * @example
+ * ```typescript
+ * import { Middleware } from '@asenajs/asena/server';
+ * import { CorsMiddleware } from '@asenajs/hono-adapter';
+ *
+ * @Middleware()
+ * export class MyCorsMiddleware extends CorsMiddleware {
+ *   constructor() {
+ *     super({
+ *       origin: '*', // or ['https://example.com']
+ *       methods: ['GET', 'POST', 'PUT', 'DELETE'],
+ *       credentials: true
+ *     });
+ *   }
+ * }
+ * ```
+ */
+import { MiddlewareService } from '../defaults';
+/**
+ * CORS Middleware
+ *
+ * Implements CORS (Cross-Origin Resource Sharing) for Hono adapter.
+ * Extend this class and configure it via constructor to customize CORS behavior.
+ *
+ * **Performance Optimizations:**
+ * - Lazy header allocation (only when needed)
+ * - Pre-joined header strings for common cases
+ * - Fast origin validation
+ * - Minimal string allocations
+ *
+ * **CORS Flow:**
+ * 1. Check if request has Origin header (if not, skip CORS)
+ * 2. Validate origin against allowed origins
+ * 3. Handle preflight OPTIONS request → return 204 immediately
+ * 4. For other requests → set CORS headers and call next()
+ */
+export class CorsMiddleware extends MiddlewareService {
+    origin;
+    methods;
+    allowedHeaders;
+    exposedHeaders;
+    credentials;
+    maxAge;
+    /**
+     * Creates a new CORS middleware instance
+     *
+     * @param options - CORS configuration options
+     *
+     * @example
+     * ```typescript
+     * @Middleware()
+     * export class CustomCors extends CorsMiddleware {
+     *   constructor() {
+     *     super({
+     *       origin: ['https://example.com', 'https://app.example.com'],
+     *       methods: ['GET', 'POST'],
+     *       credentials: true,
+     *       maxAge: 3600
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    constructor(options = {}) {
+        super();
+        // Pre-process and store configuration (avoid runtime processing)
+        this.origin = options.origin ?? '*';
+        this.methods = (options.methods ?? ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']).join(', ');
+        this.allowedHeaders = (options.allowedHeaders ?? ['Content-Type', 'Authorization']).join(', ');
+        this.exposedHeaders = (options.exposedHeaders ?? []).join(', ');
+        this.credentials = options.credentials ?? false;
+        this.maxAge = String(options.maxAge ?? 86400); // 24 hours default
+    }
+    /**
+     * CORS middleware handler
+     *
+     * Execution flow:
+     * 1. Check if Origin header present (if not, skip CORS)
+     * 2. Validate origin
+     * 3. Handle preflight OPTIONS → return 204 No Content
+     * 4. Set CORS headers for actual request → call next()
+     *
+     * @param context - Hono context wrapper
+     * @param next - Function to call next middleware or handler
+     * @returns Response for preflight, or result of next() for actual requests
+     */
+    async handle(context, next) {
+        const origin = context.req.header('Origin');
+        // If no Origin header, this is not a CORS request → skip
+        if (!origin) {
+            return await next();
+        }
+        // Validate origin
+        const allowedOrigin = this.getAllowedOrigin(origin);
+        if (!allowedOrigin) {
+            // Origin not allowed → block request
+            return new Response('CORS: Origin not allowed', { status: 403 });
+        }
+        // Set CORS headers using Hono's context (access via context.context for HonoContextWrapper)
+        const honoContext = context.context;
+        honoContext.header('Access-Control-Allow-Origin', allowedOrigin);
+        if (this.credentials) {
+            honoContext.header('Access-Control-Allow-Credentials', 'true');
+        }
+        if (this.exposedHeaders) {
+            honoContext.header('Access-Control-Expose-Headers', this.exposedHeaders);
+        }
+        // Handle preflight OPTIONS request
+        if (context.req.method === 'OPTIONS') {
+            // Build headers object for preflight response
+            const headers = {
+                'Access-Control-Allow-Origin': allowedOrigin,
+                'Access-Control-Allow-Methods': this.methods,
+                'Access-Control-Allow-Headers': this.allowedHeaders,
+                'Access-Control-Max-Age': this.maxAge,
+            };
+            if (this.credentials) {
+                headers['Access-Control-Allow-Credentials'] = 'true';
+            }
+            // Return 204 No Content for preflight
+            return new Response(null, { status: 204, headers });
+        }
+        // For actual requests, continue to handler
+        return await next();
+    }
+    /**
+     * Determines the allowed origin value for the response
+     *
+     * Performance:
+     * - Fast path for '*' (most common case)
+     * - String comparison for single origin
+     * - Array.includes() for string array (O(n) but n is typically small)
+     * - Function call for dynamic validation
+     *
+     * @param requestOrigin - Origin from request header
+     * @returns Allowed origin string or null if not allowed
+     */
+    getAllowedOrigin(requestOrigin) {
+        // Fast path: Allow all origins
+        if (this.origin === '*') {
+            return '*';
+        }
+        // Single origin string
+        if (typeof this.origin === 'string') {
+            return this.origin === requestOrigin ? requestOrigin : null;
+        }
+        // Array of specific origins
+        if (Array.isArray(this.origin)) {
+            return this.origin.includes(requestOrigin) ? requestOrigin : null;
+        }
+        // Function-based validation
+        if (typeof this.origin === 'function') {
+            return this.origin(requestOrigin) ? requestOrigin : null;
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=CorsMiddleware.js.map

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

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

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

@@ -0,0 +1,329 @@
+/**
+ * Rate Limiter Middleware for Hono Adapter
+ *
+ * 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/hono-adapter';
+ *
+ * // 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, MiddlewareService } from '../defaults';
+/**
+ * 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 CF-Connecting-IP.
+     * You can customize this to use user ID, API key, or any other identifier.
+     *
+     * @default (ctx) => ctx.req.headers.get('x-forwarded-for') || ctx.req.headers.get('cf-connecting-ip') || 'unknown'
+     *
+     * @example
+     * ```typescript
+     * // Rate limit by user ID
+     * keyGenerator: (ctx) => ctx.getValue('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.getValue('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.getValue('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 - Hono 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 CF-Connecting-IP or falls back to 'unknown'
+     *
+     * @param context - Hono 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 {};