서버 전송 이벤트

Client Plugin

Ktor 클라이언트의 Server-Sent Events (SSE)

코드 예제: client-sse

Server-Sent Events (SSE)는 서버가 HTTP 연결을 통해 클라이언트에 지속적으로 이벤트를 푸시할 수 있도록 하는 기술입니다. 이는 클라이언트가 서버를 반복적으로 폴링(polling)할 필요 없이 서버가 이벤트 기반 업데이트를 보내야 하는 경우에 특히 유용합니다.

Ktor에서 지원하는 SSE 플러그인은 서버와 클라이언트 간의 단방향 연결을 생성하는 간단한 방법을 제공합니다.

TIP

서버 측 지원을 위한 SSE 플러그인에 대해 자세히 알아보려면

SSE 서버 플러그인

SSE 플러그인을 사용하면 서버가 HTTP 연결을 통해 클라이언트에 이벤트 기반 업데이트를 보낼 수 있습니다.

을 참조하세요.

의존성 추가

SSE는

ktor-client-core

기존 프로젝트에 클라이언트 의존성을 추가하는 방법을 알아보세요.

아티팩트만 필요하며 별도의 특정 의존성은 필요하지 않습니다.

SSE 설치

SSE 플러그인을 설치하려면, 클라이언트 구성 블록 내부의 install 함수에 전달하세요:

SSE 플러그인 구성

선택적으로 install 블록 내에서 SSEConfig 클래스의 지원되는 속성을 설정하여 SSE 플러그인을 구성할 수 있습니다.

SSE 재연결

자동 재연결을 활성화하려면 maxReconnectionAttempts를 0보다 큰 값으로 설정하세요. reconnectionTime을 사용하여 시도 간의 지연 시간을 구성할 수도 있습니다:

서버와의 연결이 끊어지면 클라이언트는 재연결을 시도하기 전에 지정된 reconnectionTime 동안 기다립니다. 연결을 재설정하기 위해 지정된 maxReconnectionAttempts 횟수까지 시도합니다.

이벤트 필터링

다음 예제에서는 SSE 플러그인을 HTTP 클라이언트에 설치하고, 수신 플로우(flow)에 주석만 포함된 이벤트와 retry 필드만 포함된 이벤트를 포함하도록 구성합니다:

응답 버퍼링

SSE 응답은 본질적으로 스트리밍 방식이므로 전체 본문을 캡처하는 것이 현실적이지 않습니다. SSE 스트림이 실패할 때 응답 본문을 안전하게 검색하기 위해 진단 버퍼를 활성화할 수 있습니다. 버퍼에는 이미 처리된 데이터만 포함되며(네트워크에서 다시 읽지 않음), 실패 시 로깅 및 오류 분석을 위한 용도입니다.

호출별로 버퍼를 구성할 수도 있습니다:

버퍼 정책

SSEBufferPolicy 타입은 처리된 SSE 데이터를 저장하기 위한 여러 전략을 제공합니다. 이 정책들은 메모리에 유지되는 스트림의 양과 오류 발생 시 사용 가능한 양을 제어합니다.

<code>Off</code> (기본값)

버퍼링 없음.

<code>LastLines(n)</code>

마지막 n개 라인을 유지함.

<code>LastEvent</code>

마지막으로 완료된 SSE 이벤트를 유지함.

<code>LastEvents(n)</code>

마지막 n개의 완료된 SSE 이벤트를 유지함.

<code>All</code>

지금까지 처리된 모든 이벤트를 유지함.

NOTE

수명이 긴 스트림의 경우 주의해서 사용하세요.

실패 시 네트워크에서 다시 읽지 않고 response?.bodyAsText()를 사용하여 버퍼에 접근할 수 있습니다.

SSE 세션 처리

클라이언트의 SSE 세션은 ClientSSESession 인터페이스로 표현됩니다. 이 인터페이스는 서버로부터 서버 전송 이벤트를 받을 수 있는 API를 노출합니다.

SSE 세션 접근

HttpClient를 사용하면 다음 방법 중 하나로 SSE 세션에 접근할 수 있습니다:

• sse() 함수는 SSE 세션을 생성하고 해당 세션에서 동작할 수 있게 합니다.
• sseSession() 함수는 SSE 세션을 열 수 있게 합니다.

URL 엔드포인트를 지정하기 위해 다음 두 가지 옵션 중 선택할 수 있습니다:

• urlString 파라미터를 사용하여 전체 URL을 문자열로 지정합니다.
• schema, host, port, path 파라미터를 사용하여 각각 프로토콜 스킴, 도메인 이름, 포트 번호, 경로 이름을 지정합니다.

NOTE

ClientSSESession 및 ClientSSESessionWithDeserialization 인스턴스는 세션이 유지되는 동안에만 유효합니다. serverSentEvents { ... } 블록이 완료되거나 연결이 닫히면 해당 스코프는 자동으로 취소됩니다.

선택적으로 연결을 구성하기 위해 다음 파라미터들을 사용할 수 있습니다:

<code>reconnectionTime</code>

재연결 지연 시간을 설정합니다.

<code>showCommentEvents</code>

수신 플로우에 주석만 포함된 이벤트를 표시할지 여부를 지정합니다.

<code>showRetryEvents</code>

수신 플로우에 retry 필드만 포함된 이벤트를 표시할지 여부를 지정합니다.

<code>deserialize</code>

TypedServerSentEvent의 data 필드를 객체로 변환하는 역직렬화 함수입니다. 자세한 내용은 역직렬화(Deserialization)를 참조하세요.

SSE 세션 블록

람다 인자 내에서는 ClientSSESession 컨텍스트에 접근할 수 있습니다. 블록 내에서 다음 속성을 사용할 수 있습니다:

<code>call</code>

세션을 시작한 관련 HttpClientCall입니다.

<code>incoming</code>

수신되는 서버 전송 이벤트 플로우입니다.

아래 예제는 events 엔드포인트로 새로운 SSE 세션을 생성하고, incoming 속성을 통해 이벤트를 읽고 수신된 ServerSentEvent를 출력합니다.

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

역직렬화(Deserialization)

SSE 플러그인은 서버 전송 이벤트를 타입 안정성이 보장된 Kotlin 객체로 역직렬화하는 기능을 지원합니다. 이 기능은 서버의 구조화된 데이터로 작업할 때 특히 유용합니다.

역직렬화를 활성화하려면 SSE 접근 함수에서 deserialize 파라미터를 사용하여 커스텀 역직렬화 함수를 제공하고, ClientSSESessionWithDeserialization 클래스를 사용하여 역직렬화된 이벤트를 처리하세요.

다음은 kotlinx.serialization을 사용하여 JSON 데이터를 역직렬화하는 예제입니다:

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