
# サーバー送信イベント

Server-Sent Events (`text/event-stream`) は、一つの HTTP レスポンスを開いたままにし、起きたそばからメッセージをクライアントにプッシュします。コントローラーメソッドは値のストリーム、または他のコードがイベントを送る `SseEmitter` を返します。

## 使う理由

一つの値ではなく、時間をかけて届く一連の値である応答があります。通知、ジョブの進行状況、リアルタイムの価格、言語モデルのトークンなどです。ポーリングは何度も問い合わせ、リクエストを無駄にします。WebSocket は双方向に動きますが、独自のプロトコルとエンドポイントが必要です。Server-Sent Events は通常の HTTP です。

- ブラウザーは `EventSource` で読み、それは自分で再接続します。
- プロキシ、CORS、Cookie、セキュリティのフィルターチェーンは、他のリクエストと同じように動きます。
- 各イベントは ID を持てるので、再接続したクライアントは続きから再開できます。

サーバーが話し、クライアントが聞くときに使います。双方がメッセージを送るときは [WebSocket](../server/websocket.md) を使ってください。

スターターは二つの形を提供します。

- **ストリーム** (`EventStream<T>` または `Stream<T>`)。イベントが、リクエストが届いた時点で分かっている一つのソースから来るとき。データベースの変更フィード、`StreamController`、Feign クライアント自身のイベントストリームなどです。
- **`SseEmitter`**。イベントが別の場所から、後で来るとき。イベントリスナー、スケジュールされたタスク、別のリクエストなどです。メソッドはエミッターを作り、どこかに保持して返します。他のコードが `send` を呼びます。

## 例

```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;

  // [id] を持つ注文より後の注文 (未知の id ならすべて)、
  // その後に新しい注文。
  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;

  // 各変更を、名前と id 付きの一つのイベントにする。
  @GetMapping('/changes')
  EventStream<Order> changes() => EventStream(
    () => feed.changes().map(
      (order) => ServerSentEvent(order, id: order.id, event: 'order'),
    ),
  );

  // 通常の Stream も使える: 各要素が名前のないイベントになる。
  @GetMapping('/totals')
  Stream<int> totals() => feed.changes().map((order) => order.total);

  // 同じデータを NDJSON で: 一行に一つの JSON オブジェクト。イベントのフィールドなし。
  @GetMapping.of(path: '/export', produces: 'application/x-ndjson')
  Stream<Order> export() => feed.changes();

  // 再接続する EventSource は、最後に見た id を送る。
  @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),
  );

  // 他のコードが後で送るイベント。
  @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);
    // 何がエミッターを終わらせても一回だけ実行される: 完了、タイムアウト、エラー、
    // クライアントの離脱。
    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 {
        // クライアントは去った。onCompletion がすでに取り除いている。
      }
    }
  }
}
```

```yaml
# lib/resources/application.yaml
spring:
  mvc:
    sse:
      heartbeat-interval: 15s   # アイドル状態のストリームに 15 秒ごとにコメント行を書く
    async:
      request-timeout: 10m      # 独自のタイムアウトのないエミッターは 10 分後に終わる
```

`/api/orders/changes` からクライアントが受け取るもの:

```text
:

id: 42
event: order
data: {"id":"42","total":1900}

```

最初の `:` の行は空のコメントです。クライアントはそれを無視します。後述の「書き出されるもの」で説明します。

## どの戻り値がイベントストリームになるか

| メソッドの戻り値の型 | 書き出し方 |
|---|---|
| `EventStream<T>` | 要素ごとに一つのイベント。各要素の `ServerSentEvent` 全体 (`id`、`event`、`retry`、`comment`) が使われる。 |
| `Stream<T>` | 宣言した型がバイトストリームでなければ、要素ごとに一つのイベント。`ServerSentEvent` である要素はそのフィールドを保ち、それ以外の値はイベントのデータになる。 |
| `Stream<ServerSentEvent<T>>` | 要素ごとに、そのフィールド付きの一つのイベント。 |
| `produces: 'application/x-ndjson'` の `Stream<T>` | NDJSON: 各要素のデータを一行の JSON として、`Content-Type: application/x-ndjson`。`ServerSentEvent` の `id`、`event`、`retry`、`comment` は破棄される。 |
| `SseEmitter` | `send` ごとに一つのイベント。常に `text/event-stream`。 |
| `ResponseEntity<EventStream<T>>`、`ResponseEntity<Stream<T>>`、`ResponseEntity<SseEmitter>` | 同じイベントを、エンティティのステータスとヘッダー付きで。 |

ルール:

