Files
crank/_bmad-output/implementation-artifacts/spec-2-9-http-contract.md
T

36 KiB
Raw Blame History

title, type, created, status, baseline_revision, baseline_commit, review_loop_iteration, followup_review_recommended, context, warnings, deferred
title type created status baseline_revision baseline_commit review_loop_iteration followup_review_recommended context warnings deferred
2.9 — Сохранить полный поддерживаемый HTTP contract feature 2026-09-05 done 083974c27f 083974c27f 1 false
_bmad-output/project-context.md
_bmad-output/implementation-artifacts/epic-2-context.md
_bmad-output/implementation-artifacts/spec-2-8-references-schema-composition.md
oversized
B8
E8

Intent

Problem: Текущие candidates теряют HTTP semantics: поддержаны пять methods, три parameter locations, один JSON body и один success schema. Созданный Tool не воспроизводит полный контракт поддерживаемого endpoint.

Approach: Сохранить HTTP semantics в versioned typed IR и Operation, провести их через deterministic mapping и REST execution; unsupported constructs отражать точными findings. Источник целевого поведения — Story 2.9 / FR-8; устаревшее описание пяти методов в документации не ограничивает эту историю.

Boundaries & Constraints

Always: Поддерживать OAS 3.0/3.1 и Swagger 2.0; точные source locations и coverage; blockers запрещают actionable Draft; сохранить immutable snapshot replay, isolation, OutboundPolicy и legacy-v1 behavior. Изменение persisted contracts сопровождать compatibility/roundtrip tests и обновлением документации. sprint-status.yaml принадлежит оркестратору: не записывать и не откатывать его.

Block If: Требуемое публичное поведение не определено исходным intent и существующими контрактами; нельзя выбрать между наблюдаемо различающимися вариантами без продуктового решения.

Never: Silent loss, first-response/first-branch collapse, credential-bearing URL/headers, implicit XML fallback, network I/O из importer, изменение зависимостей/toolchain попутно или отказ от исторических jobs.

Уточнение HTTP input contract — решение пользователя 2026-09-05

Пользователь выбрал 1A + 2A: inline base64 для multipart binary/file и один Operation candidate / Tool на endpoint с явным выбором request media type. Эти правила дополняют исходные AC и снимают два вопроса из исторического Auto Run Result.

Multipart binary/file

  • Значение каждого binary/file field — JSON object с обязательным строковым data_base64 и необязательными строковыми filename и content_type; иных полей у этого объекта нет. Для массива файлов каждый элемент имеет ту же форму. Обычные text/scalar/array fields сохраняют собственную schema; такой объект применяется только к binary/file fields.
  • data_base64 содержит standard base64 с padding там, где он требуется, без whitespace, URL-safe alphabet и data-URI prefix. Пустая строка означает файл из нуля байтов. В multipart part отправляются декодированные bytes, а не base64-текст. Отсутствие обязательного файла отличается от присутствующего пустого файла.
  • filename, если указан, становится filename metadata части; если отсутствует, filename не добавляется и не угадывается. Значение не является путём к локальному файлу. Metadata проходит typed validation и безопасное quoting; управляющие символы в filename/MIME недопустимы.
  • content_type задаёт MIME части и должен соответствовать поддерживаемым ограничениям MIME из source contract. Если он опущен, используется единственный конкретный MIME из source metadata; при отсутствии такого ограничения — application/octet-stream. Если source допускает несколько MIME и не задаёт единственный выбор, вызывающий обязан указать content_type. Невалидное или несовместимое значение отклоняется, без silent replacement. Неподдерживаемая source encoding metadata по-прежнему получает finding.
  • Artifact references, filesystem paths и URL вместо inline bytes не являются альтернативными способами передачи файла в этой истории. Декодирование bounded; сохраняются существующие inbound limits и CRANK_OUTBOUND_MAX_REQUEST_BYTES для полного сериализованного HTTP body, включая multipart overhead. Невалидный base64/metadata и превышение outbound limit отклоняются до outbound I/O; новый upload lifecycle не создаётся.

