Skip to content
Server Plugin

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 アーティファクトを追加します:

kotlin
implementation(ktorLibs.server.websockets)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.server.websockets
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-websockets-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

WebSockets のインストール ​

WebSockets プラグインをアプリケーションにインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、WebSockets をインストールする方法を示しています:

  • embeddedServer() 関数呼び出し内。
  • Application クラスに明示的に定義された module() 拡張関数内。
kotlin
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)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.websocket.*
// ...
fun Application.module() {
    install(WebSockets)
    // ...
}

WebSockets の構成 ​

任意で、WebSocketOptions を渡すことで install ブロック内でプラグインを構成できます:

  • pingPeriod プロパティを使用して、ping の間隔を指定します。
  • timeout プロパティを使用して、接続が切断されるまでのタイムアウトを設定します。
  • maxFrameSize プロパティを使用して、送受信可能な最大フレームサイズを設定します。
  • masking プロパティを使用して、マスキングを有効にするかどうかを指定します。
  • contentConverter プロパティを使用して、シリアライズ/デシリアライズ用のコンバーターを設定します。
kotlin
install(WebSockets) {
    pingPeriod = 15.seconds
    timeout = 15.seconds
    maxFrameSize = Long.MAX_VALUE
    masking = false
}

WebSocket セッションの処理 ​

API の概要 ​

WebSockets プラグインをインストールして構成したら、WebSocket セッションを処理するエンドポイントを定義できます。サーバー上に WebSocket エンドポイントを定義するには、ルーティングブロック内で webSocket 関数を呼び出します:

kotlin
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 エンドポイントを作成する方法を示しています:

kotlin
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 通信を管理するためのスケーラブルで並行処理に適した手法が提供されます。このパターンの実装方法は以下のとおりです:

  1. メッセージをブロードキャストするための SharedFlow を定義します:
kotlin
val messageResponseFlow = MutableSharedFlow<MessageResponse>()
val sharedFlow = messageResponseFlow.asSharedFlow()
  1. WebSocket ルートで、ブロードキャストおよびメッセージ処理ロジックを実装します:
kotlin

        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 またはその他の例外)が発生した場合にのみ無限ループが終了します:

kotlin
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()
    }
}