Ktor Server의 Server-Sent Events
필수 의존성: io.ktor:ktor-server-sse
코드 예제: server-sse
Server-Sent Events(SSE)는 서버가 HTTP 연결을 통해 클라이언트에 이벤트를 지속적으로 푸시할 수 있도록 지원하는 기술입니다. 클라이언트가 서버를 반복적으로 폴링할 필요 없이 서버가 이벤트 기반 업데이트를 전송해야 하는 경우에 특히 유용합니다.
Ktor에서 지원하는 SSE 플러그인은 서버와 클라이언트 간의 단방향 연결을 생성하는 직관적인 방법을 제공합니다.
클라이언트 측 지원을 위한 SSE 플러그인에 대해 자세히 알아보려면 SSE 클라이언트 플러그인SSE 플러그인을 사용하면 클라이언트가 HTTP 연결을 통해 서버로부터 이벤트 기반 업데이트를 수신할 수 있습니다.을 참조하세요.
양방향 통신이 필요한 경우 WebSocketsWebSockets 플러그인을 사용하면 서버와 클라이언트 간의 양방향 통신 세션을 생성할 수 있습니다. 사용을 고려해 보세요. WebSocket 프로토콜을 사용하여 서버와 클라이언트 간의 전이중(full-duplex) 통신을 제공합니다.
제한 사항
Ktor는 SSE 응답에 대한 데이터 압축을 지원하지 않습니다. Compression필수 의존성: io.ktor:ktor-server-compression 플러그인을 사용하는 경우, 기본적으로 SSE 응답에 대한 압축을 건너뜁니다.
의존성 추가
SSE을 사용하려면 빌드 스크립트에 ktor-server-sse 아티팩트를 추가하세요:
implementation(ktorLibs.server.sse)implementation ktorLibs.server.sse<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-sse-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>SSE 설치
애플리케이션에 SSE 플러그인을 설치하려면, 지정된 모듈모듈을 사용하면 라우트를 그룹화하여 애플리케이션의 구조를 설계할 수 있습니다.의 install 함수에 전달하세요. 다음 예제는 SSE을 설치하는 방법을 보여줍니다:
embeddedServer()함수 호출 내에서 설치.Application클래스에 명시적으로 정의된module()확장 함수 내에서 설치.
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.sse.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(SSE)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.sse.*
// ...
fun Application.module() {
install(SSE)
// ...
}SSE 세션 처리
SSE 플러그인을 설치하고 나면 SSE 세션을 처리하는 라우트를 추가할 수 있습니다. 이를 위해 routing 블록 내에서 sse() 함수를 호출하세요. SSE 라우트를 설정하는 방법에는 두 가지가 있습니다:
특정 URL 경로 사용:
kotlinrouting { sse("/events") { // send events to clients } }경로 없이 사용:
kotlinrouting { sse { // send events to clients } }
SSE 세션 블록
sse 블록 내에서는 ServerSSESession 클래스로 표현되는 지정된 경로의 핸들러를 정의합니다. 블록 내에서 다음과 같은 함수와 프로퍼티를 사용할 수 있습니다:
send()ServerSentEvent를 생성하여 클라이언트에 전송합니다. callApplicationCall입니다. close()close() 메서드는 모든 send() 작업이 완료되면 자동으로 호출됩니다. close() 함수를 사용하여 세션을 닫아도 클라이언트에 종료 이벤트가 전송되지 않습니다. 세션을 닫기 전에 SSE 스트림의 종료를 나타내려면, send() 함수를 사용하여 특정 이벤트를 전송하세요. 예제: 단일 세션 처리
아래 예제는 /events 엔드포인트에서 SSE 세션을 설정하고, 각 이벤트 사이에 1초(1000ms) 지연을 두고 SSE 채널을 통해 6개의 개별 이벤트를 전송하는 방법을 보여줍니다:
routing {
sse("/events") {
repeat(6) {
send(ServerSentEvent("this is SSE #$it"))
delay(1000)
}
}
}전체 예제는 server-sse를 참조하세요.
SSE 하트비트
하트비트(Heartbeat)는 비활성 기간 동안 이벤트를 주기적으로 전송하여 SSE 연결이 활성 상태로 유지되도록 합니다. 세션이 활성 상태로 유지되는 동안 서버는 설정된 주기마다 지정된 이벤트를 전송합니다.
하트비트를 활성화하고 설정하려면 SSE 라우트 핸들러 내에서 .heartbeat() 함수를 사용하세요:
sse("/heartbeat") {
heartbeat {
period = 10.milliseconds
event = ServerSentEvent("heartbeat")
}
// ...
}이 예제에서는 연결을 유지하기 위해 10밀리초마다 하트비트 이벤트가 전송됩니다.
eventProvider 프로퍼티를 사용하여 하트비트 이벤트를 동적으로 생성할 수도 있습니다:
sse("/heartbeat-custom") {
heartbeat {
period = 30.milliseconds
eventProvider = {
ServerSentEvent(data = "ts=${Clock.System.now()}")
}
}
// ...
} 설정된 경우, eventProvider는 각 하트비트 주기(tick)마다 호출되어 ServerSentEvent를 생성합니다. 이를 통해 하트비트 이벤트에 타임스탬프나 상태 정보와 같은 동적 콘텐츠를 포함할 수 있습니다.
event와 eventProvider가 모두 구성된 경우, eventProvider가 event보다 우선 적용됩니다.
직렬화
직렬화를 활성화하려면 SSE 라우트에서 serialize 매개변수를 사용하여 커스텀 직렬화 함수를 제공하세요. 핸들러 내부에서는 ServerSSESessionWithSerialization 클래스를 사용하여 직렬화된 이벤트를 전송할 수 있습니다:
@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)
@Serializable
data class Product(val id: Int, val prices: List<Int>)
fun Application.module() {
install(SSE)
routing {
// example with serialization
sse("/json", serialize = { typeInfo, it ->
val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
Json.encodeToString(serializer, it)
}) {
send(Customer(0, "Jet", "Brains"))
send(Product(0, listOf(100, 200)))
}
}
} 이 예제의 serialize 함수는 데이터 객체를 JSON으로 변환하는 역할을 담당하며, 변환된 JSON은 ServerSentEvent의 data 필드에 배치됩니다.
전체 예제는 server-sse를 참조하세요.
