-- Views
November 17, 26
スライド概要
有料 API の API キー検証とレート制限を、FastAPI の Depends と middleware のどちらに置くかで何が変わるのか、動かして比べました。Depends だと 404 や /docs は素通りすること、ボディ引数のあるルートではキーを弾く前に 5 MB のボディを読んでしまうこと、uvicorn --workers 4 ではメモリ上のカウンターが上限 10 回のところを 21〜24 回通したことなどを、結果つきで載せています。
作者は UsageRail(API キーの発行、顧客ごとのレート制限、自分の Stripe での従量課金)を作っている 3 人のうちの 1 人です。
FastAPI の API キーと従量課金の設定
https://usagerail.com/docs/fastapi
Super Lede
FastAPI で API キーとレート制限 Depends と middleware、どこで止めるかを動かして比べた Super Lede(UsageRail) Python 3.14.7 / FastAPI 0.163.1 / Starlette 1.10.0 / uvicorn 0.54.0 FastAPI で API キーとレート制限 1 / 15
有料 API が 1 リクエストごとに決めること 誰のリクエストか:API キーから顧客を引く いま通してよいか:顧客ごとのレート制限 料金に数えるか:成功したものだけ数える FastAPI でこれを置ける場所は大きく 2 つ。ASGI の middleware と、Depends(ルーターやアプ リ全体の dependencies も含む)。置き場所によって、止められるタイミングと、見えるリクエスト が変わる。 FastAPI で API キーとレート制限 2 / 15
リクエストが通る順番 uvicorn → middleware → ルーティング → ボディ読み込み・JSON パース※ → Depends → エンドポイント middleware はルーティングより前。存在しないパスも /docs も通る Depends が走るのはルートが決まってから。※ボディ引数(Pydantic モデルなど)を宣言したル ートでは、ボディを読み終えたあと 次のページから、この順番が効いてくる場面を 7 つ試した。数字はどれも手元で実行した結果 FastAPI で API キーとレート制限 3 / 15
実験 1:Depends を通らないリクエスト キー検証を Depends に置き、どの層を通ったかを記録する middleware を足した。 リクエスト 応答 通った層 POST /v1/items/1(正しいキー) 200 middleware → Depends GET /nope 404 middleware だけ GET /docs 200 middleware だけ POST /v1/items/1/(末尾にスラッシュ) 307 middleware だけ 404 と 307 はキーなしで返る。Depends に置いたレート制限はこれを数えない キーを持たない相手を止めるなら、IP 単位の制限を前段に置く FastAPI で API キーとレート制限 4 / 15
実験 2:キーを弾く前に、ボディはもう読まれている 間違ったキーで 5 MB の JSON を POST し、アプリが receive() で受け取ったバイト数を数えた。 キー検証の場所 応答 読んだボディ Depends(ボディ引数あり) 401 5,000,012 バイト Depends(ボディ引数なし、Request から読む) 401 0 バイト 素の ASGI middleware 401 0 バイト Depends + RequestBodyLimitMiddleware(1 MB) 413 0 バイト ボディ引数があると、FastAPI はボディを読んで JSON をパースしてから Depends を解決する Starlette 1.10 には RequestBodyLimitMiddleware がある。Content-Length が上限を超えて いれば、読む前に 413 を返す FastAPI で API キーとレート制限 5 / 15
実験 3:キーもボディも間違っているとき 送ったもの Depends で検証 middleware で検証 間違ったキー + 壊れた JSON 422 json_invalid 401 間違ったキー + 項目の違う JSON 401 401 JSON として読めないと、Depends に入る前に 422 で返る 項目が違うだけなら、先に Depends が例外を投げて 401 になる 「401 ならキーを見直す」というクライアント側の分岐は、壊れた JSON のときには通らない FastAPI で API キーとレート制限 6 / 15
実験 4:middleware の中で HTTPException を投げる
@app.middleware("http")
async def limit_in_middleware(request, call_next):
raise HTTPException(429, headers={"Retry-After": "1"})
結果:500 Internal Server Error。Retry-After も付かない。
HTTPException を 429 などの応答に変える ExceptionMiddleware は、自分で足した
middleware より内側にある。外側で投げた例外はそこを通らない
middleware では例外を投げず、応答を作って返す
return JSONResponse({"detail": "rate_limited"}, status_code=429,
headers={"Retry-After": "1"})
FastAPI で API キーとレート制限
7 / 15
実験 5:あとから足した middleware が先に走る 番目に追加 app.add_middleware(RateLimitMiddleware) # 2 番目に追加 app.add_middleware(AuthMiddleware) # 1 実行順:RateLimitMiddleware → AuthMiddleware 顧客ごとのレート制限は、誰のリクエストかが分かってからでないと数えられない 認証の middleware は、レート制限の middleware より後に add する FastAPI で API キーとレート制限 8 / 15
実験 6:429 に付けたいヘッダーが消える Depends で Response を受け取って RateLimit ヘッダーを付け、上限を超えたら HTTPException を投げた。 1 回目(200) 2 回目(429) RateLimit "default";r=0;t=60 なし Retry-After なし 60 引数で受け取った Response に付けたヘッダーは、例外を投げると捨てられる 429 に載せたいヘッダーは、HTTPException(headers=...) に全部入れる FastAPI で API キーとレート制限 9 / 15
実験 7:uvicorn --workers 4 とメモリ上のカウンター 顧客ごとの token bucket(1 時間に 10 回まで)を dict に持ち、同じ顧客で 100 回リクエストし た。 送り方 keep-alive の 1 接続 毎回新しい接続 通った回数(試行 3 回) 10 / 10 / 10 24 / 21 / 24 dict はワーカーごとに別。上限は最大でワーカー数倍まで緩む 1 本の接続はずっと同じワーカーに届く。httpx.Client で試すと 10 回で止まるので、手元では気 づきにくい 何倍になるかは接続の振り分け次第で、毎回違った(macOS で計測) FastAPI で API キーとレート制限 10 / 15
ワーカーやインスタンスが複数あるとき 上限をワーカー数で割る:手軽。ただ振り分けが偏ると、上限の手前で 429 が出る顧客がいる Redis などの共有ストアで数える:正確。1 リクエストごとに往復が 1 回増える 秒単位のバースト制限は割り算、月の利用枠は共有ストアや DB、と分けることもできる FastAPI で API キーとレート制限 11 / 15
Depends に置くほうが楽なこともある
APIKeyHeader を Security で受けると、OpenAPI に載り、/docs に Authorize ボタンが出る
"securitySchemes": {"APIKeyHeader": {"type": "apiKey",
"in": "header", "name": "x-api-key"}}
middleware で検証した場合、securitySchemes は空のまま。OpenAPI には自分で書き足す
テストでは app.dependency_overrides で検証を差し替えられる。キーなしで 200 が返ること
を確認した
FastAPI で API キーとレート制限
12 / 15
どこに置くか 素の ASGI middleware Depends 404・/docs・リダイレクト 見える 見えない ボディを読む前に止める できる ボディ引数があるとできない 止めるときの書き方 応答を返す HTTPException でよい OpenAPI 自分で書く 自動で載る ルートごとに変える パスで分岐する 依存関係として書ける キーとレート制限は middleware、ルートごとの権限チェックは Depends、という分け方がしやす い。 FastAPI で API キーとレート制限 13 / 15
UsageRail の FastAPI SDK での作り 素の ASGI middleware。ルーティングと Depends より前に、キー、レート制限、利用枠を判定 する キーはプロセス内に同期した一覧と照合する。まだ同期されていない新しいキーだけ、初回に問い 合わせる その問い合わせを待つ間は、読んだボディが 64 KB 以上になったら、追加の読み込みを止める 独自の認証を使う場合、Depends の結果は使えない。認証の middleware を UsageRail より後 に add する レート制限は、既定ではインスタンスごとに数える app.add_middleware(UsageRailMiddleware, app_key=os.environ["USAGERAIL_APP_KEY"], auth="api-key") FastAPI で API キーとレート制限 14 / 15
まとめ ボディ引数のあるルートでは、Depends が走るのはボディを読んだあと。キーを弾く場所として は遅い middleware では例外を投げずに応答を返す。追加した順と逆の順で走る メモリ上のカウンターは、ワーカー数倍まで通ることがある。keep-alive のテストでは見えない https://usagerail.com/docs/fastapi Super Lede / UsageRail を作っている 3 人のうちの 1 人 FastAPI で API キーとレート制限 15 / 15