docs: extend protocol platform architecture

This commit is contained in:
a.tolmachev
2026-04-06 01:57:26 +03:00
parent 04ed704e94
commit 7f15b2db9e
12 changed files with 475 additions and 34 deletions
+100 -13
View File
@@ -49,7 +49,8 @@ Crank поддерживает streaming не как бесконечный те
- REST SSE в bounded режимах;
- GraphQL `query` и `mutation`;
- gRPC unary;
- gRPC server-streaming в bounded режимах.
- gRPC server-streaming в bounded режимах;
- WebSocket в bounded режимах.
Отложено:
@@ -59,6 +60,16 @@ Crank поддерживает streaming не как бесконечный те
- arbitrary websocket passthrough;
- raw infinite stream forwarding в MCP client.
### 3.3. Protocol capability matrix
| Protocol | Unary | Window | Session | Async Job | Notes |
| --- | --- | --- | --- | --- | --- |
| REST | Yes | Yes | Limited | Yes | SSE and long-poll sources are supported in controlled form |
| GraphQL | Yes | No | No | Limited | `query` and `mutation` only; `subscription` is future scope |
| gRPC | Yes | Yes | Yes | Yes | server-streaming only; client/bidi deferred |
| WebSocket | No | Yes | Yes | Yes | upstream adapter only; not downstream MCP transport |
| SOAP | Yes | Limited | Limited | Yes | primarily request-response enterprise workflows |
## 4. Поддерживаемые streaming modes
Crank поддерживает четыре режима выполнения operation.
@@ -71,7 +82,8 @@ Crank поддерживает четыре режима выполнения op
- REST;
- GraphQL `query` и `mutation`;
- gRPC unary.
- gRPC unary;
- SOAP.
### 4.2. `window`
@@ -91,7 +103,8 @@ Runtime открывает upstream stream или repeatedly polls upstream sour
- метрики за период;
- event window;
- SSE stream snapshot;
- gRPC server-stream window.
- gRPC server-stream window;
- WebSocket event window.
### 4.3. `session`
@@ -108,7 +121,8 @@ Runtime создает stream session, после чего данные чита
- follow logs;
- telemetry follow;
- alert/event feed;
- контроль длительных stream-подписок.
- контроль длительных stream-подписок;
- WebSocket subscriptions.
### 4.4. `async_job`
@@ -126,7 +140,8 @@ Runtime запускает long-running upstream operation и возвращае
- import/export;
- deploy/reindex;
- batch processing;
- инфраструктурные control-plane действия.
- инфраструктурные control-plane действия;
- SOAP workflows with deferred status polling.
## 5. Бизнес-кейсы
@@ -202,6 +217,38 @@ Runtime:
- пишет progress в session/job state;
- возвращает snapshots по `poll`.
### 5.6. WebSocket Realtime Feeds
LLM запрашивает:
- realtime alert snapshot;
- device telemetry window;
- market data slice;
- status feed по subscription channel.
Runtime:
- открывает upstream WebSocket;
- подписывается на channel;
- собирает bounded окно или session step;
- возвращает summary и limited items.
### 5.7. SOAP Enterprise Operations
LLM запрашивает:
- создание/поиск сущности в ERP;
- запуск enterprise workflow;
- получение статуса batch operation;
- B2B request через SOAP gateway.
Runtime:
- строит SOAP envelope из MCP input;
- вызывает enterprise endpoint;
- нормализует XML response или SOAP Fault;
- возвращает JSON-oriented output.
## 6. Функциональные требования
### 6.1. Общие
@@ -263,7 +310,7 @@ Runtime:
- устойчивость к disconnect downstream client;
- poll должен быть идемпотентным;
- long-running upstream action не должен считаться отмененным из-за SSE disconnect;
- resumability для downstream SSE допускается, но не является обязательной в MVP.
- resumability для downstream SSE допускается как следующая волна, но не является обязательной в первой реализации.
### 7.4. UX
@@ -492,13 +539,26 @@ REST:
GraphQL:
- `query` и `mutation`;
- `subscription` не входит в MVP.
- `subscription` отложен на отдельную protocol wave.
gRPC:
- unary;
- bounded server-stream collection;
- client/bidi не входят в MVP.
- client/bidi отложены на отдельную protocol wave.
WebSocket:
- bounded event collection;
- subscribe/poll/stop orchestration;
- heartbeat and reconnect policy.
SOAP:
- WSDL-driven request/response adapter;
- XML normalization;
- SOAP Fault normalization;
- future WS-Security expansion.
### 11.5. `apps/mcp-server`
@@ -526,9 +586,9 @@ gRPC:
- test-run screen для bounded window/session/job behavior;
- отдельные предупреждения про truncation и timeouts.
## 12. Ограничения MVP
## 12. Границы текущей продуктовой волны
В MVP входит:
В первой продуктовой волне входит:
- `Streamable HTTP` и SSE на MCP transport;
- `window` mode;
@@ -538,7 +598,14 @@ gRPC:
- tool family generation;
- bounded session/job state.
В MVP не входит:
Во второй продуктовой волне:
- WebSocket upstream adapter;
- SOAP adapter foundation;
- richer session tooling;
- expanded protocol smoke suite.
Отложено:
- GraphQL subscriptions;
- gRPC client streaming;
@@ -592,13 +659,33 @@ gRPC:
- `start/poll/stop`;
- `start/status/result/cancel`.
### 13.9. `feat/streaming-ui-config`
### 13.9. `feat/websocket-upstream-adapter`
- bounded WebSocket collection;
- subscribe/unsubscribe templates;
- heartbeat/reconnect policy;
- session integration.
### 13.10. `feat/soap-architecture-and-core-model`
- WSDL/XSD-driven domain model;
- SOAP execution config;
- XML normalization strategy.
### 13.11. `feat/soap-adapter-foundation`
- runtime SOAP adapter;
- envelope builder;
- fault normalization;
- test-run support.
### 13.12. `feat/streaming-ui-config`
- новый execution mode selector;
- limits/aggregation/safety blocks;
- test-run UX.
### 13.10. `feat/streaming-e2e`
### 13.13. `feat/streaming-e2e`
- публичные smoke targets;
- e2e сценарии;