import type { VextMiddleware } from "../../types/middleware.js";
import type { VextRateLimitConfig, VextRateLimiter } from "../../types/app.js";
/**
 * createRateLimitMiddleware — 速率限制中间件工厂
 *
 * 内置中间件 #4，职责：
 *   1. 对每个请求进行速率限制检查（基于 IP / user / 自定义 key）
 *   2. 超过限制时返回 429 Too Many Requests
 *   3. 在响应头中注入标准速率限制信息（RateLimit-* headers）
 *
 * 配置项（config.rateLimit）：
 *   - enabled:  是否启用速率限制（默认 true）；false 时跳过所有限流检查
 *   - max:      每个时间窗口内最大请求数（默认 100）
 *   - window:   时间窗口（秒，默认 60）
 *   - message:  超过限制时的错误消息（默认 'Too Many Requests'）
 *   - keyBy:    限流维度（默认 'ip'）：
 *                 'ip'   → 按客户端 IP
 *                 'user' → 按 req.user?.id（需 auth 中间件先行）
 *                 函数   → 自定义 key 生成（(req) => string）
 *
 * 默认实现：flex-rate-limit（sliding-window 算法 + 内存存储）
 *
 * 可替换：通过 app.setRateLimiter(limiter) 替换为自定义实现。
 *   自定义 limiter 需实现 VextRateLimiter 接口：
 *     { check(key: string): Promise<{ allowed: boolean; remaining: number; resetAt: number }> }
 *
 *   当 app.setRateLimiter() 被调用后，本中间件将使用自定义 limiter.check()
 *   代替内置 flex-rate-limit，但 keyBy / enabled / message 等配置仍然生效。
 *
 * 响应头（遵循 IETF RateLimit Header Fields 草案）：
 *   - RateLimit-Limit:     窗口期最大请求数
 *   - RateLimit-Remaining: 窗口期剩余请求数
 *   - RateLimit-Reset:     窗口重置时间（Unix 秒）
 *   - Retry-After:         超限时，客户端应等待的秒数（仅 429 响应）
 *
 * @param config       rateLimit 配置（从 VextConfig.rateLimit 提取）
 * @param getRateLimiter 获取当前自定义 limiter 的 getter（支持 app.setRateLimiter() 运行时替换）
 * @returns VextMiddleware
 */
export declare function createRateLimitMiddleware(config: VextRateLimitConfig, getRateLimiter: () => VextRateLimiter | null): VextMiddleware;