レート制限
必要な依存関係: io.ktor:ktor-server-rate-limit
コード例: rate-limit
ネイティブサーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅
RateLimit プラグインを使用すると、指定された期間内にクライアントが行えるリクエストの数を制限できます。
Ktorはレート制限を設定するためのいくつかの方法を提供しています。
- アプリケーション全体にグローバルにレート制限を適用するか、特定のリソースに対して個別の制限を設定する。
- IPアドレス、APIキー、またはアクセストークンなどのリクエストキーに基づいてレート制限を適用する。
依存関係の追加
RateLimit を使用するには、ビルドスクリプトに ktor-server-rate-limit アーティファクトを追加します。
implementation(ktorLibs.server.rateLimit)implementation ktorLibs.server.rateLimit<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-rate-limit-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>RateLimit のインストール
アプリケーションに RateLimit プラグインをインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、RateLimit をインストールする方法を示しています。
embeddedServer()関数の呼び出し内。Applicationクラスに明示的に定義されたmodule()拡張関数内。
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)
}import io.ktor.server.application.*
import io.ktor.server.plugins.ratelimit.*
// ...
fun Application.module() {
install(RateLimit)
// ...
}RateLimit の設定
概要
Ktorはレート制限にトークンバケット(token bucket)アルゴリズムを使用しており、次のように動作します。
- 指定された容量でバケットが作成され、利用可能なトークン数が定義されます。
- 送信されてくる各リクエストは、バケットから1つのトークンを消費します。
- 十分な容量がある場合、サーバーはリクエストを処理し、レスポンスに以下のヘッダーを含めます。
X-RateLimit-Limit: バケットの容量。X-RateLimit-Remaining: バケット内の残りのトークン数。X-RateLimit-Reset: バケットが補充される時期を指定する秒単位のUTCタイムスタンプ。
- 容量が不足している場合、サーバーは
429 Too Many Requestsレスポンスでリクエストを拒否します。レスポンスには、クライアントが次のリクエストを送信するまでに待機すべき秒数を示すRetry-Afterヘッダーが含まれます。
- 十分な容量がある場合、サーバーはリクエストを処理し、レスポンスに以下のヘッダーを含めます。
- 指定された補充期間の後、バケットは補充されます。
レートリミッターの登録
レート制限をアプリケーション全体にグローバルに適用することも、特定のルートに対してレートリミッターを登録することもできます。
グローバルにレート制限を適用するには、
global()関数を呼び出してレートリミッターを設定します。kotlininstall(RateLimit) { global { rateLimiter(limit = 5, refillPeriod = 60.seconds) } }特定のルートに対してレート制限を設定するには、
register()関数を使用してレートリミッターを登録します。kotlininstall(RateLimit) { register { rateLimiter(limit = 5, refillPeriod = 60.seconds) } }
上記の例は、RateLimit プラグインに必要な最小限の設定を示しています。 register() を使用する場合は、登録したレートリミッターを特定のルートに適用する必要もあります。
レート制限の設定
以下のオプションを使用してレートリミッターを設定できます。
レートリミッターへの名前付け
register() 関数を使用してレートリミッターに名前を割り当てます。その後、名前付きレートリミッターを特定のルートに適用できます。
install(RateLimit) {
register(RateLimitName("protected")) {
// ...
}
}制限数と補充期間の設定
rateLimiter() 関数を使用して、バケットの容量と補充期間を設定します。
limitは利用可能なトークン数を指定します。refillPeriodはバケットが補充される頻度を指定します。
以下の例では、1分間に最大30件のリクエストを許可します。
register(RateLimitName("protected")) {
rateLimiter(limit = 30, refillPeriod = 60.seconds)
}キーによるリクエストの識別
requestKey() 関数を使用して、各リクエストのキーを返します。異なるキーを持つリクエストは、それぞれ独立したレート制限を持ちます。デフォルトでは、すべてのリクエストが同じバケットを共有します。
リクエストキーには、適切な equals および hashCode の実装があることを確認してください。
クエリパラメーター
以下の例では、ユーザーを識別するために login クエリパラメーターを使用しています。
register(RateLimitName("protected")) {
requestKey { applicationCall ->
applicationCall.request.queryParameters["login"]!!
}
}クライアントIPアドレス
クライアントのIPアドレスごとに個別のレート制限を適用するには、call.request.origin.remoteHost をリクエストキーとして使用します。
register(RateLimitName("per-ip")) {
rateLimiter(limit = 5, refillPeriod = 60.seconds)
requestKey { call ->
call.request.origin.remoteHost
}
}アプリケーションがプロキシやロードバランサーの背後で動作している場合は、origin.remoteHost がプロキシではなく元のクライアントアドレスを表すように Forwarded headers プラグインを設定してください。
APIキーヘッダー
ヘッダーで送信されたAPIキーによってリクエストをレート制限するには、requestKey() からそのヘッダー値を返します。
register(RateLimitName("per-api-key")) {
rateLimiter(limit = 5, refillPeriod = 60.seconds)
requestKey { call ->
call.request.headers["X-Api-Key"] ?: "anonymous"
}
}このアプローチを APIキー認証と組み合わせて、生のヘッダー値の代わりに認証されたプリンシパルをリクエストキーとして使用することもできます。
アクセストークンまたはBearerトークン
各Bearerトークンに個別のレート制限を適用するには、Authorization ヘッダーから生のトークンを取り出してリクエストキーとして返します。
requestKey { call ->
call.request.authorization()?.removePrefix("Bearer ") ?: "anonymous"
}リクエストが認証されている場合は、認証されたアイデンティティごとに個別のレート制限を適用するために、リクエストキーとして認証プリンシパルを使用することをお勧めします。
認証済みユーザーのレート制限
認証プリンシパルをリクエストキーとして使用し、認証済みユーザーごとにレート制限を適用できます。
authenticate() の内部に rateLimit() をネストし、requestKey() からプリンシパルにアクセスします。
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つのトークンを消費します。
register(RateLimitName("protected")) {
requestKey { applicationCall ->
applicationCall.request.queryParameters["login"]!!
}
requestWeight { applicationCall, key ->
when (key) {
"jetbrains" -> 1
else -> 2
}
}
}レスポンスのカスタマイズ
レート制限が適用されたときのレスポンスをカスタマイズするには、modifyResponse() 関数を使用します。
たとえば、カスタムのレート制限ヘッダーを追加できます。
register(RateLimitName("protected")) {
modifyResponse { applicationCall, state ->
applicationCall.response.header("X-RateLimit-Custom-Header", "Some value")
}
}レート制限スコープの定義
レートリミッターを設定した後、rateLimit() 関数を使用して特定のルートに適用できます。
デフォルトのレートリミッターの適用
デフォルトで登録されたレートリミッターを適用するには、名前を指定せずに rateLimit() 関数を使用します。
routing {
rateLimit {
get("/") {
val requestsLeft = call.response.headers["X-RateLimit-Remaining"]
call.respondText("Welcome to the home page! $requestsLeft requests left.")
}
}
}名前付きレートリミッターの適用
名前付きレートリミッターを適用するには、rateLimit() 関数に RateLimitName を渡します。
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プラグイン。
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 を参照してください。
