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:
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.
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
, andpath
parameters to specify the protocol scheme, domain name, port number and path name respectively.
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
.
For the full example, see client-sse.