/**
 * 速率限制器接口与共享类型定义（audit-P1-6）
 *
 * 设计目标：
 * - 抽象 `RateLimiter` 接口，使限流后端可在内存与 Redis 之间切换
 * - 默认内存实现，无需引入额外依赖
 * - 通过 `RATE_LIMIT_DRIVER=redis` 切换至分布式实现，适配多实例部署
 * - 公共 API（`rateLimit` / `resetRateLimit`）统一返回 Promise，保证实现可替换
 */

/** 单次限流检查的入参（与具体后端无关） */
export interface RateLimitParams {
  /** 限流桶的唯一标识，例如 `login:${ip}` 或 `ai:${userId}` */
  key: string
  /** 窗口内允许的最大请求次数 */
  limit: number
  /** 窗口长度（毫秒） */
  windowMs: number
}

/** 限流检查结果（与 upstash `RatelimitResult` 形状兼容，便于平滑切换） */
export interface RateLimitResult {
  success: boolean
  remaining: number
  resetTime: number
  /** 距离窗口重置的毫秒数；已重置时为 0 */
  retryAfterMs: number
}

/**
 * 速率限制器抽象接口。
 *
 * 所有实现必须为 Promise 返回，以便 Redis 等异步后端无缝接入。
 * 实现需保证：
 * - `limit()` 无论成功失败均累加计数（便于失败次数累计锁定）
 * - `reset()` 幂等，重复调用不抛错
 * - 不抛错：失败时返回 `{ success: true }` 兜底，避免限流故障阻断主流程
 */
export interface RateLimiter {
  /** 检查并累加请求计数；返回当前窗口状态 */
  limit(params: RateLimitParams): Promise<RateLimitResult>
  /** 重置指定 key 的计数（例如登录成功后清除失败计数） */
  reset(key: string): Promise<void>
}
