サーバー送信イベント
サーバー送信イベント (text/event-stream) を使うと、サーバーは一つの長い HTTP レスポンスで一連のメッセージを送り出せます。通知、進捗、リアルタイムの価格などです。そうしたストリームの型は EventStream<T> です。これはイベントのデータの Stream<T> そのものなので、通常の場合はラッパーの型が要りません。ID や名前が重要なときは、.events がイベント全体 (ServerSentEvent<T>) を返します。
使う理由
イベントのストリームは値のストリームのように読めるべきで、ブラウザーの EventSource のように、ネットワークの切断後には自分で再接続すべきです。同じ型が、イベントを読む Feign クライアントにも、イベントを書くコントローラーにも使えます。
例
@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 スターターのサーバー送信イベント を参照)。
型
| 型 | 内容 |
|---|---|
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 のボディを解析する。 |
手で
// `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) との対応
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 です)。