Несколько request media types

  • Один endpoint остаётся одним Operation candidate и одним Tool; supported request variants сохраняются в typed contract целиком, включая несовместимые schemas. Отдельные candidates по media type и выбор первого варианта запрещены.
  • Когда у endpoint несколько поддерживаемых request media types, его MCP arguments содержат верхнеуровневые content_type (строка — явный selector из перечисленных поддерживаемых вариантов) и body (значение по schema выбранного варианта). Связка selector/schema отражается в опубликованной input schema и проверяется runtime. body не flatten-ится; одноимённые свойства внутри body остаются внутри body.
  • При передаче body поле content_type обязательно; defaults, определение формата по содержимому и fallback отсутствуют. Required request body требует оба поля. Для optional request body разрешено опустить оба поля, что означает отсутствие HTTP body; передача только одного из них ошибочна. Явный body: null считается переданным значением и разрешён только nullable schema выбранного варианта.
  • Path/query/header/cookie parameters остаются отдельными typed inputs. В этом контракте имена content_type и body зарезервированы для body selection; source parameters с такими именами получают детерминированные уникальные input aliases, явно отражённые в schema/mapping, с сохранением исходного wire name/location. Значения параметров не могут подменить selector или body.
  • Selector выбирает соответствующие validation и wire serialization (JSON/form/multipart); multipart boundary создаёт adapter, вызывающий его не передаёт. Неизвестный/unsupported selector, отсутствующий required field или body по чужой schema отклоняются до outbound I/O. Unsupported variants сохраняют точные findings согласно исходным blocker rules.
  • Для единственного поддерживаемого request media type формат фиксируется в typed mapping, отдельный selector не требуется. Это уточнение не меняет публичные inputs сохранённых legacy Operations/jobs; versioned replay сохраняет их прежнее поведение.

Пример MCP arguments для endpoint с несколькими форматами и multipart file field:

{
  "content_type": "multipart/form-data",
  "body": {
    "file": {
      "data_base64": "SGVsbG8=",
      "filename": "hello.txt",
      "content_type": "text/plain"
    }
  }
}

I/O & Edge-Case Matrix

Scenario Input / State Expected Output / Behavior Error Handling
Methods Resolved endpoints GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS сохраняются TRACE/CONNECT/unknown дают exact unsupported finding
Parameters Четыре locations, одинаковые имена, path/op overrides Typed identity, required/default/enum/nullable/format и поддерживаемая serialization сохраняются Invalid path required/placeholder и unsupported style дают blocker
Bodies JSON/form/multipart с text/scalar/array/binary fields Required/content type/MIME/ограничения отражены в schema и wire mapping Unsupported encoding/XML получают finding без fallback
Inline files Binary/file object или массив таких objects Standard base64 декодируется в точные bytes; filename/MIME следуют frozen contract; пустой файл отличим от отсутствующего Invalid base64/metadata, missing required и полный multipart body сверх outbound limit отклоняются до I/O
Media selector Один endpoint с JSON/form/multipart и несовместимыми schemas Один candidate/Tool; content_type + body выбирают ровно одну ветвь; обе ветви доступны после replay Missing/unknown selector, mismatched schema и неполная пара отклоняются до I/O
Selector collisions / optional body Parameters body/content_type; optional или nullable body Уникальные aliases сохраняют wire names; отсутствие обоих полей не отправляет body; null проверяется выбранной schema Нет перезаписи параметров/selector; null не равен отсутствию
Responses Несколько 2xx, 204, HEAD и bodyless Все status/media/schema branches, явный no-content outcome Валидный пустой ответ не вызывает schema error
Metadata Servers, descriptions/examples/defaults Валидный bounded candidate, URL сохраняет base path Userinfo/invalid target блокируются; secret-like examples дают finding
Replay Одинаковый IR после serialization Равные schemas/mappings/candidates Старые jobs не переинтерпретируются новой projection

