feat(import): preserve supported HTTP contracts
This commit is contained in:
1 parent
083974c27f
commit
f8ee7c9bfe
87 files changed
+7496
-534
No files matched your search
+16
-9
@@ -6,14 +6,14 @@ REST - базовый и первый по очередности реализа
|
||||
|
||||
## 2. Что поддерживается в целевом продукте
|
||||
|
||||
- HTTP methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
|
||||
- HTTP methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
|
||||
- загрузка примера входного `JSON`
|
||||
- загрузка примера выходного `JSON`
|
||||
- path parameters
|
||||
- query parameters
|
||||
- headers
|
||||
- JSON request body
|
||||
- JSON response body
|
||||
- headers и cookie parameters
|
||||
- JSON, `application/x-www-form-urlencoded` и `multipart/form-data` request body
|
||||
- JSON response body и явный no-content outcome
|
||||
- auth: `Bearer`, `Basic`, API key
|
||||
- timeout и базовые transport settings
|
||||
- request mapping
|
||||
@@ -24,13 +24,9 @@ REST - базовый и первый по очередности реализа
|
||||
|
||||
## 3. Что отложено
|
||||
|
||||
- multipart/form-data
|
||||
- file upload/download как отдельный сценарий
|
||||
- XML payload как основной формат
|
||||
- OpenAPI import с автоматическим созданием mappings
|
||||
- webhooks
|
||||
- long polling как специальный режим
|
||||
- `HEAD` и `OPTIONS` как отдельные пользовательские сценарии
|
||||
|
||||
## 4. Внутренняя модель REST operation
|
||||
|
||||
@@ -70,10 +66,13 @@ Input mapping должен поддерживать:
|
||||
- `$.mcp.* -> $.request.path.*`
|
||||
- `$.mcp.* -> $.request.query.*`
|
||||
- `$.mcp.* -> $.request.headers.*`
|
||||
- `$.mcp.* -> $.request.cookies.*`
|
||||
- `$.mcp.* -> $.request.body.*`
|
||||
- константы
|
||||
- значения по умолчанию
|
||||
|
||||
Если endpoint поддерживает несколько request media types, `content_type` и `body` образуют одну пару: selector выбирает schema и wire serialization. Для одного формата media type фиксируется в contract.
|
||||
|
||||
Output mapping должен поддерживать:
|
||||
|
||||
- `$.response.body.* -> $.output.*`
|
||||
@@ -94,9 +93,17 @@ Output mapping должен поддерживать:
|
||||
6. Применить output mapping.
|
||||
7. Вернуть итоговый результат MCP server.
|
||||
|
||||
Multipart binary field принимает inline object с обязательным строковым `data_base64` и необязательными строковыми `filename`/`content_type`. Base64 использует standard alphabet и padding, без whitespace и data-URI. Пустая строка задаёт файл из нуля байтов. Массив файлов передаётся массивом таких объектов; каждый элемент становится отдельной частью.
|
||||
|
||||
Если `filename` отсутствует, adapter не добавляет и не угадывает его. MIME выбирается из `content_type` аргумента, единственного source MIME либо `application/octet-stream`, если source не задаёт ограничения. При нескольких source MIME нужен явный выбор. Неверные metadata, MIME и base64 отклоняются до outbound I/O. Лимит `CRANK_OUTBOUND_MAX_REQUEST_BYTES` применяется ко всему сериализованному body, включая multipart boundary и headers частей.
|
||||
|
||||
Для optional body отсутствие обоих полей `content_type`/`body` означает отсутствие HTTP body. Неполная пара ошибочна; `body: null` разрешён только nullable schema выбранного формата. Параметры с wire names `body` или `content_type` получают отдельные aliases и не подменяют selector.
|
||||
|
||||
Сохранённые Operations без typed request contract продолжают сериализовать body как JSON, сохраняя ранее настроенный Content-Type. Для typed contract заголовок формируется выбранным encoder в единственном экземпляре. Если mapped cookie-параметры конфликтуют с существующим Cookie (в том числе из Auth Profile), запрос отклоняется до outbound I/O: пользовательские параметры не заменяют credentials.
|
||||
|
||||
## 8. Нюансы и ограничения
|
||||
|
||||
- `DELETE` допускается, но body для него не считается обязательным сценарием совместимости.
|
||||
- Body contract определяется исходным endpoint, включая `DELETE`.
|
||||
- `PATCH` требует аккуратной работы с частичными payload, поэтому mapping должен позволять заполнять только выбранные поля.
|
||||
- Успешный HTTP status сам по себе не гарантирует корректность бизнес-ответа, если response mapping не может извлечь ожидаемые данные.
|
||||
- REST adapter не должен содержать бизнес-логику маппинга, только transport-логику.
|
||||
|
||||
Reference in new issue
Block a user