crank/docs/protocols/soap.md

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.