a.tolmachev
134 lines
4.9 KiB
Markdown
134 lines
4.9 KiB
Markdown
# WebSocket
|
||
|
||
## 1. Роль протокола в проекте
|
||
|
||
WebSocket поддерживается как полноценный upstream protocol для realtime, push-oriented и stateful integrations. Он не заменяет downstream MCP transport, а работает за Crank proxy.
|
||
|
||
Иными словами:
|
||
|
||
- downstream: MCP `Streamable HTTP`;
|
||
- upstream: WebSocket;
|
||
- Crank нормализует WebSocket lifecycle в bounded MCP tool semantics.
|
||
|
||
## 2. Что поддерживается в целевом продукте
|
||
|
||
- клиентское WebSocket подключение к внешнему upstream;
|
||
- custom headers и auth profiles;
|
||
- handshake config;
|
||
- optional subprotocol selection;
|
||
- subscription payload или start message;
|
||
- bounded `window` mode;
|
||
- `session` mode с `start/poll/stop`;
|
||
- `async_job` mode для control-plane и progress channels;
|
||
- JSON message parsing;
|
||
- text-frame based event collection;
|
||
- mapping `MCP input -> subscribe payload`;
|
||
- mapping `WebSocket message -> normalized JSON`;
|
||
- heartbeat/keepalive config;
|
||
- reconnect policy для controlled session modes.
|
||
|
||
## 3. Что не входит в текущий продуктовый scope
|
||
|
||
- raw binary frame passthrough в LLM;
|
||
- arbitrary bidirectional conversation tunnel;
|
||
- full message bus semantics;
|
||
- generic browser-like socket inspector;
|
||
- guaranteed resumability across arbitrary upstream websocket providers.
|
||
|
||
## 4. Ключевое архитектурное ограничение
|
||
|
||
WebSocket не публикуется как "живой канал в чат". Он должен быть выражен в одной из execution models:
|
||
|
||
- `window`
|
||
- `session`
|
||
- `async_job`
|
||
|
||
Недопустимо:
|
||
|
||
- бесконечно проксировать frames напрямую в MCP client;
|
||
- скрывать жизненный цикл сокета за одним неопределенным tool call;
|
||
- смешивать downstream SSE transport и upstream WebSocket semantics в одну абстракцию.
|
||
|
||
## 5. Типовые use cases
|
||
|
||
### 5.1. Monitoring and telemetry
|
||
|
||
- realtime метрики;
|
||
- device telemetry;
|
||
- market data;
|
||
- anomaly events.
|
||
|
||
### 5.2. Event subscriptions
|
||
|
||
- alert streams;
|
||
- queue events;
|
||
- workflow transitions;
|
||
- security events.
|
||
|
||
### 5.3. Stateful control channels
|
||
|
||
- rollout progress;
|
||
- remote task status;
|
||
- infrastructure control plane updates;
|
||
- long-running remote sessions.
|
||
|
||
## 6. Внутренняя модель WebSocket operation
|
||
|
||
WebSocket operation должна включать:
|
||
|
||
- `url`
|
||
- `headers`
|
||
- `subprotocols`
|
||
- `connect_timeout_ms`
|
||
- `heartbeat_interval_ms`
|
||
- `subscribe_message_template`
|
||
- `unsubscribe_message_template`
|
||
- `input_mapping`
|
||
- `output_mapping`
|
||
- `execution_config`
|
||
- `tool_description`
|
||
|
||
## 7. Как оператор настраивает WebSocket operation
|
||
|
||
1. Указывает URL WebSocket upstream.
|
||
2. При необходимости выбирает auth profile и headers.
|
||
3. Указывает subprotocol или оставляет пустым.
|
||
4. Выбирает execution mode: `window`, `session` или `async_job`.
|
||
5. Настраивает subscribe payload.
|
||
6. Указывает правила извлечения items, status и cursor.
|
||
7. Настраивает aggregation limits.
|
||
8. Выполняет test run.
|
||
9. Публикует operation как MCP tool или tool family.
|
||
|
||
## 8. Поведение runtime
|
||
|
||
При выполнении WebSocket operation runtime должен:
|
||
|
||
1. Валидировать MCP input.
|
||
2. Построить subscribe payload.
|
||
3. Открыть WebSocket connection.
|
||
4. Пройти handshake и auth.
|
||
5. Отправить subscribe message.
|
||
6. Собрать bounded window или session step.
|
||
7. Нормализовать messages в JSON.
|
||
8. Применить output mapping.
|
||
9. Закрыть соединение или сохранить session state.
|
||
|
||
## 9. Критические нюансы
|
||
|
||
- upstream WebSocket может быть stateful и требовать explicit unsubscribe;
|
||
- heartbeat и reconnect должны быть управляемыми через config, а не захардкоженными;
|
||
- session state должен хранить cursor, last_event и subscription metadata;
|
||
- disconnect downstream MCP client не означает cancel upstream session;
|
||
- runtime обязан уметь cleanly завершать orphaned connections.
|
||
|
||
## 10. Почему WebSocket должен быть отдельным adapter
|
||
|
||
WebSocket нельзя свести к "почти SSE" или "почти HTTP", потому что:
|
||
|
||
- transport двунаправленный;
|
||
- lifecycle connection stateful;
|
||
- есть handshake, heartbeat и reconnect;
|
||
- подписка часто задается сообщением, а не URL;
|
||
- semantics событий и прогресса отличаются от request-response вызова.
|