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 関数に渡します。
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 を使用して試行間の遅延を設定することもできます。
install(SSE) {
maxReconnectionAttempts = 4
reconnectionTime = 2.seconds
} サーバーへの接続が失われた場合、クライアントは指定された reconnectionTime だけ待機してから再接続を試みます。接続を再確立するために、指定された maxReconnectionAttempts まで試行を繰り返します。
イベントのフィルタリング
以下の例では、SSE プラグインを HTTP クライアントにインストールし、受信フローにコメントのみを含むイベントと retry フィールドのみを含むイベントを含めるように構成しています。
install(SSE) {
showCommentEvents()
showRetryEvents()
}レスポンスのバッファリング
SSE レスポンスは本質的にストリーミングであるため、ボディ全体をキャプチャすることは実用的ではありません。SSE ストリームで障害が発生したときにレスポンスボディを安全に取得できるよう、診断用バッファを有効にできます。このバッファには既に処理されたデータのみが含まれ(ネットワークからの再読み込みは行われません)、障害発生時のロギングやエラー分析を目的としています。
install(SSE) {
bufferPolicy = SSEBufferPolicy.LastEvents(10)
}呼び出しごとにバッファを構成することもできます。
client.sse(url, {
bufferPolicy(SSEBufferPolicy.All)
}) {
// ...
}バッファポリシー
SSEBufferPolicy タイプは、処理された SSE データを保存するためのいくつかの戦略を提供します。これらのポリシーは、ストリームのどの程度をメモリに保持し、エラー発生時に利用可能にするかを制御します。
Off(デフォルト)LastLines(n)LastEventLastEvents(n)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パラメータを使用して、プロトコルスキーム、ドメイン名、ポート番号、パス名をそれぞれ個別に指定します。
runBlocking {
client.sse(host = "127.0.0.1", port = 8080, path = "/events") {
// this: ClientSSESession
}
}ClientSSESession および ClientSSESessionWithDeserialization インスタンスは、セッションの継続期間中のみ有効です。これらのスコープは、serverSentEvents { ... } ブロックが完了するか接続が閉じられると自動的にキャンセルされます。 オプションとして、接続を構成するために以下のパラメータが利用可能です。
reconnectionTimeshowCommentEventsshowRetryEventsretry フィールドのみを含むイベントを表示するかどうかを指定します。 deserializeTypedServerSentEvent の data フィールドをオブジェクトに変換するためのデシリアライザ関数です。詳細については、デシリアライゼーションを参照してください。 SSE セッションブロック
ラムダ引数内では、ClientSSESession コンテキストにアクセスできます。ブロック内では以下のプロパティが使用可能です。
callHttpClientCall。 incoming 以下の例では、events エンドポイントを使用して新しい SSE セッションを作成し、incoming プロパティを介してイベントを読み取り、受信した ServerSentEvent を出力します。
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 を使用する例です。
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 を参照してください。
