レート制限

レートリミッターは、一つのクライアントがどれだけ頻繁にリクエストできるかを制限します。たとえば、アドレスごとに 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

制限を超えたリクエストに返るもの

制限

制限は <回数>/<期間> と書きます: 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 リゾルバーが決める

クライアントのアドレス

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

spring:
  web:
    rate-limit:
      trusted-proxies: [173.245.48.0/20, 2400:cb00::/32]   # アドレスと CIDR の範囲
      client-address-header: X-Forwarded-For               # デフォルト。または CF-Connecting-IP

リバースプロキシの背後で を参照してください。

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

ストアは一つのインターフェース 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 のメモリ それ以外 なし
@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 行、ルールの名前を示します。キーは決して示しません。

ストアは起動時に確認されます

データベースにあるストアには、テーブルか関数が必要です。アプリケーションは起動時に一度、それがあるかをストアに尋ねます。

プロパティ

キー 型 デフォルト 意味
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.* はすべてこのスターター独自のもので、起動時のストアの確認も同様です。

関連項目