サーバー送信イベント

Server-Sent Events (text/event-stream) は、一つの HTTP レスポンスを開いたままにし、起きたそばからメッセージをクライアントにプッシュします。コントローラーメソッドは値のストリーム、または他のコードがイベントを送る SseEmitter を返します。

使う理由

一つの値ではなく、時間をかけて届く一連の値である応答があります。通知、ジョブの進行状況、リアルタイムの価格、言語モデルのトークンなどです。ポーリングは何度も問い合わせ、リクエストを無駄にします。WebSocket は双方向に動きますが、独自のプロトコルとエンドポイントが必要です。Server-Sent Events は通常の HTTP です。

サーバーが話し、クライアントが聞くときに使います。双方がメッセージを送るときは WebSocket を使ってください。

スターターは二つの形を提供します。

例

import 'dart:async';

import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

class Order {
  const Order({required this.id, required this.total});

  final String id;
  final int total;
}

@Service()
class OrderFeed {
  final _changes = StreamController<Order>.broadcast();
  final _history = <Order>[];

  Stream<Order> changes() => _changes.stream;

  // [id] を持つ注文より後の注文 (未知の id ならすべて)、
  // その後に新しい注文。
  Stream<Order> since(String id) async* {
    final start = _history.indexWhere((order) => order.id == id) + 1;
    yield* Stream.fromIterable(_history.sublist(start));
    yield* _changes.stream;
  }

  void placed(Order order) {
    _history.add(order);
    _changes.add(order);
  }
}

@RestController()
@RequestMapping('/api/orders')
class OrderEventsController {
  OrderEventsController(this.feed, this.notifications);

  final OrderFeed feed;
  final Notifications notifications;

  // 各変更を、名前と id 付きの一つのイベントにする。
  @GetMapping('/changes')
  EventStream<Order> changes() => EventStream(
    () => feed.changes().map(
      (order) => ServerSentEvent(order, id: order.id, event: 'order'),
    ),
  );

  // 通常の Stream も使える: 各要素が名前のないイベントになる。
  @GetMapping('/totals')
  Stream<int> totals() => feed.changes().map((order) => order.total);

  // 同じデータを NDJSON で: 一行に一つの JSON オブジェクト。イベントのフィールドなし。
  @GetMapping.of(path: '/export', produces: 'application/x-ndjson')
  Stream<Order> export() => feed.changes();

  // 再接続する EventSource は、最後に見た id を送る。
  @GetMapping('/resume')
  Stream<ServerSentEvent<Order>> resume(
    @RequestHeader('Last-Event-ID') String? lastId,
  ) => (lastId == null ? feed.changes() : feed.since(lastId)).map(
    (order) => ServerSentEvent(order, id: order.id),
  );

  // 他のコードが後で送るイベント。
  @GetMapping('/notifications')
  SseEmitter subscribe() => notifications.subscribe();
}

@Service()
class Notifications {
  final _emitters = <SseEmitter>{};

  SseEmitter subscribe() {
    final emitter = SseEmitter(timeout: const Duration(minutes: 30));
    _emitters.add(emitter);
    // 何がエミッターを終わらせても一回だけ実行される: 完了、タイムアウト、エラー、
    // クライアントの離脱。
    emitter.onCompletion(() => _emitters.remove(emitter));
    return emitter;
  }

  Future<void> broadcast(Order order) async {
    for (final emitter in [..._emitters]) {
      try {
        await emitter.send(ServerSentEvent(order, event: 'order', id: order.id));
      } on StateError {
        // クライアントは去った。onCompletion がすでに取り除いている。
      }
    }
  }
}
# lib/resources/application.yaml
spring:
  mvc:
    sse:
      heartbeat-interval: 15s   # アイドル状態のストリームに 15 秒ごとにコメント行を書く
    async:
      request-timeout: 10m      # 独自のタイムアウトのないエミッターは 10 分後に終わる

/api/orders/changes からクライアントが受け取るもの:

:

id: 42
event: order
data: {"id":"42","total":1900}

最初の : の行は空のコメントです。クライアントはそれを無視します。後述の「書き出されるもの」で説明します。

どの戻り値がイベントストリームになるか

メソッドの戻り値の型 書き出し方
EventStream<T> 要素ごとに一つのイベント。各要素の ServerSentEvent 全体 (id、event、retry、comment) が使われる。
Stream<T> 宣言した型がバイトストリームでなければ、要素ごとに一つのイベント。ServerSentEvent である要素はそのフィールドを保ち、それ以外の値はイベントのデータになる。
Stream<ServerSentEvent<T>> 要素ごとに、そのフィールド付きの一つのイベント。
produces: 'application/x-ndjson' の Stream<T> NDJSON: 各要素のデータを一行の JSON として、Content-Type: application/x-ndjson。ServerSentEvent の id、event、retry、comment は破棄される。
SseEmitter send ごとに一つのイベント。常に text/event-stream。
ResponseEntity<EventStream<T>>、ResponseEntity<Stream<T>>、ResponseEntity<SseEmitter> 同じイベントを、エンティティのステータスとヘッダー付きで。

ルール:

書き出されるもの

EventStream<T>

(spring_web_dart の) EventStream<T> は、イベントのデータの Stream<T> で、イベント全体を events ゲッターに保持します。同じ型が、イベントストリームを読む Feign クライアントのメソッドの戻り値の型でもあるので、コントローラーはクライアントのストリームをそのまま渡せます。