Code Map

  • crates/crank-core/src/protocol.rs:11, operation.rs:98 — пять HttpMethod и RestTarget без descriptors body/response; persisted serde contract.
  • crates/crank-schema/src/model.rs:50, validate.rs:108 — nullable/default, string-only enum; format отсутствует.
  • crates/crank-import/src/rest/{openapi3.rs,swagger2.rs} — parser, path/op parameter merge, выбор единственного body/response.
  • crates/crank-import/src/rest/{model.rs,normalize.rs,normalize_coverage.rs,normalize_schema.rs} — typed IR, source pointers, coverage и bridge в projection; текущие версии normalized-ir-v3/preview-v3.
  • crates/crank-import/src/rest/{payload.rs,mapping.rs,schema.rs} — collisions одинаковых имён разных locations, JSON field flattening, один output schema; legacy-v1 first-branch поведение изолировать.
  • crates/crank-runtime/src/request_preparation.rs:59, executor.rs:812 — scalar maps; output mapping и validation имеют доступ к status/headers/body.
  • crates/crank-adapter-rest/src/{model.rs,client.rs} — BTreeMap query, JSON-only request; empty response уже становится Null. Сохранить actual-address OutboundPolicy.
  • apps/admin-api/src/service/imports.rs:612, service/imports/job_contract.rs — persisted-v2 и legacy-v1 replay, integrity digests, full/selected Apply; новую projection version провести без потери v3 jobs.
  • crates/crank-config/src/schema.rs:321 — существующий outbound request byte limit; не путать его с upload OpenAPI до 256 KiB.
  • docs/{openapi-import.md,protocols/rest.md,operation-lifecycle.md}, docs/schemas/operation-export-v2.schema.json — обновить публичные contracts вместе с реализацией.

Tasks & Acceptance

Execution:

  • crates/crank-core/src/{protocol.rs,operation.rs}, crates/crank-schema/src/{model.rs,validate.rs} — расширить typed HTTP/schema contract с совместимым чтением старых Operations.
  • crates/crank-import/src/rest/{model.rs,openapi3.rs,swagger2.rs,normalize.rs,normalize_coverage.rs,normalize_schema.rs} — нормализовать все methods, locations, bodies и success variants, точные unsupported findings и coverage.
  • crates/crank-import/src/rest/{payload.rs,mapping.rs,schema.rs} — детерминированная projection без name collisions и потери semantics; сохранить legacy behavior.
  • crates/crank-runtime/src/{request_preparation.rs,executor.rs}, crates/crank-adapter-rest/src/{model.rs,client.rs} — выполнить поддержанный request contract на wire и корректно обработать success/no-content.
  • apps/admin-api/src/service/imports.rs, service/imports/job_contract.rs — versioned replay, serialization и blocker gates для Apply.
  • docs/{openapi-import.md,protocols/rest.md,operation-lifecycle.md}, docs/schemas/operation-export-v2.schema.json — документировать новый portable contract и поддерживаемую матрицу.
  • crates/crank-import/tests/, crates/crank-adapter-rest/tests/, crates/crank-runtime/tests/, apps/admin-api/tests/integration/openapi_import/ — regression fixtures и wire/end-to-end проверки каждой строки матрицы, включая replay и no-mutation при blocker.

Acceptance Criteria (дословно из Story 2.9):

Given resolved OpenAPI endpoint When importer определяет HTTP method Then поддерживаются GET, POST, PUT, PATCH, DELETE, HEAD и OPTIONS And TRACE, CONNECT и неизвестные methods получают explicit unsupported finding.

Given parameters на path-level и operation-level When они нормализуются Then path, query, header и cookie parameters объединяются согласно правилам specification version And operation-level override не создаёт duplicate либо silent replacement.

Given каждый parameter When строится Operation input schema и request mapping Then сохраняются location, required, default, enum, nullable, format и применимые serialization semantics And одинаковые имена в разных locations не конфликтуют во внутренней typed model.

Given path parameter When исходная specification ошибочно не помечает его required либо не содержит соответствующего path placeholder Then candidate получает blocker finding And importer не создаёт URL template с неоднозначной подстановкой.

Given OpenAPI request body When content type поддерживается Then JSON, application/x-www-form-urlencoded и multipart/form-data преобразуются в typed input schema и deterministic mapping And required body, required fields и content type сохраняются.

Given multipart body When schema содержит text, scalar, array или binary/file fields Then importer сохраняет field names, required status, MIME metadata и bounded upload expectations And unsupported multipart encoding получает finding вместо silent fallback к JSON.

Given XML request/response media type When он обнаружен Then affected content variant получает explicit unsupported finding в соответствии с release scope And XML не преобразуется неявно в JSON или text.