- `Stream<Uint8List>` または `Stream<List<int>>` を返すと **宣言した** メソッドは、イベントではなく生のバイトを書きます。[StreamingResponseBody](streaming-response-body.md) を参照してください。
- ストリームの `Future` (`Future<Stream<T>>`、`Future<EventStream<T>>`) を返すメソッドは **起動を失敗させます。** ストリームそのものを返してください。非同期の処理はストリームの中で行います (`async*`、または `Stream.fromFuture(...).asyncExpand(...)`)。`Future<SseEmitter>` は問題ありません。
- `POST` を含め、どの HTTP メソッドもイベントで応答できます。MCP の Streamable HTTP トランスポートはこれを行います。
- イベントストリームの `Content-Type` は、`ResponseEntity` が別のものを設定した場合でも、常に `text/event-stream;charset=UTF-8` です。

## 書き出されるもの

- **ヘッダー:** `Content-Type: text/event-stream;charset=UTF-8` と `Cache-Control: no-cache`、それに `ResponseEntity` のステータスとヘッダー。
- **最初のコメント行。** `dart:io` は、ボディの最初のバイトと一緒にしかステータスとヘッダーを送りません。そこで、最初のイベントを待たずにクライアントがすぐにレスポンスを見られるよう、すべてのイベントストリームは `:` と空行で始まります。クライアントはコメント行を飛ばします。NDJSON のレスポンスには付きません。
- **要素ごとに一つのイベント** を次の順で書きます。`comment` の行 (それぞれ `:` で始まる)、`id:`、`event:`、`retry:` (ミリ秒の整数)、そして `data:` の行、最後に空行です。改行を含む値は、同じフィールドの複数の行になります。`null` のフィールドは省かれます。`null` のデータには `data:` の行がありません。
- **データ:** `String` はそのまま書かれます。それ以外の値は、レスポンスボディと同じく、アプリケーションの `ObjectMapper` で JSON に変換されます。[JSON](../../spring-core-dart/json/index.md) を参照してください。
- **バックプレッシャー。** 一つのイベントを書いてフラッシュしている間、ソースのストリームは一時停止します。ゆっくり読むクライアントはストリームの速度を落とします。サーバーがそのためにイベントをメモリにためることはありません。
- **圧縮。** `text/event-stream` はデフォルトの `server.compression.mime-types` に含まれません。イベントストリームを圧縮するには追加してください。その場合、各フラッシュがそれまでに圧縮した分を送ります。[圧縮](../server/compression.md) を参照してください。

## `EventStream<T>`

(`spring_web_dart` の) `EventStream<T>` は、イベントのデータの `Stream<T>` で、イベント全体を `events` ゲッターに保持します。同じ型が、イベントストリームを読む Feign クライアントのメソッドの戻り値の型でもあるので、コントローラーはクライアントのストリームをそのまま渡せます。

| コンストラクター | 各リスナーが受け取るもの |
|---|---|
| `EventStream(Stream<ServerSentEvent<T>> Function() open)` | 新しい `open()` 呼び出しのイベント。各レスポンスに独自のソースを持たせたいときに使う。 |
| `EventStream.fromEvents(Stream<ServerSentEvent<T>> events)` | 与えられたイベント。二つ目のリスナーは同じストリームを再び listen するので、単一購読のストリームでは失敗する。 |
| `EventStream.of(Stream<T> data)` | `data` の値を持つ、id も名前もないイベント。 |
| `EventStream.fromIterable(Iterable<T> values)` | これらの値を持つイベントの後に終了。テストやフォールバック用。 |
| `EventStream.empty()` | イベントなし。レスポンスはすぐに終わる。 |

| メンバー | 意味 |
|---|---|
| `events` | `ServerSentEvent` 全体。サーバーはこれを読む。 |
| `lastEventId` | このオブジェクトのいずれかのリスナーが最後に見た id、または `null`。Feign クライアントが再接続するときに使う。 |

ストリームはコールドです。レスポンスが listen を始めるまで何も起きません。サーバーはレスポンスごとに一回 listen し、レスポンスが終わると購読をキャンセルします。

## `ServerSentEvent<T>`

| フィールド | 型 | デフォルト | 意味 |
|---|---|---|---|
| `data` (位置引数) | `T` | 必須 | ペイロード。`data:` の行。 |
| `id` | `String?` | `null` | イベントの id。ブラウザーは再接続するとき、最後のものを `Last-Event-ID` で送り返す。 |
| `event` | `String?` | `null` | イベント名。`null` は名前のないイベントで、`EventSource` はそれを `onmessage` に届ける。名前付きのものは `addEventListener(name, ...)` に届く。 |
| `retry` | `Duration?` | `null` | クライアントが再接続するまで待つべき時間。ミリ秒の整数で書かれる。 |
| `comment` | `String?` | `null` | コメント行。クライアントは無視する。 |

