サーバー送信イベント

どのようなものか

サーバー送信イベントは、ウェブサーバーからページへメッセージを送る仕
組みです。通常のHTTP応答を1本だけ開いたままにし、新しい情報があるた
びに書き込みます。WHATWGが管理するHTML
Standardに定義されており、ストリームのテキスト形式と、それを読むブラ
ウザーのインターフェースである`EventSource`の両方が規定されていま
す。名前はSSEと略されることが多く、形式そのものもメディアタイプにち
なんで`text/event-stream`と呼ばれることがあります。

ページは`new
EventSource(url)`という1行でストリームを開きます。ブラウザーは`GET`
リクエストを送り、そこには`Accept:
text/event-stream`が含まれる場合があります。期待するのは、ステータス
200で、そのコンテンツタイプを持つ応答です。サーバーはヘッダーを送っ
た後、本文を終了しません。何かが起きるたびに数行のテキストを書き込
み、ブラウザーはその行のまとまりを、ページ側で受け取れるイベントに変
換します。

形式は意図的に単純に作られています。ストリームは常にUTF-8で、各行が1
つのフィールドです。`data`行はペイロードを運び、複数の`data`行が続く
と改行を挟んで結合されます。`event`行はイベントの型を指定し、省略し
た場合の型は`message`です。`id`行は最後のイベントのIDを設定し、
`retry`行は再接続までにブラウザーが待つ時間をミリ秒単位で指定しま
す。コロンで始まる行はコメントで、ブラウザーは無視します。空行でブ
ロックが終わり、イベントが配信されるため、空行に達する前に途切れたブ
ロックは破棄されます。

再接続も標準の一部です。接続が切れると、ブラウザーは再接続までの時間
を待ってから、もう一度リクエストを送ります。この時間の初期値はブラウ
ザーが決めるもので、標準ではおそらく数秒とされています。サーバーがイ
ベントにIDを付けていれば、新しいリクエストの`Last-Event-ID`ヘッダー
に最後のIDが入り、サーバーはその続きから送信できます。一方、ストリー
ムを完全に終わらせる応答もあります。200以外のステータス、または異な
るコンテンツタイプを受け取ると、ブラウザーは接続を諦め、再試行をやめ
ます。サーバーからストリームの終了を伝える方法として、標準は204
No Contentを挙げています。

通信方向は一方向だけです。最初のリクエストの後、その接続を通じてペー
ジからサーバーへ送るものはありません。ページ側から何かを伝えるとき
は、別のHTTPリクエストを送ります。

なぜ重要なのか

リアルタイムに見える機能の多くは、一方向の通信だけで足ります。時間の
かかる処理の進捗、通知、ダッシュボードの数値、少しずつ届く回答などで
す。ストリームを使わなければ、ページはポーリングする必要があります。
数秒おきに問い合わせても、たいていの応答は変化がないことを知らせるだ
けで、新しい情報が表示されるまで最大で問い合わせ間隔と同じだけ待つこ
とになります。ストリームなら、何かが起きた時点でサーバーが書き込みま
す。

データをサーバーから送る際によく使われる別の選択肢がWebSocketです。
これは接続をHTTPから独自のプロトコルへ切り替えます。サーバー送信イベ
ントは最初から最後までHTTPの中に収まるため、他のリクエストと同じプロ
キシやロードバランサーを通り、同じCookieとクロスオリジンリクエストの
規則を使い、ページの他の通信と1本のHTTP/2接続を共有できます。再接続
や最後のイベントからの再開はブラウザーに備わっており、チームごとに実
装する必要がありません。チャットや共同編集のように、クライアントから
もサーバーと同程度に送信する場合は、引き続きWebSocketが適していま
す。

この形式はブラウザー専用でもありません。どのHTTPクライアントでも読
め、ウェブ以外の仕様でも使われています。AIエージェントがツールを呼び
出すModel
Context Protocolでは、Streamable
HTTPトランスポートにより、サーバーは1つのJSONオブジェクトか
`text/event-stream`応答のどちらかでリクエストに答えられます。スト
リーム上では、最終応答の前にサーバー自身から通知やリクエストを送れま
す。また、イベントIDを付ければ、接続を失ったクライアントが
`Last-Event-ID`を使って再開できます。Streamable
HTTPは、以前のプロトコルバージョン2024-11-05で使われていたHTTP+SSEト
ランスポートを置き換えたものです。

選ぶ前に制約も理解しておく必要があります。ストリームが運べるのはテキ
ストだけなので、バイナリデータは先にテキストへ符号化しなければなりま
せん。ブラウザーの`EventSource`コンストラクターが受け取るのはURLと
`withCredentials`という1つのオプションだけです。そのため、ページ側か
らリクエストに`Authorization`ヘッダーを追加することはできません。

実際の活用例

次のやり取りは、時間のかかるエクスポート処理を追うものです。ブラウ
ザーはイベント41の後で接続を失い、再接続しています。そのため、リクエ
ストにはそのIDが含まれ、サーバーはイベント42から送信を続けます。

```http
GET /jobs/4471/events HTTP/1.1
Host: example.com
Accept: text/event-stream
Last-Event-ID: 41

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-store

retry: 5000

i: still working		engineer.company	70

id: 42
event: progress
data: {"done": 120, "total": 400}

id: 43
event: progress
data: {"done": 400, "total": 400}

id: 44
event: finished
data: {"report": "/jobs/4471/report.pdf"}

```

`retry`行は、それ以降の再接続まで5秒待つようブラウザーに求めます。コ
メント行はイベントを一切運びません。処理に動きがない間も接続に通信を
流しておくためのものです。ページは、2種類のイベントを名前で指定して
受け取ります。

