WebSocket

Client Plugin

Ktor 클라이언트의 WebSockets

필수 의존성: io.ktor:ktor-client-websockets

코드 예제: client-websockets

WebSocket은 단일 TCP 연결을 통해 사용자의 브라우저와 서버 간에 전이중(full-duplex) 통신 세션을 제공하는 프로토콜입니다. 이는 서버와 실시간으로 데이터를 주고받아야 하는 애플리케이션을 제작할 때 특히 유용합니다. Ktor는 서버 측과 클라이언트 측 모두에서 WebSocket 프로토콜을 지원합니다.

클라이언트용 Websockets 플러그인을 사용하면 서버와 메시지를 교환하기 위한 WebSocket 세션을 처리할 수 있습니다.

NOTE

모든 엔진이 WebSocket을 지원하는 것은 아닙니다. 지원되는 엔진에 대한 개요는 제한 사항(Limitations)을 참조하세요.

TIP

서버 측의 WebSocket 지원에 대해 알아보려면

Ktor 서버의 WebSockets

Websockets 플러그인을 사용하면 서버와 클라이언트 간에 다중 통신 세션을 생성할 수 있습니다.

를 참조하세요.

의존성 추가

WebSockets를 사용하려면 빌드 스크립트에 ktor-client-websockets 아티팩트를 포함해야 합니다:

Gradle (Kotlin)Gradle (Groovy)Maven

TIP

Ktor 클라이언트에 필요한 아티팩트에 대해 자세히 알아보려면

클라이언트 의존성 추가하기

기존 프로젝트에 클라이언트 의존성을 추가하는 방법을 알아봅니다.

를 참조하세요.

WebSockets 설치

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

설정

선택 사항으로, install 블록 내에서 WebSockets.Config의 지원되는 속성들을 전달하여 플러그인을 설정할 수 있습니다.

<code>maxFrameSize</code>

수신 또는 전송할 수 있는 최대 Frame 크기를 설정합니다.

<code>contentConverter</code>

직렬화/역직렬화를 위한 컨버터를 설정합니다.

<code>pingIntervalMillis</code>

Long 형식으로 핑(ping) 사이의 간격을 지정합니다.

<code>pingInterval</code>

Duration 형식으로 핑 사이의 간격을 지정합니다.

pingInterval 및 pingIntervalMillis 속성은 OkHttp 엔진에는 적용되지 않습니다. OkHttp의 핑 간격을 설정하려면 엔진 설정을 사용할 수 있습니다:

다음 예제에서는 핑 프레임을 자동으로 전송하고 WebSocket 연결을 유지하기 위해 WebSockets 플러그인을 20초(20_000 밀리초)의 핑 간격으로 설정합니다:

WebSocket 세션 작업

클라이언트의 WebSocket 세션은 DefaultClientWebSocketSession 인터페이스로 표현됩니다. 이 인터페이스는 WebSocket 프레임을 주고받고 세션을 닫을 수 있는 API를 제공합니다.

WebSocket 세션 액세스

HttpClient는 WebSocket 세션에 액세스하는 두 가지 주요 방법을 제공합니다:

• webSocket() 함수는 DefaultClientWebSocketSession을 블록 인자로 받습니다.
• webSocketSession() 함수는 DefaultClientWebSocketSession 인스턴스를 반환하며, runBlocking 또는 launch 스코프 외부에서 세션에 액세스할 수 있게 해줍니다.

WebSocket 세션 처리

함수 블록 내에서 지정된 경로에 대한 핸들러를 정의합니다. 블록 내에서는 다음과 같은 함수와 속성을 사용할 수 있습니다:

<code>send()</code>

send() 함수를 사용하여 서버에 텍스트 콘텐츠를 보냅니다.

<code>outgoing</code>

outgoing 속성을 사용하여 WebSocket 프레임을 보내기 위한 채널에 액세스합니다. 프레임은 Frame 클래스로 표현됩니다.

<code>incoming</code>

incoming 속성을 사용하여 WebSocket 프레임을 받기 위한 채널에 액세스합니다. 프레임은 Frame 클래스로 표현됩니다.

<code>close()</code>

close() 함수를 사용하여 지정된 사유와 함께 종료(close) 프레임을 보냅니다.

프레임 유형

WebSocket 프레임의 유형을 검사하고 그에 따라 처리할 수 있습니다. 주요 프레임 유형은 다음과 같습니다:

• Frame.Text는 텍스트 프레임을 나타냅니다. 콘텐츠를 읽으려면 Frame.Text.readText()를 사용하세요.
• Frame.Binary는 바이너리 프레임을 나타냅니다. 콘텐츠를 읽으려면 Frame.Binary.readBytes()를 사용하세요.
• Frame.Close는 종료 프레임을 나타냅니다. 세션 종료 사유를 가져오려면 Frame.Close.readReason()을 사용하세요.

예제

아래 예제는 echo WebSocket 엔드포인트를 생성하고 서버와 메시지를 주고받는 방법을 보여줍니다.

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