Ktor Server における WebSockets
必要な依存関係: io.ktor:ktor-server-websockets
コード例: server-websockets
Native サーバーKtorはKotlin/Nativeをサポートしており、追加のランタイムや仮想マシンなしでサーバーを実行できます。のサポート: ✅
WebSocket は、単一の TCP 接続上でユーザーのブラウザとサーバー間の全二重通信セッションを提供するプロトコルです。サーバーとのリアルタイムなデータ送受信を必要とするアプリケーションの作成に特に役立ちます。
Ktor はサーバー側とクライアント側の両方で WebSocket プロトコルをサポートしています。
Ktor では以下のことが可能です:
- フレームサイズや ping 間隔などの基本的な WebSocket 設定を構成する。
- サーバーとクライアント間でメッセージをやり取りするための WebSocket セッションを処理する。
- WebSocket 拡張機能を追加する。例えば、Deflate 拡張機能を使用したり、カスタム拡張機能を実装したりできます。
クライアント側での WebSocket サポートについては、WebSockets クライアントプラグインを参照してください。
単方向の通信セッションには、Server-Sent Events (SSE) の使用を検討してください。SSE は、サーバーがクライアントにイベントベースの更新を送信する必要がある場合に特に有用です。
依存関係の追加
WebSockets を使用するには、ビルドスクリプトに ktor-server-websockets アーティファクトを追加します:
implementation(ktorLibs.server.websockets)implementation ktorLibs.server.websockets<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-websockets-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>WebSockets のインストール
WebSockets プラグインをアプリケーションにインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、WebSockets をインストールする方法を示しています:
embeddedServer()関数呼び出し内。Applicationクラスに明示的に定義されたmodule()拡張関数内。
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.websocket.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(WebSockets)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.websocket.*
// ...
fun Application.module() {
install(WebSockets)
// ...
}WebSockets の構成
任意で、WebSocketOptions を渡すことで install ブロック内でプラグインを構成できます:
pingPeriodプロパティを使用して、ping の間隔を指定します。timeoutプロパティを使用して、接続が切断されるまでのタイムアウトを設定します。maxFrameSizeプロパティを使用して、送受信可能な最大フレームサイズを設定します。maskingプロパティを使用して、マスキングを有効にするかどうかを指定します。contentConverterプロパティを使用して、シリアライズ/デシリアライズ用のコンバーターを設定します。
install(WebSockets) {
pingPeriod = 15.seconds
timeout = 15.seconds
maxFrameSize = Long.MAX_VALUE
masking = false
}WebSocket セッションの処理
API の概要
WebSockets プラグインをインストールして構成したら、WebSocket セッションを処理するエンドポイントを定義できます。サーバー上に WebSocket エンドポイントを定義するには、ルーティングブロック内で webSocket 関数を呼び出します:
routing {
webSocket("/echo") {
// Handle a WebSocket session
}
}この例では、デフォルト設定を使用している場合、サーバーは ws://localhost:8080/echo への WebSocket リクエストを受け付けます。
webSocket ブロック内で、DefaultWebSocketServerSession クラスによって表される WebSocket セッションのハンドラーを定義します。 ブロック内では、以下の関数およびプロパティを使用できます:
send関数を使用して、クライアントにテキストコンテンツを送信します。incomingおよびoutgoingプロパティを使用して、WebSocket フレームの送受信用のチャネルにアクセスします。フレームはFrameクラスで表されます。close関数を使用して、指定した理由を含むクローズフレームを送信します。
セッションを処理する際、以下のようにフレームタイプを確認できます:
Frame.Textはテキストフレームです。このフレームタイプでは、Frame.Text.readText()を使用してその内容を読み取ることができます。Frame.Binaryはバイナリフレームです。このタイプでは、Frame.Binary.readBytes()を使用してその内容を読み取ることができます。
incoming チャネルには、ping/pong や close フレームなどの制御フレームが含まれていないことに注意してください。 制御フレームを処理し、断片化されたフレームを再構成するには、webSocketRaw 関数を使用して WebSocket セッションを処理してください。
クライアントに関する情報(クライアントの IP アドレスなど)を取得するには、call プロパティを使用します。一般的なリクエスト情報を参照してください。
以下では、この API の使用例を見ていきます。
例: 単一セッションの処理
以下の例は、1 つのクライアントとのセッションを処理する echo WebSocket エンドポイントを作成する方法を示しています:
routing {
webSocket("/echo") {
send("Please enter your name")
for (frame in incoming) {
frame as? Frame.Text ?: continue
val receivedText = frame.readText()
if (receivedText.equals("bye", ignoreCase = true)) {
close(CloseReason(CloseReason.Codes.NORMAL, "Client said BYE"))
} else {
send(Frame.Text("Hi, $receivedText!"))
}
}
}
}完全な例については、server-websockets を参照してください。
例: 複数セッションの処理
複数の WebSocket セッションを効率的に管理し、ブロードキャストを処理するために、Kotlin の SharedFlow を利用できます。このアプローチにより、WebSocket 通信を管理するためのスケーラブルで並行処理に適した手法が提供されます。このパターンの実装方法は以下のとおりです:
- メッセージをブロードキャストするための
SharedFlowを定義します:
val messageResponseFlow = MutableSharedFlow<MessageResponse>()
val sharedFlow = messageResponseFlow.asSharedFlow()- WebSocket ルートで、ブロードキャストおよびメッセージ処理ロジックを実装します:
webSocket("/ws") {
send("You are connected to WebSocket!")
val job = launch {
sharedFlow.collect { message ->
send(message.message)
}
}
runCatching {
incoming.consumeEach { frame ->
if (frame is Frame.Text) {
val receivedText = frame.readText()
val messageResponse = MessageResponse(receivedText)
messageResponseFlow.emit(messageResponse)
}
}
}.onFailure { exception ->
println("WebSocket exception: ${exception.localizedMessage}")
}.also {
job.cancel()
}
}runCatching ブロックは受信したメッセージを処理して SharedFlow に送出し(emit)、その後すべてのコレクターにブロードキャストします。
このパターンを使用することで、個々の接続を手動で追跡することなく、複数の WebSocket セッションを効率的に管理できます。この手法は多数の同時 WebSocket 接続を持つアプリケーションにも良好にスケールし、メッセージのブロードキャストを処理するためのクリーンでリアクティブな方法を提供します。
完全な例については、server-websockets-sharedflow を参照してください。
WebSocket API と Ktor
WebSocket API の標準イベントは、以下のように Ktor にマッピングされます:
onConnectは、ブロックの開始時に発生します。onMessageは、メッセージの読み取りに成功した後(例えばincoming.receive()を使用した場合)、またはfor(frame in incoming)による中断可能なイテレーション(suspended iteration)を使用した後に発生します。onCloseは、incomingチャネルが閉じられたときに発生します。これにより中断可能なイテレーションが完了するか、メッセージを受信しようとしたときにClosedReceiveChannelExceptionがスローされます。onErrorは、その他の例外に相当します。
onClose と onError の両方で、closeReason プロパティが設定されます。
以下の例では、例外(ClosedReceiveChannelException またはその他の例外)が発生した場合にのみ無限ループが終了します:
webSocket("/echo") {
println("onConnect")
try {
for (frame in incoming){
val text = (frame as Frame.Text).readText()
println("onMessage")
received += text
outgoing.send(Frame.Text(text))
}
} catch (e: ClosedReceiveChannelException) {
println("onClose ${closeReason.await()}")
} catch (e: Throwable) {
println("onError ${closeReason.await()}")
e.printStackTrace()
}
}