Ktor Server における Server-Sent Events
必要な依存関係: io.ktor:ktor-server-sse
コード例: server-sse
Server-Sent Events (SSE) は、サーバーが HTTP 接続を介してクライアントにイベントを継続的にプッシュできるようにする技術です。クライアントがサーバーに対して繰り返しポーリングを行う必要なく、サーバーがイベントベースの更新を送信する必要がある場合に特に有用です。
Ktor がサポートする SSE プラグインは、サーバーとクライアント間に単方向の接続を作成するためのシンプルな方法を提供します。
クライアント側のサポートを目的とした SSE プラグインの詳細については、 SSE クライアントプラグインSSE プラグインを使用すると、クライアントは HTTP 接続を介してサーバーからイベントベースの更新を受信できます。 を参照してください。
双方向通信を行う場合は、WebSocketsWebsockets プラグインを使用すると、サーバーとクライアント間で双方向の通信セッションを作成できます。 の使用を検討してください。WebSocket プロトコルを使用して、サーバーとクライアント間の全二重通信を提供します。
制限事項
Ktor は SSE レスポンスのデータ圧縮をサポートしていません。 Compression必要な依存関係: io.ktor:ktor-server-compression プラグインを使用している場合、デフォルトで SSE レスポンスの圧縮はスキップされます。
依存関係の追加
SSE を使用するには、ビルドスクリプトに ktor-server-sse アーティファクトを追加します:
implementation(ktorLibs.server.sse)implementation ktorLibs.server.sse<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-sse-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>SSE のインストール
アプリケーションに SSE プラグインをインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、SSE をインストールする方法を示しています:
embeddedServer()関数の呼び出し内。Applicationクラスに明示的に定義されたmodule()拡張関数内。
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.sse.*
fun main() {
embeddedServer(Netty, port = 8080) {
install(SSE)
// ...
}.start(wait = true)
}import io.ktor.server.application.*
import io.ktor.server.sse.*
// ...
fun Application.module() {
install(SSE)
// ...
}SSE セッションの処理
SSE プラグインをインストールしたら、SSE セッションを処理するルートを追加できます。 これを行うには、routing ブロック内で sse() 関数を呼び出します。SSE ルートを設定する方法は 2 つあります:
特定の URL パスを指定する場合:
kotlinrouting { sse("/events") { // send events to clients } }パスを指定しない場合:
kotlinrouting { sse { // send events to clients } }
SSE セッションブロック
sse ブロック内では、指定されたパスのハンドラーを定義します。これは ServerSSESession クラスによって表されます。ブロック内では以下の関数やプロパティを使用できます:
send()ServerSentEvent を作成し、クライアントに送信します。 callApplicationCall。 close()close() メソッドは、すべての send() 操作が完了したときに自動的に呼び出されます。 close() 関数を使用してセッションをクローズしても、終了イベントはクライアントに送信されません。セッションをクローズする前に SSE ストリームの終了を示すには、send() 関数を使用して特定のイベントを送信してください。 例: 単一セッションの処理
以下の例は、/events エンドポイントに SSE セッションを設定し、各イベントの間に 1 秒(1000ms)の遅延を挟んで SSE チャネル経由で 6 つの個別のイベントを送信する方法を示しています:
routing {
sse("/events") {
repeat(6) {
send(ServerSentEvent("this is SSE #$it"))
delay(1000)
}
}
}完全な例については、 server-sse を参照してください。
SSE ハートビート
ハートビートは、定期的にイベントを送信することで、無通信状態の間も SSE 接続をアクティブに保ちます。セッションがアクティブである限り、サーバーは設定された間隔で指定されたイベントを送信します。
ハートビートを有効にして設定するには、SSE ルートハンドラー内で .heartbeat() 関数を使用します:
sse("/heartbeat") {
heartbeat {
period = 10.milliseconds
event = ServerSentEvent("heartbeat")
}
// ...
}この例では、接続を維持するために 10 ミリ秒ごとにハートビートイベントが送信されます。
eventProvider プロパティを使用して、ハートビートイベントを動的に生成することもできます:
sse("/heartbeat-custom") {
heartbeat {
period = 30.milliseconds
eventProvider = {
ServerSentEvent(data = "ts=${Clock.System.now()}")
}
}
// ...
} 設定されている場合、eventProvider はハートビートの各ティックで呼び出され、ServerSentEvent を生成します。これにより、タイムスタンプやステータス情報などの動的コンテンツをハートビートイベントに含めることができます。
event と eventProvider の両方が設定されている場合、eventProvider が event よりも優先されます。
シリアライズ
シリアライズを有効にするには、SSE ルートの serialize パラメーターを使用してカスタムシリアライズ関数を指定します。ハンドラー内では、 ServerSSESessionWithSerialization クラスを使用して、シリアライズされたイベントを送信できます:
@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)
@Serializable
data class Product(val id: Int, val prices: List<Int>)
fun Application.module() {
install(SSE)
routing {
// example with serialization
sse("/json", serialize = { typeInfo, it ->
val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
Json.encodeToString(serializer, it)
}) {
send(Customer(0, "Jet", "Brains"))
send(Product(0, listOf(100, 200)))
}
}
} この例の serialize 関数は、データオブジェクトを JSON に変換する役割を果たし、変換された JSON は ServerSentEvent の data フィールドに配置されます。
完全な例については、 server-sse を参照してください。
