MINARA多重化 WebSocket によるストリーミング
1 本の WebSocket でチャット、通知、設定、入出金監視、ワークフロー、Data Studio プレビューを運び、チャンネル別シーケンスと再接続リプレイを提供します。
GET /v1/stream (WebSocket)
ゲートウェイの長時間サーバープッシュは 1 本の WebSocket に多重化されます。ブラウザーのオリジン当たり約 6 本という HTTP/1.1 接続枠を圧迫せず、あるタブの混雑したストリームが他の通常リクエストを妨げません。
| メソッド | GET (HTTP Upgrade: websocket) |
| パス | /v1/stream |
| 認証 | ?token=<GATEWAY_AUTH_TOKEN> |
接続
ゲートウェイのオリジンから ws:// または wss:// を選び、/v1/stream に接続します。GATEWAY_AUTH_TOKEN が有効なら ?token=<token> を追加します。不正または欠落した token はハンドシェイク時に 401 で拒否されます。チャンネルはストリーム種別、キーはチャンネル内の購読対象です。
wss://<gateway-host>/v1/stream?token=<GATEWAY_AUTH_TOKEN>チャンネル
| Channel | Key | Replay | Source |
|---|---|---|---|
chat | session_id | yes | POST /v1/chat/stream |
notifications | "" | no | notification bus |
prefs | "" | no | runtime preferences |
deposit | chain:asset:address | yes | deposit watch |
withdraw | operationId | yes | withdraw watch |
workflow | instanceId | yes | workflow run bus |
data-studio | session_id | yes | Data Studio preview |
chat、deposit、withdraw、workflow、data-studio はリプレイ対応です。notifications と prefs は購読後のライブイベントだけを配信します。オンデマンドチャンネルは最初の購読者で上流処理を開始し、最後の購読者が離れると停止します。
クライアントからサーバーへのフレーム
JSON 制御フレームで購読と解除を行います。同じ (channel, key) の再購読は以前の接続を置き換えます。fromSeq は再接続カーソルで、サーバーはそれより厳密に大きいシーケンスのイベントだけを再送します。
{ "op": "subscribe", "channel": "chat", "key": "chat_abc", "fromSeq": 0 }{ "op": "unsubscribe", "channel": "chat", "key": "chat_abc" }サーバーからクライアントへのフレーム
各イベントは 1 個の JSON フレームです。seq は (channel, key) ごとに 1 から単調増加し、type と data は各チャンネルのイベント構造をそのまま保持します。
{ "channel": "chat", "key": "chat_abc", "seq": 12, "type": "text_delta", "data": { "text": "…" }制御フレーム
__error は購読拒否またはライブストリームなし、__truncated はリプレイバッファのあふれで古いイベントが失われたことを示します。どちらも seq: 0 でリプレイ対象外です。
再接続と再開
切断後、参照クライアントは指数バックオフで再接続し、各チャンネルで確認済みの最大 seq から再開します。バッファはプロセスローカルで、ゲートウェイ再起動後は残りません。再接続予算を使い切ると各ライブ購読のエラーハンドラーが一度呼ばれ、その後も上限付きバックオフで試行を続けます。
キープアライブ
ゲートウェイは一定間隔で開いている各ソケットへ ping を送ります。ブラウザーは自動的に pong を返すため、アクティブな購読がない接続もプロキシのアイドル切断から守られます。