Skip to content
Server Plugin

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 아티팩트를 추가하세요:

kotlin
implementation(ktorLibs.server.sse)
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.server.sse
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-sse-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

SSE 설치

애플리케이션에 SSE 플러그인을 설치하려면, 지정된 모듈모듈을 사용하면 라우트를 그룹화하여 애플리케이션의 구조를 설계할 수 있습니다.의 install 함수에 전달하세요. 다음 예제는 SSE을 설치하는 방법을 보여줍니다:

  • embeddedServer() 함수 호출 내에서 설치.
  • Application 클래스에 명시적으로 정의된 module() 확장 함수 내에서 설치.
kotlin
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)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.sse.*
// ...
fun Application.module() {
    install(SSE)
    // ...
}

SSE 세션 처리

SSE 플러그인을 설치하고 나면 SSE 세션을 처리하는 라우트를 추가할 수 있습니다. 이를 위해 routing 블록 내에서 sse() 함수를 호출하세요. SSE 라우트를 설정하는 방법에는 두 가지가 있습니다:

  1. 특정 URL 경로 사용:

    kotlin
    routing {
        sse(&quot;/events&quot;) {
            // send events to clients
        }
    }
  2. 경로 없이 사용:

    kotlin
    routing {
        sse {
            // send events to clients
        }
    }

SSE 세션 블록

sse 블록 내에서는 ServerSSESession 클래스로 표현되는 지정된 경로의 핸들러를 정의합니다. 블록 내에서 다음과 같은 함수와 프로퍼티를 사용할 수 있습니다:

send()
ServerSentEvent를 생성하여 클라이언트에 전송합니다.
call
세션을 시작한 수신된 관련 ApplicationCall입니다.
close()
세션을 닫고 클라이언트와의 연결을 종료합니다. close() 메서드는 모든 send() 작업이 완료되면 자동으로 호출됩니다.
close() 함수를 사용하여 세션을 닫아도 클라이언트에 종료 이벤트가 전송되지 않습니다. 세션을 닫기 전에 SSE 스트림의 종료를 나타내려면, send() 함수를 사용하여 특정 이벤트를 전송하세요.

예제: 단일 세션 처리

아래 예제는 /events 엔드포인트에서 SSE 세션을 설정하고, 각 이벤트 사이에 1초(1000ms) 지연을 두고 SSE 채널을 통해 6개의 개별 이벤트를 전송하는 방법을 보여줍니다:

kotlin
routing {
    sse("/events") {
        repeat(6) {
            send(ServerSentEvent("this is SSE #$it"))
            delay(1000)
        }
    }
}

전체 예제는 server-sse를 참조하세요.

SSE 하트비트

하트비트(Heartbeat)는 비활성 기간 동안 이벤트를 주기적으로 전송하여 SSE 연결이 활성 상태로 유지되도록 합니다. 세션이 활성 상태로 유지되는 동안 서버는 설정된 주기마다 지정된 이벤트를 전송합니다.

하트비트를 활성화하고 설정하려면 SSE 라우트 핸들러 내에서 .heartbeat() 함수를 사용하세요:

kotlin
sse("/heartbeat") {
    heartbeat {
        period = 10.milliseconds
        event = ServerSentEvent("heartbeat")
    }
    // ...
}

이 예제에서는 연결을 유지하기 위해 10밀리초마다 하트비트 이벤트가 전송됩니다.

eventProvider 프로퍼티를 사용하여 하트비트 이벤트를 동적으로 생성할 수도 있습니다:

kotlin
sse("/heartbeat-custom") {
    heartbeat {
        period = 30.milliseconds
        eventProvider = {
            ServerSentEvent(data = "ts=${Clock.System.now()}")
        }
    }
    // ...
}

설정된 경우, eventProvider는 각 하트비트 주기(tick)마다 호출되어 ServerSentEvent를 생성합니다. 이를 통해 하트비트 이벤트에 타임스탬프나 상태 정보와 같은 동적 콘텐츠를 포함할 수 있습니다.

event와 eventProvider가 모두 구성된 경우, eventProvider가 event보다 우선 적용됩니다.

직렬화

직렬화를 활성화하려면 SSE 라우트에서 serialize 매개변수를 사용하여 커스텀 직렬화 함수를 제공하세요. 핸들러 내부에서는 ServerSSESessionWithSerialization 클래스를 사용하여 직렬화된 이벤트를 전송할 수 있습니다:

kotlin
@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를 참조하세요.