# 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.