Skip to content
Client Plugin

Ktor Client의 WebSockets

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

코드 예제: client-websockets

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

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

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

서버 측의 WebSocket 지원에 대해 알아보려면 Ktor Server의 WebSocketsWebSockets 플러그인을 사용하면 서버와 클라이언트 간의 양방향 통신 세션을 생성할 수 있습니다.를 참조하세요.

의존성 추가

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

kotlin
implementation(ktorLibs.client.websockets)
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.client.websockets
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-websockets-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>
Ktor 클라이언트에 필요한 아티팩트에 대한 자세한 내용은 클라이언트 의존성 추가기존 프로젝트에 클라이언트 의존성을 추가하는 방법을 알아봅니다.를 참조하세요.

WebSockets 설치

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

kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.websocket.*

//...
val client = HttpClient(CIO) {
    install(WebSockets)
}

구성

선택적으로, WebSockets.Config에서 지원하는 프로퍼티를 전달하여 install 블록 내부에서 플러그인을 구성할 수 있습니다.

maxFrameSize
수신하거나 전송할 수 있는 최대 Frame 크기를 설정합니다.
contentConverter
직렬화/역직렬화를 위한 컨버터를 설정합니다.
pingIntervalMillis
핑(ping) 사이의 간격을 Long 형식으로 지정합니다.
pingInterval
핑(ping) 사이의 간격을 Duration 형식으로 지정합니다.

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

kotlin
import io.ktor.client.engine.okhttp.OkHttp

val client = HttpClient(OkHttp) {
    engine {
        preconfigured = OkHttpClient.Builder()
            .pingInterval(20, TimeUnit.SECONDS)
            .build()
    }
}

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

kotlin
val client = HttpClient(CIO) {
    install(WebSockets) {
        pingIntervalMillis = 20_000
    }
}

WebSocket 세션 작업하기

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

WebSocket 세션 접근

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

  • webSocket() 함수는 DefaultClientWebSocketSession을 블록 인수로 받습니다.

    kotlin
    runBlocking {
        client.webSocket(
            method = HttpMethod.Get,
            host = "127.0.0.1",
            port = 8080,
            path = "/echo"
        ) {
            // this: DefaultClientWebSocketSession
        }
    }
  • webSocketSession() 함수는 DefaultClientWebSocketSession 인스턴스를 반환하며, runBlocking 또는 launch 스코프 외부에서 세션에 접근할 수 있도록 해줍니다.

WebSocket 세션 처리

함수 블록 내에서 지정된 경로에 대한 핸들러를 정의합니다. 블록 내에서 다음 함수와 프로퍼티를 사용할 수 있습니다:

send()
서버에 텍스트 콘텐츠를 전송하려면 send() 함수를 사용하세요.
outgoing
WebSocket 프레임을 전송하기 위한 채널에 접근하려면 outgoing 프로퍼티를 사용하세요. 프레임은 Frame 클래스로 표현됩니다.
incoming
WebSocket 프레임을 수신하기 위한 채널에 접근하려면 incoming 프로퍼티를 사용하세요. 프레임은 Frame 클래스로 표현됩니다.
close()
지정된 사유와 함께 close 프레임을 전송하려면 close() 함수를 사용하세요.

프레임 유형

WebSocket 프레임의 유형을 확인하고 그에 따라 처리할 수 있습니다. 몇 가지 일반적인 프레임 유형은 다음과 같습니다:

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

예제

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

kotlin
package com.example

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.websocket.*
import io.ktor.http.*
import io.ktor.websocket.*
import kotlinx.coroutines.*
import java.util.*

fun main() {
    val client = HttpClient(CIO) {
        install(WebSockets) {
            pingIntervalMillis = 20_000
        }
    }
    runBlocking {
        client.webSocket(method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/echo") {
            while(true) {
                val othersMessage = incoming.receive() as? Frame.Text
                println(othersMessage?.readText())
                val myMessage = Scanner(System.`in`).next()
                if(myMessage != null) {
                    send(myMessage)
                }
            }
        }
    }
    client.close()
}

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