`withData(other)` は、データだけを変えた同じイベントを返します。`encode()` は、イベントが書き出されるテキストを返します。

## `SseEmitter`

| メンバー | 意味 |
|---|---|
| `SseEmitter({Duration? timeout})` | 新しいエミッター。`timeout` はレスポンスが始まった時点から数える。`null` なら `spring.mvc.async.request-timeout` をとる。ゼロまたは負の値はタイムアウトなし。 |
| `timeout` | コンストラクターに与えたタイムアウト。 |
| `Future<void> send(Object? data)` | 一つのイベントを送る。`ServerSentEvent` はそのフィールドを保ち、それ以外の値は名前のないイベントのデータになる。 |
| `void complete()` | それまでに送ったイベントが書かれた後、レスポンスを正常に終える。エミッターがすでに終わっていれば何もしない。 |
| `void completeWithError(Object error)` | `error` を理由にレスポンスを終える。エラーは警告としてログに記録される。 |
| `void onCompletion(void Function() callback)` | 理由を問わず、エミッターが終わったときに `callback` を一回実行する。 |
| `void onTimeout(void Function() callback)` | タイムアウトが過ぎたとき、エミッターが完了する前に `callback` を実行する。 |
| `void onError(void Function(Object error) callback)` | 送信が失敗したとき、または `completeWithError` が呼ばれたときに `callback` を実行する。 |
| `bool isComplete` | エミッターが終わったかどうか。完了、タイムアウト、失敗、またはクライアントの離脱。 |
| `initialize(handler, defaultTimeout: ...)` | エミッターをレスポンスにつなぐ。スターターが呼ぶ。アプリケーションは呼ばない。 |

### `send` の動作

- **レスポンスの準備ができる前は**、イベントはバッファーに入ります。メソッドはエミッターを返す前にイベントを送れます。それらはレスポンスが始まると最初に書かれます。
- **返される `Future` は、イベントがクライアントに書かれると完了します。** クライアントのペースで送るには await してください。
- **エミッターが終わった後は**、`send` は `StateError` (`The SseEmitter has already completed`) を投げます。`isComplete` を確認するか、エラーを捕まえてください。
- **書き込みが失敗すると** (クライアントが去った)、エミッターは終わります。`onError` コールバック、続いて `onCompletion` コールバックが実行され、エラーは再スローされます。
- **送信を await せず**、何も読まないクライアントのためにすでに 1000 個のイベントが待っている場合、次の `send` は `StateError` (`The client does not read the event stream: 1000 events are waiting`) で失敗し、エミッターは終わります。止まったクライアントがサーバーのメモリを埋めることはできません。

### エミッターの終わり方

| 原因 | コールバック (順に) | クライアントに見えるもの |
|---|---|---|
| `complete()` | `onCompletion` | ストリームが正常に終わる。 |
| `completeWithError(e)` | `onError(e)`、`onCompletion` | ストリームが終わる。ステータスはすでに 200 なので、エラーのステータスは送れない。 |
| タイムアウトが過ぎる | `onTimeout`、`onCompletion` | ストリームが終わる。 |
| 送信が失敗する | `onError(e)`、`onCompletion` | 接続はなくなっている。 |
| クライアントが去る | `onCompletion` | 何もない。去っている。 |
| サーバーが停止する | `onCompletion` | ストリームが終わる。開いているイベントストリームは、グレースフルシャットダウンでもすぐに閉じられる。[シャットダウン](../server/shutdown.md) を参照。 |

レスポンスが始まる前に呼ばれた `complete()` と `completeWithError()` は保持されます。バッファーのイベントが書かれ、その後レスポンスが終わります。

### `SseEmitterHandler`

エミッターが書き込むレスポンスは `SseEmitterHandler` です: `send(event)`、`complete()`、`completeWithError(error)`、`done`。単体テストではこれを実装して `emitter.initialize(handler)` を呼び、サーバーなしでサービスが何を送るかを確認できます。

## ストリーム: エラーと切断

- **クライアントが去る:** サーバーはストリームの購読をキャンセルします。`StreamController` は `onCancel` を受け取り、`async*` ジェネレーターは次の `yield` で止まります。
- **ストリームがエラーを出す:** 警告がログに記録され (`The stream of GET /api/orders/changes failed`)、レスポンスが終わります。ステータスはすでに送信済みなので、クライアントにはストリームの終わりしか見えません。クライアントに伝えるには、ストリームの中でエラーを捕まえ、それを表すイベントを送ってください。

  ```dart
  // 失敗は `failed` という名前の最後のイベントになり、その後ストリームが終わる。
  @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(),
        ),
      );
  ```

