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
-7
@@ -8,7 +8,7 @@ Crank умеет импортировать REST API из OpenAPI 3.x и Swagger
|
||||
2. Нажмите **Импорт OpenAPI** рядом с кнопкой **Новая операция**.
|
||||
3. Загрузите ровно один UTF-8 `.yaml`, `.yml` или `.json` файл размером от 1 B до 256 KiB. Вставка текста не поддерживается.
|
||||
4. Нажмите **Разобрать документ**.
|
||||
5. Проверьте preview: для каждого метода показываются поля `Path`, `Query`, `Header`, `Body` и поля ответа.
|
||||
5. Проверьте preview: сгенерированный contract сохраняет parameter locations, body formats и варианты успешного ответа.
|
||||
6. Выберите нужные группы и методы.
|
||||
7. Проверьте `Base URL`. Если в документе нет `servers`, укажите URL вручную.
|
||||
8. Выберите поведение при конфликте имени:
|
||||
@@ -30,16 +30,19 @@ Crank умеет импортировать REST API из OpenAPI 3.x и Swagger
|
||||
- отображаемое имя берется из `summary`;
|
||||
- описание инструмента берется из `description`;
|
||||
- группа берется из первого `tag`;
|
||||
- query/path/header параметры становятся входными параметрами MCP-инструмента;
|
||||
- JSON `requestBody` с объектной схемой раскладывается в отдельные входные поля;
|
||||
- схема успешного ответа берется из `200`, `201`, `202` или `default`.
|
||||
- query/path/header/cookie параметры становятся отдельными typed inputs MCP-инструмента;
|
||||
- JSON, `application/x-www-form-urlencoded` и `multipart/form-data` сохраняются как request contract; при нескольких поддерживаемых форматах вызов передаёт верхнеуровневые `content_type` и `body`;
|
||||
- все успешные `2xx` варианты сохраняются, включая `204` и response без тела.
|
||||
|
||||
Form/multipart поддерживает object root со scalar-полями, массивами scalar-значений и multipart files. Вложенные обычные объекты и массивы массивов блокируют импорт. Для URL-encoded массивов поддержана повторная передача ключей (`style: form`, `explode: true`; в Swagger — `collectionFormat: multi`). CSV и другие неподдерживаемые encoding-настройки получают blocker с указанием места в исходной спецификации.
|
||||
|
||||
После импорта откройте созданный черновик в мастере операции. На шаге **Связи полей** Crank покажет уже созданный маппинг в визуальном виде:
|
||||
|
||||
- `Path` — параметры из пути, например `/users/{id}`;
|
||||
- `Query` — query-параметры URL;
|
||||
- `Header` — заголовки запроса;
|
||||
- `Body` — поля JSON-тела.
|
||||
- `Cookie` — cookie-параметры, которые adapter сериализует в один wire header;
|
||||
- `Body` — typed тело запроса. Multipart file передаётся inline-объектом `{data_base64, filename?, content_type?}`; путь к файлу и URL не принимаются.
|
||||
|
||||
YAML-маппинг остается доступен в блоке **Дополнительно**, но для обычной настройки его редактировать не нужно.
|
||||
|
||||
@@ -52,7 +55,7 @@ YAML-маппинг остается доступен в блоке **Допол
|
||||
- нет схемы успешного ответа;
|
||||
- нет `servers`;
|
||||
- слишком много входных параметров;
|
||||
- используется тело запроса без JSON-схемы.
|
||||
- требуется ручная проверка неполных metadata.
|
||||
|
||||
Эти предупреждения не блокируют импорт, но перед публикацией лучше открыть созданную операцию и проверить:
|
||||
|
||||
@@ -64,6 +67,12 @@ YAML-маппинг остается доступен в блоке **Допол
|
||||
|
||||
## Ограничения Community
|
||||
|
||||
В Community импортируются только REST/HTTP методы: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
|
||||
В Community импортируются только REST/HTTP методы: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`. `TRACE` и `CONNECT`, XML media types и неподдерживаемые serialization constructs получают явный finding и не получают неявного fallback.
|
||||
|
||||
Semantic loss получает blocker с source location: такой candidate нельзя применить как actionable Draft. Это относится к неподдерживаемым schema/serialization constructs и невалидным target URL, включая embedded userinfo.
|
||||
|
||||
Один endpoint с несколькими request formats остаётся одним Tool. Поля `content_type` и `body` выбирают одну schema и соответствующую сериализацию; неизвестный selector или body другой ветви отклоняются до отправки запроса. Для единственного формата selector не нужен. Подробный inline-file contract описан в [REST](protocols/rest.md).
|
||||
|
||||
Новые imports используют `normalized-ir-v4` / `preview-v4`. Сохранённые v2/v3 jobs воспроизводят сохранённый preview, а legacy-v1 использует отдельную историческую projection. Обновление importer не меняет inputs существующих jobs.
|
||||
|
||||
Другие форматы спецификаций и протоколов в Community-импорт не входят.
|
||||
@@ -22,6 +22,10 @@ Aggregate reads return a strong state `ETag` bound to workspace, Operation ident
|
||||
|
||||
Canonical export uses `format_version: "2"`. Legacy version 1 is import-only and is normalized into v2. The body limit is 256 KiB; one document, depth 64, at most 20,000 nodes, 4,096 collection items and 64 KiB line/scalar values are accepted. Credentials, URL userinfo, storage paths and persistence/runtime-only metadata are never portable.
|
||||
|
||||
Portable REST targets use the uppercase HTTP method names `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` and `OPTIONS`. The optional versioned `request_contract` records supported media types and their input-schema branches. A multi-media request exposes a `content_type` selector alongside the typed `body`; selecting a media type also selects its validation schema. Multipart field MIME choices remain in `multipart_field_mime_types`.
|
||||
|
||||
`response_contract` preserves successful status/media branches and their output-schema association. A branch without a media type represents an explicit no-content outcome, with `null` as its output. Schema `format`, defaults and nullability survive export/import. Existing documents without HTTP descriptors retain their legacy execution semantics; their bodies are not interpreted as internal media-selector envelopes.
|
||||
|
||||
## Stable failure codes
|
||||
|
||||
- `operation_precondition_required`
|
||||
|
||||
+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-логику.
|
||||
|
||||
@@ -36,15 +36,53 @@
|
||||
"required": ["kind", "base_url", "method", "path_template"],
|
||||
"properties": {
|
||||
"kind": { "const": "rest" }, "base_url": { "type": "string", "minLength": 1, "maxLength": 4096 },
|
||||
"method": { "enum": ["get", "post", "put", "patch", "delete"] },
|
||||
"method": { "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "get", "post", "put", "patch", "delete"] },
|
||||
"path_template": { "type": "string", "minLength": 1, "maxLength": 4096 },
|
||||
"static_headers": { "$ref": "#/$defs/string_map" }
|
||||
"static_headers": { "$ref": "#/$defs/string_map" },
|
||||
"request_contract": { "$ref": "#/$defs/rest_request_contract" },
|
||||
"response_contract": { "type": "array", "maxItems": 4096, "items": { "$ref": "#/$defs/rest_response_descriptor" } },
|
||||
"multipart_field_mime_types": {
|
||||
"type": "object", "maxProperties": 64,
|
||||
"additionalProperties": {
|
||||
"type": "object", "maxProperties": 4096,
|
||||
"additionalProperties": { "type": "array", "maxItems": 64, "items": { "type": "string", "maxLength": 256 } }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"rest_request_contract": {
|
||||
"type": "object", "additionalProperties": false,
|
||||
"required": ["version", "body_field", "body_required", "variants"],
|
||||
"properties": {
|
||||
"version": { "const": "1" },
|
||||
"body_field": { "type": "string", "minLength": 1, "maxLength": 256 },
|
||||
"selector_field": { "type": "string", "minLength": 1, "maxLength": 256 },
|
||||
"body_required": { "type": "boolean" },
|
||||
"variants": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "$ref": "#/$defs/rest_request_descriptor" } }
|
||||
}
|
||||
},
|
||||
"rest_request_descriptor": {
|
||||
"type": "object", "additionalProperties": false,
|
||||
"required": ["media_type", "schema_variant"],
|
||||
"properties": {
|
||||
"media_type": { "type": "string", "minLength": 1, "maxLength": 256 },
|
||||
"schema_variant": { "type": "integer", "minimum": 0 }
|
||||
}
|
||||
},
|
||||
"rest_response_descriptor": {
|
||||
"type": "object", "additionalProperties": false,
|
||||
"required": ["status_code", "schema_variant"],
|
||||
"properties": {
|
||||
"status_code": { "type": "integer", "minimum": 200, "maximum": 299 },
|
||||
"media_type": { "type": "string", "minLength": 1, "maxLength": 256 },
|
||||
"schema_variant": { "type": "integer", "minimum": 0 }
|
||||
}
|
||||
},
|
||||
"schema": {
|
||||
"type": "object", "additionalProperties": false, "required": ["type"],
|
||||
"properties": {
|
||||
"type": { "enum": ["object", "array", "string", "integer", "number", "boolean", "enum", "null", "oneof"] },
|
||||
"format": { "type": "string", "maxLength": 256 },
|
||||
"description": { "type": "string", "maxLength": 65536 }, "required": { "type": "boolean" }, "nullable": { "type": "boolean" },
|
||||
"default_value": {}, "fields": { "type": "object", "maxProperties": 4096, "additionalProperties": { "$ref": "#/$defs/schema" } },
|
||||
"items": { "$ref": "#/$defs/schema" }, "enum_values": { "type": "array", "maxItems": 4096, "items": { "type": "string", "maxLength": 65536 } },
|
||||
|
||||
Reference in new issue
Block a user