サーバー送信イベント
EventStream<T> を返すメソッドは、text/event-stream のレスポンスを読みます。サービスが更新 (注文のステータス、価格、進捗) を送り出す、長く続く応答です。EventStream<T> はデコードされたデータの Stream<T> で、id、event、retry のフィールドを持つイベント全体は .events を通して得られます。ストリームは、ブラウザーの EventSource と同じく、自分で再接続します。
使う理由
数秒ごとにサービスをポーリングすると、リクエストが無駄になり、それでも遅れて届きます。サーバー送信イベントは、普通の HTTP で、各変更を起きたそばから送り出します。Spring Cloud OpenFeign はストリーミングがまったくできませんが、ここでは同じクライアントのインターフェースが、再接続を組み込んでそれをカバーします。
例
@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}');
});
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 はイベントで応答します。
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.* のプロパティは追加されたものです。