docs: extend protocol platform architecture

2026-04-06 01:57:26 +03:00
parent 04ed704e94
commit 7f15b2db9e
12 changed files with 475 additions and 34 deletions
@@ -4,7 +4,7 @@

 GraphQL поддерживается как отдельный тип интеграции, но на слое MCP намеренно ограничивается. Цель платформы не в том, чтобы дать LLM универсальный доступ ко всему GraphQL endpoint, а в том, чтобы превратить конкретный GraphQL-запрос в узкий и предсказуемый MCP tool.

-## 2. Что поддерживается в MVP
+## 2. Что поддерживается в целевом продукте

 - `query`
 - `mutation`
@@ -21,7 +21,7 @@ GraphQL поддерживается как отдельный тип интег
 - ручная донастройка через `JSONPath`
 - тестовый вызов перед публикацией

-## 3. Что не входит в MVP
+## 3. Что отложено

 - `subscription`
 - универсальный GraphQL explorer для LLM
@@ -4,7 +4,7 @@

 gRPC поддерживается как третий основной протокол платформы в управляемой форме. Цель состоит не в том, чтобы покрыть все возможности gRPC, а в том, чтобы представить unary и bounded server-streaming методы как MCP tools с предсказуемым жизненным циклом.

-## 2. Что поддерживается в MVP
+## 2. Что поддерживается в целевом продукте

 - unary RPC
 - bounded server-streaming через execution modes `window`, `session`, `async_job`
@@ -21,7 +21,7 @@ gRPC поддерживается как третий основной прот
 - auth/transport settings на уровне соединения
 - тестовый вызов перед публикацией

-## 3. Что не входит в MVP
+## 3. Что отложено

 - `client streaming`
 - `bidirectional streaming`
@@ -4,7 +4,7 @@

 REST - базовый и первый по очередности реализации протокол платформы. На нем должна быть обкатана общая модель `Operation`, схема входа и выхода, маппинг, тестовый запуск и публикация MCP tool.

-## 2. Что поддерживается в MVP
+## 2. Что поддерживается в целевом продукте

 - HTTP methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
 - загрузка примера входного `JSON`
@@ -23,7 +23,7 @@ REST - базовый и первый по очередности реализа
 - тестовый вызов перед публикацией
 - optional REST SSE upstream в bounded `window` и `session` режимах

-## 3. Что не входит в MVP
+## 3. Что отложено

 - multipart/form-data
 - file upload/download как отдельный сценарий
@@ -0,0 +1,126 @@
+# SOAP
+
+## 1. Роль протокола в проекте
+
+SOAP поддерживается как enterprise-oriented upstream protocol для интеграций с системами, где REST уже не является стандартом де-факто.
+
+Типичные домены:
+
+- ERP;
+- banking;
+- insurance;
+- government and B2B gateways;
+- legacy enterprise systems;
+- ESB-oriented internal APIs.
+
+## 2. Что поддерживается в целевом продукте
+
+- SOAP 1.1 и SOAP 1.2;
+- WSDL upload/import;
+- выбор `service`, `port` и `operation`;
+- document/literal first;
+- XML schema extraction из WSDL/XSD;
+- input/output schema generation;
+- mapping `MCP JSON -> SOAP body`;
+- mapping `SOAP response -> normalized JSON`;
+- SOAP headers config;
+- basic auth, bearer auth и auth profiles;
+- test run;
+- publish as MCP tool.
+
+## 3. Что не входит в текущий продуктовый scope
+
+- полный стек WS-* расширений;
+- MTOM attachments;
+- arbitrary XML transformation engine;
+- full schema authoring inside UI;
+- server-side SOAP hosting.
+
+## 4. Ключевое архитектурное ограничение
+
+SOAP не является просто HTTP POST с XML body.
+
+Для платформы SOAP operation определяется:
+
+- WSDL model;
+- service/port/operation binding;
+- envelope structure;
+- namespaces;
+- optional SOAPAction;
+- fault model;
+- XML schema contract.
+
+Поэтому SOAP должен иметь отдельный adapter и отдельную конфигурационную модель.
+
+## 5. Типовые use cases
+
+- enterprise CRM/ERP operations;
+- payment and settlement integrations;
+- policy and claims systems;
+- regulated B2B data exchange;
+- legacy internal service contracts.
+
+## 6. Внутренняя модель SOAP operation
+
+SOAP operation должна включать:
+
+- `wsdl_ref`
+- `service_name`
+- `port_name`
+- `operation_name`
+- `endpoint_override`
+- `soap_version`
+- `soap_action`
+- `input_schema`
+- `output_schema`
+- `input_mapping`
+- `output_mapping`
+- `header_config`
+- `execution_config`
+- `tool_description`
+
+## 7. Как оператор настраивает SOAP operation
+
+1. Загружает WSDL.
+2. Система извлекает services, ports, operations и XSD schemas.
+3. Оператор выбирает service, port и operation.
+4. UI показывает input/output schema в JSON-oriented виде.
+5. Оператор настраивает mapping `MCP input -> SOAP body`.
+6. При необходимости задает SOAP headers и auth profile.
+7. Настраивает output mapping и fault handling.
+8. Выполняет test run.
+9. Публикует operation как MCP tool.
+
+## 8. Поведение runtime
+
+При выполнении SOAP operation runtime должен:
+
+1. Валидировать MCP input.
+2. Построить XML envelope.
+3. Подставить namespaces и headers.
+4. Выполнить HTTP request.
+5. Разобрать SOAP response и SOAP Fault.
+6. Нормализовать XML result в JSON.
+7. Применить output mapping.
+8. Вернуть итоговый результат.
+
+## 9. Критические нюансы
+
+- WSDL import должен быть отделен от runtime call;
+- XML namespaces должны быть first-class частью конфигурации;
+- SOAP Fault нельзя сводить только к HTTP error;
+- input/output schema должны отображаться в UI как нормализованные поля, а не как raw XML;
+- auth и headers должны настраиваться отдельно от body mapping.
+
+## 10. Почему SOAP должен входить в product scope
+
+Если Crank позиционируется как enterprise integration platform, отсутствие SOAP оставляет большую часть legacy и regulated environments вне продукта.
+
+Поэтому SOAP должен быть частью общей protocol strategy наравне с:
+
+- REST
+- GraphQL
+- gRPC
+- WebSocket
+
+Но при этом он должен оставаться request-response oriented adapter, а не ломать общую execution model.
@@ -0,0 +1,133 @@
+# 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 вызова.