Server Plugin

KtorサーバーでのServer-Sent Events (SSE)

必須の依存関係: io.ktor:ktor-server-sse

コード例: server-sse

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

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

TIP

クライアント側のSSEプラグインについては、

SSEクライアントプラグイン

SSEプラグインを使用すると、クライアントはHTTP接続経由でサーバーからイベントベースの更新を受信できます。

を参照してください。

NOTE

双方向通信には

WebSockets

WebSocketsプラグインを使用すると、サーバーとクライアント間で双方向通信セッションを作成できます。

の使用を検討してください。WebSocketsは、WebSocketプロトコルを使用してサーバーとクライアント間で全二重通信を提供します。

制限事項

KtorはSSEレスポンスのデータ圧縮をサポートしていません。

Compression

必須の依存関係: io.ktor:ktor-server-sse コード例: server-sse ネイティブサーバーサポート: ✖️

プラグインを使用している場合、デフォルトでSSEレスポンスの圧縮はスキップされます。

依存関係の追加

SSE を使用するには、ビルドスクリプトに ktor-server-sse アーティファクトを含める必要があります。

Gradle (Kotlin)Gradle (Groovy)Maven

SSEのインストール

アプリケーションに SSE プラグインをインストールするには、指定された

モジュール

モジュールを使用すると、ルートをグループ化することでアプリケーションを構造化できます。

の install 関数に渡します。 以下のコードスニペットは、SSE をインストールする方法を示しています...

• ... embeddedServer 関数呼び出し内で。
• ... Application クラスの拡張関数である、明示的に定義された module 内で。

embeddedServermodule

SSEセッションの処理

SSE プラグインをインストールしたら、SSEセッションを処理するためのルートを追加できます。 そのためには、ルーティング ブロック内で sse() 関数を呼び出します。SSEルートを設定するには、2つの方法があります。

1. 特定のURLパスを使用する場合:

2. パスなしの場合:

SSEセッションブロック

sse ブロック内では、指定されたパスのハンドラを定義します。これは ServerSSESession クラスで表されます。このブロック内で利用できる関数とプロパティは次のとおりです。

send()

ServerSentEvent を作成し、クライアントに送信します。

call

セッションの起点となった関連する受信 ApplicationCall です。

close()

セッションを閉じ、クライアントとの接続を終了します。すべての send() 操作が完了すると、close() メソッドが自動的に呼び出されます。

NOTE

close() 関数を使用してセッションを閉じても、クライアントに終了イベントは送信されません。セッションを閉じる前にSSEストリームの終了を示すには、send() 関数を使用して特定のイベントを送信します。

例: 単一セッションの処理

以下の例では、/events エンドポイントでSSEセッションを設定し、SSEチャネル経由で6つの個別のイベントをそれぞれ1秒（1000ミリ秒）の間隔で送信する方法を示します。

完全な例は server-sse を参照してください。

SSEハートビート

ハートビートは、非アクティブ期間中に定期的にイベントを送信することで、SSE接続がアクティブな状態を維持するようにします。セッションがアクティブである限り、サーバーは設定された間隔で指定されたイベントを送信します。

ハートビートを有効にして設定するには、SSEルートハンドラ内で .heartbeat() 関数を使用します。

この例では、接続を維持するために10ミリ秒ごとにハートビートイベントが送信されます。

シリアライズ

シリアライズを有効にするには、SSEルートの serialize パラメータを使用してカスタムシリアライズ関数を提供します。ハンドラ内で、 ServerSSESessionWithSerialization クラスを使用して、シリアライズされたイベントを送信できます。

この例の serialize 関数は、データオブジェクトをJSONに変換し、それを ServerSentEvent の data フィールドに配置する役割を担っています。

完全な例は server-sse を参照してください。