
# サーバー送信イベント

`EventStream<T>` を返すメソッドは、`text/event-stream` のレスポンスを読みます。サービスが更新 (注文のステータス、価格、進捗) を送り出す、長く続く応答です。`EventStream<T>` はデコードされたデータの `Stream<T>` で、`id`、`event`、`retry` のフィールドを持つイベント全体は `.events` を通して得られます。ストリームは、ブラウザーの `EventSource` と同じく、自分で再接続します。

## 使う理由

数秒ごとにサービスをポーリングすると、リクエストが無駄になり、それでも遅れて届きます。サーバー送信イベントは、普通の HTTP で、各変更を起きたそばから送り出します。Spring Cloud OpenFeign はストリーミングがまったくできませんが、ここでは同じクライアントのインターフェースが、再接続を組み込んでそれをカバーします。

## 例

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

// データだけ:
await for (final order in orders.events('neon')) {
  log.info(order.status);
}

// ID やイベント名が重要なときは、イベント全体:
orders.events('neon').events.listen((e) {
  log.info('${e.id} ${e.event}: ${e.data.status}');
});
```

```properties
spring.feign.client.config.orders.event-stream.reconnect=true
spring.feign.client.config.orders.event-stream.reconnect-delay=3s
spring.feign.client.config.orders.event-stream.max-attempts=10
```

## 読み方

- 各イベントのデータは、JSON のボディと同じく `ObjectMapper` を通して読まれます。`EventStream<String>` は送られたとおりのデータを返します。読めないイベントはストリーム上のエラー (`DecodeException`) として届き、ストリームは続きます。
- ストリームはコールドです。購読者ごとに自分の接続を開きます。購読をキャンセルする (または `await for` で `break` する) と、それを閉じます。
- リクエストは `Accept: text/event-stream` (`produces` で変えられます) と `Cache-Control: no-cache` を持ちます。
- インターセプターは接続のたびに実行されるため、ストリームが再接続するときは更新されたトークンが使われます。
- `read-timeout` はレスポンスのヘッダーを待つ間だけをカバーします。その後は、ストリームは好きなだけ静かでいられます。
- `call-timeout` は、ストリームの生存期間ではなく、各接続の確立に適用されます。
- `Stream<T>` も戻り値の型として使えます (`EventStream<T>` が得られます)。`Future<EventStream<T>>` は起動時に拒否されます。ストリームを直接返してください。誰かが購読すると接続します。

## 再接続

レスポンスが終わるか接続が切れると、クライアントは遅延の後に再び接続し、最後のイベント ID を `Last-Event-ID` で送ります。

- サーバーからの `retry:` フィールドは、設定された遅延を置き換えます。
- `204 No Content` はストリームを終わらせます。
- エラーのステータスは、`ErrorDecoder` の `FeignException` でストリームを終わらせます。ただし、その例外が再接続する `RetryableException` である場合は除きます。
- `call-timeout` 以内に接続できないストリームは `FeignCallTimeoutException` で失敗し、再接続しません。
- `logger-level` が `basic` 以上では、各再接続は `---> RECONNECTING ...` としてログに出されます。

| プロパティ | デフォルト | 意味 |
|---|---|---|
| `event-stream.reconnect` | `true` | 接続が終わったり切れたりした後に再び接続する。 |
| `event-stream.reconnect-delay` | `3s`、またはサーバーの `retry:` | 再び接続する前の待機。 |
| `event-stream.max-attempts` | 上限なし | ストリームがあきらめるまでに、イベントなしで連続して終わってよい接続の数。 |

それぞれ `spring.feign.client.config.<name>.` (または `default`) の下に置きます。

## フォールバック

`fallback` がある場合、ストリームが最初のイベントの前に失敗すると、フォールバックのストリームが引き継ぎます。その後の失敗は購読者に届きます。

## テストで

`MockHttpTransport` はイベントで応答します。

```dart
server
  ..when(HttpMethod.get, '/shops/neon/orders/events').respondEvents([
    ServerSentEvent({'id': 1, 'status': 'NEW'}, id: '1'),
  ])
  ..when(HttpMethod.get, '/shops/neon/orders/events').respond(204); // 再接続: 止まる
```

## Spring (Java) との対応

Spring Cloud OpenFeign はストリーミングができません。Spring 自身の答えは、`WebClient` や `@HttpExchange` インターフェースからの `Flux<ServerSentEvent<OrderEvent>>` (または `Flux<OrderEvent>`) で、再接続は `retryWhen` に任されます。ここでは `EventStream<T>` がイベントのラッパーをストリームに畳み込み、自分で再接続します。`event-stream.*` のプロパティは追加されたものです。

## 関連項目

- [メソッド](methods.md)
- [Web スターターのサーバー送信イベント](../spring-boot-starter-web/streaming/sse.md)
- [テスト](testing.md)
