Skip to content
Server Plugin

レート制限

必要な依存関係: io.ktor:ktor-server-rate-limit

コード例: rate-limit

ネイティブサーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅

RateLimit プラグインを使用すると、指定された期間内にクライアントが行えるリクエストの数を制限できます。

Ktorはレート制限を設定するためのいくつかの方法を提供しています。

依存関係の追加 ​

RateLimit を使用するには、ビルドスクリプトに ktor-server-rate-limit アーティファクトを追加します。

kotlin
implementation(ktorLibs.server.rateLimit)
上記のコードスニペットでは、Ktorの依存関係を指定するためにKtorバージョンカタログを使用しています。
groovy
implementation ktorLibs.server.rateLimit
上記のコードスニペットでは、Ktorの依存関係を指定するためにKtorバージョンカタログを使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-rate-limit-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

RateLimit のインストール ​

アプリケーションに RateLimit プラグインをインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、RateLimit をインストールする方法を示しています。

  • embeddedServer() 関数の呼び出し内。
  • Application クラスに明示的に定義された module() 拡張関数内。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.plugins.ratelimit.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(RateLimit)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.plugins.ratelimit.*
// ...
fun Application.module() {
    install(RateLimit)
    // ...
}

RateLimit の設定 ​

概要 ​

Ktorはレート制限にトークンバケット(token bucket)アルゴリズムを使用しており、次のように動作します。

  1. 指定された容量でバケットが作成され、利用可能なトークン数が定義されます。
  2. 送信されてくる各リクエストは、バケットから1つのトークンを消費します。
    • 十分な容量がある場合、サーバーはリクエストを処理し、レスポンスに以下のヘッダーを含めます。
      • X-RateLimit-Limit: バケットの容量。
      • X-RateLimit-Remaining: バケット内の残りのトークン数。
      • X-RateLimit-Reset: バケットが補充される時期を指定する秒単位のUTCタイムスタンプ。
    • 容量が不足している場合、サーバーは 429 Too Many Requests レスポンスでリクエストを拒否します。レスポンスには、クライアントが次のリクエストを送信するまでに待機すべき秒数を示す Retry-After ヘッダーが含まれます。
  3. 指定された補充期間の後、バケットは補充されます。

レートリミッターの登録 ​

レート制限をアプリケーション全体にグローバルに適用することも、特定のルートに対してレートリミッターを登録することもできます。

  • グローバルにレート制限を適用するには、global() 関数を呼び出してレートリミッターを設定します。

    kotlin
    install(RateLimit) {
        global {
            rateLimiter(limit = 5, refillPeriod = 60.seconds)
        }
    }
  • 特定のルートに対してレート制限を設定するには、register() 関数を使用してレートリミッターを登録します。

    kotlin
    install(RateLimit) {
        register {
            rateLimiter(limit = 5, refillPeriod = 60.seconds)
        }
    }

上記の例は、RateLimit プラグインに必要な最小限の設定を示しています。 register() を使用する場合は、登録したレートリミッターを特定のルートに適用する必要もあります。

レート制限の設定 ​

以下のオプションを使用してレートリミッターを設定できます。

レートリミッターへの名前付け ​

register() 関数を使用してレートリミッターに名前を割り当てます。その後、名前付きレートリミッターを特定のルートに適用できます。

kotlin
    install(RateLimit) {
        register(RateLimitName("protected")) {
            // ...
        }
    }

制限数と補充期間の設定 ​

rateLimiter() 関数を使用して、バケットの容量と補充期間を設定します。

  • limit は利用可能なトークン数を指定します。
  • refillPeriod はバケットが補充される頻度を指定します。

以下の例では、1分間に最大30件のリクエストを許可します。

kotlin
register(RateLimitName("protected")) {
    rateLimiter(limit = 30, refillPeriod = 60.seconds)
}

キーによるリクエストの識別 ​

requestKey() 関数を使用して、各リクエストのキーを返します。異なるキーを持つリクエストは、それぞれ独立したレート制限を持ちます。デフォルトでは、すべてのリクエストが同じバケットを共有します。