コンストラクター 各リスナーが受け取るもの
EventStream(Stream<ServerSentEvent<T>> Function() open) 新しい open() 呼び出しのイベント。各レスポンスに独自のソースを持たせたいときに使う。
EventStream.fromEvents(Stream<ServerSentEvent<T>> events) 与えられたイベント。二つ目のリスナーは同じストリームを再び listen するので、単一購読のストリームでは失敗する。
EventStream.of(Stream<T> data) data の値を持つ、id も名前もないイベント。
EventStream.fromIterable(Iterable<T> values) これらの値を持つイベントの後に終了。テストやフォールバック用。
EventStream.empty() イベントなし。レスポンスはすぐに終わる。
メンバー 意味
events ServerSentEvent 全体。サーバーはこれを読む。
lastEventId このオブジェクトのいずれかのリスナーが最後に見た id、または null。Feign クライアントが再接続するときに使う。

ストリームはコールドです。レスポンスが listen を始めるまで何も起きません。サーバーはレスポンスごとに一回 listen し、レスポンスが終わると購読をキャンセルします。

ServerSentEvent<T>

フィールド 型 デフォルト 意味
data (位置引数) T 必須 ペイロード。data: の行。
id String? null イベントの id。ブラウザーは再接続するとき、最後のものを Last-Event-ID で送り返す。
event String? null イベント名。null は名前のないイベントで、EventSource はそれを onmessage に届ける。名前付きのものは addEventListener(name, ...) に届く。
retry Duration? null クライアントが再接続するまで待つべき時間。ミリ秒の整数で書かれる。
comment String? null コメント行。クライアントは無視する。

withData(other) は、データだけを変えた同じイベントを返します。encode() は、イベントが書き出されるテキストを返します。

SseEmitter

メンバー 意味
SseEmitter({Duration? timeout}) 新しいエミッター。timeout はレスポンスが始まった時点から数える。null なら spring.mvc.async.request-timeout をとる。ゼロまたは負の値はタイムアウトなし。
timeout コンストラクターに与えたタイムアウト。
Future<void> send(Object? data) 一つのイベントを送る。ServerSentEvent はそのフィールドを保ち、それ以外の値は名前のないイベントのデータになる。
void complete() それまでに送ったイベントが書かれた後、レスポンスを正常に終える。エミッターがすでに終わっていれば何もしない。
void completeWithError(Object error) error を理由にレスポンスを終える。エラーは警告としてログに記録される。
void onCompletion(void Function() callback) 理由を問わず、エミッターが終わったときに callback を一回実行する。
void onTimeout(void Function() callback) タイムアウトが過ぎたとき、エミッターが完了する前に callback を実行する。
void onError(void Function(Object error) callback) 送信が失敗したとき、または completeWithError が呼ばれたときに callback を実行する。
bool isComplete エミッターが終わったかどうか。完了、タイムアウト、失敗、またはクライアントの離脱。
initialize(handler, defaultTimeout: ...) エミッターをレスポンスにつなぐ。スターターが呼ぶ。アプリケーションは呼ばない。

send の動作

エミッターの終わり方

原因 コールバック (順に) クライアントに見えるもの
complete() onCompletion ストリームが正常に終わる。
completeWithError(e) onError(e)、onCompletion ストリームが終わる。ステータスはすでに 200 なので、エラーのステータスは送れない。
タイムアウトが過ぎる onTimeout、onCompletion ストリームが終わる。
送信が失敗する onError(e)、onCompletion 接続はなくなっている。
クライアントが去る onCompletion 何もない。去っている。
サーバーが停止する onCompletion ストリームが終わる。開いているイベントストリームは、グレースフルシャットダウンでもすぐに閉じられる。シャットダウン を参照。

レスポンスが始まる前に呼ばれた complete() と completeWithError() は保持されます。バッファーのイベントが書かれ、その後レスポンスが終わります。

SseEmitterHandler

エミッターが書き込むレスポンスは SseEmitterHandler です: send(event)、complete()、completeWithError(error)、done。単体テストではこれを実装して emitter.initialize(handler) を呼び、サーバーなしでサービスが何を送るかを確認できます。

ストリーム: エラーと切断

プロパティ

spring.mvc.sse.heartbeat-interval

キー 型 デフォルト
spring.mvc.sse.heartbeat-interval Duration なし

開いているすべてのイベントストリームに、この間隔でコメント行 (: と空行) を書きます。

spring:
  mvc:
    sse:
      heartbeat-interval: 20s

spring.mvc.async.request-timeout

キー 型 デフォルト
spring.mvc.async.request-timeout Duration なし (制限なし)

タイムアウトなしで作られた SseEmitter (SseEmitter()) のタイムアウトです。

spring:
  mvc:
    async:
      request-timeout: 30m

server.request-timeout との関係

server.request-timeout は、リクエストが応答するまでにかけられる時間を制限します。イベントストリームになるレスポンスは、始まった時点でその期限から離れます。切られることはなく、その後にそのために実行されるコード (ストリーム、エミッターのコールバック、それらが行う Feign の呼び出し) は、リクエストの期限なしで実行されます。タイムアウト を参照してください。

テスト

MockMvc は、イベントストリームを届いたそばから読みます。

final feed = app.context.getBean<OrderFeed>();
final result = await app.mockMvc.get('/api/orders/changes').andReturn();
final next = result.response.eventStream.firstWhere((e) => e.data != null);
feed.placed(const Order(id: '42', total: 1900));
expect((await next).id, '42');
await result.cancel();

テスト を参照してください。

Spring (Java) との対応

@GetMapping("/notifications")
SseEmitter subscribe() {
  SseEmitter emitter = new SseEmitter(1_800_000L);
  emitters.add(emitter);
  emitter.onCompletion(() -> emitters.remove(emitter));
  return emitter;
}

emitter.send(SseEmitter.event().id(order.id()).name("order").data(order));

重要な違い:

関連項目