Ktor Client의 Server-Sent Events
코드 예제: client-sse
Server-Sent Events(SSE)는 서버가 HTTP 연결을 통해 클라이언트에 지속적으로 이벤트를 푸시할 수 있도록 하는 기술입니다. 클라이언트가 서버에 반복적으로 폴링할 필요 없이 서버가 이벤트 기반 업데이트를 전송해야 하는 경우에 특히 유용합니다.
Ktor에서 지원하는 SSE 플러그인은 서버와 클라이언트 간에 단방향 연결을 생성하는 직관적인 방법을 제공합니다.
서버 측 지원을 위한 SSE 플러그인에 대해 자세히 알아보려면 SSE 서버 플러그인SSE 플러그인을 사용하면 서버가 HTTP 연결을 통해 클라이언트에 이벤트 기반 업데이트를 전송할 수 있습니다.을 참조하세요.
의존성 추가
SSE는 ktor-client-core기존 프로젝트에 클라이언트 의존성을 추가하는 방법을 알아봅니다. 아티팩트만 필요로 하며 별도의 특정 의존성이 필요하지 않습니다.
SSE 설치
SSE 플러그인을 설치하려면 클라이언트 구성 블록 내의 install 함수에 전달합니다:
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.sse.*
//...
val client = HttpClient(CIO) {
install(SSE)
}SSE 플러그인 구성
install 블록 내에서 SSEConfig 클래스에서 지원하는 프로퍼티를 설정하여 SSE 플러그인을 선택적으로 구성할 수 있습니다.
SSE 재연결
자동 재연결을 활성화하려면 maxReconnectionAttempts를 0보다 큰 값으로 설정하세요. 또한 reconnectionTime을 사용하여 시도 간의 지연 시간을 구성할 수 있습니다:
install(SSE) {
maxReconnectionAttempts = 4
reconnectionTime = 2.seconds
} 서버와의 연결이 끊어지면 클라이언트는 재연결을 시도하기 전에 지정된 reconnectionTime 동안 대기합니다. 그리고 연결을 재설정하기 위해 지정된 maxReconnectionAttempts 횟수까지 시도합니다.
이벤트 필터링
다음 예제에서는 SSE 플러그인이 HTTP 클라이언트에 설치되어 주석만 포함된 이벤트와 retry 필드만 포함된 이벤트를 수신 flow에 포함하도록 구성됩니다:
install(SSE) {
showCommentEvents()
showRetryEvents()
}응답 버퍼링
SSE 응답은 본질적으로 스트리밍 방식이므로 전체 본문을 캡처하기 어렵습니다. 진단 버퍼를 활성화하면 SSE 스트림에 오류가 발생했을 때 응답 본문을 안전하게 검색할 수 있습니다. 버퍼에는 이미 처리된 데이터만 포함되며(네트워크에서 다시 읽지 않음), 오류 발생 시 로깅 및 오류 분석을 목적으로 사용됩니다.
install(SSE) {
bufferPolicy = SSEBufferPolicy.LastEvents(10)
}호출별로 버퍼를 구성할 수도 있습니다:
client.sse(url, {
bufferPolicy(SSEBufferPolicy.All)
}) {
// ...
}버퍼 정책
SSEBufferPolicy 타입은 처리된 SSE 데이터를 저장하기 위한 여러 전략을 제공합니다. 이러한 정책은 스트림의 얼마만큼을 메모리에 유지하고 오류 발생 시 사용할 수 있게 할지 제어합니다.
Off (기본값)LastLines(n)LastEventLastEvents(n)All 실패 시 네트워크에서 다시 읽지 않고 response?.bodyAsText()를 사용하여 버퍼에 접근할 수 있습니다.
SSE 세션 처리
클라이언트의 SSE 세션은 ClientSSESession 인터페이스로 표현됩니다. 이 인터페이스는 서버로부터 server-sent events를 수신할 수 있는 API를 노출합니다.
SSE 세션 접근
HttpClient를 사용하면 다음 방법 중 하나로 SSE 세션에 접근할 수 있습니다:
sse()함수는 SSE 세션을 생성하고 이를 기반으로 동작을 수행할 수 있게 합니다.sseSession()함수는 SSE 세션을 열 수 있게 합니다.
URL 엔드포인트를 지정하려면 두 가지 옵션 중 선택할 수 있습니다:
urlString매개변수를 사용하여 전체 URL을 문자열로 지정합니다.schema,host,port,path매개변수를 사용하여 프로토콜 스키마, 도메인 이름, 포트 번호, 경로 이름을 각각 지정합니다.
runBlocking {
client.sse(host = "127.0.0.1", port = 8080, path = "/events") {
// this: ClientSSESession
}
}ClientSSESession 및 ClientSSESessionWithDeserialization 인스턴스는 세션이 유지되는 동안에만 유효합니다. 이들의 스코프는 serverSentEvents { ... } 블록이 완료되거나 연결이 닫힐 때 자동으로 취소됩니다. 선택적으로 연결을 구성하기 위해 다음 매개변수들을 사용할 수 있습니다:
reconnectionTimeshowCommentEventsshowRetryEventsretry 필드만 포함된 이벤트를 수신 flow에 표시할지 여부를 지정합니다. deserializeTypedServerSentEvent의 data 필드를 객체로 변환하기 위한 역직렬화 함수입니다. 자세한 내용은 역직렬화(Deserialization)를 참조하세요. SSE 세션 블록
람다 인자 내에서는 ClientSSESession 컨텍스트에 접근할 수 있습니다. 해당 블록 내에서 사용할 수 있는 프로퍼티는 다음과 같습니다:
callHttpClientCall입니다. incoming 아래 예제는 events 엔드포인트로 새 SSE 세션을 생성하고, incoming 프로퍼티를 통해 이벤트를 읽은 다음 수신된 ServerSentEvent를 출력합니다.
fun main() {
val client = HttpClient {
install(SSE) {
showCommentEvents()
showRetryEvents()
}
}
runBlocking {
client.sse(host = "0.0.0.0", port = 8080, path = "/events") {
while (true) {
incoming.collect { event ->
println("Event from server:")
println(event)
}
}
}
}
}전체 예제는 client-sse를 참조하세요.
역직렬화
SSE 플러그인은 server-sent events를 타입 안전한 Kotlin 객체로 역직렬화하는 기능을 지원합니다. 이 기능은 서버의 구조화된 데이터를 처리할 때 특히 유용합니다.
역직렬화를 활성화하려면 SSE 접근 함수에서 deserialize 매개변수를 사용하여 커스텀 역직렬화 함수를 제공하고, ClientSSESessionWithDeserialization 클래스를 사용하여 역직렬화된 이벤트를 처리하세요.
다음은 kotlinx.serialization을 사용하여 JSON 데이터를 역직렬화하는 예제입니다:
client.sse({
url("http://localhost:8080/serverSentEvents")
}, deserialize = {
typeInfo, jsonString ->
val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
Json.decodeFromString(serializer, jsonString)!!
}) { // `this` is `ClientSSESessionWithDeserialization`
incoming.collect { event: TypedServerSentEvent<String> ->
when (event.event) {
"customer" -> {
val customer: Customer? = deserialize<Customer>(event.data)
}
"product" -> {
val product: Product? = deserialize<Product>(event.data)
}
}
}
}전체 예제는 client-sse를 참조하세요.