Given endpoint с одним или несколькими успешными 2xx responses When строится output contract Then сохраняются status codes, content types и все поддерживаемые success schemas And importer не выбирает произвольно первый response и не теряет остальные branches.

Given 204 No Content, HEAD либо success response без body When строится output schema Then candidate получает явный no-content outcome без требования JSON body And runtime mapping не классифицирует корректный пустой response как schema error.

Given API/server/base-path metadata When строится REST target template Then scheme, host, port и base path нормализуются без embedded credential и проходят typed validation And фактическое execution по-прежнему подчиняется OutboundPolicy из Story 1.9.

Given descriptions, examples или defaults из source document When они включаются в candidate preview Then значения bounded и не влияют на executable mapping без явного typed contract And secret-like examples создают finding и не попадают в generated headers/Auth Profile.

Given unsupported parameter style, schema keyword, content type или response shape When candidate формируется Then coverage ledger содержит точный source construct и finding severity And blocker semantic loss не может быть помечена как actionable Draft.

Given одинаковый resolved IR When HTTP mapping запускается повторно Then Operation candidates, input/output schemas и mappings совпадают детерминированно And каждый candidate можно сериализовать и валидировать без обращения к исходному parser state.

Given HTTP-contract test suite When выполняется representative matrix Then покрыты все обязательные methods, четыре parameter locations, JSON/form/multipart, multiple 2xx, 204, defaults/enums/nullability/formats и unsupported XML And каждый fixture доказывает expected semantics либо expected finding, а just verify проходит.

Дополнительные AC по решению 1A + 2A:

  • Multipart wire fixture доказывает точные decoded bytes, filename present/absent, MIME из аргумента/единственного source значения/default, MIME mismatch и выбор при нескольких source MIME; отдельно покрывает пустой файл, required omission, массив файлов, malformed base64 и multipart overhead при проверке существующего лимита. Ошибочные вызовы не достигают outbound server.
  • Fixture одного endpoint минимум с двумя несовместимыми supported body schemas доказывает один candidate/Tool, доступность каждого варианта, schema публикации в MCP и корректную wire serialization выбранного формата. Проверяются missing/unknown/unsupported selector, body другой ветви, optional omission, nullable body и collisions с source parameters body/content_type.
  • Serialization/replay сохраняют все request variants, их selector/schema mapping и file metadata contract детерминированно; persisted legacy fixtures сохраняют прежние inputs и execution semantics.

Spec Change Log

  • 2026-09-05 — пользователь утвердил 1A + 2A; уточнены frozen input contract, edge-case matrix и дополнительные AC. Исходный blocked status оставлен оркестратору для re-arm.

Review Triage Log

2026-09-06 — ручное завершение после остановки loop

Ревью выполнено тремя независимыми слоями по diff /tmp/crank-story-2-4-review-Lpwiir.diff (baseline указан выше). Откат/повторная генерация не выполнялись: сохранённая работа пользователя остаётся в worktree. Перед автоматическим loopback требуется решение пользователя; предложено завершить ограниченным набором прямых исправлений. Повторное открытое ревью не запускалось.