リクエストキーには、適切な equals および hashCode の実装があることを確認してください。

クエリパラメーター ​

以下の例では、ユーザーを識別するために login クエリパラメーターを使用しています。

kotlin
register(RateLimitName("protected")) {
    requestKey { applicationCall ->
        applicationCall.request.queryParameters["login"]!!
    }
}
クライアントIPアドレス ​

クライアントのIPアドレスごとに個別のレート制限を適用するには、call.request.origin.remoteHost をリクエストキーとして使用します。

kotlin
register(RateLimitName("per-ip")) {
    rateLimiter(limit = 5, refillPeriod = 60.seconds)
    requestKey { call ->
        call.request.origin.remoteHost
    }
}

アプリケーションがプロキシやロードバランサーの背後で動作している場合は、origin.remoteHost がプロキシではなく元のクライアントアドレスを表すように Forwarded headers プラグインを設定してください。

APIキーヘッダー ​

ヘッダーで送信されたAPIキーによってリクエストをレート制限するには、requestKey() からそのヘッダー値を返します。

kotlin
register(RateLimitName("per-api-key")) {
    rateLimiter(limit = 5, refillPeriod = 60.seconds)
    requestKey { call ->
        call.request.headers["X-Api-Key"] ?: "anonymous"
    }
}

このアプローチを APIキー認証と組み合わせて、生のヘッダー値の代わりに認証されたプリンシパルをリクエストキーとして使用することもできます。

アクセストークンまたはBearerトークン ​

各Bearerトークンに個別のレート制限を適用するには、Authorization ヘッダーから生のトークンを取り出してリクエストキーとして返します。

kotlin
requestKey { call ->
    call.request.authorization()?.removePrefix("Bearer ") ?: "anonymous"
}

リクエストが認証されている場合は、認証されたアイデンティティごとに個別のレート制限を適用するために、リクエストキーとして認証プリンシパルを使用することをお勧めします。

認証済みユーザーのレート制限 ​

認証プリンシパルをリクエストキーとして使用し、認証済みユーザーごとにレート制限を適用できます。

authenticate() の内部に rateLimit() をネストし、requestKey() からプリンシパルにアクセスします。

kotlin
install(Authentication) {
    basic("auth") { validate { UserIdPrincipal(it.name) } }
}
install(RateLimit) {
    register(RateLimitName("per-user")) {
        rateLimiter(limit = 10, refillPeriod = 60.seconds)
        requestKey { call.principal<UserIdPrincipal>()?.name ?: "anonymous" }
    }
}

routing {
    authenticate("auth") {
        rateLimit(RateLimitName("per-user")) {
            get("/api") { call.respondText("OK") }
        }
    }
}

リクエストの重みの設定 ​

requestWeight() 関数を使用して、各リクエストが消費するトークン数を指定します。この関数は、アプリケーションコールとリクエストキーを受け取ります。

以下の例では、jetbrains キーを持つリクエストは1つのトークンを消費し、その他のすべてのリクエストは2つのトークンを消費します。

kotlin
register(RateLimitName("protected")) {
    requestKey { applicationCall ->
        applicationCall.request.queryParameters["login"]!!
    }
    requestWeight { applicationCall, key ->
        when (key) {
            "jetbrains" -> 1
            else -> 2
        }
    }
}

レスポンスのカスタマイズ ​

レート制限が適用されたときのレスポンスをカスタマイズするには、modifyResponse() 関数を使用します。

たとえば、カスタムのレート制限ヘッダーを追加できます。

kotlin
register(RateLimitName("protected")) {
    modifyResponse { applicationCall, state ->
        applicationCall.response.header("X-RateLimit-Custom-Header", "Some value")
    }
}

レート制限スコープの定義 ​

レートリミッターを設定した後、rateLimit() 関数を使用して特定のルートに適用できます。

デフォルトのレートリミッターの適用 ​

デフォルトで登録されたレートリミッターを適用するには、名前を指定せずに rateLimit() 関数を使用します。

kotlin
routing {
    rateLimit {
        get("/") {
            val requestsLeft = call.response.headers["X-RateLimit-Remaining"]
            call.respondText("Welcome to the home page! $requestsLeft requests left.")
        }
    }
}