```js
const source = new EventSource("/jobs/4471/events");
source.addEventListener("progress", (event) => {
  const { done, total } = JSON.parse(event.data);
  showProgress(done / total);
});
source.addEventListener("finished", (event) => {
  showReport(JSON.parse(event.data).report);
  source.close();
});
source.addEventListener("error", () => {
  if (source.readyState === EventSource.CLOSED) showRetryButton();
});
```

`close()`の呼び出しが重要です。サーバーが応答を正常に終了しても、ブ
ラウザーは接続が途切れたものとして再接続します。そのため、この呼び出
しがなければ、完了した処理のストリームが5秒後にまた開かれます。
`error`ハンドラーは2種類の失敗を区別します。`readyState`が
`CONNECTING`の間はまだ接続を試みていますが、`CLOSED`になった時点で諦
めています。

エージェントが回答を得た後も続く処理は、当サイトの既存ソフトウェアを
AIエージェント用のツールにするページでも扱っています。企業の業務操作
をツールとして提供し、MCPを扱えるエージェントにはMCPサーバーから同じ
操作を提供する仕組みです。時間のかかる処理はキューへ移すことで、処理
が続く間にエージェントへ回答を返します。MCP仕様では、サーバーは上の
例のようなイベントストリームを使い、クライアントのリクエストに対する
最終応答の前に、自身のリクエストや通知を送れます。

問題が起きるところ

イベントがまとめて届く、または最後に全部届きます。
サーバーとブラウザーの間にある何かが、応答をせき止めています。例えば
nginxは、背後のサーバーからの応答を既定でバッファリングし、バッファ
リングを無効にした場合だけ、受け取るそばから応答を転送します。HTML
Standardも、ストリームの送信タイミングを知らない層がHTTPのチャンク分
割を行うと、信頼性を損なう可能性があると警告しています。ストリームを
配信する場所のバッファリングを無効にしてください。nginxでは
`proxy_buffering
off`、または`X-Accel-Buffering:
no`応答ヘッダーを使います。サーバーのコードではイベントごとに出力を
フラッシュし、サーバー単体ではなく、プロキシを含む経路全体でテストし
ます。

動きのないストリームがタイムアウトで切れます。
しばらくデータが流れないと、プロキシは接続が失われたと判断します。
nginxの`proxy_read_timeout`は、2回の読み取りの間隔について既定値が60
秒で、それを過ぎると接続を閉じます。HTML
Standardも、一部の古いプロキシは短いタイムアウトで接続を切ると警告し
ています。対策として、15秒程度おきにコメント行を送ることを勧めていま
す。数バイトで済み、ブラウザーは無視します。

再接続時にイベントが失われます。
ブラウザーが`Last-Event-ID`を送るのは、サーバーがイベントにIDを付け
ていた場合だけです。また、このヘッダーが役立つのも、サーバーがそのID
の後に起きたことをまだ取り出せる場合だけです。すべてのイベントにスト
リーム内のカーソルとして使えるIDを付け、最近のイベントを一定範囲保存
して再送できるようにし、古すぎるIDからは再開できない場合には現在の状
態全体を送ります。MCP仕様には、取り入れる価値のある規則もあります。
IDは1つのストリームに属し、別のストリーム向けのメッセージを他のスト
リームで再送してはいけません。

再接続が止まらないか、完全に止まります。
正常に終了したストリームは、再接続までの時間が過ぎるたびに何度でも再
開されます。そのため、ページが`close()`を呼ばず、サーバーも再接続に
204で応答しなければ、完了した処理のストリームが開き直され続けます。
デプロイ中は逆のことが起きます。サーバーの再起動中にプロキシが502や
503を返すと、開いているすべての`EventSource`が200以外のステータスを
受け取り、どれも完全に停止します。`error`を受け取り、`readyState`が
`CLOSED`なら、失敗するたびに長くなるランダムな遅延を挟んで、新しい
`EventSource`を作成します。

1つのブラウザーでストリームを開きすぎます。
ブラウザーには、1つのサーバーに対して同時に開ける接続数の上限があり
ます。HTTP/1.1で配信するストリームは、続いている間ずっとそのうち1本
を占有します。HTML
Standardは、開いているページごとに専用の`EventSource`があるサイトで
は、この上限に達し得ると警告しています。ストリームをHTTP/2で配信すれ
ば、複数のストリームで1本の接続を共有でき、RFC
9113は少なくとも100本のストリームを同時に許可することを推奨していま
す。あるいは、共有ワーカーを介してタブ間で1つの`EventSource`を共有し
ます。

アドレスにトークンが入ります。
`EventSource`は`Authorization`ヘッダーを送れないため、手早い対処とし
てURLにトークンを入れがちです。しかし、そのURLはリバースプロキシやア
クセスログに記録されます。ストリームは、ページがすでに持つセッション
Cookieで認証し、別オリジンから取得する場合は`withCredentials`を付け
ます。または、ストリームを開く直前に認証済みリクエストで取得する、有
効期間が短く1回だけ使えるチケットで認証します。

参考資料

  * HTML Standard：サーバー送信イベント —
ストリーム形式、`EventSource`インターフェース、再接続、プロキシと接
続数上限に関する作成者向けの注意事項を説明しています。

  * トランスポート — Model Context Protocol —
サーバーがイベントストリームで応答できるStreamable HTTPと、切れたス
トリームの再開方法を説明しています。

  * RFC 9113：HTTP/2 — 1本の接続を共有するストリームと、同時に開ける
本数を制限する設定を説明しています。

  * nginx：ngx_http_proxy_moduleモジュール —
`proxy_buffering`、`X-Accel-Buffering`ヘッダー、`proxy_read_timeout`
を説明しています。

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/server-sent-events/	engineer.company	70