- **ストリームが終わる:** 最後のイベントが書かれると、レスポンスが終わります。
- **最初のイベントの前の例外** (メソッド自身が例外を投げる) は、他のエラーと同じように応答されます。`@ExceptionHandler` または `ProblemDetail` です。[エラー](../errors/index.md) を参照してください。

## プロパティ

### `spring.mvc.sse.heartbeat-interval`

| キー | 型 | デフォルト |
|---|---|---|
| `spring.mvc.sse.heartbeat-interval` | `Duration` | なし |

開いているすべてのイベントストリームに、この間隔でコメント行 (`:` と空行) を書きます。

- **理由:** プロキシ、ロードバランサー、一部のモバイルネットワークは、しばらく何も送らない接続を閉じます (nginx の `proxy_read_timeout` はデフォルトで 60 秒です)。次のイベントまで長く待つストリームは、そうして切れてしまいます。ハートビートはそれを生かし続けます。クライアントはコメント行を無視します。
- **仕組み:** コメントは他に何も書いていないときにだけ書かれるので、読まないクライアントの後ろにハートビートが積み上がることはありません。`EventStream`、`Stream`、`SseEmitter` のレスポンスに適用され、NDJSON には適用されません。
- **値:** `15s` や `PT15S` のような期間。単なる数値はミリ秒です。未設定、ゼロ、負の値ならハートビートなし。
- **値の選び方:** 経路上の最も短いアイドルタイムアウトより小さい値、たとえば `15s` や `30s`。
- このキーはこのスターター独自のものです。Spring Boot にはこのプロパティはありません。

```yaml
spring:
  mvc:
    sse:
      heartbeat-interval: 20s
```

### `spring.mvc.async.request-timeout`

| キー | 型 | デフォルト |
|---|---|---|
| `spring.mvc.async.request-timeout` | `Duration` | なし (制限なし) |

タイムアウトなしで作られた `SseEmitter` (`SseEmitter()`) のタイムアウトです。

- **仕組み:** レスポンスが始まった時点から数えて時間が過ぎると、エミッターの `onTimeout` コールバックが実行され、エミッターが完了します。
- **理由:** 完了されないエミッターは、クライアントが去るまで開いたままです。閉じ忘れるクライアントが多いと、エミッターとそのメモリが積み上がります。デフォルトのタイムアウトはそれに上限を設けます。ブラウザーの `EventSource` は、ストリームが終わった後に自分で再接続します。
- **値:** `30m` のような期間。単なる数値はミリ秒です。ゼロまたは負の値ならタイムアウトなし。
- **範囲:** `SseEmitter` だけです。`EventStream` と `Stream` の戻り値にはタイムアウトがなく、ストリームが終わるかクライアントが去ると終わります。
- エミッター自身の `timeout` が、このプロパティより優先されます。

```yaml
spring:
  mvc:
    async:
      request-timeout: 30m
```

### `server.request-timeout` との関係

`server.request-timeout` は、リクエストが応答するまでにかけられる時間を制限します。イベントストリームになるレスポンスは、始まった時点でその期限から離れます。切られることはなく、その後にそのために実行されるコード (ストリーム、エミッターのコールバック、それらが行う Feign の呼び出し) は、リクエストの期限なしで実行されます。[タイムアウト](../server/timeouts.md) を参照してください。

## テスト

`MockMvc` は、イベントストリームを届いたそばから読みます。

```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();
```

[テスト](../testing.md) を参照してください。

## 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));
```

重要な違い:

- Spring MVC は Reactor の `Flux<T>` や `Flux<ServerSentEvent<T>>` をストリーミングします。ここでは Dart の `Stream<T>` や `EventStream<T>` が同じことをします。
- Spring は `SseEmitter.event()` でイベントを組み立てます。ここでは `send` が `ServerSentEvent` を受け取ります。
- タイムアウトのないエミッターは、`spring.mvc.async.request-timeout` が未設定ならタイムアウトしません。Tomcat 上の Spring では、コンテナーの 30 秒が適用されます。
- `dart:io` はボディの最初のバイトと一緒にしかヘッダーを送らないため、すべてのイベントストリームは `:` のコメント行で始まります。
- `spring.mvc.sse.heartbeat-interval` は Spring Boot にはありません。
- await しない送信は、待っているイベントが 1000 個で止まります。

## 関連項目

- [StreamingResponseBody](streaming-response-body.md): イベントの代わりにバイト
- [戻り値](../controllers/results.md)
- [タイムアウト](../server/timeouts.md)
- [圧縮](../server/compression.md)
- [WebSocket](../server/websocket.md)
- [すべてのプロパティ](../properties.md)