ID Verdict Route Evidence
B1 high bad_spec MappingSet::empty_target_context создаёт body {}, а typed PreparedRequest сохраняет его. Optional omission не отличим от явного пустого объекта; код подтверждён, сквозной wire test после исправления импорта test support падает.
B2 high patch output_schema_for_response выбирает variants[0] у единственного HTTP descriptor с исходной union schema; необходимо сохранить целую schema при одном descriptor.
B3 high patch reqwest 0.12.28 RequestBuilder::header вызывает append. После .headers(headers) body encoder добавляет второй Content-Type, не заменяя первый.
B4 high bad_spec Baseline сериализует legacy body через .json(body). Новый adapter выбирает form/multipart по configured Content-Type и отвергает JSON с charset; это несовместимость существующих Operations.
B5 high bad_spec Baseline сначала применяет bounded writer; новый body encoder полностью собирает JSON/form и все decoded multipart parts до общей проверки. Ограничение памяти утрачено.
B6 high bad_spec openapi3_findings::operation проверяет encoding только для multipart, тогда как form encoder всегда повторяет ключи массива. explode=false незаметно игнорируется.
B7 high bad_spec Form/multipart schema допускает scalar root и вложенный обычный object, а adapter требует object root и scalar/file fields; unsupported shape не блокируется при импорте.
B8 medium defer Проверка только parameter→placeholder не покрывает обратное направление. Подстановка отсутствующих path parameters уже оставляла placeholder в baseline; malformed-spec дефект предшествует текущей story.
B9 high bad_spec const, multipleOf, minProperties, maxProperties, dependentRequired не входят в список findings и не исполняются Schema; заявленное отсутствие silent loss не обеспечено.
B10 maybe-false defer Adapter действительно заменяет Cookie после build_headers; ResolvedAuth может применять произвольное header_name. Для подтверждения доступности через публичный API требуется проследить validation Auth Profile с Cookie и проверить совместный вызов. Потенциальная severity high; не считать подтверждённым bypass.
E1 high bad_spec Дубликат B1, независимо подтверждён чтением MappingSet и PreparedRequest.
E2 high patch Дубликат B2: одиночный response с Oneof смешивается с union HTTP descriptors.
E3 high bad_spec Дубликат B6: form encoding metadata не проверяется.
E4 high bad_spec Swagger parser возвращается для formData до проверки collectionFormat; adapter всегда использует повторяющиеся ключи, а csv/default CSV не сохранён.
E5 high bad_spec Дубликат B7: schema-valid form input может неизбежно отвергаться adapter.
E6 high bad_spec Дубликат B4: baseline .json заменён выбором encoder по заголовку, меняя legacy wire semantics.
E7 medium bad_spec valid_http_server_url проверяет prefix/authority строковыми операциями и принимает нечисловой port; promised typed validation отсутствует на этапе candidate.
E8 medium defer Object/array defaults теряются через normalized_literal, поддерживающий скаляры. Представление scalar-only defaults уже существовало; требуется отдельное решение совместимого расширения IR либо blocker для неподдерживаемых defaults.
E9 high bad_spec Дубликат B9: отсутствуют blockers для неисполняемых schema keywords.
V1 medium patch Существующий runtime test проверяет только отрицательный 200/схема206. Мутация выбора на variants[0] проходит его. Добавить позитивные 200/object и 206/array с точным результатом.

Проверки текущего ручного прохода

  • Implementation handoff: import suite 79 passed; adapter suite до последних двух fixes 34 passed; targeted nullable-enum, request base-path и response-only base-path regressions passed.
  • just verify: tooling 138 passed; capability inventory/baseline, Community scope, config/migration/metrics contracts, boundaries, Rust code health, dependency audit passed. Остановился на fmt-check; форматирование исправлено.
  • just clippy: обнаружен collapsible_if в schema validation; исправлен, повторный полный Clippy ещё не выполнен.
  • cargo test -p crank-runtime --test http_contract_wire: сначала compile error из-за отсутствующего импорта RuntimeExecutorTestExt; импорт исправлен. Повторный запуск: 0 passed, 1 failed (PreparedRequestInvalid на valid-input loop).
  • Общий workspace test suite и admin integration suite на финальном diff ещё не пройдены. Story не закрыта, коммит/merge/push не выполнялись.

2026-09-13 — разрешённые прямые исправления

