Server-sent events
Server-sent events (text/event-stream) keep one HTTP response open and push messages to the client as they happen. A controller method returns a stream of values, or an SseEmitter that other code sends events to.
Why
Some answers are not one value but a series that arrives over time: notifications, the progress of a job, live prices, the tokens of a language model. Polling asks again and again and wastes requests. A WebSocket works in both directions but needs its own protocol and endpoint. Server-sent events are plain HTTP:
- the browser reads them with
EventSource, which reconnects by itself; - proxies, CORS, cookies and the security filter chain work as for any request;
- each event can carry an id, so a client that reconnects can resume.
Use them when the server talks and the client listens. Use a WebSocket when both sides send messages.
The starter offers two shapes:
- A stream (
EventStream<T>orStream<T>), when the events come from one source known when the request arrives: a database change feed, aStreamController, a Feign client's own event stream. - An
SseEmitter, when the events come from elsewhere, later: an event listener, a scheduled task, another request. The method creates the emitter, keeps it somewhere, and returns it. Other code callssend.
Example
import 'dart:async';
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
class Order {
const Order({required this.id, required this.total});
final String id;
final int total;
}
@Service()
class OrderFeed {
final _changes = StreamController<Order>.broadcast();
final _history = <Order>[];
Stream<Order> changes() => _changes.stream;
// The orders after the one with [id] (all of them for an unknown id),
// then the new ones.
Stream<Order> since(String id) async* {
final start = _history.indexWhere((order) => order.id == id) + 1;
yield* Stream.fromIterable(_history.sublist(start));
yield* _changes.stream;
}
void placed(Order order) {
_history.add(order);
_changes.add(order);
}
}
@RestController()
@RequestMapping('/api/orders')
class OrderEventsController {
OrderEventsController(this.feed, this.notifications);
final OrderFeed feed;
final Notifications notifications;
// Every change as one event, named and with an id.
@GetMapping('/changes')
EventStream<Order> changes() => EventStream(
() => feed.changes().map(
(order) => ServerSentEvent(order, id: order.id, event: 'order'),
),
);
// A plain Stream works too: each item is one unnamed event.
@GetMapping('/totals')
Stream<int> totals() => feed.changes().map((order) => order.total);
// The same data as NDJSON: one JSON object per line, no event fields.
@GetMapping.of(path: '/export', produces: 'application/x-ndjson')
Stream<Order> export() => feed.changes();
// A reconnecting EventSource sends the last id it saw.
@GetMapping('/resume')
Stream<ServerSentEvent<Order>> resume(
@RequestHeader('Last-Event-ID') String? lastId,
) => (lastId == null ? feed.changes() : feed.since(lastId)).map(
(order) => ServerSentEvent(order, id: order.id),
);
// Events that other code sends later.
@GetMapping('/notifications')
SseEmitter subscribe() => notifications.subscribe();
}
@Service()
class Notifications {
final _emitters = <SseEmitter>{};
SseEmitter subscribe() {
final emitter = SseEmitter(timeout: const Duration(minutes: 30));
_emitters.add(emitter);
// Runs once, whatever ends the emitter: complete, timeout, error,
// a client that went away.
emitter.onCompletion(() => _emitters.remove(emitter));
return emitter;
}
Future<void> broadcast(Order order) async {
for (final emitter in [..._emitters]) {
try {
await emitter.send(ServerSentEvent(order, event: 'order', id: order.id));
} on StateError {
// The client went away; onCompletion has removed it.
}
}
}
}
# lib/resources/application.yaml
spring:
mvc:
sse:
heartbeat-interval: 15s # a comment line every 15 s on idle streams
async:
request-timeout: 10m # emitters without their own timeout end after 10 min
What the client receives from /api/orders/changes:
:
id: 42
event: order
data: {"id":"42","total":1900}
The first : line is an empty comment. Clients ignore it. It is explained under "What is written" below.
Which results are event streams
| Return type of the method | Written as |
|---|---|
EventStream<T> |
One event per item. The whole ServerSentEvent of each item is used (its id, event, retry, comment). |
Stream<T> |
One event per item, when the declared type is not a byte stream. An item that is a ServerSentEvent keeps its fields; any other value is the event's data. |
Stream<ServerSentEvent<T>> |
One event per item, with its fields. |
Stream<T> with produces: 'application/x-ndjson' |
NDJSON: each item's data as one line of JSON, Content-Type: application/x-ndjson. The id, event, retry and comment of a ServerSentEvent are dropped. |
SseEmitter |
One event per send. Always text/event-stream. |
ResponseEntity<EventStream<T>>, ResponseEntity<Stream<T>>, ResponseEntity<SseEmitter> |
The same events, with the entity's status and headers. |
Rules:
- A method declared to return
Stream<Uint8List>orStream<List<int>>writes raw bytes, not events. See StreamingResponseBody. - A method that returns a
Futureof a stream (Future<Stream<T>>,Future<EventStream<T>>) fails the startup: return the stream itself. Do the asynchronous work inside the stream (async*, orStream.fromFuture(...).asyncExpand(...)). AFuture<SseEmitter>is fine. - Any HTTP method can answer with events,
POSTincluded. MCP's Streamable HTTP transport does this. - The
Content-Typeof an event stream is alwaystext/event-stream;charset=UTF-8, also when aResponseEntitysets another one.
What is written
- Headers:
Content-Type: text/event-stream;charset=UTF-8andCache-Control: no-cache, plus the status and headers of aResponseEntity. - A first comment line.
dart:iosends the status and headers only together with the first bytes of the body. So that the client sees the response at once, and not only with the first event, every event stream starts with:and a blank line. Clients skip comment lines. NDJSON responses do not get it. - One event per item, in this order: the
commentlines (each starting with:),id:,event:,retry:(whole milliseconds), then thedata:lines, then a blank line. A value with line breaks becomes several lines of the same field. Anullfield is left out. Anulldata gives nodata:line. - The data: a
Stringis written as it is. Any other value is turned into JSON by the application'sObjectMapper, as a response body would be. See JSON. - Back pressure. While one event is written and flushed, the source stream is paused. A client that reads slowly slows the stream down. The server does not queue events in memory for it.
- Compression.
text/event-streamis not in the defaultserver.compression.mime-types. Add it to compress event streams; each flush then sends what was compressed so far. See Compression.
EventStream<T>
EventStream<T> (from spring_web_dart) is a Stream<T> of the events' data that keeps the whole events in its events getter. The same type is the return type of a Feign client method that reads an event stream, so a controller can pass a client's stream on.
| Constructor | What each listener gets |
|---|---|
EventStream(Stream<ServerSentEvent<T>> Function() open) |
The events of a new open() call. Use it when each response should get its own source. |
EventStream.fromEvents(Stream<ServerSentEvent<T>> events) |
The given events. A second listener listens to the same stream again, which fails for a single-subscription stream. |
EventStream.of(Stream<T> data) |
Events with the values of data, without id or name. |
EventStream.fromIterable(Iterable<T> values) |
Events with these values, then the end. For tests and fallbacks. |
EventStream.empty() |
No event: the response ends at once. |
| Member | Meaning |
|---|---|
events |
The whole ServerSentEvents. The server reads this one. |
lastEventId |
The last id seen by any listener of this object, or null. Used by Feign clients when they reconnect. |
The stream is cold: nothing happens until the response starts listening. The server listens once per response, and cancels the subscription when the response ends.
ServerSentEvent<T>
| Field | Type | Default | Meaning |
|---|---|---|---|
data (positional) |
T |
required | The payload: the data: lines. |
id |
String? |
null |
The event id. A browser sends the last one back in Last-Event-ID when it reconnects. |
event |
String? |
null |
The event name. null is an unnamed event, which EventSource delivers to onmessage; a named one goes to addEventListener(name, ...). |
retry |
Duration? |
null |
How long the client should wait before it reconnects. Written in whole milliseconds. |
comment |
String? |
null |
Comment lines. Clients ignore them. |
withData(other) gives the same event with other data. encode() gives the text an event is written as.
SseEmitter
| Member | Meaning |
|---|---|
SseEmitter({Duration? timeout}) |
A new emitter. timeout counts from when the response starts. null takes spring.mvc.async.request-timeout. Zero or negative means no timeout. |
timeout |
The timeout given to the constructor. |
Future<void> send(Object? data) |
Sends one event. A ServerSentEvent keeps its fields; any other value is the data of an unnamed event. |
void complete() |
Ends the response normally, after the events sent so far are written. Does nothing when the emitter has already ended. |
void completeWithError(Object error) |
Ends the response because of error. The error is logged as a warning. |
void onCompletion(void Function() callback) |
Runs callback once when the emitter ends, for any reason. |
void onTimeout(void Function() callback) |
Runs callback when the timeout passes, before the emitter completes. |
void onError(void Function(Object error) callback) |
Runs callback when a send fails or completeWithError is called. |
bool isComplete |
Whether the emitter has ended: completed, timed out, failed, or the client went away. |
initialize(handler, defaultTimeout: ...) |
Connects the emitter to the response. The starter calls it. Applications do not. |
How send behaves
- Before the response is ready, the event is buffered. The method may send events before it returns the emitter. They are written first when the response starts.
- The returned
Futurecompletes when the event is written to the client. Await it to send at the client's pace. - After the emitter has ended,
sendthrows aStateError(The SseEmitter has already completed). CheckisCompleteor catch the error. - When the write fails (the client went away), the emitter ends: the
onErrorcallbacks run, then theonCompletioncallbacks, and the error is rethrown. - When sends are not awaited and 1000 events are already waiting for a client that reads nothing, the next
sendfails with aStateError(The client does not read the event stream: 1000 events are waiting) and the emitter ends. A stalled client cannot fill the server's memory.
How an emitter ends
| Cause | Callbacks, in order | The client sees |
|---|---|---|
complete() |
onCompletion |
The stream ends normally. |
completeWithError(e) |
onError(e), onCompletion |
The stream ends. The status was already 200, so no error status can be sent. |
| The timeout passes | onTimeout, onCompletion |
The stream ends. |
| A send fails | onError(e), onCompletion |
The connection is gone. |
| The client goes away | onCompletion |
Nothing: it is gone. |
| The server stops | onCompletion |
The stream ends. Open event streams are closed at once, in graceful shutdown too. See Shutdown. |
complete() and completeWithError() called before the response starts are kept: the buffered events are written, then the response ends.
SseEmitterHandler
The response an emitter writes to is an SseEmitterHandler: send(event), complete(), completeWithError(error) and done. A unit test can implement it and call emitter.initialize(handler) to see what a service sends, without a server.
Streams: errors and disconnects
-
The client goes away: the server cancels its subscription to the stream. A
StreamControllerseesonCancel; anasync*generator stops at its nextyield. -
The stream emits an error: a warning is logged (
The stream of GET /api/orders/changes failed) and the response ends. The status has gone out already, so the client only sees the end of the stream. To tell the client, catch the error in the stream and send an event for it:// A failure becomes a last event named `failed`, then the stream ends. @GetMapping('/safe-changes') Stream<ServerSentEvent<Object>> safeChanges() => feed .changes() .map((order) => ServerSentEvent<Object>(order, id: order.id)) .transform( StreamTransformer< ServerSentEvent<Object>, ServerSentEvent<Object> >.fromHandlers( handleError: (error, stackTrace, sink) => sink ..add(const ServerSentEvent<Object>('retry later', event: 'failed')) ..close(), ), ); -
The stream ends: the response ends once the last event is written.
-
An exception before the first event (the method itself throws) is answered as any error: an
@ExceptionHandleror aProblemDetail. See Errors.
Properties
spring.mvc.sse.heartbeat-interval
| Key | Type | Default |
|---|---|---|
spring.mvc.sse.heartbeat-interval |
Duration |
none |
Writes a comment line (: and a blank line) into every open event stream at this interval.
- Why: proxies, load balancers and some mobile networks close a connection that has sent nothing for a while (nginx's
proxy_read_timeoutis 60 seconds by default). A stream that waits a long time for its next event then breaks. A heartbeat keeps it alive. Clients ignore comment lines. - How: the comment is written only when nothing else is being written, so heartbeats never pile up behind a client that does not read. It applies to
EventStream,StreamandSseEmitterresponses, not to NDJSON. - Values: a duration such as
15sorPT15S. A plain number is milliseconds. Not set, zero or negative: no heartbeat. - Pick a value below the shortest idle timeout on the way, for example
15sor30s. - This key is this starter's own. Spring Boot has no such property.
spring:
mvc:
sse:
heartbeat-interval: 20s
spring.mvc.async.request-timeout
| Key | Type | Default |
|---|---|---|
spring.mvc.async.request-timeout |
Duration |
none (no limit) |
The timeout of an SseEmitter created without one (SseEmitter()).
- How: when the time passes, counted from when the response starts, the emitter's
onTimeoutcallbacks run and the emitter completes. - Why: an emitter that is never completed stays open until the client leaves. With many clients that forget to close, emitters and their memory add up. A default timeout bounds them. The browser's
EventSourcereconnects by itself after the stream ends. - Values: a duration such as
30m. A plain number is milliseconds. Zero or negative: no timeout. - Scope: only
SseEmitter.EventStreamandStreamresults have no timeout; they end when their stream ends or the client leaves. - An emitter's own
timeoutwins over this property.
spring:
mvc:
async:
request-timeout: 30m
Interaction with server.request-timeout
server.request-timeout limits how long a request may take to answer. A response that becomes an event stream leaves that deadline as soon as it starts: it is not cut, and the code that runs for it later (the stream, the emitter's callbacks, a Feign call they make) runs without the request's deadline. See Timeouts.
Testing
MockMvc reads an event stream as it comes:
final feed = app.context.getBean<OrderFeed>();
final result = await app.mockMvc.get('/api/orders/changes').andReturn();
final next = result.response.eventStream.firstWhere((e) => e.data != null);
feed.placed(const Order(id: '42', total: 1900));
expect((await next).id, '42');
await result.cancel();
See Testing.
In Spring (Java)
@GetMapping("/notifications")
SseEmitter subscribe() {
SseEmitter emitter = new SseEmitter(1_800_000L);
emitters.add(emitter);
emitter.onCompletion(() -> emitters.remove(emitter));
return emitter;
}
emitter.send(SseEmitter.event().id(order.id()).name("order").data(order));
Differences that matter:
- Spring MVC streams a
Flux<T>orFlux<ServerSentEvent<T>>from Reactor. Here a DartStream<T>orEventStream<T>does the same. - Spring builds an event with
SseEmitter.event(). Heresendtakes aServerSentEvent. - An emitter without a timeout never times out when
spring.mvc.async.request-timeoutis not set. In Spring on Tomcat, the container's 30 seconds apply. - Every event stream starts with a
:comment line, becausedart:iosends the headers only with the first body bytes. spring.mvc.sse.heartbeat-intervalis not in Spring Boot.- Sends that are not awaited stop at 1000 waiting events.
See also
- StreamingResponseBody: bytes instead of events
- Results
- Timeouts
- Compression
- WebSocket
- All properties