Skip to content
Server Plugin

속도 제한 (Rate limiting)

필수 의존성: io.ktor:ktor-server-rate-limit

코드 예제: rate-limit

네이티브 서버(Native server)Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✅

RateLimit 플러그인을 사용하면 지정된 시간 동안 클라이언트가 보낼 수 있는 요청 수를 제한할 수 있습니다.

Ktor는 속도 제한(rate limiting)을 구성하는 여러 가지 방법을 제공합니다:

의존성 추가 ​

RateLimit을(를) 사용하려면 ktor-server-rate-limit 아티팩트를 빌드 스크립트에 추가하세요:

kotlin
implementation(ktorLibs.server.rateLimit)
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그(version catalog)를 사용합니다.
groovy
implementation ktorLibs.server.rateLimit
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그(version catalog)를 사용합니다.
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. 사용 가능한 토큰 수를 정의하는 지정된 용량(capacity)으로 버킷이 생성됩니다.
  2. 들어오는 각 요청은 버킷에서 하나의 토큰을 소비합니다:
    • 잔여 용량이 충분하면 서버는 요청을 처리하고 응답에 다음 헤더를 포함합니다:
      • X-RateLimit-Limit: 버킷 용량.
      • X-RateLimit-Remaining: 버킷에 남아 있는 토큰 수.
      • X-RateLimit-Reset: 버킷이 다시 채워지는 시점을 초 단위로 나타낸 UTC 타임스탬프.
    • 용량이 부족하면 서버는 429 Too Many Requests 응답으로 요청을 거절합니다. 응답에는 클라이언트가 다음 요청을 보내기 전까지 몇 초 동안 대기해야 하는지를 나타내는 Retry-After 헤더가 포함됩니다.
  3. 지정된 리필 기간(refill period)이 지나면 버킷이 다시 채워집니다.

속도 제한기 등록 ​

속도 제한을 애플리케이션 전체에 전역으로 적용하거나 특정 라우트에 대한 속도 제한기를 등록할 수 있습니다:

  • 속도 제한을 전역으로 적용하려면 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는 버킷이 얼마나 자주 다시 채워지는지를 지정합니다.

다음 예제는 분당 최대 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 키 인증과 결합하여 원시 헤더 값 대신 인증된 주체(principal)를 요청 키로 사용할 수도 있습니다.

액세스 토큰 또는 Bearer 토큰 ​

각 Bearer 토큰에 별도의 속도 제한을 적용하려면 Authorization 헤더의 원시 토큰을 요청 키로 반환하세요:

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

요청이 인증된 경우, 인증된 각 식별자에 별도의 속도 제한을 적용할 수 있도록 인증 주체를 요청 키로 사용하는 것이 좋습니다.

인증된 사용자에 대한 속도 제한 ​

인증 주체(authentication principal)를 요청 키로 사용하여 인증된 사용자별로 속도 제한을 적용할 수 있습니다.

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() 함수를 사용하여 각 요청이 소비하는 토큰 수를 지정합니다. 이 함수는 애플리케이션 호출(application call)과 요청 키를 전달받습니다.

다음 예제에서 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을 참고하세요.