Server-Sent Eventsとは何か？ ストリーム、その用途と制約

Scrapeless Agent Browser は、ページが server-sent events を通じて更新を受け取る可能性がある動的な Web サイトに対してブラウザ自動化を実行します。

Server-Sent Events は一方向の HTTP ストリームである

Server-sent events（一般に SSE と略される）は、サーバーが長時間継続する HTTP レスポンスを通じてテキストイベントの連なりを配信できるようにします。クライアントが接続を開き、サーバーは更新が利用可能になり次第それを書き込みます。ダッシュボードはジョブの進捗を受け取ることができ、ページは、何かが変化するたびに毎回リソース全体を要求することなく、増分的な出力を表示できます。

この HTML event-stream 仕様 は、イベントフォーマットとブラウザの EventSource インターフェイスの両方を定義しています。レスポンスのメディアタイプは text/event-streamであり、ストリームは UTF-8 テキストです。SSE はペイロードフォーマットとして JSON を要求しません。アプリケーションはイベントの data 内にシリアライズされた JSON を入れることができますが、その JSON をパースするのは、イベントのフレーミングの後に行う別のステップです。

SSE はアプリケーションのメッセージング層では一方向です。ブラウザはストリームを開く HTTP リクエストを依然として送信し、ユーザー操作用に別のリクエストを送ることもできます。イベントストリーム自体がサーバーからクライアントへのメッセージを運びます。この区別により、通知や進捗表示には SSE を利用しつつ、コマンドは独自の認可とバリデーションを持つ通常のアプリケーションエンドポイントに保持する、といった使い方が可能になります。

テキストをメッセージに変えるイベントフレーミングの仕組み

SSE メッセージは、改行で区切られたフィールドから構成され、空行でディスパッチされます。 data フィールドはペイロードテキストを運び、 event フィールドはイベントタイプに名前を付けることができ、 id フィールドはイベント ID を更新できます。コロンで始まる行はコメントです。1 つのイベント内に複数の data 行がある場合、それらは改行文字で連結されます。

ネットワークリードはイベントと対応しません。トランスポートチャンクには、フィールドの一部、複数の完全なメッセージ、あるいは 1 つのメッセージの終端と次のメッセージの開始が含まれていることがあります。カスタムコンシューマーには、永続的なテキストデコーダーとフレーミング用バッファが必要です。到着した各チャンクを、未完成のテキストを保持せずに改行で分割すると、文字のデコードとメッセージ境界の両方が壊れる可能性があります。

名前のないイベントは EventSource の汎用 message ハンドラーに届き、名前付きイベントは対応するイベントタイプを使用します。アプリケーション開発者は、それらの名前とペイロードの形状を文書化すべきです。進捗メッセージ、アイテム更新、最終完了メッセージは、同じものとして解釈されるべきではありません。ストリームトランスポートはイベントを届けるだけであり、各イベントの意味を定義するのはアプリケーションです。

EventSource と Fetch は異なるインターフェイスを公開する

EventSource はイベントストリーム用に設計されたブラウザ API であり、Fetch はより一般的なリクエストとレスポンスのインターフェイスを公開します。EventSource は任意のリクエスト構成ではなく、URL と限られたオプションのセットを受け取ります。一般的なカスタム認可ヘッダーを設定したり、リクエストボディを送信したりするためのオプションは提供しません。API 契約が特定のヘッダーや POST リクエストを要求する場合、これは重要になります。

Fetch ベースのコンシューマーはストリーミングレスポンスのバイトを読み取り、自身でイベントパースを実装できます。 web Streams API はストリーム抽象を提供しますが、任意のテキストを自動的に正しくフレーミングされた SSE メッセージにしてくれるわけではありません。Fetch を利用するコンシューマーは、段階的なデコード、メッセージ境界、キャンセル、およびサービスのアプリケーションレベルでの完了シグナルを考慮しなければなりません。

エンドポイントの契約に基づいてインターフェイスを選択してください。ストリーミングと記述されているサービスであっても、SSE ではなく、改行区切りの JSON、独自のバイナリフォーマット、あるいは通常のレスポンステキストを送信している場合があります。パーサーを選ぶ前に、レスポンスのメディアタイプとフレーミングを確認してください。徐々に更新されていくビジュアルなページも、十分な証拠にはなりません。そうした更新は、SSE、WebSockets、ポーリング、あるいはすでにダウンロードされたデータのクライアントサイドレンダリングによって届いている可能性があります。

プロキシとバッファリングが体験を変える場所

コンポーネントがレスポンスを転送する前にバッファリングすることで、見かけ上は遅くてもイベントストリーム自体は正しく動作している場合があります。リバースプロキシ、アプリケーションサーバー、ミドルウェア、圧縮レイヤーなどが、バイトがクライアントに到達するタイミングに影響します。更新が意図したケイデンスではなく大きな塊で現れる場合は、配信経路全体を確認してください。サーバー側での書き込みがすぐに完了しても、それがブラウザへの即時配信を証明するものではありません。

The SSE イベント配信ガイダンス では、接続を維持するためのメッセージフォーマットやコメントについて説明しています。運用上の設定は、最終的にはデプロイされているスタックに依存します。特定のサーバーおよびプロキシ構成におけるアイドルタイムアウトとレスポンスバッファリングを確認し、バックエンドのタイムスタンプだけに頼るのではなく、ブラウザでの到着時刻を観察してください。

