
# サーバー送信イベント

サーバー送信イベント (`text/event-stream`) を使うと、サーバーは一つの長い HTTP レスポンスで一連のメッセージを送り出せます。通知、進捗、リアルタイムの価格などです。そうしたストリームの型は `EventStream<T>` です。これはイベントのデータの `Stream<T>` **そのもの**なので、通常の場合はラッパーの型が要りません。ID や名前が重要なときは、`.events` がイベント全体 (`ServerSentEvent<T>`) を返します。

## 使う理由

イベントのストリームは値のストリームのように読めるべきで、ブラウザーの `EventSource` のように、ネットワークの切断後には自分で再接続すべきです。同じ型が、イベントを読む Feign クライアントにも、イベントを書くコントローラーにも使えます。

## 例

```dart
@FeignClient('orders', url: r'${orders.url}')
abstract interface class OrdersClient {
  @GetMapping('/orders/events')
  EventStream<OrderEvent> events();
}

// データだけ: 各イベントの JSON を OrderEvent として読む。
await for (final order in orders.events()) {
  log.info(order.status);
}

// イベント名で種類を区別するときは、イベント全体。
orders.events().events.listen((e) => log.info('${e.id} ${e.event} ${e.data}'));
```

サーバーでは、`@RestController` のメソッドが `EventStream<T>` を返せます。Web スターターはイベントをレスポンスとして書きます ([Web スターターのサーバー送信イベント](../spring-boot-starter-web/streaming/sse.md) を参照)。

## 型

| 型 | 内容 |
|---|---|
| `EventStream<T>` | イベントのデータのコールドな `Stream<T>`: 誰かが購読するまで何も起こらず、購読者ごとに自分の接続を開き、キャンセル (または `await for` での `break`) でそれを閉じる。`.events` はイベント全体を返す。 |
| `EventStream.fromIterable`、`EventStream.of`、`EventStream.fromEvents` | フォールバックやテストのために作る。 |
| `ServerSentEvent<T>` | 一つのイベント: `data`、`id`、`event`、`retry`、`comment`。 |
| `connectServerSentEvents(connect, reconnect:, onReconnect:)` | 任意の `HttpTransport` で接続を開き、`EventSource` と同じく再接続する。 |
| `SseReconnect(enabled:, delay:, maxAttempts:, retryIf:)` | ルール: `delay` (デフォルトは 3 秒)、またはサーバーの `retry:` だけ待ち、サーバーが再開できるよう `Last-Event-ID` を送る。`204 No Content` はストリームを止める。`SseReconnect.never` は再接続しない。 |
| `SseDecoder` | HTML 仕様に従って `text/event-stream` のボディを解析する。 |

## 手で

```dart
// `transport` はアプリケーションの HttpTransport の Bean。
Stream<ServerSentEvent<String>> orderEvents() =>
    connectServerSentEvents((lastEventId) async {
      final response = await transport.stream(HttpRequest(
        method: HttpMethod.get,
        url: Uri.parse('https://api.neon.books/orders/events'),
        headers: HttpHeaders({
          'Accept': MediaType.textEventStream,
          // 切断前に最後に見たイベントの後から再開する。
          if (lastEventId != null) 'Last-Event-ID': lastEventId,
        }),
      ));
      if (!response.isSuccess) {
        // ネットワークの失敗ではない: ストリームはこのエラーで終わる。
        throw StateError((await response.read()).bodyText);
      }
      return response;
    });

// `orders` の購読者はそれぞれ自分の接続を開く。
final orders = EventStream<String>(orderEvents);
```

## Spring (Java) との対応

```java
Flux<ServerSentEvent<OrderEvent>> events = webClient.get().uri("/orders/events")
    .retrieve().bodyToFlux(new ParameterizedTypeReference<>() {});
```

Spring には `EventStream` がありません。`WebClient` と `@HttpExchange` のインターフェースは `Flux<ServerSentEvent<T>>` (または `Flux<T>`) を返し、Spring Cloud OpenFeign はストリーミングがまったくできません。ここではイベントのラッパーがストリームの型に畳み込まれ、再接続が組み込まれています (Spring では `Flux.retryWhen` です)。

## 関連項目

- [HTTP トランスポート](http-transport.md)
- [Feign のサーバー送信イベント](../spring-boot-starter-feign/server-sent-events.md)
- [テスト](testing.md)
