Ktor Client의 WebSockets
필수 의존성: io.ktor:ktor-client-websockets
코드 예제: client-websockets
클라이언트용 Websockets 플러그인을 사용하면 서버와 메시지를 주고받기 위한 WebSocket 세션을 처리할 수 있습니다.
모든 엔진이 WebSockets를 지원하는 것은 아닙니다. 지원되는 엔진에 대한 개요는 제한 사항을 참조하세요.
서버 측의 WebSocket 지원에 대해 알아보려면 Ktor Server의 WebSocketsWebSockets 플러그인을 사용하면 서버와 클라이언트 간의 양방향 통신 세션을 생성할 수 있습니다.를 참조하세요.
의존성 추가
WebSockets를 사용하려면 빌드 스크립트에 ktor-client-websockets 아티팩트를 포함해야 합니다:
implementation(ktorLibs.client.websockets)implementation ktorLibs.client.websockets<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-client-websockets-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>WebSockets 설치
WebSockets 플러그인을 설치하려면 클라이언트 구성 블록 내부의 install 함수에 전달하세요:
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 블록 내부에서 플러그인을 구성할 수 있습니다.
maxFrameSizeFrame 크기를 설정합니다. contentConverterpingIntervalMillisLong 형식으로 지정합니다. pingIntervalDuration 형식으로 지정합니다. pingInterval 및 pingIntervalMillis 프로퍼티는 OkHttp 엔진에는 적용되지 않습니다. OkHttp의 핑 간격을 설정하려면 엔진 구성을 사용할 수 있습니다:
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 연결을 유지하도록 합니다:
val client = HttpClient(CIO) {
install(WebSockets) {
pingIntervalMillis = 20_000
}
}WebSocket 세션 작업하기
클라이언트의 WebSocket 세션은 DefaultClientWebSocketSession 인터페이스로 표현됩니다. 이 인터페이스는 WebSocket 프레임을 송수신하고 세션을 닫을 수 있는 API를 제공합니다.
WebSocket 세션 접근
HttpClient는 WebSocket 세션에 접근하는 두 가지 주요 방법을 제공합니다:
webSocket() 함수는
DefaultClientWebSocketSession을 블록 인수로 받습니다.kotlinrunBlocking { client.webSocket( method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/echo" ) { // this: DefaultClientWebSocketSession } }- webSocketSession() 함수는
DefaultClientWebSocketSession인스턴스를 반환하며,runBlocking또는launch스코프 외부에서 세션에 접근할 수 있도록 해줍니다.
WebSocket 세션 처리
함수 블록 내에서 지정된 경로에 대한 핸들러를 정의합니다. 블록 내에서 다음 함수와 프로퍼티를 사용할 수 있습니다:
send()send() 함수를 사용하세요. outgoingoutgoing 프로퍼티를 사용하세요. 프레임은 Frame 클래스로 표현됩니다. incomingincoming 프로퍼티를 사용하세요. 프레임은 Frame 클래스로 표현됩니다. close()close() 함수를 사용하세요. 프레임 유형
WebSocket 프레임의 유형을 확인하고 그에 따라 처리할 수 있습니다. 몇 가지 일반적인 프레임 유형은 다음과 같습니다:
Frame.Text는 텍스트 프레임을 나타냅니다. 내용을 읽으려면Frame.Text.readText()를 사용하세요.Frame.Binary는 바이너리 프레임을 나타냅니다. 내용을 읽으려면Frame.Binary.readBytes()를 사용하세요.Frame.Close는 종료 프레임을 나타냅니다. 세션이 종료된 사유를 확인하려면Frame.Close.readReason()을 사용하세요.
예제
아래 예제는 echo WebSocket 엔드포인트를 생성하고 서버와 메시지를 주고받는 방법을 보여줍니다.
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를 참조하세요.
