Skip to content
Client Plugin

Ktor Client における Server-Sent Events

コード例: client-sse

Server-Sent Events(SSE)は、サーバーが HTTP 接続を介してクライアントにイベントを継続的にプッシュできるようにする技術です。クライアントがサーバーに対して繰り返しポーリングを行うことなく、サーバーからイベントベースの更新を送信する必要がある場合に特に有用です。

Ktor がサポートする SSE プラグインは、サーバーとクライアント間の単方向接続を作成するための分かりやすい方法を提供します。

サーバー側のサポートを提供する SSE プラグインの詳細については、 SSE サーバープラグインSSE プラグインを使用すると、サーバーは HTTP 接続を介してイベントベースの更新をクライアントに送信できます。 を参照してください。

依存関係の追加

SSE に必要なのは ktor-client-core既存のプロジェクトにクライアントの依存関係を追加する方法を学びます。 アーティファクトのみであり、特定の個別依存関係は必要ありません。

SSE のインストール

SSE プラグインをインストールするには、クライアント構成ブロック内で install 関数に渡します。

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

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

SSE プラグインの設定

必要に応じて、SSEConfig クラスのサポートされているプロパティを設定することで、install ブロック内で SSE プラグインを構成できます。

SSE の再接続

自動再接続を有効にするには、maxReconnectionAttempts を 0 より大きい値に設定します。また、reconnectionTime を使用して試行間の遅延を設定することもできます。

kotlin
install(SSE) {
    maxReconnectionAttempts = 4
    reconnectionTime = 2.seconds
}

サーバーへの接続が失われた場合、クライアントは指定された reconnectionTime だけ待機してから再接続を試みます。接続を再確立するために、指定された maxReconnectionAttempts まで試行を繰り返します。

イベントのフィルタリング

以下の例では、SSE プラグインを HTTP クライアントにインストールし、受信フローにコメントのみを含むイベントと retry フィールドのみを含むイベントを含めるように構成しています。

kotlin
install(SSE) {
    showCommentEvents()
    showRetryEvents()
}

レスポンスのバッファリング

SSE レスポンスは本質的にストリーミングであるため、ボディ全体をキャプチャすることは実用的ではありません。SSE ストリームで障害が発生したときにレスポンスボディを安全に取得できるよう、診断用バッファを有効にできます。このバッファには既に処理されたデータのみが含まれ(ネットワークからの再読み込みは行われません)、障害発生時のロギングやエラー分析を目的としています。

kotlin
install(SSE) {
    bufferPolicy = SSEBufferPolicy.LastEvents(10)
}

呼び出しごとにバッファを構成することもできます。

kotlin
client.sse(url, {
    bufferPolicy(SSEBufferPolicy.All)
}) {
    // ...
}

バッファポリシー

SSEBufferPolicy タイプは、処理された SSE データを保存するためのいくつかの戦略を提供します。これらのポリシーは、ストリームのどの程度をメモリに保持し、エラー発生時に利用可能にするかを制御します。

Off(デフォルト)
バッファリングを行いません。
LastLines(n)
直近の n 行を保持します。
LastEvent
最後に完了した SSE イベントを保持します。
LastEvents(n)
直近の完了した n 個の SSE イベントを保持します。
All
それまでに処理されたすべてのイベントを保持します。
長時間実行されるストリームでは注意して使用してください。

障害が発生した場合は、ネットワークから再読み込みすることなく response?.bodyAsText() を使用してバッファにアクセスできます。

SSE セッションの処理

クライアントの SSE セッションは、ClientSSESession インターフェースによって表されます。このインターフェースは、サーバーから Server-Sent Events を受信するための API を公開しています。

SSE セッションへのアクセス

HttpClient では、次のいずれかの方法で SSE セッションにアクセスできます。

  • sse() 関数は、SSE セッションを作成し、そのセッションに対する操作を可能にします。
  • sseSession() 関数を使用すると、SSE セッションを開くことができます。

URL エンドポイントを指定するには、2 つのオプションから選択できます。

  • urlString パラメータを使用して、URL 全体を文字列として指定します。
  • schema、host、port、および path パラメータを使用して、プロトコルスキーム、ドメイン名、ポート番号、パス名をそれぞれ個別に指定します。
kotlin
runBlocking {
    client.sse(host = "127.0.0.1", port = 8080, path = "/events") {
        // this: ClientSSESession
    }
}
ClientSSESession および ClientSSESessionWithDeserialization インスタンスは、セッションの継続期間中のみ有効です。これらのスコープは、serverSentEvents { ... } ブロックが完了するか接続が閉じられると自動的にキャンセルされます。

オプションとして、接続を構成するために以下のパラメータが利用可能です。

reconnectionTime
再接続の遅延時間を設定します。
showCommentEvents
受信フローにコメントのみを含むイベントを表示するかどうかを指定します。
showRetryEvents
受信フローに retry フィールドのみを含むイベントを表示するかどうかを指定します。
deserialize
TypedServerSentEvent の data フィールドをオブジェクトに変換するためのデシリアライザ関数です。詳細については、デシリアライゼーションを参照してください。

SSE セッションブロック

ラムダ引数内では、ClientSSESession コンテキストにアクセスできます。ブロック内では以下のプロパティが使用可能です。

call
セッションを開始した関連付けられている HttpClientCall。
incoming
受信する Server-Sent Events のフロー。

以下の例では、events エンドポイントを使用して新しい SSE セッションを作成し、incoming プロパティを介してイベントを読み取り、受信した ServerSentEvent を出力します。

kotlin
fun main() {
    val client = HttpClient {
        install(SSE) {
            showCommentEvents()
            showRetryEvents()
        }
    }
    runBlocking {
        client.sse(host = "0.0.0.0", port = 8080, path = "/events") {
            while (true) {
                incoming.collect { event ->
                    println("Event from server:")
                    println(event)
                }
            }
        }
    }
}

完全なコード例については、client-sse を参照してください。

デシリアライゼーション

SSE プラグインは、Server-Sent Events からタイプセーフな Kotlin オブジェクトへのデシリアライゼーションをサポートしています。この機能は、サーバーからの構造化データを処理する際に特に便利です。

デシリアライゼーションを有効にするには、SSE アクセス関数の deserialize パラメータを使用してカスタムのデシリアライゼーション関数を指定し、ClientSSESessionWithDeserialization クラスを使用してデシリアライズされたイベントを処理します。

以下は、JSON データをデシリアライズするために kotlinx.serialization を使用する例です。

kotlin
client.sse({
    url("http://localhost:8080/serverSentEvents")
}, deserialize = {
        typeInfo, jsonString ->
    val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
    Json.decodeFromString(serializer, jsonString)!!
}) { // `this` is `ClientSSESessionWithDeserialization`
    incoming.collect { event: TypedServerSentEvent<String> ->
        when (event.event) {
            "customer" -> {
                val customer: Customer? = deserialize<Customer>(event.data)
            }
            "product" -> {
                val product: Product? = deserialize<Product>(event.data)
            }
        }
    }
}

完全なコード例については、client-sse を参照してください。