fix(import): единая идентичность внешних URI (#96)
CI / Rust Checks (push) Successful in 25m54s
CI / UI Checks (push) Successful in 5s
CI / Community Image Smoke (push) Successful in 1m47s
CI / Frontend E2E (push) Successful in 10m12s
CI / Deploy (push) Successful in 1m22s

Единая transport-canonical идентичность внешних документов; normalizer v6 с immutable historical replay; matrix 1.0.4 / corpus 1.0.5. PR CI run840 success, локальная приёмка и independent review выполнены.

Co-authored-by: bsodfather <bsodfather@gmail.com>
This commit was merged in pull request #96.
This commit is contained in:
bsodfather authored and bsodfather committed 2026-10-11 06:19:16 +00:00
1 parent 178093e81b
commit 1b6db09bd1
22 files changed
+1669 -353

No files matched your search

@@ -1,11 +1,16 @@
use super::super::common::test_service_with_external_references;
use super::super::common::{
authorized_client, build_test_app_with_external_references, spawn_admin_api,
test_service_with_external_references,
};
mod isolation;
mod uri_transport;
use super::*;
use admin_api::error::ApiError;
use axum::{Router, body::to_bytes, http::StatusCode, response::IntoResponse, routing::get};
use crank_artifacts::ArtifactStore;
use crank_core::{Workspace, WorkspaceStatus};
use crank_registry::{ArtifactSourceId, CreateWorkspaceRequest, RegistryError};
use reqwest::multipart::{Form, Part};
use sha2::{Digest, Sha256};
use std::sync::{
Arc,
@@ -0,0 +1,603 @@
//! F1 transport-parity cases for the Admin external-reference import.
//!
//! The external materializer stores snapshot keys produced by the URL transport
//! (`url::Url`), which collapses a `%2e%2e` path segment and percent-encodes an
//! apostrophe in a query (`'` -> `%27`). Because the materializer and the pure
//! resolver used different URI keys, both references produced a false
//! `external_reference_unavailable` blocker. These cases run the real allowlisted
//! fixture server through preview -> apply -> replay (service) and through the
//! authenticated multipart route (outer). They are registered from
//! `external_references.rs` so the parent file stays within the repository
//! file-size budget; shared helpers and imports come from `super`.
use super::*;
// F1 acceptance (both cases): the service preview -> apply -> replay path. The
// assertions verify the transport-canonical keys resolve, the dependency
// bytes/digests verify, apply never refetches, and replay is a stable no-op.
#[tokio::test]
#[serial]
async fn transport_canonical_external_uris_resolve_without_false_blocker_or_refetch() {
// Distinct bytes so each canonical URI owns a distinct content-addressed
// blob; byte-identical documents collapse into a single dependency envelope
// (the recorded alias/digest observation) and could not be told apart.
const ROOT_ITEM: &str =
"Item: { type: object, required: [id], properties: { id: { type: string } } }";
const QUERY_ITEM: &str =
"Item: { type: object, required: [id], properties: { id: { type: integer } } }";
let fetches = Arc::new(AtomicUsize::new(0));
let root_fetches = Arc::clone(&fetches);
let query_fetches = Arc::clone(&fetches);
let app = Router::new()
.route(
"/root.yaml",
get(move || {
let fetches = Arc::clone(&root_fetches);
async move {
fetches.fetch_add(1, Ordering::SeqCst);
ROOT_ITEM
}
}),
)
.route(
"/schema.json",
get(move || {
let fetches = Arc::clone(&query_fetches);
async move {
fetches.fetch_add(1, Ordering::SeqCst);
QUERY_ITEM
}
}),
);
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let fixture_server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
let origin = format!("http://{address}");
let registry = test_registry().await;
let storage_root = test_storage_root("openapi_import_external_uri_transport_parity");
let service = test_service_with_external_references(
registry.clone(),
storage_root.clone(),
vec![format!("{origin}/")],
);
let workspace_id = WorkspaceId::new("ws_default");
let upload = OpenApiUpload {
bytes: format!(
r##"
openapi: 3.1.0
info: {{ title: External URI transport parity }}
servers: [{{ url: https://api.example.test }}]
paths:
/dot:
get:
operationId: encodedDot
responses:
'200':
description: ok
content: {{ application/json: {{ schema: {{ $ref: '{origin}/a/%2e%2e/root.yaml#/Item' }} }} }}
/query:
get:
operationId: quotedQuery
responses:
'200':
description: ok
content: {{ application/json: {{ schema: {{ $ref: "{origin}/schema.json?filter='x'#/Item" }} }} }}
"##
)
.into_bytes(),
mime_type: "application/yaml".to_owned(),
locale: OpenApiUploadLocale::En,
};
let preview = service
.preview_openapi_import(&workspace_id, upload)
.await
.unwrap();
// Materialization first: the external materializer must have downloaded and
// stored both snapshots under the transport-canonical keys before resolution
// is judged. This separates the F1 resolver key mismatch from a snapshot that
// was never fetched at all.
let job_id: crank_registry::ImportJobId = preview.job_id.as_str().into();
let job = registry
.get_import_job(&workspace_id, &job_id)
.await
.unwrap()
.unwrap();
let dependencies = job.preview_payload["dependencies"].as_array().unwrap();
assert_eq!(dependencies.len(), 2);
let canonical_uris = dependencies
.iter()
.map(|dependency| dependency["canonical_uri"].as_str().unwrap().to_owned())
.collect::<std::collections::BTreeSet<_>>();
assert_eq!(
canonical_uris,
std::collections::BTreeSet::from([
format!("{origin}/root.yaml"),
format!("{origin}/schema.json?filter=%27x%27"),
]),
"materialized dependency keys must be the transport-canonical URIs"
);
assert_eq!(
fetches.load(Ordering::SeqCst),
2,
"both external documents must be fetched exactly once during preview"
);
// Dependency bytes and digests verify against the workspace-scoped store.
let store = Arc::new(ArtifactStore::open(&storage_root).unwrap());
for dependency in dependencies {
let source_id = ArtifactSourceId::new(dependency["source_id"].as_str().unwrap());
let digest = dependency["digest"].as_str().unwrap();
let verified = registry
.read_artifact_source(Arc::clone(&store), &workspace_id, &source_id)
.await
.unwrap();
assert_eq!(verified.source.blob.artifact_ref.as_str(), digest);
let canonical_uri = dependency["canonical_uri"].as_str().unwrap();
let expected = if canonical_uri.ends_with("/root.yaml") {
ROOT_ITEM
} else {
QUERY_ITEM
};
assert_eq!(verified.bytes, expected.as_bytes());
}
// Criterion-defining: neither transport-canonical URI may become a false
// blocker. Collected across all operations so one failure reports both.
let false_blockers = preview
.preview
.groups
.iter()
.flat_map(|group| &group.operations)
.flat_map(|operation| {
operation
.findings
.iter()
.filter(|finding| finding.code == "external_reference_unavailable")
.map(|_| operation.key.clone())
})
.collect::<Vec<_>>();
assert!(
false_blockers.is_empty(),
"both transport-canonical URIs must resolve; false external blockers: {false_blockers:?}"
);
let resolved = preview
.preview
.groups
.iter()
.flat_map(|group| &group.operations)
.map(|operation| (operation.key.clone(), operation.output_fields))
.collect::<std::collections::BTreeMap<_, _>>();
assert_eq!(resolved["GET /dot"], 1, "encoded-dot schema must resolve");
assert_eq!(
resolved["GET /query"], 1,
"quoted-query schema must resolve"
);
// Apply consumes the saved snapshots and must not refetch.
let created = service
.create_openapi_import(
&workspace_id,
&job_id,
OpenApiImportCreatePayload {
selected_operation_keys: vec!["GET /dot".to_owned(), "GET /query".to_owned()],
server_url: None,
conflict_mode: "skip".to_owned(),
},
)
.await
.unwrap();
assert_eq!(created.created.len(), 2);
assert_eq!(
fetches.load(Ordering::SeqCst),
2,
"apply must reuse the saved dependency snapshots"
);
let drafts_after_apply = registry.list_operations(&workspace_id).await.unwrap().len();
// AC-2 replay: re-issue the SAME request key/payload. The import is already
// applied, so the service must return the stored application result, create
// no extra Draft, and refetch nothing. The fixture server stays alive until
// after the replay so the counter would observe any real request.
let replay = service
.create_openapi_import(
&workspace_id,
&job_id,
OpenApiImportCreatePayload {
selected_operation_keys: vec!["GET /dot".to_owned(), "GET /query".to_owned()],
server_url: None,
conflict_mode: "skip".to_owned(),
},
)
.await
.unwrap();
assert_eq!(
replay.created, created.created,
"replay must return the stored application result for the same request key and payload"
);
assert_eq!(replay.created.len(), 2);
assert_eq!(
fetches.load(Ordering::SeqCst),
2,
"replay must not refetch dependency snapshots"
);
fixture_server.abort();
let completed = registry
.get_import_job(&workspace_id, &job_id)
.await
.unwrap()
.unwrap();
assert_eq!(completed.status, ImportJobStatus::Completed);
assert_eq!(
registry.list_operations(&workspace_id).await.unwrap().len(),
drafts_after_apply,
"replay must not create extra Drafts"
);
}
// F1 outer path: the same references uploaded as authenticated multipart through
// the outer router must preview without a false blocker, and the materializer
// must have stored both transport-canonical snapshots before resolution is
// judged. The run then continues through the real router apply and a replay of
// the same payload key while the fixture is still alive: the stored application
// result must be returned unchanged, no extra Draft may appear, and the fetch
// counter must not grow.
#[tokio::test(flavor = "multi_thread")]
#[serial]
async fn outer_authenticated_multipart_preview_matches_transport_canonical_uri() {
// Distinct bytes so the two canonical URIs cannot collapse into one
// dependency envelope; both remain valid resolvable schemas.
const ROOT_ITEM: &str =
"Item: { type: object, required: [id], properties: { id: { type: string } } }";
const QUERY_ITEM: &str =
"Item: { type: object, required: [id], properties: { id: { type: integer } } }";
let fetches = Arc::new(AtomicUsize::new(0));
let root_fetches = Arc::clone(&fetches);
let query_fetches = Arc::clone(&fetches);
let fixture = Router::new()
.route(
"/root.yaml",
get(move || {
let fetches = Arc::clone(&root_fetches);
async move {
fetches.fetch_add(1, Ordering::SeqCst);
ROOT_ITEM
}
}),
)
.route(
"/schema.json",
get(move || {
let fetches = Arc::clone(&query_fetches);
async move {
fetches.fetch_add(1, Ordering::SeqCst);
QUERY_ITEM
}
}),
);
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let fixture_server = tokio::spawn(async move { axum::serve(listener, fixture).await.unwrap() });
let origin = format!("http://{address}");
let registry = test_registry().await;
let app = build_test_app_with_external_references(
registry.clone(),
test_storage_root("openapi_import_external_uri_multipart"),
vec![format!("{origin}/")],
);
let server = spawn_admin_api(app).await;
let client = authorized_client(&server).await;
let document = format!(
r##"
openapi: 3.1.0
info: {{ title: Multipart transport parity }}
servers: [{{ url: https://api.example.test }}]
paths:
/dot:
get:
operationId: encodedDot
responses:
'200':
description: ok
content: {{ application/json: {{ schema: {{ $ref: '{origin}/a/%2e%2e/root.yaml#/Item' }} }} }}
/query:
get:
operationId: quotedQuery
responses:
'200':
description: ok
content: {{ application/json: {{ schema: {{ $ref: "{origin}/schema.json?filter='x'#/Item" }} }} }}
"##
);
let response = client
.post(format!("{server}/imports/openapi/preview"))
.multipart(
Form::new().part(
"file",
Part::bytes(document.into_bytes())
.file_name("openapi.yaml".to_owned())
.mime_str("application/yaml")
.unwrap(),
),
)
.send()
.await
.unwrap();
let status = response.status();
let body = response.json::<serde_json::Value>().await.unwrap();
assert_eq!(status, reqwest::StatusCode::OK, "{body}");
// The materializer must have downloaded both snapshots under the
// transport-canonical keys before the blocker check is meaningful.
let job_id_str = body["job_id"].as_str().unwrap().to_owned();
let job_id: crank_registry::ImportJobId = job_id_str.as_str().into();
let job = registry
.get_import_job(&WorkspaceId::new("ws_default"), &job_id)
.await
.unwrap()
.unwrap();
let canonical_uris = job.preview_payload["dependencies"]
.as_array()
.unwrap()
.iter()
.map(|dependency| dependency["canonical_uri"].as_str().unwrap().to_owned())
.collect::<std::collections::BTreeSet<_>>();
assert_eq!(
canonical_uris,
std::collections::BTreeSet::from([
format!("{origin}/root.yaml"),
format!("{origin}/schema.json?filter=%27x%27"),
]),
"both transport-canonical external URIs must be materialized"
);
assert_eq!(
fetches.load(Ordering::SeqCst),
2,
"preview must fetch each external document exactly once"
);
assert!(
!body.to_string().contains("external_reference_unavailable"),
"outer multipart preview must not report a false external blocker: {body}"
);
let resolved = body["preview"]["groups"][0]["operations"]
.as_array()
.unwrap()
.iter()
.map(|operation| {
(
operation["key"].as_str().unwrap().to_owned(),
operation["output_fields"].clone(),
)
})
.collect::<std::collections::BTreeMap<_, _>>();
assert_eq!(resolved["GET /dot"], serde_json::json!(1));
assert_eq!(resolved["GET /query"], serde_json::json!(1));
// AC-2: apply through the real authenticated router, then replay the SAME
// payload key. The fixture stays alive so a real refetch would move the
// counter, and the same application key must not create another Draft.
let create_payload = serde_json::json!({
"selected_operation_keys": ["GET /dot", "GET /query"],
"server_url": null,
"conflict_mode": "skip"
});
let create_response = client
.post(format!("{server}/imports/openapi/{job_id_str}/create"))
.json(&create_payload)
.send()
.await
.unwrap();
assert_eq!(
create_response.status(),
reqwest::StatusCode::OK,
"apply through the router must succeed"
);
let created: serde_json::Value = create_response.json().await.unwrap();
assert_eq!(created["created"].as_array().unwrap().len(), 2);
assert_eq!(
fetches.load(Ordering::SeqCst),
2,
"apply must reuse the saved dependency snapshots"
);
let drafts_after_apply = client
.get(format!("{server}/operations"))
.send()
.await
.unwrap()
.json::<serde_json::Value>()
.await
.unwrap()["total"]
.clone();
assert_eq!(drafts_after_apply, serde_json::json!(2));
let replay_response = client
.post(format!("{server}/imports/openapi/{job_id_str}/create"))
.json(&create_payload)
.send()
.await
.unwrap();
assert_eq!(replay_response.status(), reqwest::StatusCode::OK);
let replay: serde_json::Value = replay_response.json().await.unwrap();
assert_eq!(
replay, created,
"replaying the same payload key must return the stored application result"
);
assert_eq!(
fetches.load(Ordering::SeqCst),
2,
"replay must not refetch dependency snapshots"
);
let drafts_after_replay = client
.get(format!("{server}/operations"))
.send()
.await
.unwrap()
.json::<serde_json::Value>()
.await
.unwrap()["total"]
.clone();
assert_eq!(
drafts_after_replay, drafts_after_apply,
"replay must not create extra Drafts"
);
fixture_server.abort();
}
// AC-3 over real HTTP: the primary document references an encoded-dot root alias
// (`/a/%2e%2e/root.yaml`) whose document contains a relative child `$ref`. The
// materializer must canonicalize the alias to `/root.yaml`, then join the child
// against that real canonical root (not the raw alias), so `/child.yaml` is
// fetched exactly once and the derived schema resolves through the chain.
#[tokio::test(flavor = "multi_thread")]
#[serial]
async fn encoded_dot_root_alias_chain_resolves_relative_child_against_canonical_root_over_http() {
const ROOT_ALIAS_DOCUMENT: &str = "Item: { $ref: './child.yaml#/Item' }";
const CHILD_ITEM: &str =
"Item: { type: object, required: [id], properties: { id: { type: string } } }";
let fetches = Arc::new(AtomicUsize::new(0));
let root_fetches = Arc::clone(&fetches);
let child_fetches = Arc::clone(&fetches);
let app = Router::new()
.route(
"/root.yaml",
get(move || {
let fetches = Arc::clone(&root_fetches);
async move {
fetches.fetch_add(1, Ordering::SeqCst);
ROOT_ALIAS_DOCUMENT
}
}),
)
.route(
"/child.yaml",
get(move || {
let fetches = Arc::clone(&child_fetches);
async move {
fetches.fetch_add(1, Ordering::SeqCst);
CHILD_ITEM
}
}),
);
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let fixture_server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
let origin = format!("http://{address}");
let registry = test_registry().await;
let storage_root = test_storage_root("openapi_import_external_uri_dot_root_chain");
let service = test_service_with_external_references(
registry.clone(),
storage_root.clone(),
vec![format!("{origin}/")],
);
let workspace_id = WorkspaceId::new("ws_default");
let upload = OpenApiUpload {
bytes: format!(
r##"
openapi: 3.1.0
info: {{ title: Canonical root alias chain }}
servers: [{{ url: https://api.example.test }}]
paths:
/items:
get:
operationId: listItems
responses:
'200':
description: ok
content: {{ application/json: {{ schema: {{ $ref: '{origin}/a/%2e%2e/root.yaml#/Item' }} }} }}
"##
)
.into_bytes(),
mime_type: "application/yaml".to_owned(),
locale: OpenApiUploadLocale::En,
};
let preview = service
.preview_openapi_import(&workspace_id, upload)
.await
.unwrap();
let job_id: crank_registry::ImportJobId = preview.job_id.as_str().into();
let job = registry
.get_import_job(&workspace_id, &job_id)
.await
.unwrap()
.unwrap();
let dependencies = job.preview_payload["dependencies"].as_array().unwrap();
assert_eq!(dependencies.len(), 2);
let canonical_uris = dependencies
.iter()
.map(|dependency| dependency["canonical_uri"].as_str().unwrap().to_owned())
.collect::<std::collections::BTreeSet<_>>();
assert_eq!(
canonical_uris,
std::collections::BTreeSet::from([
format!("{origin}/root.yaml"),
format!("{origin}/child.yaml"),
]),
"the child must be materialized relative to the canonical root, not the raw encoded-dot alias"
);
assert_eq!(
fetches.load(Ordering::SeqCst),
2,
"the canonical root alias and its relative child must each be fetched exactly once"
);
// Dependency bytes and digests verify against the workspace-scoped store.
let store = Arc::new(ArtifactStore::open(&storage_root).unwrap());
for dependency in dependencies {
let source_id = ArtifactSourceId::new(dependency["source_id"].as_str().unwrap());
let digest = dependency["digest"].as_str().unwrap();
let verified = registry
.read_artifact_source(Arc::clone(&store), &workspace_id, &source_id)
.await
.unwrap();
assert_eq!(verified.source.blob.artifact_ref.as_str(), digest);
let canonical_uri = dependency["canonical_uri"].as_str().unwrap();
let expected = if canonical_uri.ends_with("/root.yaml") {
ROOT_ALIAS_DOCUMENT
} else {
CHILD_ITEM
};
assert_eq!(verified.bytes, expected.as_bytes());
}
// No false blocker: the chain resolves through the canonical root.
let false_blockers = preview
.preview
.groups
.iter()
.flat_map(|group| &group.operations)
.flat_map(|operation| {
operation
.findings
.iter()
.filter(|finding| finding.code == "external_reference_unavailable")
.map(|_| operation.key.clone())
})
.collect::<Vec<_>>();
assert!(
false_blockers.is_empty(),
"the encoded-dot root alias chain must resolve; false blockers: {false_blockers:?}"
);
assert_eq!(preview.preview.groups[0].operations[0].output_fields, 1);
// The derived schema must be the child object reached through the canonical
// root, projected into the persisted preview.
let output_schema =
&job.preview_payload["preview"]["groups"][0]["operations"][0]["draft"]["output_schema"];
assert_eq!(
output_schema["type"], "object",
"the operation output schema must be the child object derived through the chain: {output_schema}"
);
assert_eq!(
output_schema["fields"]["id"]["type"], "string",
"the child `id` property must survive resolution: {output_schema}"
);
fixture_server.abort();
}
@@ -0,0 +1,170 @@
{
"dependencies": [],
"dependency_snapshots": [],
"normalization": {
"config": {
"external_references_enabled": false,
"max_aliases": 128,
"max_bytes": 262144,
"max_collection_items": 10000,
"max_depth": 64,
"max_expanded_nodes": 100000,
"max_external_document_bytes": 262144,
"max_nodes": 50000,
"max_reference_depth": 32,
"max_reference_documents": 32,
"max_references": 4096,
"max_scalar_bytes": 262144,
"normalizer_version": "normalized-ir-v5",
"projection_version": "preview-v6"
},
"ir_fingerprint": "1e7a724e849b657d79d78f494d962ba5ebc164f154902153a8ed0610e0744679",
"normalizer_version": "normalized-ir-v5",
"projection_version": "preview-v6"
},
"preview": {
"findings": [],
"groups": [
{
"key": "imported_operation",
"operations": [
{
"category": "imported",
"description": "Выполняет GET /items",
"draft": {
"category": "imported",
"display_name": "List Items",
"input_mapping": {},
"input_schema": {
"description": "Входные параметры MCP-инструмента",
"nullable": false,
"required": true,
"type": "object"
},
"name": "list_items",
"output_mapping": {
"rules": [
{
"required": true,
"source": "$.response.body.id",
"target": "$.output.id"
}
]
},
"output_schema": {
"description": "Ответ API",
"fields": {
"id": {
"nullable": false,
"required": true,
"type": "string"
}
},
"nullable": false,
"required": true,
"type": "object"
},
"target": {
"base_url": "https://api.example.test",
"method": "GET",
"path_template": "/items",
"response_contract": [
{
"media_type": "application/json",
"schema_variant": 0,
"status_code": 200
}
]
},
"tool_description": {
"description": "Выполняет GET /items",
"examples": [
{
"input": {}
}
],
"title": "List Items"
},
"wizard_state": {}
},
"findings": [
{
"code": "missing_summary",
"message": "У метода нет summary, отображаемое имя будет сгенерировано автоматически.",
"operation_key": "GET /items",
"severity": "warning",
"source_location": {
"pointer": "/paths/~1items/get"
}
},
{
"code": "missing_description",
"message": "У метода нет description. Перед публикацией лучше описать, когда агенту стоит вызывать этот инструмент.",
"operation_key": "GET /items",
"severity": "warning",
"source_location": {
"pointer": "/paths/~1items/get"
}
},
{
"code": "no_input_fields",
"message": "У инструмента нет входных параметров. Это нормально для справочных методов, но проверьте, что агенту не нужно передавать фильтры.",
"operation_key": "GET /items",
"severity": "info",
"source_location": {
"pointer": "/paths/~1items/get"
}
},
{
"code": "weak_tool_description",
"message": "Описание инструмента слишком короткое или техническое. Перед публикацией добавьте, когда агент должен вызывать инструмент и что будет в успешном ответе.",
"operation_key": "GET /items",
"severity": "warning",
"source_location": {
"pointer": "/paths/~1items/get"
}
},
{
"code": "weak_tool_name",
"message": "Имя инструмента `list_items` выглядит слишком общим. Лучше использовать имя с конкретным действием и объектом.",
"operation_key": "GET /items",
"severity": "warning",
"source_location": {
"pointer": "/paths/~1items/get"
}
}
],
"input_fields": 0,
"key": "GET /items",
"method": "GET",
"operation_id": "listItems",
"output_fields": 1,
"path": "/items",
"server_urls": [
"https://api.example.test"
],
"source_location": {
"pointer": "/paths/~1items/get"
},
"suggested_display_name": "List Items",
"suggested_name": "list_items"
}
],
"title": "Без группы"
}
],
"source": {
"format": "openapi",
"servers": [
"https://api.example.test"
],
"title": "URI preview parity",
"version": "3.1.0"
}
},
"preview_digest": "ab615bbb932979b3c9d7d78223fc932069e1d7443860a24c682edddc0de11637",
"source": {
"digest": "sha256:edc9f4ec760d76a6830ae5b9932881d898626faffbc0067162ddb44ebdf8b94c",
"source_id": "src_openapi_01a1278095397d018780ab3dafd4b464"
}
}
@@ -8,9 +8,17 @@ use admin_api::service::{
use crank_core::WorkspaceId;
use crank_registry::{CreateImportPlanRequest, ImportPlanId};
fn single_operation_upload() -> OpenApiUpload {
OpenApiUpload {
bytes: OPENAPI_SINGLE.as_bytes().to_vec(),
mime_type: "application/yaml".to_owned(),
locale: OpenApiUploadLocale::En,
}
}
#[tokio::test]
#[serial]
async fn older_v2_support_matrix_rejects_new_apply_but_keeps_plan_auditable() {
async fn older_support_matrix_rejects_new_apply_but_keeps_plan_auditable() {
let registry = test_registry().await;
let service = test_service(
registry.clone(),
@@ -20,14 +28,7 @@ async fn older_v2_support_matrix_rejects_new_apply_but_keeps_plan_auditable() {
);
let workspace_id = WorkspaceId::new("ws_default");
let preview = service
.preview_openapi_import(
&workspace_id,
OpenApiUpload {
bytes: OPENAPI_SINGLE.as_bytes().to_vec(),
mime_type: "application/yaml".to_owned(),
locale: OpenApiUploadLocale::En,
},
)
.preview_openapi_import(&workspace_id, single_operation_upload())
.await
.unwrap();
let job_id = preview.job_id.as_str().into();
@@ -51,56 +52,120 @@ async fn older_v2_support_matrix_rejects_new_apply_but_keeps_plan_auditable() {
.unwrap()
.unwrap();
// Model an immutable plan saved under an earlier support matrix. The
// registry derives its valid semantic digest from the changed payload.
let old_id: ImportPlanId = "plan_older_support_matrix".into();
let mut old_payload = original.payload.clone();
old_payload["plan_reference"] = json!(old_id.as_str());
old_payload["support_matrix_version"] = json!("1.0.2");
let older = registry
.create_import_plan(CreateImportPlanRequest {
id: &old_id,
workspace_id: &workspace_id,
job_id: &original.job_id,
payload: &old_payload,
created_at: &original.created_at,
expires_at: &original.expires_at,
})
// 1.0.2 is the historical matrix contract and 1.0.3 the immediate previous
// one; against the shipped 1.0.4 matrix both must stay stale and must not
// authorize a new Apply, while the original immutable plan stays auditable.
for version in ["1.0.2", "1.0.3"] {
// Model an immutable plan saved under an earlier support matrix. The
// registry derives its valid semantic digest from the changed payload.
let old_id: ImportPlanId =
format!("plan_older_support_matrix_{}", version.replace('.', "_")).into();
let mut old_payload = original.payload.clone();
old_payload["plan_reference"] = json!(old_id.as_str());
old_payload["support_matrix_version"] = json!(version);
let older = registry
.create_import_plan(CreateImportPlanRequest {
id: &old_id,
workspace_id: &workspace_id,
job_id: &original.job_id,
payload: &old_payload,
created_at: &original.created_at,
expires_at: &original.expires_at,
})
.await
.unwrap();
assert_ne!(older.digest, original.digest);
let audit = service
.revalidate_openapi_import_plan(&workspace_id, &old_id)
.await
.unwrap();
assert_eq!(audit.revalidation_status, "stale", "{version}");
assert!(audit.revalidation_required, "{version}");
assert_eq!(
audit.reason.as_deref(),
Some("importer_version_changed"),
"{version}"
);
let error = service
.apply_openapi_import_plan(
&workspace_id,
&old_id,
OpenApiImportPlanApplyPayload {
plan_digest: older.digest,
idempotency_key: format!("old-matrix-{version}"),
},
)
.await
.expect_err("old support matrix must not authorize a new Apply");
match error {
ApiError::Conflict {
context: Some(context),
..
} => assert_eq!(context["error_code"], "importer_version_changed"),
other => panic!("expected typed re-preview conflict, got {other:?}"),
}
assert!(
service
.list_operations(&workspace_id)
.await
.unwrap()
.is_empty(),
"{version} apply must not mutate the workspace"
);
}
}
// The runtime matrix version stamped into a fresh plan must equal the version
// recorded in the machine matrix the corpus validates. Reading the machine YAML
// (rather than a second literal) keeps an app release honest: it can never
// advertise a matrix the repository does not actually ship.
#[tokio::test]
#[serial]
async fn fresh_plan_support_matrix_version_matches_machine_matrix() {
let machine_text = std::fs::read_to_string(
std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../crates/crank-import/tests/support-matrix.yaml"),
)
.unwrap();
let machine: serde_yaml::Value = serde_yaml::from_str(&machine_text).unwrap();
let machine_version = machine["matrix_version"].as_str().unwrap().to_owned();
let registry = test_registry().await;
let service = test_service(
registry.clone(),
test_storage_root("openapi_support_matrix_runtime_version"),
test_auth_settings(),
test_secret_crypto(),
);
let workspace_id = WorkspaceId::new("ws_default");
let preview = service
.preview_openapi_import(&workspace_id, single_operation_upload())
.await
.unwrap();
assert_ne!(older.digest, original.digest);
let audit = service
.revalidate_openapi_import_plan(&workspace_id, &old_id)
.await
.unwrap();
assert_eq!(audit.revalidation_status, "stale");
assert!(audit.revalidation_required);
assert_eq!(audit.reason.as_deref(), Some("importer_version_changed"));
let error = service
.apply_openapi_import_plan(
let job_id = preview.job_id.as_str().into();
let created = service
.create_openapi_import_plan(
&workspace_id,
&old_id,
OpenApiImportPlanApplyPayload {
plan_digest: older.digest,
idempotency_key: "old-matrix-new-attempt".to_owned(),
&job_id,
OpenApiImportPlanCreatePayload {
selection_mode: "full".to_owned(),
selected_operation_keys: Vec::new(),
server_url: None,
decisions: Vec::new(),
},
)
.await
.expect_err("old support matrix must not authorize a new Apply");
match error {
ApiError::Conflict {
context: Some(context),
..
} => assert_eq!(context["error_code"], "importer_version_changed"),
other => panic!("expected typed re-preview conflict, got {other:?}"),
}
assert!(
service
.list_operations(&workspace_id)
.await
.unwrap()
.is_empty()
.unwrap();
let stored = registry
.get_import_plan(&workspace_id, &created.plan_reference.as_str().into())
.await
.unwrap()
.unwrap();
assert_eq!(
stored.payload["support_matrix_version"],
json!(machine_version),
"the runtime support-matrix version must match the machine matrix"
);
}
@@ -208,7 +208,7 @@ async fn full_plan_is_server_authored_with_bounded_confirmation_and_no_mutation(
assert_eq!(stored.digest, plan.plan_digest);
assert_eq!(stored.payload["schema_version"], "import-plan-v2");
assert_eq!(stored.payload["catalog_revision"], plan.catalog_revision);
assert_eq!(stored.payload["support_matrix_version"], "1.0.3");
assert_eq!(stored.payload["support_matrix_version"], "1.0.4");
assert!(stored.payload["findings"]["document"].is_array());
assert!(stored.payload["findings"]["candidates"].is_array());
assert_eq!(stored.expires_at, expires_at);
@@ -91,3 +91,173 @@ async fn exact_v5_contract_replays_saved_preview_without_source_locations() {
.unwrap();
assert_eq!(completed.status, ImportJobStatus::Completed);
}
// Deterministic baseline source for the v5/v6 replay characterization. It uses
// a local reference so the preview is self-contained (no external dependency
// or ephemeral fixture port) while still exercising the reference graph.
const URI_PREVIEW_DOCUMENT: &str = r#"
openapi: 3.1.0
info: { title: URI preview parity, version: '1' }
servers: [{ url: https://api.example.test }]
paths:
/items:
get:
operationId: listItems
responses:
'200':
description: ok
content: { application/json: { schema: { $ref: '#/components/schemas/Item' } } }
components:
schemas:
Item: { type: object, required: [id], properties: { id: { type: string } } }
"#;
fn uri_preview_upload() -> OpenApiUpload {
OpenApiUpload {
bytes: URI_PREVIEW_DOCUMENT.as_bytes().to_vec(),
mime_type: "application/yaml".to_owned(),
locale: OpenApiUploadLocale::En,
}
}
fn v5_v6_fixture_path() -> std::path::PathBuf {
std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("tests/integration/openapi_import/fixtures/v5-v6-uri-preview.json")
}
// AC-4 (history): a preview persisted under the historical (v5, v6) contract
// must replay unchanged, and a new preview of the same source must use the
// current contract. Captured from baseline execution before the URI change.
#[tokio::test]
#[serial]
async fn v5_v6_uri_preview_replays_unchanged_and_new_preview_uses_current_contract() {
let fixture_text = std::fs::read_to_string(v5_v6_fixture_path())
.expect("baseline v5/v6 URI preview fixture must be captured before the change");
let fixture: serde_json::Value = serde_json::from_str(&fixture_text).unwrap();
assert_eq!(
fixture["normalization"]["normalizer_version"],
serde_json::json!("normalized-ir-v5")
);
assert_eq!(
fixture["normalization"]["projection_version"],
serde_json::json!("preview-v6")
);
let fixture_preview = fixture["preview"].clone();
let fixture_digest = fixture["preview_digest"].clone();
let registry = test_registry().await;
let service = test_service(
registry.clone(),
test_storage_root("openapi_import_v5_v6_replay"),
test_auth_settings(),
test_secret_crypto(),
);
let workspace_id = WorkspaceId::new("ws_default");
// A current preview of the same bytes must use the current contract.
let fresh = service
.preview_openapi_import(&workspace_id, uri_preview_upload())
.await
.unwrap();
let job_id: crank_registry::ImportJobId = fresh.job_id.as_str().into();
let fresh_job = registry
.get_import_job(&workspace_id, &job_id)
.await
.unwrap()
.unwrap();
assert_eq!(
fresh_job.preview_payload["source"]["digest"], fixture["source"]["digest"],
"fixture must refer to the exact captured source bytes"
);
assert_eq!(
fresh_job.preview_payload["normalization"]["normalizer_version"],
serde_json::json!(crank_import::rest::NORMALIZER_VERSION)
);
assert_eq!(
fresh_job.preview_payload["normalization"]["projection_version"],
serde_json::json!(crank_import::rest::PROJECTION_VERSION)
);
// Bind the historical payload to this run's freshly registered source blob.
let mut payload = fixture.clone();
payload["source"]["source_id"] = fresh_job.preview_payload["source"]["source_id"].clone();
sqlx::query("update import_jobs set preview_payload = $1::jsonb where id = $2")
.bind(serde_json::to_string(&payload).unwrap())
.bind(job_id.as_str())
.execute(registry.pool())
.await
.unwrap();
let result = service
.create_openapi_import(
&workspace_id,
&job_id,
OpenApiImportCreatePayload {
selected_operation_keys: vec!["GET /items".to_owned()],
server_url: None,
conflict_mode: "skip".to_owned(),
},
)
.await
.unwrap();
assert_eq!(result.created.len(), 1);
// The historical preview is replayed from its saved projection, never
// recomputed under the current normalizer.
let completed = registry
.get_import_job(&workspace_id, &job_id)
.await
.unwrap()
.unwrap();
assert_eq!(completed.status, ImportJobStatus::Completed);
assert_eq!(completed.preview_payload["preview"], fixture_preview);
assert_eq!(
completed.preview_payload["normalization"]["normalizer_version"],
serde_json::json!("normalized-ir-v5")
);
assert_eq!(
completed.preview_payload["normalization"]["projection_version"],
serde_json::json!("preview-v6")
);
assert_eq!(completed.preview_payload["preview_digest"], fixture_digest);
}
// AC-4 (version RED): a fresh preview of the fixture source must be stamped with
// the approved v6 normalizer contract. This is the version RED, distinct from
// the URI transport RED: it pins the exact approved literals instead of
// following the current `NORMALIZER_VERSION`/`PROJECTION_VERSION` constants,
// which do not by themselves prove the approved v6 value. Deliberately no
// if-current branch and no skip: the assertion is unconditional and is expected
// to fail until the implementation bumps the normalizer to `normalized-ir-v6`.
#[tokio::test]
#[serial]
async fn fresh_preview_matches_approved_v6_normalizer_contract() {
let registry = test_registry().await;
let service = test_service(
registry.clone(),
test_storage_root("openapi_import_v5_v6_version_contract"),
test_auth_settings(),
test_secret_crypto(),
);
let workspace_id = WorkspaceId::new("ws_default");
let fresh = service
.preview_openapi_import(&workspace_id, uri_preview_upload())
.await
.unwrap();
let job_id: crank_registry::ImportJobId = fresh.job_id.as_str().into();
let fresh_job = registry
.get_import_job(&workspace_id, &job_id)
.await
.unwrap()
.unwrap();
assert_eq!(
fresh_job.preview_payload["normalization"]["normalizer_version"],
serde_json::json!("normalized-ir-v6"),
"approved normalizer contract is normalized-ir-v6"
);
assert_eq!(
fresh_job.preview_payload["normalization"]["projection_version"],
serde_json::json!("preview-v6"),
"approved projection contract is preview-v6"
);
}