サーバー送信イベント

サーバー送信イベント (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 です)。

関連項目