
# 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](../server/websocket.md) when both sides send messages.

The starter offers two shapes:

- **A stream** (`EventStream<T>` or `Stream<T>`), when the events come from one source known when the request arrives: a database change feed, a `StreamController`, 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 calls `send`.

## Example

```dart
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.
      }
    }
  }
}
```

```yaml
# 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`:

```text
:

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>` or `Stream<List<int>>` writes raw bytes, not events. See [StreamingResponseBody](streaming-response-body.md).
- A method that returns a `Future` of a stream (`Future<Stream<T>>`, `Future<EventStream<T>>`) **fails the startup**: return the stream itself. Do the asynchronous work inside the stream (`async*`, or `Stream.fromFuture(...).asyncExpand(...)`). A `Future<SseEmitter>` is fine.
- Any HTTP method can answer with events, `POST` included. MCP's Streamable HTTP transport does this.
- The `Content-Type` of an event stream is always `text/event-stream;charset=UTF-8`, also when a `ResponseEntity` sets another one.

## What is written

- **Headers:** `Content-Type: text/event-stream;charset=UTF-8` and `Cache-Control: no-cache`, plus the status and headers of a `ResponseEntity`.
- **A first comment line.** `dart:io` sends 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 `comment` lines (each starting with `:`), `id:`, `event:`, `retry:` (whole milliseconds), then the `data:` lines, then a blank line. A value with line breaks becomes several lines of the same field. A `null` field is left out. A `null` data gives no `data:` line.
- **The data:** a `String` is written as it is. Any other value is turned into JSON by the application's `ObjectMapper`, as a response body would be. See [JSON](../../spring-core-dart/json/index.md).
- **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-stream` is not in the default `server.compression.mime-types`. Add it to compress event streams; each flush then sends what was compressed so far. See [Compression](../server/compression.md).

## `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 `ServerSentEvent`s. 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 `Future` completes when the event is written** to the client. Await it to send at the client's pace.
- **After the emitter has ended**, `send` throws a `StateError` (`The SseEmitter has already completed`). Check `isComplete` or catch the error.
- **When the write fails** (the client went away), the emitter ends: the `onError` callbacks run, then the `onCompletion` callbacks, and the error is rethrown.
- **When sends are not awaited** and 1000 events are already waiting for a client that reads nothing, the next `send` fails with a `StateError` (`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](../server/shutdown.md). |

`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 `StreamController` sees `onCancel`; an `async*` generator stops at its next `yield`.
- **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:

  ```dart
  // 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 `@ExceptionHandler` or a `ProblemDetail`. See [Errors](../errors/index.md).

## 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_timeout` is 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`, `Stream` and `SseEmitter` responses, not to NDJSON.
- **Values:** a duration such as `15s` or `PT15S`. 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 `15s` or `30s`.
- This key is this starter's own. Spring Boot has no such property.

```yaml
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 `onTimeout` callbacks 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 `EventSource` reconnects 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`. `EventStream` and `Stream` results have no timeout; they end when their stream ends or the client leaves.
- An emitter's own `timeout` wins over this property.

```yaml
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](../server/timeouts.md).

## Testing

`MockMvc` reads an event stream as it comes:

```dart
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](../testing.md).

## In Spring (Java)

```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>` or `Flux<ServerSentEvent<T>>` from Reactor. Here a Dart `Stream<T>` or `EventStream<T>` does the same.
- Spring builds an event with `SseEmitter.event()`. Here `send` takes a `ServerSentEvent`.
- An emitter without a timeout never times out when `spring.mvc.async.request-timeout` is not set. In Spring on Tomcat, the container's 30 seconds apply.
- Every event stream starts with a `:` comment line, because `dart:io` sends the headers only with the first body bytes.
- `spring.mvc.sse.heartbeat-interval` is not in Spring Boot.
- Sends that are not awaited stop at 1000 waiting events.

## See also

- [StreamingResponseBody](streaming-response-body.md): bytes instead of events
- [Results](../controllers/results.md)
- [Timeouts](../server/timeouts.md)
- [Compression](../server/compression.md)
- [WebSocket](../server/websocket.md)
- [All properties](../properties.md)
