@tylercoles/mcp-rate-limit/dist/index.d.ts

Rate limiting utilities for MCP framework

/**
 * Rate limiting result
 */
export interface RateLimitResult {
    allowed: boolean;
    remaining: number;
    resetTime: number;
    totalRequests: number;
    retryAfter?: number;
}
/**
 * Rate limit statistics
 */
export interface RateLimitStats {
    key: string;
    requests: number;
    remaining: number;
    resetTime: number;
    windowMs: number;
    limit: number;
}
/**
 * Rate limiter interface
 */
export interface RateLimiter {
    check(key: string, limit: number, windowMs: number): Promise<RateLimitResult>;
    reset(key: string): Promise<void>;
    getStats(key: string): Promise<RateLimitStats | null>;
    cleanup(): Promise<void>;
}
/**
 * Memory-based rate limiter implementation
 */
export declare class MemoryRateLimiter implements RateLimiter {
    private windows;
    private cleanupInterval;
    constructor(cleanupIntervalMs?: number);
    check(key: string, limit: number, windowMs: number): Promise<RateLimitResult>;
    reset(key: string): Promise<void>;
    getStats(key: string): Promise<RateLimitStats | null>;
    cleanup(): Promise<void>;
    private cleanupExpiredWindows;
    /**
     * Get current number of active windows (for monitoring)
     */
    getActiveWindowCount(): number;
    /**
     * Get all active keys (for monitoring)
     */
    getActiveKeys(): string[];
}
/**
 * HTTP rate limiting configuration
 */
export interface HttpRateLimitConfig {
    global?: {
        windowMs: number;
        maxRequests: number;
        skipSuccessfulRequests?: boolean;
        skipFailedRequests?: boolean;
    };
    perClient?: {
        windowMs: number;
        maxRequests: number;
        keyGenerator?: (req: any) => string;
    };
    perEndpoint?: {
        [endpoint: string]: {
            windowMs: number;
            maxRequests: number;
        };
    };
    oauthClientLimits?: {
        [clientId: string]: {
            windowMs: number;
            maxRequests: number;
        };
    };
    headers?: {
        includeHeaders?: boolean;
        headerNames?: {
            remaining?: string;
            reset?: string;
            limit?: string;
            retryAfter?: string;
        };
    };
    onLimitReached?: (req: any, res: any, result: RateLimitResult) => void;
    skipOnError?: boolean;
    store?: RateLimiter;
}
/**
 * WebSocket rate limiting configuration
 */
export interface WebSocketRateLimitConfig {
    connectionLimits?: {
        perIp?: {
            maxConnections: number;
            windowMs?: number;
        };
        global?: {
            maxConnections: number;
        };
    };
    messageLimits?: {
        perConnection?: {
            maxMessages: number;
            windowMs: number;
        };
        perMethod?: {
            [method: string]: {
                maxMessages: number;
                windowMs: number;
            };
        };
    };
    actions?: {
        onConnectionLimitReached?: 'reject' | 'close_oldest';
        onMessageLimitReached?: 'drop' | 'close_connection' | 'throttle';
    };
    cleanupInterval?: number;
    enableMetrics?: boolean;
    store?: RateLimiter;
}
/**
 * Rate limiting utility functions
 */
export declare class RateLimitUtils {
    /**
     * Generate rate limit key from IP address
     */
    static ipKey(ip: string, prefix?: string): string;
    /**
     * Generate rate limit key from session ID
     */
    static sessionKey(sessionId: string, prefix?: string): string;
    /**
     * Generate rate limit key from OAuth client ID
     */
    static oauthClientKey(clientId: string, prefix?: string): string;
    /**
     * Generate rate limit key from user ID
     */
    static userKey(userId: string, prefix?: string): string;
    /**
     * Generate composite key from multiple components
     */
    static compositeKey(...components: string[]): string;
    /**
     * Extract IP address from request with proxy support
     */
    static getClientIp(req: any): string;
    /**
     * Calculate retry-after header value in seconds
     */
    static calculateRetryAfter(resetTime: number): number;
    /**
     * Format rate limit error message
     */
    static formatErrorMessage(result: RateLimitResult): string;
}
/**
 * HTTP rate limit middleware factory
 */
export declare class HttpRateLimitMiddleware {
    private store;
    private config;
    constructor(config: HttpRateLimitConfig);
    /**
     * Create Express middleware for global rate limiting
     */
    createGlobalMiddleware(): (req: any, res: any, next: any) => any;
    /**
     * Create Express middleware for per-client rate limiting
     */
    createClientMiddleware(): (req: any, res: any, next: any) => any;
    /**
     * Handle rate limit exceeded
     */
    private handleRateLimit;
    /**
     * Add rate limit headers to response
     */
    private addHeaders;
    /**
     * Get rate limiter store
     */
    getStore(): RateLimiter;
    /**
     * Cleanup resources
     */
    cleanup(): Promise<void>;
}
/**
 * WebSocket rate limit manager
 */
export declare class WebSocketRateLimitManager {
    private store;
    private config;
    private connectionCounts;
    private activeConnections;
    constructor(config: WebSocketRateLimitConfig);
    /**
     * Check if new connection is allowed
     */
    checkConnectionLimit(ip: string, connection: any): Promise<boolean>;
    /**
     * Check if message is allowed
     */
    checkMessageLimit(connection: any, message: any): Promise<boolean>;
    /**
     * Handle message rate limit exceeded
     */
    private handleMessageRateLimit;
    /**
     * Track new connection
     */
    private trackConnection;
    /**
     * Untrack closed connection
     */
    private untrackConnection;
    /**
     * Close oldest connection for global limit enforcement
     */
    private closeOldestConnection;
    /**
     * Get unique connection identifier
     */
    private getConnectionId;
    /**
     * Get connection statistics
     */
    getConnectionStats(): {
        totalConnections: number;
        connectionsPerIp: Record<string, number>;
    };
    /**
     * Cleanup resources
     */
    cleanup(): Promise<void>;
}
//# sourceMappingURL=index.d.ts.map