Пользователь подтвердил завершение по зафиксированному ревью без отката и повторной генерации. Маршруты bad_spec выше обрабатываются прямыми fixes в существующей реализации; frozen contract и scope не меняются. Повторное открытое ревью не запускается, выполняются проверка конкретных fixes и полный gate.

  • B1/E1: воспроизведено regression test (ожидалось отсутствие body, получен {}). Runtime теперь сохраняет отсутствие публичного body argument независимо от legacy initializer mapping.
  • B2/E2/V1: воспроизведён отказ второй исходной union-ветви при единственном response descriptor. Runtime различает union HTTP descriptors и исходную composition; добавлены позитивные 200/206 с точным результатом.
  • Целевой запуск cargo test -p crank-runtime --test http_contract --test http_contract_wire: 6 passed после fixes; до fixes новые regressions дали 2 failed.
  • B10 подтверждён дополнительно: validate_auth_header_name в admin API разрешает Cookie, а ResolvedAuth::ApiKeyHeader помечает его trusted. Finding переведён из unverified в high и включён в исправления: конфликт с mapped cookies должен отклоняться до I/O, не заменять trusted credentials.
  • B3/B4/E6: typed encoder заменяет Content-Type, legacy JSON encoder сохраняет настроенный заголовок и прежнюю JSON-сериализацию. Wire regression проверяет единственный Content-Type для JSON/form/multipart и legacy charset/form headers.
  • B5: bounded writer останавливает JSON/form encoding при превышении лимита; multipart использует общий бюджет decoded payload и bounded сборку полного wire body. Проверены percent-encoding expansion, несколько файлов и multipart overhead.
  • B10: конфликт mapped/trusted Cookie теперь возвращает InvalidBodyContract до dispatch; отдельный positive case сохраняет trusted Cookie без конфликта.
  • B6/E3/E4: неподдерживаемое form encoding и Swagger csv/default arrays получают blockers с exact source pointers. Swagger operation parameter findings привязаны к операции, а не только document-level.
  • B7/E5: scalar form root, вложенные object/array fields и object composition branches блокируются до создания actionable Draft; provenance валидирует соответствующие pointers.
  • B9/E9/E7: добавлены blockers для перечисленных в review schema keywords; URL разбирается существующей workspace-библиотекой url, с проверкой схемы, host, port, userinfo и control characters. Версии зависимостей не обновлялись.
  • B8 и E8 остаются pre-existing deferred, записаны в корневой deferred-work.md. B10 больше не отложен. Остальные findings этого review исправлены прямыми patches.
  • cargo test -p crank-adapter-rest --all-targets: 40 passed. cargo test -p crank-import --test http_contract_regressions: 7 passed после исправления propagation (первый запуск выявил отсутствующий operation-level CSV blocker).

Итоговый gate — 2026-09-13

  • just verify на финальном diff завершился с exit code 0. Tooling: 138 passed; capability/config/migration/metrics contracts, boundaries, code health, dependencies, fmt и полный Clippy прошли.
  • Workspace cargo test --workspace --all-targets -- --test-threads=1 прошёл. В том числе admin integration: 81 passed; MCP integration: 40 passed; importer: 82 passed в отдельном полном запуске; adapter: 40 passed; целевые runtime HTTP tests: 6 passed.
  • Исправлены два устаревших test expectations: legacy job теперь содержит настоящий legacy preview с соответствующим digest; Swagger diagnostics проверяются на document- и operation-level, включая точную привязку к операции. Production integrity checks не ослаблялись.
  • Disk-full subprocess test использует RLIMIT_FSIZE: прямой redirect его stdout/stderr в regular file мешал завершению harness. Финальный gate выполнен через pipe/tee с pipefail; тест прошёл без изменения кода.
  • Один ранее ignored benchmark production_size_invocation_history_queries_stay_bounded (1 000 000 строк) остаётся ignored по существующему правилу; в рамках этой story его не запускали. Browser E2E и deploy не запускались.
  • Принятые review fixes завершены; повторного открытого ревью не было. B8/E8 остаются явно отложенными pre-existing findings. Коммит f8ee7c9bfeaa8a3f73a4850ff3f82b2bc2155fe8 интегрирован в main fast-forward 2026-09-13; статус спринта согласован: done. Интеграция не меняет проверенное дерево коммита; полный тестовый gate повторно не запускался. Push, bmad-loop и Story 2.10 не запускались.

Design Notes

Сохранить направление слоёв: importer pure, runtime orchestrates, adapter owns REST wire behavior. Выбор success schema по status/media может быть внутренним и не требует нового MCP envelope. Версия normalization/projection должна измениться при изменении preview semantics; v1/v2/v3 jobs сохраняют старое значение.

Verification

Commands:

  • cargo test -p crank-import --all-targets — representative fixture matrix и deterministic replay.
  • cargo test -p crank-adapter-rest --all-targets — wire serialization и прежняя outbound policy.
  • cargo test -p crank-runtime --all-targets — request/output semantics и no-content.
  • cargo test -p admin-api --test integration -- --test-threads=1 — preview/apply/replay и blocker no-mutation.
  • just verify — обязательный полный gate Story 2.4.

Исходный baseline: cargo test -p crank-import --all-targets — 64 passed, 0 failed, 0 ignored. Это проверка исходного кода, не доказательство выполнения AC Story 2.4.