raffel 0.1.2

package/dist/http/rate-limit.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Rate Limiting Middleware
+ *
+ * Provides configurable rate limiting with sliding window algorithm,
+ * custom rules per path/method, and event emission.
+ *
+ * @example
+ * import { createRateLimiter, rateLimitMiddleware } from 'raffel/http/rate-limit'
+ *
+ * // Basic usage - 100 requests per minute per IP
+ * const limiter = createRateLimiter({
+ *   windowMs: 60000,
+ *   max: 100,
+ * })
+ * app.use('*', rateLimitMiddleware(limiter))
+ *
+ * // Advanced - different limits per path
+ * const limiter = createRateLimiter({
+ *   windowMs: 60000,
+ *   max: 100,
+ *   rules: [
+ *     { path: '/api/auth/*', method: 'POST', max: 5 },   // Strict for auth
+ *     { path: '/api/search', max: 30 },                  // Moderate for search
+ *     { path: '/api/public/*', max: 1000 },              // Lenient for public
+ *   ],
+ * })
+ */
+import type { HttpContextInterface } from './context.js';
+import type { HttpMiddleware } from './app.js';
+import type { ApiEventEmitter } from './events.js';
+/**
+ * Rate limit rule for specific path/method combinations
+ */
+export interface RateLimitRule {
+    /** Path pattern (supports * wildcard) */
+    path: string;
+    /** HTTP method (optional, applies to all if not specified) */
+    method?: string | string[];
+    /** Maximum requests in window */
+    max: number;
+    /** Window duration in ms (overrides global) */
+    windowMs?: number;
+    /** Custom key generator for this rule */
+    keyGenerator?: KeyGenerator;
+    /** Skip this rule if returns true */
+    skip?: (c: HttpContextInterface) => boolean | Promise<boolean>;
+}
+/**
+ * Key generator function type
+ */
+export type KeyGenerator = (c: HttpContextInterface) => string | Promise<string>;
+/**
+ * Rate limit entry for tracking requests
+ */
+export interface RateLimitEntry {
+    /** Request timestamps in the current window */
+    timestamps: number[];
+    /** Total requests in current window */
+    count: number;
+    /** Window start time */
+    windowStart: number;
+}
+/**
+ * Rate limiter configuration options
+ */
+export interface RateLimiterOptions {
+    /**
+     * Time window in milliseconds
+     * @default 60000 (1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Maximum requests per window
+     * @default 100
+     */
+    max?: number;
+    /**
+     * Custom key generator
+     * @default IP address from x-forwarded-for or x-real-ip
+     */
+    keyGenerator?: KeyGenerator;
+    /**
+     * Path/method specific rules (checked in order, first match wins)
+     */
+    rules?: RateLimitRule[];
+    /**
+     * Maximum unique keys to track (prevents memory exhaustion)
+     * @default 10000
+     */
+    maxUniqueKeys?: number;
+    /**
+     * Event emitter for rate limit events
+     */
+    events?: ApiEventEmitter;
+    /**
+     * Custom store for distributed rate limiting
+     */
+    store?: RateLimitStore;
+    /**
+     * Skip rate limiting if returns true
+     */
+    skip?: (c: HttpContextInterface) => boolean | Promise<boolean>;
+    /**
+     * Callback when rate limit is exceeded
+     */
+    onLimit?: (c: HttpContextInterface, info: RateLimitInfo) => void | Promise<void>;
+    /**
+     * Include rate limit headers in response
+     * @default true
+     */
+    headers?: boolean;
+    /**
+     * Header names for rate limit info
+     */
+    headerNames?: {
+        limit?: string;
+        remaining?: string;
+        reset?: string;
+        retryAfter?: string;
+    };
+    /**
+     * Use sliding window algorithm (more accurate but slightly more memory)
+     * @default true
+     */
+    slidingWindow?: boolean;
+    /**
+     * Cleanup interval for expired entries (ms)
+     * @default 60000 (1 minute)
+     */
+    cleanupInterval?: number;
+}
+/**
+ * Rate limit info returned by check
+ */
+export interface RateLimitInfo {
+    /** Whether rate limit is exceeded */
+    limited: boolean;
+    /** Maximum requests allowed */
+    limit: number;
+    /** Remaining requests in window */
+    remaining: number;
+    /** Time until window resets (ms) */
+    resetIn: number;
+    /** Timestamp when window resets */
+    resetAt: number;
+    /** Current request count */
+    current: number;
+    /** The key used for this request */
+    key: string;
+    /** Rule that matched (if any) */
+    rule?: RateLimitRule;
+}
+/**
+ * Custom store interface for distributed rate limiting
+ */
+export interface RateLimitStore {
+    /**
+     * Increment counter and get current count
+     */
+    increment(key: string, windowMs: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    /**
+     * Get current count for a key
+     */
+    get(key: string): Promise<{
+        count: number;
+        resetAt: number;
+    } | undefined>;
+    /**
+     * Reset a key
+     */
+    reset(key: string): Promise<void>;
+    /**
+     * Clear all entries
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Rate limiter manager interface
+ */
+export interface RateLimiter {
+    /**
+     * Check rate limit for a context
+     */
+    check(c: HttpContextInterface): Promise<RateLimitInfo>;
+    /**
+     * Increment counter for a context
+     */
+    increment(c: HttpContextInterface): Promise<RateLimitInfo>;
+    /**
+     * Reset rate limit for a key
+     */
+    reset(key: string): Promise<void>;
+    /**
+     * Get current stats
+     */
+    getStats(): RateLimitStats;
+    /**
+     * Clear all rate limit data
+     */
+    clear(): Promise<void>;
+    /**
+     * Stop cleanup timer
+     */
+    stop(): void;
+}
+/**
+ * Rate limit statistics
+ */
+export interface RateLimitStats {
+    totalKeys: number;
+    totalRequests: number;
+    limitedRequests: number;
+}
+/**
+ * Create a rate limiter
+ *
+ * @param options - Rate limiter configuration
+ * @returns Rate limiter instance
+ *
+ * @example
+ * // Basic usage
+ * const limiter = createRateLimiter({
+ *   windowMs: 60000,  // 1 minute
+ *   max: 100,         // 100 requests per minute
+ * })
+ *
+ * // With path-specific rules
+ * const limiter = createRateLimiter({
+ *   windowMs: 60000,
+ *   max: 100,
+ *   rules: [
+ *     { path: '/api/auth/login', method: 'POST', max: 5 },
+ *     { path: '/api/auth/*', max: 20 },
+ *     { path: '/api/heavy/*', max: 10, windowMs: 300000 },
+ *   ],
+ * })
+ */
+export declare function createRateLimiter(options?: RateLimiterOptions): RateLimiter;
+/**
+ * Rate limit middleware options
+ */
+export interface RateLimitMiddlewareOptions {
+    /**
+     * Include rate limit headers in response
+     * @default true
+     */
+    headers?: boolean;
+    /**
+     * Header names
+     */
+    headerNames?: {
+        limit?: string;
+        remaining?: string;
+        reset?: string;
+        retryAfter?: string;
+    };
+    /**
+     * Custom response when rate limited
+     */
+    onLimit?: (c: HttpContextInterface, info: RateLimitInfo) => Response | Promise<Response>;
+    /**
+     * Message in default rate limit response
+     * @default 'Too many requests'
+     */
+    message?: string;
+}
+/**
+ * Create rate limit middleware
+ *
+ * @param limiter - Rate limiter instance
+ * @param options - Middleware options
+ * @returns Middleware function
+ *
+ * @example
+ * const limiter = createRateLimiter({ windowMs: 60000, max: 100 })
+ * app.use('*', rateLimitMiddleware(limiter))
+ */
+export declare function rateLimitMiddleware<E extends Record<string, unknown> = Record<string, unknown>>(limiter: RateLimiter, options?: RateLimitMiddlewareOptions): HttpMiddleware<E>;
+/**
+ * Key generator by IP address (default)
+ */
+export declare const keyByIp: KeyGenerator;
+/**
+ * Key generator by user ID (requires auth middleware)
+ */
+export declare function keyByUserId(userIdKey?: string): KeyGenerator;
+/**
+ * Key generator by API key header
+ */
+export declare function keyByApiKey(headerName?: string): KeyGenerator;
+/**
+ * Key generator combining IP and path
+ */
+export declare const keyByIpAndPath: KeyGenerator;
+/**
+ * Key generator combining IP and method
+ */
+export declare const keyByIpAndMethod: KeyGenerator;
+declare const _default: {
+    createRateLimiter: typeof createRateLimiter;
+    rateLimitMiddleware: typeof rateLimitMiddleware;
+    keyByIp: KeyGenerator;
+    keyByUserId: typeof keyByUserId;
+    keyByApiKey: typeof keyByApiKey;
+    keyByIpAndPath: KeyGenerator;
+    keyByIpAndMethod: KeyGenerator;
+};
+export default _default;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/http/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/http/rate-limit.ts"],"names":[],"mappings":"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"}