リソースの所有関係も重要です。イベントが送信されていない場合でも、開いているストリームはシステムのどこかに接続状態を占有します。ユーザーが関連ビューから離れたときや、有限な観測タスクで十分な情報が集まったときにはストリームを閉じてください。キャパシティプランニングでは、同時接続数とイベントのボリュームを別々に考慮する必要があります。静かな接続と頻繁にイベントが流れる接続とでは、処理コストが大きく異なり得ます。

イベント ID は配信保証を定義しない

イベント識別子は、アプリケーションがストリーム内での位置を表現する手段を提供します。ブラウザは、後続の event-stream 接続を確立するときに最後のイベント ID を伝えることができますが、識別子があるからといってサーバーに履歴データの保持が義務付けられるわけではありません。過去の取り逃したイベントを提供できるかどうか、また期限切れの位置をどのように扱うかは、サーバーの保持ポリシーおよびリプレイポリシーによって決まります。

厳密に 1 回限りの処理を実現するには、ID を受信するだけでは不十分です。アプリケーションはイベントを受信しても保存する前に終了する可能性がありますし、処理位置を記録する前にイベントを保存してしまう可能性もあります。耐久性のある取り込みを行うには、イベントの同一性を定義し、ストレージの振る舞いを明示的にしてください。重複検出は、ペイロードの見えるテキストがイベントを一意に特定すると仮定するのではなく、アプリケーションのイベント契約に基づいて行う必要があります。

進捗インジケーターには、恒久的なイベント履歴が不要な場合がよくあります。財務台帳や監査ログは要件が異なり、文書化された耐久的なインターフェースを使用すべきです。タスクに必要な記録保証に基づいてデータソースを選択してください。ライブのビジュアルフィードは、プロセスを観察するのに役立ちますが、完全な履歴データセットの唯一のソースとしては不適切な場合があります。

認証、オリジン、および機微なペイロード

SSE エンドポイントは、他のエンドポイントに期待されるのと同じリソース認可を強制しなければなりません。ユーザーがストリームを開くことができるからといって、バックエンドが公開し得るあらゆるイベントがそのユーザーに許可されるわけではありません。呼び出し元に応じてメッセージをフィルタリングし、テナント境界をサーバー側の購読ロジック内に保ってください。EventSource の制約された設定オプションを回避する目的だけで、ストリーム URL にシークレットを埋め込むことは避けましょう。

クロスオリジンのストリームも、ブラウザのアクセスルールの対象になります。 Fetch のオリジンとクレデンシャルのモデル は、CORS とクレデンシャルがブラウザリクエストとどのように相互作用するかを規定します。サーバーのレスポンスが成功していても、ブラウザがそれを呼び出し元ページに公開できなければ不十分です。クレデンシャルを使用する場合は、実際のクライアントに合わせて、許可されるオリジンとクレデンシャルの扱いを構成してください。

ログやブラウザキャプチャには、イベントペイロードが保持されることがあります。個人データやクレデンシャルを日常的な診断から排除し、キャプチャされたストリームコンテンツに適切な保持期間を設定してください。認可されたテスト中は、診断上の問いに答えるために必要な場合に限り、イベントタイプ、サニタイズされた識別子、および到着タイミングを記録します。完全なプライベートイベント履歴をキャプチャするには、実際のタスク上の必要性と許可が伴うべきです。

本当に必要なアプリケーション状態を観測する

ブラウザ自動化タスクは、すべてのネットワークアクティビティが終了するのを待つのではなく、意味のあるページ状態に達した時点で停止すべきです。SSE 接続は、ページのライフタイム全体にわたって開いたままにできてしまいます。有限なデータ収集の場合は、関連するセレクタ、完了ラベル、レコード ID、または観測ウィンドウを定義してください。永続的なストリームを持つページでは、ネットワークアイドル状態が完了を表すとは限りません。

有用な仮想的な進捗タスクとしては、公開されたジョブページを監視し、完了ラベルが表示されたら可視の結果サマリを読み取る、というものがあります。自動化は、観測ウィンドウ内に完了が現れたかどうかを記録しますが、すべての内部進捗イベントが保存されたと推論することはありません。関連する WebSocket メッセージングの概念 では、アプリケーションが頻繁な双方向のやりとりを必要とする場合、別個の双方向チャネルの方が適している理由を説明しています。

SSE が製品要件に適合するかどうかを判断する

SSE は、サーバーが更新を配信し、クライアントが主に受信側に回るインターフェースに適しています。接続およびバッファリングの挙動がデプロイ環境に合致している限り、ステータスフィード、通知、インクリメンタルテキストなどに実用的な選択肢となります。耐久的な一括エクスポートや任意の双方向メッセージング、または選択した SSE クライアントでは表現できないリクエスト形状が必要な場合は、別のインターフェースを優先してください。

SSE を採用する前に、メッセージタイプ、認可スコープ、完了時の挙動、保持に関する期待、リソースクリーンアップを明文化してください。ブラウザ観測の予算策定にあたっては、 Scrapeless の料金 を別途確認します。健全な設計とは、セッションが生み出した有用な作業を計測し、その作業が完了した時点で接続を閉じることであり、無期限に開きっぱなしのページを成功した収集として扱うことではありません。

結論

ページがサーバー発信のテキスト更新を必要とし、アプリケーション側でその意味とライフサイクルを定義できる場合に SSE を使用してください。ストリームに依存する前に、フレーミング、オリジン規則、バッファリング、および配信に関する前提を検証します。ブラウザでの観測では、宣言された境界内で必要な状態を収集し、その観測が完了したらセッションを終了します。