API 속도 제한 정책 시뮬레이터

--- name: api-rate-limit-policy-simulator description: 배포 전에 API 속도 제한을 시뮬레이션합니다 - 토큰 버킷, 고정 창, 슬라이딩 로그 및 슬라이딩 카운터를 클라이언트, 엔드포인트, 티어 또는 전역 기준으로, 생성되거나 기록된 트래픽과 재시도하는 클라이언트에 대해 적용합니다. 누가 429를 받고 얼마나 오래 받는지, 고정 창 경계 버스트, 재시도 무리, 시끄러운 이웃, 여전히 통과하는 악성 클라이언트 및 백엔드 용량을 초과하는 피크를 보여줍니다. 오프라인 stdlib Python 시뮬레이터와 --self-test를 포함합니다. --- # API 속도 제한 정책 시뮬레이터 당신은 백엔드 및 플랫폼 엔지니어가 추측이 아닌 증거로 속도 제한을 선택하도록 돕습니다. 종이에 안전해 보이는 제한("키당 분당 300")은 창 경계에서 1.8배까지 통과시키고, 수천 명의 사용자가 하나의 API 키를 공유하는 모바일 앱을 제한하고, 재설정 초에 재시도 무리를 풀어내며, 그 바로 아래에 머무는 스크래퍼에는 아무 효과가 없을 수 있습니다. 당신은 정책과 트래픽을 작은 JSON 파일로 설명하고, 이를 재생하고, 결과를 클라이언트별 및 정책별로 읽습니다. ## 이 스킬의 파일 - `scripts/rate_sim.py` - 클라이언트, 엔드포인트, 클라이언트+엔드포인트 또는 전역 기준으로 키가 지정된 토큰 버킷, 고정 창, 슬라이딩 로그 및 슬라이딩 카운터 리미터를 시뮬레이션합니다. 엔드포인트 및 클라이언트 티어로 범위를 지정합니다. 꾸준한, 포아송 또는 버스트 트래픽을 생성하거나 CSV 트레이스를 재생합니다. 클라이언트가 즉시, 백오프 또는 Retry-After를 준수하여 재시도하도록 하고, 429, 지연, 실패, 최악의 경우 및 관찰된 창 수, 용량 대비 피크, 발견 사항 RL01-RL10 및 샘플 429 응답을 보고합니다 (Python 3.8+ 표준 라이브러리만 사용). - `references/algorithms.md` - 각 알고리즘이 어떻게 동작하는지, 최악의 경우, 메모리 비용 및 선택 시점. - `references/policy-design.md` - 키, 티어, 숫자, 헤더 및 클라이언트 재시도 규칙 선택. 발견 코드의 의미. - `templates/rate-limit-review.md` - 반환할 검토 보고서. - `examples/orders-api.json` - 키당 고정 창, 로그인 제한 및 전역 고정 창이 있는 공개 주문 API. 공유 모바일 키, 대량 파트너, 스크래퍼 및 자격 증명 스터퍼를 포함한 다섯 클라이언트. - `examples/orders-api-report.md` - 해당 파일에 대한 실제 시뮬레이터 출력. - `examples/orders-api-tuned.json` - 수정 후 동일한 API: 티어별 토큰 버킷, 용량에 맞게 조정된 전역 토큰 버킷. ## 워크플로우 ### 1. 입력 수집 다음을 요청하세요: 현재 구성된 또는 제안된 제한 (알고리즘, 키, 숫자, 대상 엔드포인트 및 클라이언트), 적용 위치 (게이트웨이, CDN, 앱, Redis), 백엔드가 지속할 수 있는 초당 요청 수 용량, 그리고 트래픽: 가장 큰 합법적 클라이언트와 그 형태 (꾸준함, 버스트 배치 작업, 하나의 키 또는 하나의 NAT IP 뒤의 많은 사용자), 각각의 재시도 방식, 그리고 로그에서 본 남용. 실제 액세스 로그가 추측보다 낫습니다: 바쁜 5-15분 동안 `t,client,endpoint`를 내보내고 `--trace`로 전달하세요. ### 2. 시뮬레이터 실행 ``` python3 scripts/rate_sim.py examples/orders-api.json python3 scripts/rate_sim.py examples/orders-api-tuned.json python3 scripts/rate_sim.py policies.json --trace access-sample.csv python3 scripts/rate_sim.py policies.json --json python3 scripts/rate_sim.py --self-test ``` 종료 0 = 높은 발견 사항 없음, 1 = 높은 발견 사항 (합법적 클라이언트 제한 또는 허용된 트래픽이 용량 초과), 2 = 잘못된 입력. 셸이 없으면 `references/algorithms.md`로 추론하세요: 키별로, 클라이언트의 창당 피크를 제한과 비교하고, 최악의 경우 (고정 창의 경우 2배 제한, 버킷의 경우 버스트 + 속도)를 용량과 비교하고, 각 클라이언트가 429 후에 무엇을 하는지 생각하세요. ### 3. 결과 읽기 - 합법적 클라이언트 먼저 (RL01): 실패하거나 지연된 요청 및 대기 시간. 앱 사용자가 공유하는 하나의 키는 자체 티어 또는 사용자별 키가 필요합니다. - 용량 (RL03): 허용된 피크 초당 요청 수 vs 백엔드가 지속하는 양. 전역 제한만이 용량을 보호합니다. 키별 제한은 키 수만큼 곱해집니다. - 형태 (RL04, RL10): 고정 창은 경계에서 버스트를 통과시키고 한 번에 전체 창을 제공합니다. 지터 없는 재시도는 모두 같은 초에 돌아옵니다. - 남용 (RL02): 키별 제한 아래의 스크래퍼는 제한으로 막을 수 없습니다. 탐지, 인증 또는 엔드포인트별 제한이 필요합니다. - 재시도 (RL05): 논리적 요청당 시도가 1.5 이상이면 클라이언트가 제한될 때 부하를 증폭시킵니다. ### 4. 조정 및 재실행 한 번에 하나씩 변경하고 동일한 트래픽으로 재실행하세요: 고정 창을 토큰 버킷 또는 슬라이딩 카운터로 전환하고, `clients` / `exclude_clients`로 티어를 추가하고, 전역 버킷을 용량에 맞게 조정하고 (속도 = 지속 가능한 rps, 버스트 = 백엔드가 1초 동안 흡수하는 양), 로그인 및 비용이 많이 드는 호출에 엔드포인트 제한을 추가하고, 배치 파트너와 페이싱을 합의하세요. 숫자는 `references/policy-design.md`를 사용하세요. ### 5. 전달 `templates/rate-limit-review.md`를 작성하세요: 판정, 클라이언트별 전후 표, 구성으로서의 정책 변경, 429 응답 및 헤더, 클라이언트 지침 (Retry-After, 지터 포함 백오프, 최대 재시도) 및 롤아웃 후 모니터링할 항목. ## 예시 결과 `examples/orders-api.json`에서 공유 `mobile-app` 키가 분당 300의 키당 창에 도달합니다: 1,839개의 요청 중 1,042개가 최대 60초를 기다린 후에만 성공합니다 (RL01, 높음). 지터 없이 Retry-After를 준수하면 240초에 289개의 재시도가 풀려 허용된 트래픽이 용량 80 대비 초당 313개로 피크를 칩니다 (RL03, RL10). 키당 고정 창은 1분 동안 544개의 요청을 통과시키고 (1.8배, RL04), 스크래퍼는 즉시 재시도로 요청당 2.67회 시도하면서 여전히 호출의 45%를 통과시킵니다. 로그인 제한은 자격 증명 스터퍼를 막습니다 (480 중 40). `examples/orders-api-tuned.json` (티어 토큰 버킷, 전역 버킷 50 req/s + 30 버스트, 파트너 페이싱 2 req/s)에서 합법적 클라이언트는 429를 보지 않고, 피크는 27 req/s이며 스크래퍼 발견 사항만 남습니다. ## 규칙 - 평균이 아닌 실제 트래픽 (또는 트레이스)으로 시뮬레이션하세요. 버스트와 재시도가 제한이 실패하는 지점입니다. - 전역 제한이 총량을 제한하지 않는 한 제한을 용량에 안전하다고 부르지 마세요. - 합법적 클라이언트의 지연된 요청을 성공이 아닌 피해로 취급하세요. - 항상 Retry-After와 함께 429를 반환하고, 지터를 추가하고, 클라이언트에게 백오프 방법을 알려주세요. - 속도 제한은 그 자체로 남용 방지가 아닙니다. 인증, 봇 탐지 또는 WAF 규칙이 필요한 경우 말하세요. - 결과는 모델입니다. 롤아웃 후 게이트웨이 메트릭으로 확인하고 제한을 코드가 아닌 구성에 유지하세요.