Server-Sent Events

Client Plugin

Ktor Client における Server-Sent Events

コード例: client-sse

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

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

TIP

サーバー側のサポートのための SSE プラグインの詳細については、

SSE サーバープラグイン

The SSE plugin allows a server to send event-based updates to a client over an HTTP connection.

を参照してください。

依存関係の追加

SSE は

ktor-client-core

Learn how to add client dependencies to an existing project.

アーティファクトのみを必要とし、特定の依存関係は必要ありません。

SSE のインストール

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

SSE プラグインの設定

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

SSE の再接続

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

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

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

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

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

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

コールごとにバッファを設定することもできます。

バッファポリシー

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

<code>Off</code> (デフォルト)

バッファリングなし。

<code>LastLines(n)</code>

直近の n 行を保持します。

<code>LastEvent</code>

最後に完了した SSE イベントを保持します。

<code>LastEvents(n)</code>

直近の n 個の完了した SSE イベントを保持します。

<code>All</code>

これまでに処理されたすべてのイベントを保持します。

NOTE

長期間存続するストリームでは注意して使用してください。

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

SSE セッションの処理

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

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

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

• sse() 関数は、SSE セッションを作成し、それに対してアクションを実行できるようにします。
• sseSession() 関数を使用すると、SSE セッションを開くことができます。

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

• urlString パラメータを使用して、URL 全体を文字列として指定します。
• schema、host、port、path パラメータを使用して、それぞれプロトコルスキーム、ドメイン名、ポート番号、パス名を指定します。

NOTE

ClientSSESession および ClientSSESessionWithDeserialization のインスタンスは、セッションの期間中のみ有効です。serverSentEvents { ... } ブロックが完了するか、接続が閉じられると、それらのスコープは自動的にキャンセルされます。

オプションで、接続を設定するために以下のパラメータを使用できます。

<code>reconnectionTime</code>

再接続の遅延を設定します。

<code>showCommentEvents</code>

受信フローにコメントのみを含むイベントを表示するかどうかを指定します。

<code>showRetryEvents</code>

受信フローに retry フィールドのみを含むイベントを表示するかどうかを指定します。

<code>deserialize</code>

TypedServerSentEvent の data フィールドをオブジェクトに変換するためのデシリアライザー関数。詳細については、デシリアライズを参照してください。

SSE セッションブロック

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

<code>call</code>

セッションを開始した、関連付けられた HttpClientCall。

<code>incoming</code>

受信するサーバー送信イベントのフロー。

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

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

デシリアライズ

SSE プラグインは、サーバー送信イベントの型安全な Kotlin オブジェクトへのデシリアライズをサポートしています。この機能は、サーバーからの構造化されたデータを扱う場合に特に有用です。

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

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

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