Skip to content
Server Plugin

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 アーティファクトを追加します:

kotlin
implementation(ktorLibs.server.sse)
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
groovy
implementation ktorLibs.server.sse
上記のコードスニペットでは、Ktor の依存関係を指定するために Ktor バージョンカタログ を使用しています。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-sse-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

SSE のインストール

アプリケーションに SSE プラグインをインストールするには、指定されたモジュールモジュールを使用すると、ルートをグループ化してアプリケーションを構造化できます。内の install 関数に渡します。 以下の例は、SSE をインストールする方法を示しています:

  • embeddedServer() 関数の呼び出し内。
  • Application クラスに明示的に定義された module() 拡張関数内。
kotlin
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)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.sse.*
// ...
fun Application.module() {
    install(SSE)
    // ...
}

SSE セッションの処理

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

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

    kotlin
    routing {
        sse(&quot;/events&quot;) {
            // send events to clients
        }
    }
  2. パスを指定しない場合:

    kotlin
    routing {
        sse {
            // send events to clients
        }
    }

SSE セッションブロック

sse ブロック内では、指定されたパスのハンドラーを定義します。これは ServerSSESession クラスによって表されます。ブロック内では以下の関数やプロパティを使用できます:

send()
ServerSentEvent を作成し、クライアントに送信します。
call
セッションの起点となった、関連する受信 ApplicationCall。
close()
セッションをクローズし、クライアントとの接続を終了します。close() メソッドは、すべての send() 操作が完了したときに自動的に呼び出されます。
close() 関数を使用してセッションをクローズしても、終了イベントはクライアントに送信されません。セッションをクローズする前に SSE ストリームの終了を示すには、send() 関数を使用して特定のイベントを送信してください。

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

以下の例は、/events エンドポイントに SSE セッションを設定し、各イベントの間に 1 秒(1000ms)の遅延を挟んで SSE チャネル経由で 6 つの個別のイベントを送信する方法を示しています:

kotlin
routing {
    sse("/events") {
        repeat(6) {
            send(ServerSentEvent("this is SSE #$it"))
            delay(1000)
        }
    }
}

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

SSE ハートビート

ハートビートは、定期的にイベントを送信することで、無通信状態の間も SSE 接続をアクティブに保ちます。セッションがアクティブである限り、サーバーは設定された間隔で指定されたイベントを送信します。

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

kotlin
sse("/heartbeat") {
    heartbeat {
        period = 10.milliseconds
        event = ServerSentEvent("heartbeat")
    }
    // ...
}

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

eventProvider プロパティを使用して、ハートビートイベントを動的に生成することもできます:

kotlin
sse("/heartbeat-custom") {
    heartbeat {
        period = 30.milliseconds
        eventProvider = {
            ServerSentEvent(data = "ts=${Clock.System.now()}")
        }
    }
    // ...
}

設定されている場合、eventProvider はハートビートの各ティックで呼び出され、ServerSentEvent を生成します。これにより、タイムスタンプやステータス情報などの動的コンテンツをハートビートイベントに含めることができます。

event と eventProvider の両方が設定されている場合、eventProvider が event よりも優先されます。

シリアライズ

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

kotlin
@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 を参照してください。