MINARA멀티플렉스 WebSocket 스트리밍
하나의 WebSocket으로 채팅, 알림, 설정, 입출금 감시, 워크플로, Data Studio 미리보기를 전송하며 채널별 시퀀스와 재연결 재생을 제공합니다.
GET /v1/stream (WebSocket)
게이트웨이의 모든 장기 서버 푸시 스트림은 하나의 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" }서버에서 클라이언트로 보내는 프레임
각 이벤트는 하나의 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을 반환하므로 활성 구독이 없는 연결도 프록시의 유휴 연결 종료를 피할 수 있습니다.