Server-Sent Events

Server-Sent Events (SSE) is a technology that allows a server to continuously push events to a client over an HTTP connection. It's particularly useful in cases where the server needs to send event-based updates without requiring the client to repeatedly poll the server.

The SSE plugins supported by Ktor provide a straightforward method for creating a one-way connection between the server and the client.

Add dependencies

SSE only requires the ktor-client-core artifact and doesn't need any specific dependencies.

Install SSE

To install the SSE plugin, pass it to the install function inside a client configuration block:

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.sse.*

//...
val client = HttpClient(CIO) {
    install(SSE)
}

Configure the SSE plugin

Optionally, you can configure the plugin inside the install block by passing the supported properties of the SSEConfig class.

Use the reconnectionTime property to specify a reconnection time. If the connection to the server is lost, the client will wait for the specified time before attempting to reconnect.

Use the showCommentEvents() function to add events consisting only of comments in the incoming flow.
Use the showRetryEvents() function to add events consisting only of the retry field in the incoming flow.

    val client = HttpClient {
        install(SSE) {
            showCommentEvents()
            showRetryEvents()
        }
    }

Handle an SSE session

API overview

A client's SSE session is represented by the DefaultClientSSESession interface. This interface exposes the API that allows you to receive SSE events from a server.

The HttpClient allows you to get access to an SSE session in one of the following ways:

The sse() function creates the SSE session and allows you to act on it.
The sseSession() function allows you to open an SSE session.

The following parameters are available to both functions. To specify the URL endpoint, choose from two options:

Use the urlString parameter to specify the whole URL as a string.
Use the schema, host, port, and path parameters to specify the protocol scheme, domain name, port number and path name respectively.

   runBlocking {
      client.sse(host = "127.0.0.1", port = 8080, path = "/events") {
           // this: ClientSSESession
       }
   }

Optionally, use the following parameters to configure the connection:

Use the reconnectionTime parameter to specify a reconnection time.
Use the showCommentEvents parameter to specify whether to show events consisting only of comments in the incoming flow.
Use the showRetryEvents parameter to specify whether to show events consisting only of the retry field in the incoming flow.

Within the lambda argument, you have access to the ClientSSESession context. Use the incoming property to access the channel for receiving events.

Example

The example below creates a new SSE session with the events endpoint, reads events through the incoming property and prints the received 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.close()
}

For the full example, see client-sse.

Last modified: 28 September 2023