커스텀 서버 플러그인
코드 예제: custom-plugin
Ktor를 사용하면 커스텀 플러그인을 직접 생성할 수 있습니다. 일반적으로 이 API는 파이프라인이나 단계(phase)와 같은 Ktor 내부 개념에 대한 이해를 필요로 하지 않습니다. 대신 onCall(), onCallReceive(), onCallRespond()와 같은 핸들러를 사용하여 요청 및 응답 처리의 다양한 단계에 접근할 수 있습니다.
첫 번째 플러그인 생성 및 설치
이 섹션에서는 첫 번째 플러그인을 생성하고 설치하는 방법을 알아봅니다.
새 Ktor 프로젝트 생성, 열기 및 실행 튜토리얼에서 생성한 애플리케이션을 시작 프로젝트로 사용할 수 있습니다.
플러그인을 생성하려면
createApplicationPlugin()함수를 호출하고 플러그인 이름을 지정합니다.kotlinimport io.ktor.server.application.* val SimplePlugin = createApplicationPlugin(name = "SimplePlugin") { println("SimplePlugin is installed!") }이 함수는 애플리케이션에 설치할 수 있는
ApplicationPlugin인스턴스를 반환합니다.createRouteScopedPlugin()함수를 사용하여 특정 라우트에 설치할 수 있는 플러그인을 생성할 수도 있습니다.플러그인을 설치하려면 애플리케이션 초기화 코드에서 생성된
ApplicationPlugin인스턴스를Application.install()함수에 전달합니다.kotlinfun Application.module() { install(SimplePlugin) }애플리케이션을 실행하여 콘솔 출력에서 플러그인 메시지를 확인합니다.
Bash2021-10-14 14:54:08.269 [main] INFO Application - Autoreload is disabled because the development mode is off. SimplePlugin is installed! 2021-10-14 14:54:08.900 [main] INFO Application - Responding at http://0.0.0.0:8080
전체 예제는 SimplePlugin.kt를 참조하세요.
호출(Call) 처리
커스텀 플러그인에서는 호출의 다양한 단계에 대한 접근을 제공하는 일련의 핸들러를 사용하여 요청 및 응답을 처리할 수 있습니다.
onCall(): 요청 및 응답 정보에 접근하고 헤더와 같은 응답 파라미터를 수정할 수 있습니다.onCallValidators(): 호출 유효성 검사를 수행할 수 있습니다. 라우트 스코프 플러그인의 경우, 유효성 검사기는 라우트 중첩 구조에 따라 실행됩니다.onCallReceive(): 클라이언트로부터 수신한 데이터를 변환할 수 있습니다.onCallRespond(): 클라이언트로 전송하기 전에 데이터를 변환할 수 있습니다.on(): 호출 처리의 다른 단계나 호출 중 발생하는 예외에 대한 특정 훅(hook)을 처리할 수 있습니다.
또한 call.attributes를 사용하여 핸들러 간에 호출 상태를 공유할 수도 있습니다.
onCall()
onCall() 핸들러는 람다 인자로 ApplicationCall을 받습니다. 이를 통해 요청 및 응답 정보에 접근하고, 커스텀 헤더 추가와 같이 응답 파라미터를 수정할 수 있습니다.
요청 또는 응답 본문을 변환하려면 onCallReceive() 및 onCallRespond()를 사용하세요.
예제 1: 요청 로깅
다음 예제는 onCall()을 사용하여 수신 요청 URL을 로깅하는 플러그인을 만듭니다.
val RequestLoggingPlugin = createApplicationPlugin(name = "RequestLoggingPlugin") {
onCall { call ->
call.request.origin.apply {
println("Request URL: $scheme://$localHost:$localPort$uri")
}
}
}이 플러그인을 설치하면 요청된 URL이 콘솔에 출력됩니다.
Request URL: http://0.0.0.0:8080/
Request URL: http://0.0.0.0:8080/index예제 2: 커스텀 헤더 추가
다음 예제는 각 응답에 커스텀 헤더를 추가하는 플러그인을 생성합니다.
val CustomHeaderPlugin = createApplicationPlugin(name = "CustomHeaderPlugin") {
onCall { call ->
call.response.headers.append("X-Custom-Header", "Hello, world!")
}
}결과 응답에는 커스텀 헤더가 포함됩니다.
HTTP/1.1 200 OK
X-Custom-Header: Hello, world!이 예제에서는 헤더 이름과 값이 하드코딩되어 있습니다. 이를 설정 가능하도록 만들려면 플러그인 설정을 제공하세요.
onCallReceive()
onCallReceive() 핸들러를 사용하면 클라이언트로부터 수신한 데이터를 변환할 수 있습니다. 핸들러 내부에서 transformBody()를 호출하여 요청 본문이 call.receive()로 전달되기 전에 변환합니다.
클라이언트가 text/plain 본문으로 10을 포함하는 다음과 같은 POST 요청을 보낸다고 가정해 보겠습니다.
POST http://localhost:8080/transform-data
Content-Type: text/plain
10이 본문을 정수 값으로 수신하려면 POST 요청에 대한 라우트 핸들러를 생성하고 Int 파라미터와 함께 call.receive()를 호출해야 합니다.
post("/transform-data") {
val data = call.receive<Int>()
}다음 플러그인은 본문을 정수 값으로 수신하고 여기에 1을 더합니다.
val DataTransformationPlugin = createApplicationPlugin(name = "DataTransformationPlugin") {
onCallReceive { call ->
transformBody { data ->
if (requestedType?.type == Int::class) {
val line = data.readLine() ?: "1"
line.toInt() + 1
} else {
data
}
}
}
}위 예제에서:
TransformBodyContext는 람다 수신 객체(lambda receiver)입니다. 이 객체의requestedType프로퍼티는call.receive()에서 요청한 타입에 대한 정보를 담고 있습니다.data인자는 현재 요청 본문을 포함합니다. 이 경우ByteReadChannel이며,ByteReadChannel.readLine()으로 해당 내용을 읽습니다.- 요청된 타입이
Int인 경우, 플러그인은 수신된 값을 정수로 변환하고1을 더한 후 변환된 값을 반환합니다. 그렇지 않으면 본문을 변경하지 않고 그대로 반환합니다.
전체 예제는 DataTransformationPlugin.kt를 참조하세요.
onCallRespond()
onCallRespond() 핸들러를 사용하면 데이터가 클라이언트로 전송되기 전에 데이터를 변환할 수 있습니다. 이 핸들러는 라우트 핸들러에서 call.respond 함수가 호출될 때 실행됩니다.
예를 들어 다음과 같은 라우트를 고려해 보세요.
post("/transform-data") {
val data = call.receive<Int>()
call.respond(data)
}call.respond를 호출하면 onCallRespond()가 호출되며, 이를 통해 클라이언트로 전송될 데이터를 변환할 수 있습니다.
onCallRespond() 내부에서 transformBody()를 사용하여 응답 본문을 변환합니다. 다음 예제는 정수 응답에 1을 더하고 이를 문자열로 변환합니다.
onCallRespond { call ->
transformBody { data ->
if (data is Int) {
(data + 1).toString()
} else {
data
}
}
}전체 예제는 DataTransformationPlugin.kt를 참조하세요.
onCallValidators()
onCallValidators() 핸들러를 사용하면 수신되는 각 호출에 대해 유효성 검사를 수행할 수 있습니다.
중첩된 라우트에 여러 유효성 검사기가 적용된 경우, 상위 라우트의 유효성 검사기가 하위 라우트의 유효성 검사기보다 먼저 실행됩니다. 이를 통해 유효성 검사기는 인증된 주체(principal)와 같이 라우트 계층 구조의 상위에서 생성된 정보를 사용할 수 있습니다.
예를 들어 다음 라우트 스코프 플러그인은 인증 라우트에서 제공하는 주체(principal)에 접근할 수 있습니다.
package com.example.plugins
import io.ktor.server.application.*
import io.ktor.server.auth.UserIdPrincipal
import io.ktor.server.auth.principal
val UserValidationPlugin = createRouteScopedPlugin("UserValidationPlugin") {
onCallValidators { call ->
val principal = call.principal<UserIdPrincipal>()
if (principal != null) {
call.application.log.info("Validating request for ${principal.name}")
}
}
}인증 후 플러그인이 실행되도록 인증된 라우트 내부에 플러그인을 설치합니다.
routing {
authenticate("auth") {
install(UserValidationPlugin)
get("/api") {
call.respondText("OK")
}
}
}라우트 스코프 유효성 검사의 순서가 중요한 경우 onCallValidators()를 사용하세요. 다른 유효성 검사기에 의존하지 않는 일반적인 요청 및 응답 처리에는 onCall()을 대신 사용하세요.
기타 유용한 핸들러
위에서 설명한 호출 핸들러 외에도 Ktor는 호출 처리의 다른 단계를 다루기 위한 다양한 훅(hook)을 제공합니다. on() 함수를 사용하여 특정 Hook에 대한 핸들러를 등록할 수 있습니다.
사용 가능한 훅은 다음과 같습니다.
CallSetup: 호출 처리가 시작될 때 호출됩니다.ResponseBodyReadyForSend: 응답 본문이 모든 변환을 거쳐 전송될 준비가 되었을 때 호출됩니다.ResponseSent: 응답이 클라이언트에 성공적으로 전송된 후 호출됩니다.CallFailed: 호출 처리 중 예외가 발생하여 실패했을 때 호출됩니다.AuthenticationChecked: 인증 자격 증명이 확인된 후 호출됩니다. 이 훅을 사용하여 인가(authorization)를 구현할 수 있습니다. 예제는 custom-plugin-authorization을 참조하세요.
다음 예제는 CallSetup 훅을 처리합니다.
on(CallSetup) { call->
// ...
}애플리케이션 시작 또는 종료와 같은 애플리케이션 이벤트를 처리하기 위해 MonitoringEvent를 사용할 수도 있습니다.
호출 상태 공유
커스텀 플러그인은 서로 다른 핸들러 간에 호출과 연관된 값을 공유할 수 있습니다. 이 값들은 고유한 AttributeKey를 사용하여 call.attributes 컬렉션에 저장됩니다.
다음 예제는 onCall()이 호출된 시간을 저장하고, 이를 onCallReceive()에서 사용하여 요청 본문을 읽기 전까지의 지연 시간을 계산합니다.
val DataTransformationBenchmarkPlugin = createApplicationPlugin(name = "DataTransformationBenchmarkPlugin") {
val onCallTimeKey = AttributeKey<Long>("onCallTimeKey")
onCall { call ->
val onCallTime = System.currentTimeMillis()
call.attributes.put(onCallTimeKey, onCallTime)
}
onCallReceive { call ->
val onCallTime = call.attributes[onCallTimeKey]
val onCallReceiveTime = System.currentTimeMillis()
println("Read body delay (ms): ${onCallReceiveTime - onCallTime}")
}
}POST 요청을 보내면 플러그인이 콘솔에 지연 시간을 출력합니다.
Request URL: http://localhost:8080/transform-data
Read body delay (ms): 52전체 예제는 DataTransformationBenchmarkPlugin.kt를 참조하세요.
라우트 핸들러에서도 호출 속성(call attributes)에 접근할 수 있습니다.
애플리케이션 이벤트 처리
on() 핸들러는 MonitoringEvent 훅을 사용하여 애플리케이션 라이프사이클과 관련된 이벤트를 처리하는 기능을 제공합니다.
Ktor는 on() 핸들러에 대해 다음과 같은 사전 정의된 이벤트를 제공합니다.
ApplicationStartingApplicationStartedApplicationStopPreparingApplicationStoppingApplicationStopped
다음 예제는 ApplicationStopped 이벤트를 사용하여 애플리케이션 종료를 처리합니다.
package com.example.plugins
import io.ktor.events.EventDefinition
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.application.hooks.*
val ApplicationMonitoringPlugin = createApplicationPlugin(name = "ApplicationMonitoringPlugin") {
on(MonitoringEvent(ApplicationStarted)) { application ->
application.log.info("Server is started")
}
on(MonitoringEvent(ApplicationStopped)) { application ->
application.log.info("Server is stopped")
// 리소스를 해제하고 이벤트 구독 취소
application.monitor.unsubscribe(ApplicationStarted) {}
application.monitor.unsubscribe(ApplicationStopped) {}
}
on(ResponseSent) { call ->
if (call.response.status() == HttpStatusCode.NotFound) {
this@createApplicationPlugin.application.monitor.raise(NotFoundEvent, call)
}
}
}
val NotFoundEvent: EventDefinition<ApplicationCall> = EventDefinition()이 접근 방식은 연결 닫기, 백그라운드 작업 중지, 버퍼링된 데이터 플러시 등 플러그인이 소유한 리소스를 정리하는 데 유용합니다.
플러그인 설정 제공
커스텀 헤더 예제는 각 응답에 미리 정의된 헤더를 추가하는 플러그인을 생성합니다. 이 플러그인을 재사용 가능하게 만들려면 사용자가 헤더 이름과 값을 지정할 수 있도록 설정을 정의합니다.
설정 클래스를 정의합니다.
kotlinclass PluginConfiguration { var headerName: String = "Custom-Header-Name" var headerValue: String = "Default value" }설정 클래스 참조를
createApplicationPlugin()에 전달합니다.kotlinval CustomHeaderPlugin = createApplicationPlugin( name = "CustomHeaderPlugin", createConfiguration = ::PluginConfiguration ) { val headerName = pluginConfig.headerName val headerValue = pluginConfig.headerValue pluginConfig.apply { onCall { call -> call.response.headers.append(headerName, headerValue) } } }플러그인 설정 프로퍼티는 플러그인 설치 중에 변경될 수 있습니다. 플러그인이 핸들러에서 이 값들을 사용하는 경우, 플러그인 본문 내부의 로컬 변수에 저장하세요.
플러그인을 설치하고 설정합니다.
kotlininstall(CustomHeaderPlugin) { headerName = "X-Custom-Header" headerValue = "Hello, world!" }
전체 예제는 CustomHeaderPlugin.kt를 참조하세요.
파일 기반 설정
Ktor는 설정 파일에서 플러그인 설정을 로드할 수 있습니다.
다음 예제는 파일에서 CustomHeaderPlugin을 설정하는 방법을 보여줍니다.
application.conf또는application.yaml파일에 플러그인 설정이 포함된 새 그룹을 추가합니다.shellhttp { custom_header { header_name = X-Another-Custom-Header header_value = Some value } }yamlhttp: custom_header: header_name: X-Another-Custom-Header header_value: Some value이 예제에서 플러그인 설정은
http.custom_header그룹에 저장됩니다.설정 파일 프로퍼티에 접근하려면 설정 클래스 생성자에
ApplicationConfig를 전달합니다.tryGetString()함수는 지정된 프로퍼티의 값을 반환합니다.kotlinclass CustomHeaderConfiguration(config: ApplicationConfig) { var headerName: String = config.tryGetString("header_name") ?: "Custom-Header-Name" var headerValue: String = config.tryGetString("header_value") ?: "Default value" }createApplicationPlugin()함수의configurationPath파라미터에http.custom_header값을 지정합니다.kotlinval CustomHeaderPluginConfigurable = createApplicationPlugin( name = "CustomHeaderPluginConfigurable", configurationPath = "http.custom_header", createConfiguration = ::CustomHeaderConfiguration ) { val headerName = pluginConfig.headerName val headerValue = pluginConfig.headerValue pluginConfig.apply { onCall { call -> call.response.headers.append(headerName, headerValue) } } }
전체 예제는 CustomHeaderPluginConfigurable.kt를 참조하세요.
애플리케이션 설정 접근
커스텀 플러그인은 플러그인 본문에서 애플리케이션 수준의 설정에 접근할 수 있습니다. 이는 플러그인의 동작이 서버 설정이나 환경에 의존하는 경우에 유용합니다.
설정(Configuration)
서버 설정에 접근하려면 applicationConfig 프로퍼티를 사용합니다. 이 프로퍼티는 ApplicationConfig 인스턴스를 반환합니다.
다음 예제는 서버에서 사용하는 호스트와 포트를 읽습니다.
val SimplePlugin = createApplicationPlugin(name = "SimplePlugin") {
val host = applicationConfig?.host
val port = applicationConfig?.port
println("Listening on $host:$port")
}환경(Environment)
애플리케이션 환경에 접근하려면 environment 프로퍼티를 사용합니다. 예를 들어 개발 모드(development mode)가 활성화되어 있는지 확인할 수 있습니다.
val SimplePlugin = createApplicationPlugin(name = "SimplePlugin") {
val isDevMode = environment?.developmentMode
onCall { call ->
if (isDevMode == true) {
println("handling request ${call.request.uri}")
}
}
}기타
플러그인 상태 저장
플러그인은 플러그인 본문에서 값을 캡처하고 핸들러 람다에서 이를 사용하여 상태를 저장할 수 있습니다.
플러그인은 여러 호출을 동시에 처리할 수 있으므로 공유 가변 상태는 동시성 컬렉션이나 원자적(atomic) 타입과 같은 스레드 안전한 구조에 저장하세요.
val SimplePlugin = createApplicationPlugin(name = "SimplePlugin") {
val activeRequests = AtomicInteger(0)
onCall {
activeRequests.incrementAndGet()
}
onCallRespond {
activeRequests.decrementAndGet()
}
}데이터베이스
일시 중단 데이터베이스 API 사용
모든 커스텀 플러그인 핸들러는 일시 중단 함수(suspending function)입니다. 즉, 핸들러에서 직접 일시 중단 데이터베이스 API를 호출할 수 있습니다.
특정 호출에 스코프가 지정된 리소스는 반드시 해제해야 합니다. 예를 들어 on(ResponseSent)를 사용하여 응답이 전송된 후 리소스를 정리할 수 있습니다.
블로킹 데이터베이스 API 사용
Ktor는 코루틴을 사용하므로 블로킹 데이터베이스 호출이 기본 코루틴 디스패처에서 실행되어서는 안 됩니다. 블로킹 호출은 스레드를 점유하여 다른 코루틴의 진행을 방해할 수 있습니다.
블로킹 데이터베이스 API를 호출하려면 블로킹 작업을 위한 별도의 CoroutineContext를 생성하세요.
val databaseContext = Dispatchers.IO그런 다음 각 블로킹 데이터베이스 호출을 withContext()로 래핑합니다.
onCall {
withContext(databaseContext) {
database.access(...) // 데이터베이스 호출
}
}