a.tolmachev
163 lines
5.5 KiB
Markdown
163 lines
5.5 KiB
Markdown
# 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`
|
||
|
||
Code-level model:
|
||
|
||
- `crank_core::SoapTarget`
|
||
- `crank_core::SoapProtocolOptions`
|
||
- `crank_core::SoapVersion`
|
||
- `crank_core::SoapBindingStyle`
|
||
- `crank_core::SoapHeaderConfig`
|
||
- `crank_core::SoapFaultContract`
|
||
- `crank_core::SoapOperationMetadata`
|
||
- `crank_schema::XmlNodeKind`
|
||
- `crank_schema::XmlQualifiedName`
|
||
- `crank_schema::XmlSchemaBinding`
|
||
|
||
Execution constraints:
|
||
|
||
- `Protocol::Soap` поддерживает только `unary` и `async_job`;
|
||
- `window` и `session` для SOAP не поддерживаются;
|
||
- runtime foundation поддерживает `unary` SOAP request-response execution;
|
||
- `window` и `session` execution по-прежнему отклоняются как unsupported mode.
|
||
|
||
## 7. Как оператор настраивает SOAP operation
|
||
|
||
1. Загружает WSDL.
|
||
2. При необходимости загружает supporting XSD.
|
||
3. Система извлекает services, ports и operations из WSDL.
|
||
4. Оператор выбирает service, port и operation.
|
||
5. UI показывает input/output schema в JSON-oriented виде.
|
||
6. Оператор настраивает mapping `MCP input -> SOAP body`.
|
||
7. При необходимости задает SOAP headers и auth profile.
|
||
8. Настраивает output mapping и fault handling.
|
||
9. Выполняет test run.
|
||
10. Публикует operation как MCP tool.
|
||
|
||
Foundation routes:
|
||
|
||
- `POST /operations/{operation_id}/descriptors/wsdl`
|
||
- `POST /operations/{operation_id}/descriptors/xsd`
|
||
- `GET /operations/{operation_id}/soap/services`
|
||
|
||
Current UI foundation:
|
||
|
||
- protocol selection card on wizard step 1;
|
||
- dedicated SOAP step 3 panel;
|
||
- WSDL upload;
|
||
- optional XSD upload;
|
||
- backend-driven inspection of `service -> port -> operation`;
|
||
- applying selected binding metadata into the operation draft target.
|
||
|
||
## 8. Поведение runtime
|
||
|
||
При выполнении SOAP operation runtime должен:
|
||
|
||
1. Валидировать MCP input.
|
||
2. Построить XML envelope.
|
||
3. Подставить namespaces, `Content-Type` и `SOAPAction`.
|
||
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.
|