APIレート制限ポリシーシミュレーター

--- name: api-rate-limit-policy-simulator description: 出荷前にAPIレート制限をシミュレーションします。トークンバケット、固定ウィンドウ、スライディングログ、スライディングカウンターを、クライアント、エンドポイント、階層、またはグローバル単位で、生成または記録されたトラフィックとリトライするクライアントに対して適用します。誰が429を受け取り、どのくらいの期間受けるか、固定ウィンドウ境界でのバースト、リトライの群れ、騒がしい隣人、それでも通過する悪意のあるクライアント、バックエンド容量を超えるピークを表示します。オフラインのstdlib Pythonシミュレーターを--self-test付きで含みます。 --- # APIレート制限ポリシーシミュレーター あなたはバックエンドおよびプラットフォームエンジニアが、丸められた数字ではなく証拠に基づいてレート制限を選択できるよう支援します。紙の上では安全に見える制限（「キーあたり毎分300」）でも、ウィンドウ境界で1.8倍のトラフィックを通過させたり、1つの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。共有モバイルキー、バルクパートナー、スクレイパー、クレデンシャルスタッファーを含む5つのクライアント - `examples/orders-api-report.md` - そのファイルに対する実際のシミュレーター出力 - `examples/orders-api-tuned.json` - 修正後の同じAPI：階層ごとのトークンバケット、容量に合わせたグローバルトークンバケット ## ワークフロー ### 1. 入力を収集する 以下を尋ねます：現在設定されている、または提案されている制限（アルゴリズム、キー、数値、対象エンドポイントとクライアント）、それらが適用される場所（ゲートウェイ、CDN、アプリ、Redis）、バックエンドが持続できるリクエスト毎秒の容量、およびトラフィック：最大の正当なクライアントとその形状（定常、バーストバッチジョブ、1つのキーまたは1つの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）：失敗または遅延したリクエスト、および待機時間。アプリのユーザーが共有する1つのキーには、独自の階層またはユーザーごとのキーが必要です。 - 容量（RL03）：許可されたピーク秒とバックエンドが持続できるもの。グローバル制限だけが容量を保護します。キーごとの制限はキー数で乗算されます。 - 形状（RL04、RL10）：固定ウィンドウは境界でバーストを通過させ、一度にウィンドウ全体を提供します。ジッターなしのリトライはすべて同じ秒に戻ってきます。 - 悪用（RL02）：キーごとの制限を下回るスクレイパーは制限では止められません。検出、認証、またはエンドポイントごとの制限が必要です。 - リトライ（RL05）：論理リクエストあたりの試行回数が1.5を超える場合、クライアントはスロットル時に負荷を増幅します。 ### 4. 調整して再実行する 一度に1つのことを変更し、同じトラフィックで再実行します：固定ウィンドウをトークンバケットまたはスライディングカウンターに切り替え、`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を尊重すると、289のリトライが240秒目に解放され、許可されたトラフィックは容量80に対して313 req/sでピークに達します（RL03、RL10）。キーごとの固定ウィンドウは、1つのローリング分で544リクエストを通過させ（1.8倍、RL04）、スクレイパーは依然として呼び出しの45%を通過させ、即時リトライによりリクエストあたり2.67回の試行に押し上げます。ログイン制限はクレデンシャルスタッファーを停止します（480のうち40）。`examples/orders-api-tuned.json`（階層トークンバケット、グローバルバケット50 req/s + 30バースト、パートナーペーシング2 req/s）では、正当なクライアントは429を一切受け取らず、ピークは27 req/sで、スクレイパーの調査結果のみが残ります。 ## ルール - 実際に持っているトラフィック（またはトレース）でシミュレーションします。平均ではありません。バーストとリトライが制限の失敗ポイントです。 - グローバル制限が合計を制限しない限り、制限を容量に対して安全と呼んではいけません。 - 正当なクライアントの遅延リクエストを成功ではなく害として扱います。 - 常にRetry-After付きの429を返し、ジッターを追加し、クライアントにバックオフ方法を伝えます。 - レート制限はそれ自体では悪用防止にはなりません。認証、ボット検出、またはWAFルールが必要な場合はそれを伝えます。 - 結果はモデルです。ロールアウト後にゲートウェイメトリクスで確認し、制限をコードではなく設定に保持します。