
# レート制限

レートリミッターは、一つのクライアントがどれだけ頻繁にリクエストできるかを制限します。たとえば、アドレスごとに 1 分 5 回のログイン、ユーザーごとに 1 分 120 回の呼び出しです。制限を超えたリクエストには、`Retry-After` 付きの `429 Too Many Requests` が返ります。ルールを与えるか、`spring.web.rate-limit.enabled: true` にするまではオフです。

## なぜ必要か

誰でも到達できるサーバーには、誰でも、好きなだけリクエストできます。制限がなければ、一つのクライアントが一日中パスワードを推測したり、サーバー全体を独り占めしたりできます。[過負荷](server/overload.md) はサーバー全体を守り、レートリミッターは一つのクライアントがそのうちどれだけを使えるかを決めます。

数は、リクエストが同時に届いても正しく、すべてのサーバーと関数のすべてのインスタンスで同じでなければなりません。そのためバケットは一回のアトミックな操作で変更され、置き場所は選べます。サーバーのメモリ、データベースのテーブル、Supabase プロジェクトのデータベース関数、Cloudflare Worker の D1 データベースです。

## 例

```yaml
# 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
```

```properties
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
```

コントローラーの一つのメソッドやクラスには、次のように書きます。

```dart
@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 回目のログインには、次が返ります。

```text
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](errors/problem-detail.md) が付きます。
- **ボディは読まれません。** リクエストのそれ以外の部分も処理されません。
- **一致するすべてのルールが適用されます。** リクエストは、すべてのルールが許したときだけ通ります。
- **ヘッダー** `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 行、ルールごとに一度だけ、そのことを伝えます。

## クライアントのアドレス

アドレスは接続そのもののアドレスです。リバースプロキシの後ろでは、プロキシを指定します。

```yaml
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 になります。

[リバースプロキシの背後で](server/reverse-proxy.md) を参照してください。

## ストア: バケットの置き場所

ストアは一つのインターフェース `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 のプール](server/isolates.md) を動かす | なし |
| `memory` | isolate のメモリ | それ以外 | なし |

- **`procedure`、`jdbc`、`d1`** は、そのデータベース上のすべてのサーバーと関数のすべてのインスタンスで共有され、再起動後も残ります。
- **`memory` と `primary-isolate`** は、最大で `spring.web.rate-limit.memory.max-entries` 個 (100 000) のキーを保持します。一つのサーバーの中だけで数え、再起動後は空から始まります。
- **独自の Bean は、これらすべてに代わります。**

```dart
@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.*` はすべてこのスターター独自のもので、起動時のストアの確認も同様です。

## 関連項目

- [過負荷](server/overload.md)
- [リバースプロキシの背後で](server/reverse-proxy.md)
- [isolate のプール](server/isolates.md)
- [フィルター](filters.md)
- [ProblemDetail](errors/problem-detail.md)
- [すべてのプロパティ](properties.md)
- [spring_boot_starter_edge](../spring-boot-starter-edge/index.md)
- [spring_boot_starter_supabase](../spring-boot-starter-supabase/index.md)
