レート制限
レートリミッターは、一つのクライアントがどれだけ頻繁にリクエストできるかを制限します。たとえば、アドレスごとに 1 分 5 回のログイン、ユーザーごとに 1 分 120 回の呼び出しです。制限を超えたリクエストには、Retry-After 付きの 429 Too Many Requests が返ります。ルールを与えるか、spring.web.rate-limit.enabled: true にするまではオフです。
なぜ必要か
誰でも到達できるサーバーには、誰でも、好きなだけリクエストできます。制限がなければ、一つのクライアントが一日中パスワードを推測したり、サーバー全体を独り占めしたりできます。過負荷 はサーバー全体を守り、レートリミッターは一つのクライアントがそのうちどれだけを使えるかを決めます。
数は、リクエストが同時に届いても正しく、すべてのサーバーと関数のすべてのインスタンスで同じでなければなりません。そのためバケットは一回のアトミックな操作で変更され、置き場所は選べます。サーバーのメモリ、データベースのテーブル、Supabase プロジェクトのデータベース関数、Cloudflare Worker の D1 データベースです。
例
# lib/resources/application.yml
spring:
web:
rate-limit:
rules:
- path: /api/auth/** # ログイン: アドレスごと
methods: [POST]
key: ip
limit: 5/1m
- path: /api/** # API: ユーザーごと
limit: 120/1m
spring.web.rate-limit.rules[0].path=/api/auth/**
spring.web.rate-limit.rules[0].methods=POST
spring.web.rate-limit.rules[0].key=ip
spring.web.rate-limit.rules[0].limit=5/1m
spring.web.rate-limit.rules[1].path=/api/**
spring.web.rate-limit.rules[1].limit=120/1m
コントローラーの一つのメソッドやクラスには、次のように書きます。
@RestController()
class ReportController {
ReportController(this.reports);
final ReportService reports;
// ルールが何を許していても、ユーザーごとに 1 分 10 回のエクスポート。
@PostMapping('/reports/export')
@RateLimiter('10/1m', key: '#{authentication.name}')
Future<Report> export() => reports.export();
}
一つのアドレスからの 1 分以内の 6 回目のログインには、次が返ります。
HTTP/1.1 429 Too Many Requests
Retry-After: 12
RateLimit-Limit: 5
RateLimit-Remaining: 0
RateLimit-Reset: 12
Content-Type: application/problem+json
制限を超えたリクエストに返るもの
429 Too Many Requests。秒単位のRetry-Afterと、通常の ProblemDetail が付きます。- ボディは読まれません。 リクエストのそれ以外の部分も処理されません。
- 一致するすべてのルールが適用されます。 リクエストは、すべてのルールが許したときだけ通ります。
- ヘッダー
RateLimit-Limit、RateLimit-Remaining、RateLimit-Resetは、残りがもっとも少ないルールのものです。spring.web.rate-limit.headers: falseでオフにできます。 - ルールなしで
@RateLimiterだけを使う場合:spring.web.rate-limit.enabled: trueを設定します。コントローラーにアノテーションがあるのに、リミッターをオンにするものが何もないと、起動は失敗します。
制限
制限は <回数>/<期間> と書きます: 5/1m、10/s、1000/1h。期間には単位が必要です。100/60 は起動時に拒否されます。100/60s と書いてください。
これはトークンバケットです。回数 分のリクエストを一度に受け、その後は 期間 / 回数 ごとに一つずつ均等に補充されます。burst は、バケットの大きさをレートとは別に決めます。limit: 60/1m に burst: 10 を付けると、一度に 10 回、その後は 1 秒に 1 回です。
キー: バケットが誰のものか
key |
数える単位 | 判定される場所 |
|---|---|---|
user (デフォルト) |
認証されたユーザー。いなければクライアントのアドレス | セキュリティフィルターチェーンの直後 |
ip |
クライアントのアドレス | セッションとセキュリティフィルターチェーンの前 |
#{...} |
request、headers、principal、authentication、address、method、path に対する SpEL 式。何もない場合や空のテキストはアドレスで数える |
セキュリティフィルターチェーンの直後 |
| 独自の名前 | それを supports する RateLimitKeyResolver の Bean |
リゾルバーが決める |
ipをキーにしたルールは、セッションを探したりパスワードをハッシュしたりする前に、大量のリクエストを拒否します (フィルターrateLimitFilter、順序 -5000)。userをキーにしたルールは、セキュリティスターターが認証したユーザーを見ます (フィルターauthenticatedRateLimitFilter、順序 -50。-100 のセキュリティチェーンのすぐ後)。- セキュリティチェーン自身が応答したリクエスト (401、403) は、ユーザーをキーにしたルールに届きません。それらは
ipで制限してください。 @RateLimiterはインターセプターで実行されます。両方のフィルターの後、メソッドの引数がバインドされる前です。- 送られていないヘッダー:
#{request.headers['X-Api-Key']}は、そのヘッダーのないリクエストをアドレスで数えます。ヘッダー名は大文字と小文字を区別せずに見つかります。 - 式の間違い: パースできない式は、ルールの名前を示して起動を失敗させます。存在しないものを読む式は、リクエストが来て初めて分かります。そのルールはアドレスで数え、
spring.web.ratelimitの WARN が 1 行、ルールごとに一度だけ、そのことを伝えます。
クライアントのアドレス
アドレスは接続そのもののアドレスです。リバースプロキシの後ろでは、プロキシを指定します。
spring:
web:
rate-limit:
trusted-proxies: [173.245.48.0/20, 2400:cb00::/32] # アドレスと CIDR の範囲
client-address-header: X-Forwarded-For # デフォルト。または CF-Connecting-IP
- ヘッダーが読まれるのは、信頼されたプロキシからの接続だけです。 クライアントは、右から数えて最初の信頼されたプロキシが追加したエントリーです。その左にあるものはすべてクライアント自身が送ったもので、無視されます。
- 信頼されたプロキシがなければ、ヘッダーは決して読まれません。 そのため、クライアントはヘッダーを送って自分のバケットを選ぶことができません。
- IPv6 のクライアントはネットワークで数えます。 アドレスの最初の 64 ビットです。プロバイダーは一つのクライアントに /64 全体を与え、クライアントはリクエストごとにその中の別のアドレスを使えるからです。
spring.web.rate-limit.ipv6-prefix-lengthで長さを変えられます (より多くを割り当てるプロバイダーには56や48、すべてのアドレスを個別に数えるには128)。IPv4 のアドレスは全体で数えます。 - ストアにアドレスを平文で置かない:
hash-addresses: trueとhash-secretを設定します。アドレスのキーは、その HMAC-SHA-256 になります。
リバースプロキシの背後で を参照してください。
ストア: バケットの置き場所
ストアは一つのインターフェース RateLimitStore で、一つのアトミックな操作を持ちます。spring.web.rate-limit.store がなければ、アプリケーションが持つもののうち、もっとも具体的なものになります。
store |
バケットの場所 | デフォルトになる場合 | テーブル |
|---|---|---|---|
procedure |
Supabase プロジェクトのデータベース関数の後ろ。REST API を通じてサービスロールとして呼ばれる | アプリケーションが、データベース接続なしで spring_boot_starter_supabase を使う |
マイグレーションから: そのパッケージの sql/rate_limit.sql |
jdbc |
プライマリーの DataSource のテーブル (PostgreSQL、SQLite) |
アプリケーションにプライマリーの DataSource がある |
spring.data.jdbc.schema: create または spring.data.jdbc.rate-limit.create-table: true のときはストアが作る。それ以外はマイグレーションから (spring_boot_starter_data の sql/rate_limit/) |
d1 |
Cloudflare Worker の D1 データベース (spring_boot_starter_edge) |
spring.edge.cloudflare.rate-limit.database がバインディングを指定している |
ストアが作る |
primary-isolate |
最初の isolate のメモリ。プール全体で共有 | サーバーが isolate のプール を動かす | なし |
memory |
isolate のメモリ | それ以外 | なし |
procedure、jdbc、d1は、そのデータベース上のすべてのサーバーと関数のすべてのインスタンスで共有され、再起動後も残ります。memoryとprimary-isolateは、最大でspring.web.rate-limit.memory.max-entries個 (100 000) のキーを保持します。一つのサーバーの中だけで数え、再起動後は空から始まります。- 独自の Bean は、これらすべてに代わります。
@Component()
class KvRateLimitStore implements RateLimitStore {
@override
Future<RateLimitDecision> tryAcquire(String key, RateLimit limit,
{int permits = 1}) => ...; // 自分のストアでの一回のアトミックな操作
}
ストアに到達できないとき
リクエストは、Retry-After 付きの 503 で拒否されます (on-store-failure: deny、デフォルト)。データベースが落ちているときに、ログインの制限が開いてはならないからです。allow はリクエストを通し、数えません。どちらもルールごとに設定できます。spring.web.ratelimit の WARN が 1 行、ルールの名前を示します。キーは決して示しません。
ストアは起動時に確認されます
データベースにあるストアには、テーブルか関数が必要です。アプリケーションは起動時に一度、それがあるかをストアに尋ねます。
- ない場合 (実行されていないマイグレーション、宣言されていないバインディング、関数を呼べないサービスロール): アプリケーションは起動せず、エラーが実行すべきものを示します。この確認がなければ、忘れたマイグレーションは、制限のかかった最初のリクエストで
503として初めて現れます。 - その時点で到達できない場合 (データベースが落ちている、ネットワーク): WARN が 1 行出て、起動は続きます。その後はリクエストごとに
on-store-failureが決めます。 - 関数では (
spring_boot_starter_edge)、起動はインスタンスの最初のリクエストです。確認に失敗すると、そのリクエストには500が返り、次のリクエストで再び試みます。確認には、コールドスタートごとにストアへの呼び出しが 1 回かかります。 spring.web.rate-limit.verify-store: falseは、確認とその呼び出しを省略します。- 独自のストアは、
VerifiableRateLimitStoreを実装すれば確認に加わります。
プロパティ
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
spring.web.rate-limit.enabled |
bool |
未設定: rules にルールがあればオン |
リクエストを制限するかどうか。false はルールとアノテーションをオフにする |
spring.web.rate-limit.store |
memory / primary-isolate / jdbc / procedure / d1、または他のライブラリのストアの名前 |
アプリケーションが持つもののうち、もっとも具体的なもの | バケットの置き場所 |
spring.web.rate-limit.on-store-failure |
deny / allow |
deny |
ストアに到達できないときにリクエストに返るもの |
spring.web.rate-limit.store-failure-retry-after |
Duration |
5s |
その 503 の Retry-After |
spring.web.rate-limit.verify-store |
bool |
true |
起動時に、テーブル、関数、バインディングがあるかをストアに尋ねるかどうか |
spring.web.rate-limit.trusted-proxies |
アドレスと CIDR の範囲のリスト | 空 | ヘッダーを読むリバースプロキシ |
spring.web.rate-limit.client-address-header |
ヘッダー名 | X-Forwarded-For |
信頼されたプロキシがクライアントのアドレスを入れるヘッダー |
spring.web.rate-limit.ipv6-prefix-length |
int、1 から 128 |
64 |
IPv6 アドレスの何ビットがクライアントを表すか |
spring.web.rate-limit.hash-addresses |
bool |
false |
アドレスから作ったキーを、その HMAC-SHA-256 として保存する |
spring.web.rate-limit.hash-secret |
String |
なし | hash-addresses のシークレット。ストアを共有するすべてのサーバーで同じにする |
spring.web.rate-limit.headers |
bool |
true |
応答に RateLimit-* ヘッダーを付けるかどうか |
spring.web.rate-limit.memory.max-entries |
int |
100000 |
メモリ上のストアが保持するキーの最大数 |
spring.web.rate-limit.rules[n].name |
String |
rule-<n+1> |
ルールの名前: ストア内のキーの最初の部分であり、ログでの呼び名 |
spring.web.rate-limit.rules[n].path |
パスパターン | /** |
ルールが対象とするパス。コンテキストパスの内側 |
spring.web.rate-limit.rules[n].methods |
HTTP メソッドのリスト | 空: すべて | ルールが対象とするメソッド |
spring.web.rate-limit.rules[n].key |
user / ip / #{...} / RateLimitKeyResolver の名前 |
user |
バケットが誰のものか |
spring.web.rate-limit.rules[n].limit |
<回数>/<期間> |
必須 | 制限: 5/1m、120/1m、10/s |
spring.web.rate-limit.rules[n].burst |
int |
limit の回数 |
一度に受けるリクエストの最大数 |
spring.web.rate-limit.rules[n].on-store-failure |
deny / allow |
spring.web.rate-limit.on-store-failure |
このルールについての同じ設定 |
データベースにあるストアには、それぞれのキーがあります。spring.data.jdbc.rate-limit.table と .create-table (spring_boot_starter_data)、spring.supabase.rate-limit.function (spring_boot_starter_supabase)、spring.edge.cloudflare.rate-limit.database と .table (spring_boot_starter_edge) です。
Spring (Java) との対応
Spring のコアにレートリミッターはありません。もっとも近いのは、Resilience4j の @RateLimiter (メソッドのすべての呼び出し元に一つの制限)、Bucket4j、そして Spring Cloud Gateway の RequestRateLimiter (KeyResolver と Redis のストア) で、このリミッターはその形に従っています。キーのリゾルバー、トークンバケット、データのそばで計算を行うストアです。spring.web.rate-limit.* はすべてこのスターター独自のもので、起動時のストアの確認も同様です。