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:

Use them when the server talks and the client listens. Use a WebSocket when both sides send messages.

The starter offers two shapes:

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:

What is written

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

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

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.

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()).

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:

See also