@hm-soft/rate-limit

요청 속도 제한 — 슬라이딩 윈도우 / 토큰 버킷. 저장소 비의존 순수 로직(상태는 직렬화 가능). 의존성 0, 시간 주입으로 테스트 친화. @hm-soft/account-lock과 보안 라인업.

설치

npm install @hm-soft/rate-limit

사용

import { slidingWindow, initialSlidingState, tokenBucket, initialBucketState } from "@hm-soft/rate-limit";

// 슬라이딩 윈도우 — IP당 1분에 60회
let state = (await store.get(ip)) ?? initialSlidingState();
const r = slidingWindow(state, { limit: 60, windowMs: 60_000 });
await store.set(ip, r.state);
if (!r.allowed) return res.status(429).header("Retry-After", Math.ceil(r.retryAfterMs / 1000));

// 토큰 버킷 — 버스트 10, 초당 2개 리필
const b = tokenBucket(bucketState, { capacity: 10, refillTokens: 2, refillIntervalMs: 1000 });
if (!b.allowed) throw new Error(`${b.retryAfterMs}ms 후 재시도`);

API

| 함수 | 설명 | |------|------| | initialSlidingState() | 빈 슬라이딩 상태 | | slidingWindow(state, {limit, windowMs}, now?) | → { state, allowed, remaining, retryAfterMs, resetAt } | | initialBucketState() | 빈 버킷 상태(첫 호출 시 가득) | | tokenBucket(state, {capacity, refillTokens, refillIntervalMs}, now?) | → { state, allowed, remaining, retryAfterMs } |

언제 무엇을

• 슬라이딩 윈도우: "1분에 N회"처럼 정확한 횟수 제한. 정밀하지만 타임스탬프 보관.
• 토큰 버킷: 버스트 허용 + 평균 속도 제한. 상태가 작고(토큰 수 + 시각) 가벼움.

상태는 키(IP·사용자ID)별로 직접 저장하세요. now 주입으로 결정적 테스트 가능.

License

Apache-2.0