名前付きレートリミッターの適用 ​

名前付きレートリミッターを適用するには、rateLimit() 関数に RateLimitName を渡します。

kotlin
routing {
    rateLimit(RateLimitName("protected")) {
        get("/protected-api") {
            val requestsLeft = call.response.headers["X-RateLimit-Remaining"]
            val login = call.request.queryParameters["login"]
            call.respondText("Welcome to protected API, $login! $requestsLeft requests left.")
        }
    }
}

例 ​

以下の例は、異なるルートに異なるレートリミッターを適用する方法を示しています。 ここでは以下を設定しています。

  • ホームページ用のデフォルトのレートリミッター。
  • パブリックAPI用の「public」という名前のレートリミッター。
  • リクエストキーと重みを使用する「protected」という名前のレートリミッター。
  • クライアントIPおよび X-Api-Key ヘッダーによってキー設定された名前付きレートリミッター。
  • 429 Too Many Requests レスポンスで拒否されたリクエストのレスポンスをカスタマイズするための StatusPages プラグイン。
kotlin
package com.example

import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.plugins.*
import io.ktor.server.plugins.ratelimit.*
import io.ktor.server.plugins.statuspages.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import kotlin.time.Duration.Companion.seconds

fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args)

fun Application.module() {
    install(RateLimit) {
        register {
            rateLimiter(limit = 5, refillPeriod = 60.seconds)
        }
        register(RateLimitName("public")) {
            rateLimiter(limit = 10, refillPeriod = 60.seconds)
        }
        register(RateLimitName("protected")) {
            rateLimiter(limit = 30, refillPeriod = 60.seconds)
            requestKey { applicationCall ->
                applicationCall.request.queryParameters["login"]!!
            }
            requestWeight { applicationCall, key ->
                when (key) {
                    "jetbrains" -> 1
                    else -> 2
                }
            }
        }
        register(RateLimitName("per-ip")) {
            rateLimiter(limit = 5, refillPeriod = 60.seconds)
            requestKey { call ->
                call.request.origin.remoteHost
            }
        }
        register(RateLimitName("per-api-key")) {
            rateLimiter(limit = 5, refillPeriod = 60.seconds)
            requestKey { call ->
                call.request.headers["X-Api-Key"] ?: "anonymous"
            }
        }
    }
    install(StatusPages) {
        status(HttpStatusCode.TooManyRequests) { call, status ->
            val retryAfter = call.response.headers["Retry-After"]
            call.respondText(text = "429: Too many requests. Wait for $retryAfter seconds.", status = status)
        }
    }
    routing {
        rateLimit {
            get("/") {
                val requestsLeft = call.response.headers["X-RateLimit-Remaining"]
                call.respondText("Welcome to the home page! $requestsLeft requests left.")
            }
        }
        rateLimit(RateLimitName("public")) {
            get("/public-api") {
                val requestsLeft = call.response.headers["X-RateLimit-Remaining"]
                call.respondText("Welcome to public API! $requestsLeft requests left.")
            }
        }
        rateLimit(RateLimitName("protected")) {
            get("/protected-api") {
                val requestsLeft = call.response.headers["X-RateLimit-Remaining"]
                val login = call.request.queryParameters["login"]
                call.respondText("Welcome to protected API, $login! $requestsLeft requests left.")
            }
        }
        rateLimit(RateLimitName("per-ip")) {
            get("/ip-api") {
                val requestsLeft = call.response.headers["X-RateLimit-Remaining"]
                val clientHost = call.request.origin.remoteHost
                call.respondText("Welcome to IP API, $clientHost! $requestsLeft requests left.")
            }
        }
        rateLimit(RateLimitName("per-api-key")) {
            get("/keyed-api") {
                val requestsLeft = call.response.headers["X-RateLimit-Remaining"]
                val apiKey = call.request.headers["X-Api-Key"] ?: "anonymous"
                call.respondText("Welcome to keyed API, $apiKey! $requestsLeft requests left.")
            }
        }
    }
}

完全な例については、rate-limit を参照してください。