14 KiB
title, type, created, status, baseline_commit, review_loop_iteration, context
| title | type | created | status | baseline_commit | review_loop_iteration | context | |
|---|---|---|---|---|---|---|---|
| 2.8 — Безопасно разрешать references и schema composition | feature | 2026-08-29 | done | 6c2a3712d8 |
0 |
|
Intent
Problem: NormalizedIR сохраняет $ref и composition как placeholders, поэтому даже локальные ссылки блокируют Apply, а preview упрощает composition до первой ветки и теряет семантику.
Approach: Добавить bounded graph resolver: чистый crank-import разрешает local и переданные immutable external snapshots, а Admin API отдельно и до normalization получает allowlisted snapshots через общий SSRF-safe outbound boundary. Resolved IR сохраняет provenance, recursion, alternatives и точные findings; Apply использует только закреплённые digests без повторного network fetch.
Boundaries & Constraints
Always: RFC 6901 escaping и OAS 3.0/3.1 sibling semantics version-specific; external fetch default-off и разрешён только отдельными operator URL-prefix rules поверх deny-before-allow actual-address policy. HTTP(S) без userinfo, proxy и redirects; hop/depth/count/document/expanded-node limits обязательны. Все external bytes становятся workspace-scoped immutable artifacts до preview; graph и findings canonical, redacted и детерминированы. Compatible allOf объединяется с provenance, recursion остаётся graph edge, oneOf/anyOf/discriminator сохраняются typed либо дают blocker affected candidate.
Ask First: Новая внешняя dependency, изменение публичного import HTTP DTO, ослабление SSRF/default-deny, изменение crank-schema wire contract либо отказ от replay существующих legacy-v1 jobs.
Never: Network I/O из crank-import или во время Apply/registry transaction; повторный fetch при Apply; credential из URL/OpenAPI; unbounded recursive expansion; last-write-wins при allOf; first-branch collapse в v2+; global cross-workspace cache; raw URL/content/digest/parser error в публичных errors, logs, traces или metrics.
I/O & Edge-Case Matrix
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|---|---|---|---|
| Local reference | Schema/object ref с escaped pointer | Target разрешён относительно primary snapshot; source/target provenance сохранён | Missing/invalid/type mismatch — точный blocker без panic |
| External default | HTTP(S) ref без import allowlist | Ни DNS, ни request не выполняются | external_reference_disabled с безопасной location |
| External allowed | Canonical URL проходит prefix и outbound policy | Chain загружена bounded, сохранена как artifacts и входит в dependency digest set | Redirect/private IP/forbidden origin/limit — blocker, все созданные snapshots detached |
| Replay/TOCTOU | Remote изменился после preview | Apply проверяет и использует прежние snapshot digests | Missing/changed snapshot — fail-closed до Draft mutation |
| Recursion | Self/mutual cycle в schema graph | Typed edge указывает на stable node, без дублирования | Graph limit excess — blocker affected candidates |
| Composition | allOf/oneOf/anyOf/discriminator |
Compatible merge либо lossless typed alternatives с provenance | Conflict/unsupported projection — explicit blocker, siblings остаются |
Code Map
crates/crank-import/src/rest/{model.rs,normalize.rs,normalize_schema.rs,normalize_coverage.rs}— расширить versioned IR графом, snapshot identity, discriminator/constraints, resolver limits и exact coverage; сохранить crate pure.crates/crank-import/src/rest/{openapi3.rs,swagger2.rs,schema.rs,payload.rs}— разрешить object/schema refs до projection; убрать modern first-branch loss, legacy-v1 оставить изолированным.crates/crank-adapter-rest/src/client.rs— переиспользовать policy DNS resolver/no-proxy/no-redirect в отдельном bounded GET boundary, не меняя REST execution semantics.crates/crank-config/src/{process.rs,schema.rs,validation.rs}— добавить отдельный default-off import external-reference contract: URL prefixes и graph/fetch limits; провести generated config contract.apps/admin-api/src/service/imports.rs— materialize/dedupe dependency snapshots до normalization, одинаково передать verified bundle в preview/apply и redacted cleanup paths.crates/crank-registry/src/{model,postgres}/,crates/crank-registry/src/migrations/— workspace-scoped import-job dependency set; атомарно verify/detach все digests при Apply/expiry.crates/crank-import/tests/**,crates/crank-adapter-rest/tests/integration/**,apps/admin-api/tests/integration/openapi_{import,source}.rs— reuse determinism/redaction/no-mutation suites; добавить graph, SSRF, TOCTOU и composition fixtures.
Tasks & Acceptance
Execution:
crank-importresolver/model/projection — построить canonical bounded resolved graph для local и supplied snapshots, composition/provenance и operation-scoped findings без I/O.crank-adapter-rest,crank-config— реализовать отдельный operator-controlled external-reference fetch contract на существующей actual-address security policy.crank-registry,apps/admin-api— закрепить полный dependency snapshot set за job и reparse/apply только из verified artifacts с корректным lifecycle cleanup.- Tests/fixtures — покрыть OAS 3.0/3.1/Swagger2, pointer escaping/type mismatch, default deny, redirects/DNS/private IP/relative chains, TOCTOU, cycles/limits, composition conflicts/discriminators, determinism, redaction и legacy replay.
Acceptance Criteria:
- Given один повреждённый dependency graph, when preview завершается, then только зависимые candidates получают blocker, независимые остаются видимыми, а полный Apply не создаёт Draft.
- Given одинаковые primary/external bytes, digests и config, when resolution выполняется повторно или конкурентно, then resolved IR, dependency set, preview и ordered findings совпадают byte-for-byte.
- Given preview либо любой failure/expiry/apply path, when lifecycle завершается, then все dependency artifacts остаются workspace-isolated и либо атомарно referenced, либо detached без orphan leak.
Spec Change Log
Design Notes
External I/O — orchestration concern Admin API; resolver принимает immutable {canonical_origin, digest, bytes} inputs. URL используется только при сборе цепочки, а resolved graph адресует external nodes snapshot digest + RFC 6901 pointer. Новая parser/projection семантика получает новые version identifiers; существующий legacy-v1 replay не меняется.
Verification
Результат проверки матрицы:
- Local reference — RFC 6901 escaping, object/schema refs, missing pointer и type mismatch проверены в
reference_resolution; создание Draft после успешного local resolution проверено интеграционно в Admin API. - External default/allowed — отсутствие request при default-off, URL-prefix boundary, actual-address policy, redirect/userinfo rejection и bounded response проверены в
external_reference_fetcher; relative chain и deterministic dependency ordering проверены вreference_resolution. - Replay/TOCTOU — Admin API получает snapshot ровно один раз, Apply читает artifact без network fetch; missing/detached dependency завершает Apply до Draft mutation.
- Recursion — self-cycle остаётся stable recursive edge; depth и expanded-node limits дают blocker без unbounded expansion.
- Composition — compatible/conflicting
allOf, обе ветвиoneOf/anyOf, discriminator, OAS 3.0/3.1 sibling semantics и invalid composition покрыты и прошли.
Фактические результаты:
crank-import: 64 теста прошли; review-regressions дополнительно покрывают RFC 3986 dot-segments/absolute paths, percent-decoding, literal payload exclusions, OAS 3.1 external siblings, compatible constraint intersections и parameter override semantics.crank-adapter-rest: 23 теста прошли, включая subprocess proxy regression.crank-registry: 82 теста прошли, 1 production-size million-row test штатно ignored.admin-api: 76 интеграционных тестов прошли; среди них selected-only blocker isolation, full-selection atomic failure, relative two-snapshot chain без refetch, total-chain timeout cleanup, failed dependency lifecycle, telemetry redaction иnormalized-ir-v2TTL replay.config-contract-check,cargo fmt --check, workspaceclippy -D warnings,rust-boundariesиgit diff --checkпрошли.rust-code-healthсообщает только о двух известных baseline-файлах Story 2.1 (crank-artifacts/src/housekeeping.rs,crank-artifacts/tests/artifact_store.rs); все изменённые Story 2.8 Rust-файлы меньше 1000 строк.
Commands:
cargo test -p crank-import --all-targets— graph/composition/version matrix зелёная.cargo test -p crank-adapter-rest --all-targets— SSRF, redirect, DNS и bounded-fetch regressions зелёные.cargo test -p crank-registry --test integration -- --test-threads=1— dependency ownership/lifecycle/transaction guarantees зелёные.cargo test -p admin-api --test integration -- --test-threads=1— snapshot replay, TOCTOU, redaction и no-Draft guarantees зелёные.just config-contract-check && cargo fmt --all -- --check && cargo clippy --workspace --all-targets --all-features -- -D warnings— contracts и lint чисты.just rust-boundaries && just rust-code-health— dependency direction и module limits сохранены.
Suggested Review Order
Оркестрация preview и Apply
-
Главный поток закрепляет snapshots до preview и проверяет их перед Apply.
imports.rs:47 -
Ошибки replay атомарно завершают job и сохраняют completed-race semantics.
external_references.rs:76 -
Внешняя цепочка материализуется в общем deadline с cancellation cleanup.
external_references.rs:119
Чистый resolver и schema semantics
-
Pure resolver строит deterministic bounded graph только из verified snapshots.
reference.rs:100 -
URI resolution объединяет RFC 3986 canonicalization и RFC 6901 fragment lookup.
reference.rs:427 -
allOfобъединяется пересечением совместимых ограничений без last-write-wins.reference.rs:460 -
Versioned IR contract отделяет modern semantics от legacy replay.
model.rs:12
Security и lifecycle boundaries
-
Fetch boundary применяет prefix allowlist поверх actual-address SSRF policy.
client.rs:229 -
Failed jobs и dependency sources завершаются под одной database transaction.
import_job.rs:82 -
Apply блокирует missing или изменённые artifacts до Draft mutation.
import_job.rs:301
Конфигурация и доказательства
-
Builder сохраняет одинаковую policy независимо от порядка настройки.
service.rs:285 -
Generated contract фиксирует default-off и единые graph/fetch limits.
schema.rs:81 -
End-to-end chain доказывает два fetch, два snapshots и Apply без refetch.
external_references.rs:11 -
Resolver regressions покрывают relative paths, fragments и canonical authorities.
reference_resolution.rs:522 -
Selection regression доказывает локальные blockers и атомарный full failure.
openapi_import.rs:560