构建滑动窗口限流器

项目概述

本项目实现一个面向 precise rate limiting 的完整系统，核心要解决的问题是 counting requests in a sliding window without storing every timestamp, so the limit is exact and memory is bounded。整体由 Window counter、Timestamp trim、Boundary check、Distributed sync、Rejection responder 五个模块组成，每个模块单一职责、可独立测试，最后通过集成测试验证端到端正确性。设计上把 a burst exactly at the window boundary that the counter admits twice if the trim runs after the check 作为第一类需求先行处理，而非事后再补。

架构与关键决策

数据模型为 a sorted list of request timestamps within the window, trimmed at the head as the window slides forward。Window counter 定义其余阶段共同依赖的数据形状并在边界处校验输入；Timestamp trim 承载 precise rate limiting 的正确性逻辑；Boundary check 专门处理 a burst exactly at the window boundary that the counter admits twice if the trim runs after the check，在失败路径上给出明确的拒绝、重试或降级策略；Distributed sync 提供可观测性，每次操作输出带关联 id 的结构化事件；Rejection responder 在过载时按既定方式降级，避免过载演变为数据损坏。配置与代码分离，使风险变更可经 diff 审阅。

实施与测试

按五个阶段依次实现 Window counter、Timestamp trim、Boundary check、Distributed sync、Rejection responder，每阶段配套聚焦单测。集成测试组合各模块并驱动真实 precise rate limiting 场景：先验证正常路径，再刻意触发 a burst exactly at the window boundary that the counter admits twice if the trim runs after the check 并断言系统降级而非损坏。所有依赖均在进程内或被桩替换，用例在 CI 中确定可复现。

限制与后续

• 单区域设计，多区域复制超出范围。
• Window counter 默认进程内，未水平共享。
• 无鉴权层，假定部署在强制身份的边缘之后。

代码示例

# setup for rate-limiter-sliding-window
pnpm init
pnpm add redis fastify
pnpm add -D typescript tsx vitest

rate_limiter_sliding_window/
├── src/index.ts
├── src/window-counter.ts
├── src/timestamp-trim.ts
├── tests/rate_limiter_sliding_window.test.ts
└── package.json

// Window counter: precise rate limiting core
export function windowcounter(input: WindowcounterInput): WindowcounterResult {
  // Build the window counter that anchors precise rate limiting and defines the core data shape.
  return processWindowcounter(input);
}

// Timestamp trim — handles precise rate limiting Add the timestamp trim so
export class Timestamptrim {
  constructor(private opts: TimestamptrimOptions) {}
  async run(ctx: Context): Promise<TimestamptrimOutput> {
    return this.execute(ctx);
  }
}

// Boundary check: precise rate limiting stage
export const boundarycheck = (next: Next) => async (req: Request) => {
  const out = await transform(req);
  return next(out);
};

// Distributed sync for precise rate limiting
export async function distributedsync(stream: AsyncIterable<Chunk>): Promise<Aggregate> {
  let acc = init();
  for await (const c of stream) acc = merge(acc, c);
  return acc;
}

// Rejection responder: precise rate limiting finalization
export function rejectionresponder(state: State): Result {
  validate(state);
  return finalize(state);
}

# run the precise rate limiting test suite
pnpm vitest run