속도 제한 (Rate limiting)
필수 의존성: io.ktor:ktor-server-rate-limit
코드 예제: rate-limit
네이티브 서버(Native server)Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✅
RateLimit 플러그인을 사용하면 지정된 시간 동안 클라이언트가 보낼 수 있는 요청 수를 제한할 수 있습니다.
Ktor는 속도 제한(rate limiting)을 구성하는 여러 가지 방법을 제공합니다:
- 애플리케이션 전체에 전역으로 속도 제한을 적용하거나 특정 리소스에 서로 다른 제한을 구성합니다.
- IP 주소, API 키, 액세스 토큰과 같은 요청 키(request key)를 기반으로 속도 제한을 적용합니다.
의존성 추가
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) 알고리즘을 사용하며, 다음과 같이 동작합니다:
- 사용 가능한 토큰 수를 정의하는 지정된 용량(capacity)으로 버킷이 생성됩니다.
- 들어오는 각 요청은 버킷에서 하나의 토큰을 소비합니다:
- 잔여 용량이 충분하면 서버는 요청을 처리하고 응답에 다음 헤더를 포함합니다:
X-RateLimit-Limit: 버킷 용량.X-RateLimit-Remaining: 버킷에 남아 있는 토큰 수.X-RateLimit-Reset: 버킷이 다시 채워지는 시점을 초 단위로 나타낸 UTC 타임스탬프.
- 용량이 부족하면 서버는
429 Too Many Requests응답으로 요청을 거절합니다. 응답에는 클라이언트가 다음 요청을 보내기 전까지 몇 초 동안 대기해야 하는지를 나타내는Retry-After헤더가 포함됩니다.
- 잔여 용량이 충분하면 서버는 요청을 처리하고 응답에 다음 헤더를 포함합니다:
- 지정된 리필 기간(refill period)이 지나면 버킷이 다시 채워집니다.
속도 제한기 등록
속도 제한을 애플리케이션 전체에 전역으로 적용하거나 특정 라우트에 대한 속도 제한기를 등록할 수 있습니다:
속도 제한을 전역으로 적용하려면
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는 버킷이 얼마나 자주 다시 채워지는지를 지정합니다.
다음 예제는 분당 최대 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 키 인증과 결합하여 원시 헤더 값 대신 인증된 주체(principal)를 요청 키로 사용할 수도 있습니다.
액세스 토큰 또는 Bearer 토큰
각 Bearer 토큰에 별도의 속도 제한을 적용하려면 Authorization 헤더의 원시 토큰을 요청 키로 반환하세요:
requestKey { call ->
call.request.authorization()?.removePrefix("Bearer ") ?: "anonymous"
}요청이 인증된 경우, 인증된 각 식별자에 별도의 속도 제한을 적용할 수 있도록 인증 주체를 요청 키로 사용하는 것이 좋습니다.
인증된 사용자에 대한 속도 제한
인증 주체(authentication principal)를 요청 키로 사용하여 인증된 사용자별로 속도 제한을 적용할 수 있습니다.
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() 함수를 사용하여 각 요청이 소비하는 토큰 수를 지정합니다. 이 함수는 애플리케이션 호출(application call)과 요청 키를 전달받습니다.
다음 예제에서 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을 참고하세요.
