diff --git a/Cargo.lock b/Cargo.lock index b50df08..9457f57 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -651,6 +651,7 @@ version = "0.3.1" dependencies = [ "async-trait", "axum", + "base64", "crank-core", "crank-metrics", "crank-trace", @@ -766,6 +767,7 @@ dependencies = [ "serde_json", "serde_yaml", "thiserror 2.0.18", + "url", ] [[package]] @@ -846,6 +848,7 @@ dependencies = [ "base64", "crank-adapter-rest", "crank-core", + "crank-import", "crank-mapping", "crank-metrics", "crank-schema", diff --git a/apps/admin-api/src/import_guidance.rs b/apps/admin-api/src/import_guidance.rs index 65949bc..5b0a948 100644 --- a/apps/admin-api/src/import_guidance.rs +++ b/apps/admin-api/src/import_guidance.rs @@ -134,9 +134,13 @@ mod tests { method: HttpMethod::Delete, path_template: "/items/{id}".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -148,6 +152,7 @@ mod tests { }, output_schema: Schema { kind: SchemaKind::Object, + format: None, description: None, required: false, nullable: false, @@ -198,6 +203,7 @@ mod tests { fn string_schema() -> Schema { Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, diff --git a/apps/admin-api/src/service/demo.rs b/apps/admin-api/src/service/demo.rs index 8d12fa3..3b71562 100644 --- a/apps/admin-api/src/service/demo.rs +++ b/apps/admin-api/src/service/demo.rs @@ -421,6 +421,9 @@ fn demo_rest_operation_payload() -> OperationPayload { method: crank_core::HttpMethod::Get, path_template: "/v1/latest".to_owned(), static_headers: BTreeMap::from([("Accept".to_owned(), "application/json".to_owned())]), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: Schema::from_json_sample(&input), output_schema: Schema::from_json_sample(&output), diff --git a/apps/admin-api/src/service/imports.rs b/apps/admin-api/src/service/imports.rs index 36be097..835f5c2 100644 --- a/apps/admin-api/src/service/imports.rs +++ b/apps/admin-api/src/service/imports.rs @@ -639,7 +639,12 @@ fn import_replay_contract( if normalizer == NORMALIZER_VERSION && projection == PROJECTION_VERSION { return Ok(ImportReplayContract::Current); } - if normalizer != "normalized-ir-v2" || projection != "preview-v2" { + // Historical preview payloads are replayed as their persisted projection. + // They must never be parsed again with the current v4 semantics. + if !matches!( + (normalizer, projection), + ("normalized-ir-v2", "preview-v2") | ("normalized-ir-v3", "preview-v3") + ) { return Err(ApiError::openapi_upload(locale, "source_integrity")); } diff --git a/apps/admin-api/src/service/operation_validation.rs b/apps/admin-api/src/service/operation_validation.rs index 8f7de41..a535186 100644 --- a/apps/admin-api/src/service/operation_validation.rs +++ b/apps/admin-api/src/service/operation_validation.rs @@ -93,7 +93,14 @@ pub(super) fn validate_idempotency_policy( } match target { - Target::Rest(rest_target) if rest_target.method != crank_core::HttpMethod::Get => {} + Target::Rest(rest_target) + if matches!( + rest_target.method, + crank_core::HttpMethod::Post + | crank_core::HttpMethod::Put + | crank_core::HttpMethod::Patch + | crank_core::HttpMethod::Delete + ) => {} _ => { return Err(ApiError::validation_with_context( "idempotency is supported only for mutating REST operations".to_owned(), @@ -206,6 +213,9 @@ mod tests { method: HttpMethod::Get, path_template: "/catalog".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }); let result = validate_response_cache_policy(&target, &cacheable_execution_config()); @@ -233,6 +243,9 @@ mod tests { method: HttpMethod::Post, path_template: "/catalog".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }); let error = @@ -252,6 +265,9 @@ mod tests { method: HttpMethod::Post, path_template: "/orders".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }); let result = validate_idempotency_policy( @@ -269,6 +285,9 @@ mod tests { method: HttpMethod::Get, path_template: "/orders".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }); let error = validate_idempotency_policy( @@ -291,6 +310,9 @@ mod tests { method: HttpMethod::Post, path_template: "/orders".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }); let mut config = idempotent_execution_config(IdempotencyMode::Required); let policy = config.idempotency.as_mut().unwrap(); diff --git a/apps/admin-api/tests/integration/common.rs b/apps/admin-api/tests/integration/common.rs index bf59278..06f450f 100644 --- a/apps/admin-api/tests/integration/common.rs +++ b/apps/admin-api/tests/integration/common.rs @@ -435,6 +435,9 @@ pub(super) fn test_operation_payload(base_url: &str, name: &str) -> OperationPay method: HttpMethod::Post, path_template: "/crm/leads".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: object_schema("email"), output_schema: object_schema("id"), @@ -483,6 +486,7 @@ pub(super) fn test_operation_payload(base_url: &str, name: &str) -> OperationPay pub(super) fn object_schema(field_name: &str) -> Schema { Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -491,6 +495,7 @@ pub(super) fn object_schema(field_name: &str) -> Schema { field_name.to_owned(), Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, diff --git a/apps/admin-api/tests/integration/community_access_usage.rs b/apps/admin-api/tests/integration/community_access_usage.rs index 8475e1e..acd1f2b 100644 --- a/apps/admin-api/tests/integration/community_access_usage.rs +++ b/apps/admin-api/tests/integration/community_access_usage.rs @@ -323,6 +323,9 @@ async fn rejects_response_cache_for_operation_with_auth_profile() { method: HttpMethod::Get, path_template: "/crm/leads".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }); payload.execution_config.response_cache = Some(ResponseCachePolicy { ttl_ms: 5_000 }); payload.execution_config.auth_profile_ref = Some("auth_profile_01".into()); diff --git a/apps/admin-api/tests/integration/openapi_import.rs b/apps/admin-api/tests/integration/openapi_import.rs index 650c6b3..acc294a 100644 --- a/apps/admin-api/tests/integration/openapi_import.rs +++ b/apps/admin-api/tests/integration/openapi_import.rs @@ -10,6 +10,7 @@ use super::common::{ }; mod external_references; +mod http_contract; const OPENAPI3: &str = r#" openapi: 3.0.3 @@ -77,11 +78,11 @@ async fn previews_openapi_and_creates_draft_operations() { assert_eq!(preview_job.status, ImportJobStatus::Pending); assert_eq!( preview_job.preview_payload["normalization"]["normalizer_version"], - "normalized-ir-v3" + "normalized-ir-v4" ); assert_eq!( preview_job.preview_payload["normalization"]["projection_version"], - "preview-v3" + "preview-v4" ); assert!(preview_job.preview_payload["normalization"]["ir_fingerprint"].is_string()); @@ -451,6 +452,8 @@ async fn apply_fails_closed_for_each_normalization_contract_field_and_digest_sha #[tokio::test] #[serial] async fn legacy_job_without_normalization_contract_replays_until_expiry() { + use sha2::{Digest, Sha256}; + let registry = test_registry().await; let service = test_service( registry.clone(), @@ -464,10 +467,22 @@ async fn legacy_job_without_normalization_contract_replays_until_expiry() { .await .unwrap(); let job_id: crank_registry::ImportJobId = preview.job_id.as_str().into(); + // A legacy job stores the legacy projection and its matching fingerprint, + // not a current projection with only the version metadata removed. + let legacy_preview = + serde_json::to_value(crank_import::rest::preview_document_legacy_v1(OPENAPI3).unwrap()) + .unwrap(); + let legacy_digest = format!( + "{:x}", + Sha256::digest(serde_json::to_vec(&legacy_preview).unwrap()) + ); sqlx::query( - "update import_jobs set preview_payload = preview_payload - 'normalization' where id = $1", + "update import_jobs set preview_payload = (preview_payload - 'normalization') || \ + jsonb_build_object('preview', $2::jsonb, 'preview_digest', $3::text) where id = $1", ) .bind(job_id.as_str()) + .bind(legacy_preview) + .bind(legacy_digest) .execute(registry.pool()) .await .unwrap(); diff --git a/apps/admin-api/tests/integration/openapi_import/external_references.rs b/apps/admin-api/tests/integration/openapi_import/external_references.rs index 24d0e5b..9150b0a 100644 --- a/apps/admin-api/tests/integration/openapi_import/external_references.rs +++ b/apps/admin-api/tests/integration/openapi_import/external_references.rs @@ -536,3 +536,73 @@ async fn exact_v2_contract_replays_persisted_preview_without_v3_or_dependency_re .unwrap(); assert_eq!(completed.status, ImportJobStatus::Completed); } + +#[tokio::test] +#[serial] +async fn exact_v3_contract_replays_persisted_preview_without_v4_or_dependency_reads() { + let registry = test_registry().await; + let service = test_service( + registry.clone(), + test_storage_root("openapi_import_v3_compatibility"), + test_auth_settings(), + test_secret_crypto(), + ); + let workspace_id = WorkspaceId::new("ws_default"); + let preview = service + .preview_openapi_import(&workspace_id, openapi_upload()) + .await + .unwrap(); + let job_id: crank_registry::ImportJobId = preview.job_id.as_str().into(); + let missing_dependency = serde_json::json!([{ + "source_id": "src_openapi_dep_v3_must_not_be_read", + "digest": format!("sha256:{}", "0".repeat(64)), + "canonical_uri": "https://schemas.example.test/v3.yaml" + }]); + sqlx::query( + "update import_jobs + set preview_payload = jsonb_set( + jsonb_set( + jsonb_set( + jsonb_set( + preview_payload, + '{normalization,normalizer_version}', + to_jsonb('normalized-ir-v3'::text) + ), + '{normalization,projection_version}', + to_jsonb('preview-v3'::text) + ), + '{normalization,ir_fingerprint}', + to_jsonb($1::text) + ), + '{dependency_snapshots}', + $2::jsonb + ) + where id = $3", + ) + .bind("a".repeat(64)) + .bind(missing_dependency) + .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 /v2/latest".to_owned()], + server_url: Some("https://api.frankfurter.dev".to_owned()), + conflict_mode: "skip".to_owned(), + }, + ) + .await + .unwrap(); + assert_eq!(result.created.len(), 1); + let completed = registry + .get_import_job(&workspace_id, &job_id) + .await + .unwrap() + .unwrap(); + assert_eq!(completed.status, ImportJobStatus::Completed); +} diff --git a/apps/admin-api/tests/integration/openapi_import/http_contract.rs b/apps/admin-api/tests/integration/openapi_import/http_contract.rs new file mode 100644 index 0000000..e00cb66 --- /dev/null +++ b/apps/admin-api/tests/integration/openapi_import/http_contract.rs @@ -0,0 +1,296 @@ +use super::*; + +use crank_core::Target; +use serde_json::json; + +#[tokio::test] +#[serial] +async fn http_contract_preview_apply_and_replay_preserve_json_multipart_schemas_mapping_and_mime() { + let registry = test_registry().await; + let service = test_service( + registry.clone(), + test_storage_root("openapi_import_http_contract_replay"), + test_auth_settings(), + test_secret_crypto(), + ); + let workspace_id = WorkspaceId::new("ws_default"); + let preview = service + .preview_openapi_import(&workspace_id, rich_http_contract_upload()) + .await + .unwrap(); + let job_id: crank_registry::ImportJobId = preview.job_id.as_str().into(); + let persisted_preview_before_apply = registry + .get_import_job(&workspace_id, &job_id) + .await + .unwrap() + .unwrap() + .preview_payload["preview"] + .clone(); + assert_eq!( + persisted_preview_before_apply, + serde_json::to_value(&preview.preview).unwrap() + ); + + let operations = preview + .preview + .groups + .iter() + .flat_map(|group| group.operations.iter()) + .collect::>(); + assert_eq!(operations.len(), 1, "media variants must not split a Tool"); + let candidate = operations[0]; + assert_eq!(candidate.key, "POST /documents"); + assert!( + candidate.findings.iter().all(|finding| { + finding.severity != crank_import::rest::ImportFindingSeverity::Error + }) + ); + + let json_arguments = json!({ + "content_type": "application/json", + "body": {"title": "Quarterly report"} + }); + let multipart_arguments = json!({ + "content_type": "multipart/form-data", + "body": { + "file": { + "data_base64": "AA==", + "filename": "report.png", + "content_type": "image/png" + }, + "caption": "Quarterly report" + } + }); + candidate + .draft + .input_schema + .validate_shape(&json_arguments) + .unwrap(); + candidate + .draft + .input_schema + .validate_shape(&multipart_arguments) + .unwrap(); + assert!( + candidate + .draft + .input_schema + .validate_shape(&json!({ + "content_type": "multipart/form-data", + "body": {"title": "wrong branch"} + })) + .is_err() + ); + + let mapped = candidate + .draft + .input_mapping + .apply(&json!({"mcp": multipart_arguments})) + .unwrap(); + assert_eq!( + mapped["request"]["body_content_type"], + "multipart/form-data" + ); + assert_eq!(mapped["request"]["body"]["file"]["data_base64"], "AA=="); + + let preview_target = &candidate.draft.target; + let preview_contract = preview_target.request_contract.as_ref().unwrap(); + assert_eq!(preview_contract.body_field, "body"); + assert_eq!( + preview_contract.selector_field.as_deref(), + Some("content_type") + ); + assert_eq!(preview_contract.variants.len(), 2); + assert_eq!( + preview_target.multipart_field_mime_types["multipart/form-data"]["file"], + ["image/png", "image/jpeg"] + ); + + let payload = OpenApiImportCreatePayload { + selected_operation_keys: vec![candidate.key.clone()], + server_url: None, + conflict_mode: "skip".to_owned(), + }; + let created = service + .create_openapi_import(&workspace_id, &job_id, payload.clone()) + .await + .unwrap(); + assert_eq!(created.created.len(), 1); + + let replayed = service + .create_openapi_import(&workspace_id, &job_id, payload) + .await + .unwrap(); + assert_eq!(replayed.created, created.created); + let persisted_preview_after_replay = registry + .get_import_job(&workspace_id, &job_id) + .await + .unwrap() + .unwrap() + .preview_payload["preview"] + .clone(); + assert_eq!( + persisted_preview_after_replay, + persisted_preview_before_apply + ); + + let version = service + .get_operation_version( + &workspace_id, + &created.created[0].operation_id.as_str().into(), + created.created[0].version, + ) + .await + .unwrap(); + assert_eq!(version.snapshot.input_schema, candidate.draft.input_schema); + assert_eq!( + version.snapshot.output_schema, + candidate.draft.output_schema + ); + assert_eq!( + version.snapshot.input_mapping, + candidate.draft.input_mapping + ); + assert_eq!( + version.snapshot.output_mapping, + candidate.draft.output_mapping + ); + assert_eq!( + version.snapshot.target, + Target::Rest(candidate.draft.target.clone()) + ); +} + +#[tokio::test] +#[serial] +async fn xml_and_unsupported_media_block_apply_without_registry_mutation() { + let registry = test_registry().await; + let service = test_service( + registry.clone(), + test_storage_root("openapi_import_http_contract_blockers"), + test_auth_settings(), + test_secret_crypto(), + ); + let workspace_id = WorkspaceId::new("ws_default"); + let preview = service + .preview_openapi_import(&workspace_id, unsupported_media_upload()) + .await + .unwrap(); + let candidate = preview + .preview + .groups + .iter() + .flat_map(|group| group.operations.iter()) + .find(|operation| operation.key == "POST /blocked") + .unwrap(); + assert!(candidate.findings.iter().any(|finding| { + finding.code == "unsupported_xml_request_media_type" + && finding.severity == crank_import::rest::ImportFindingSeverity::Error + })); + assert!(candidate.findings.iter().any(|finding| { + finding.code == "unsupported_request_media_type" + && finding.severity == crank_import::rest::ImportFindingSeverity::Error + })); + + assert!( + service + .create_openapi_import( + &workspace_id, + &preview.job_id.as_str().into(), + OpenApiImportCreatePayload { + selected_operation_keys: vec![candidate.key.clone()], + server_url: None, + conflict_mode: "skip".to_owned(), + }, + ) + .await + .is_err() + ); + assert!( + service + .list_operations(&workspace_id) + .await + .unwrap() + .is_empty() + ); + + let job = registry + .get_import_job(&workspace_id, &preview.job_id.as_str().into()) + .await + .unwrap() + .unwrap(); + assert_eq!(job.status, ImportJobStatus::Failed); + assert_eq!( + job.error_text.as_deref(), + Some("reference_resolution_blocked") + ); +} + +fn rich_http_contract_upload() -> OpenApiUpload { + OpenApiUpload { + bytes: br#" +openapi: 3.0.3 +info: { title: Document import } +servers: [{ url: https://api.example.test/v1 }] +paths: + /documents: + post: + operationId: importDocument + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [title] + properties: + title: { type: string } + multipart/form-data: + schema: + type: object + required: [file] + properties: + file: { type: string, format: binary } + caption: { type: string } + encoding: + file: { contentType: 'image/png, image/jpeg' } + responses: + '201': + description: Created + content: + application/json: + schema: { type: object, properties: { id: { type: string } } } +"# + .to_vec(), + mime_type: "application/yaml".to_owned(), + locale: OpenApiUploadLocale::En, + } +} + +fn unsupported_media_upload() -> OpenApiUpload { + OpenApiUpload { + bytes: br#" +openapi: 3.0.3 +info: { title: Unsupported request media } +servers: [{ url: https://api.example.test/v1 }] +paths: + /blocked: + post: + operationId: blockedMedia + requestBody: + required: true + content: + application/json: + schema: { type: object, properties: { name: { type: string } } } + application/xml: + schema: { type: string } + application/pdf: + schema: { type: string, format: binary } + responses: + '200': { description: OK } +"# + .to_vec(), + mime_type: "application/yaml".to_owned(), + locale: OpenApiUploadLocale::En, + } +} diff --git a/apps/mcp-server/tests/integration/common.rs b/apps/mcp-server/tests/integration/common.rs index e7f44b8..fbe3b5d 100644 --- a/apps/mcp-server/tests/integration/common.rs +++ b/apps/mcp-server/tests/integration/common.rs @@ -489,6 +489,9 @@ pub(super) fn test_operation(base_url: &str, name: &str) -> Operation Operation Schema { Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -551,6 +555,7 @@ pub(super) fn object_schema(field_name: &str) -> Schema { field_name.to_owned(), Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, diff --git a/crates/crank-adapter-rest/Cargo.toml b/crates/crank-adapter-rest/Cargo.toml index e94a956..b63dda1 100644 --- a/crates/crank-adapter-rest/Cargo.toml +++ b/crates/crank-adapter-rest/Cargo.toml @@ -8,6 +8,7 @@ version.workspace = true [dependencies] async-trait = "0.1" +base64.workspace = true crank-core = { path = "../crank-core" } crank-metrics = { path = "../crank-metrics" } crank-trace = { path = "../crank-trace" } diff --git a/crates/crank-adapter-rest/src/body.rs b/crates/crank-adapter-rest/src/body.rs new file mode 100644 index 0000000..b4fbbac --- /dev/null +++ b/crates/crank-adapter-rest/src/body.rs @@ -0,0 +1,488 @@ +use std::{collections::BTreeMap, io}; + +use base64::{Engine as _, engine::general_purpose::STANDARD}; +use crank_core::RestTarget; +use futures_util::StreamExt; +use serde_json::Value; + +use crate::RestAdapterError; + +pub(crate) async fn apply_body( + builder: reqwest::RequestBuilder, + body: &Value, + content_type: &str, + multipart_mime_types: Option<&BTreeMap>>, + max_request_bytes: usize, +) -> Result { + match content_type { + "application/x-www-form-urlencoded" => { + let encoded = form_urlencoded(body, max_request_bytes)?; + Ok(builder.header("content-type", content_type).body(encoded)) + } + "multipart/form-data" => { + let form = multipart_form(body, multipart_mime_types, max_request_bytes)?; + let boundary = form.boundary().to_owned(); + let mut encoded = BoundedBuffer::new(max_request_bytes); + let mut stream = Box::pin(form.into_stream()); + while let Some(chunk) = stream.next().await { + let chunk = chunk?; + encoded.append(&chunk)?; + } + Ok(builder + .header( + "content-type", + format!("multipart/form-data; boundary={boundary}"), + ) + .body(encoded.into_bytes())) + } + content_type if content_type == "application/json" || content_type.ends_with("+json") => { + let encoded = json_bytes(body, max_request_bytes)?; + Ok(builder.header("content-type", content_type).body(encoded)) + } + _ => Err(RestAdapterError::InvalidBodyContract { + reason: "unsupported request content type".to_owned(), + }), + } +} + +pub(crate) fn apply_legacy_json_body( + builder: reqwest::RequestBuilder, + body: &Value, + has_content_type: bool, + limit_bytes: usize, +) -> Result { + let builder = if has_content_type { + builder + } else { + builder.header("content-type", "application/json") + }; + Ok(builder.body(json_bytes(body, limit_bytes)?)) +} + +pub(crate) fn selected_request_content_type( + target: &RestTarget, + request: &crate::RestRequest, +) -> Result, RestAdapterError> { + let Some(contract) = &target.request_contract else { + if request.body_content_type.is_some() { + return Err(RestAdapterError::InvalidBodyContract { + reason: "body content type requires a typed request contract".to_owned(), + }); + } + return Ok(None); + }; + let selected = match (&contract.selector_field, &request.body_content_type) { + (Some(_), Some(selected)) => selected, + (Some(_), None) => { + return Err(RestAdapterError::InvalidBodyContract { + reason: "content_type selector is required".to_owned(), + }); + } + (None, Some(_)) => { + return Err(RestAdapterError::InvalidBodyContract { + reason: "single-variant request does not accept a selector".to_owned(), + }); + } + (None, None) => contract + .variants + .as_slice() + .first() + .filter(|_| contract.variants.len() == 1) + .map(|variant| &variant.media_type) + .ok_or_else(|| RestAdapterError::InvalidBodyContract { + reason: "request contract without selector must have one media variant".to_owned(), + })?, + }; + contract + .variants + .iter() + .any(|variant| variant.media_type == *selected) + .then(|| selected.clone()) + .map(Some) + .ok_or_else(|| RestAdapterError::InvalidBodyContract { + reason: "content_type selector is not declared by request contract".to_owned(), + }) +} + +fn json_bytes(body: &Value, limit_bytes: usize) -> Result, RestAdapterError> { + let mut encoded = BoundedBuffer::new(limit_bytes); + let result = serde_json::to_writer(&mut encoded, body); + if encoded.exceeded { + return Err(RestAdapterError::RequestTooLarge { limit_bytes }); + } + result.map_err(|_| RestAdapterError::InvalidBodyContract { + reason: "body cannot be serialized as JSON".to_owned(), + })?; + Ok(encoded.into_bytes()) +} + +fn form_urlencoded(body: &Value, limit_bytes: usize) -> Result, RestAdapterError> { + let object = body + .as_object() + .ok_or_else(|| RestAdapterError::InvalidBodyContract { + reason: "form body must be an object".to_owned(), + })?; + let mut encoded = BoundedBuffer::new(limit_bytes); + let mut first = true; + for (name, value) in object { + match value { + Value::Array(values) => { + for value in values { + append_form_pair(&mut encoded, &mut first, name, &form_scalar(value)?)?; + } + } + value => { + append_form_pair(&mut encoded, &mut first, name, &form_scalar(value)?)?; + } + }; + } + Ok(encoded.into_bytes()) +} + +fn append_form_pair( + encoded: &mut BoundedBuffer, + first: &mut bool, + name: &str, + value: &str, +) -> Result<(), RestAdapterError> { + if !*first { + encoded.append(b"&")?; + } + *first = false; + append_form_component(encoded, name.as_bytes())?; + encoded.append(b"=")?; + append_form_component(encoded, value.as_bytes()) +} + +fn append_form_component( + encoded: &mut BoundedBuffer, + value: &[u8], +) -> Result<(), RestAdapterError> { + const HEX: &[u8; 16] = b"0123456789ABCDEF"; + for byte in value { + match byte { + b'*' | b'-' | b'.' | b'0'..=b'9' | b'A'..=b'Z' | b'_' | b'a'..=b'z' => { + encoded.append(&[*byte])?; + } + b' ' => encoded.append(b"+")?, + _ => encoded.append(&[b'%', HEX[(byte >> 4) as usize], HEX[(byte & 0x0f) as usize]])?, + } + } + Ok(()) +} + +fn form_scalar(value: &Value) -> Result { + match value { + Value::Null => Ok("null".to_owned()), + Value::Bool(value) => Ok(value.to_string()), + Value::Number(value) => Ok(value.to_string()), + Value::String(value) => Ok(value.clone()), + Value::Array(_) | Value::Object(_) => Err(RestAdapterError::InvalidBodyContract { + reason: "form fields must be scalar or arrays of scalars".to_owned(), + }), + } +} + +fn multipart_form( + body: &Value, + source_mime_types: Option<&BTreeMap>>, + max_request_bytes: usize, +) -> Result { + let object = body + .as_object() + .ok_or_else(|| RestAdapterError::InvalidBodyContract { + reason: "multipart body must be an object".to_owned(), + })?; + let mut form = reqwest::multipart::Form::new(); + let mut payload_budget = MultipartPayloadBudget::new(max_request_bytes); + for (name, value) in object { + let values = value + .as_array() + .map_or_else(|| vec![value], |values| values.iter().collect()); + for value in values { + if let Some(file) = value + .as_object() + .filter(|file| file.contains_key("data_base64")) + { + form = form.part( + name.clone(), + multipart_file(name, file, source_mime_types, &mut payload_budget)?, + ); + } else { + let value = form_scalar(value)?; + payload_budget.reserve(value.len())?; + form = form.text(name.clone(), value); + } + } + } + Ok(form) +} + +fn multipart_file( + field_name: &str, + file: &serde_json::Map, + source_mime_types: Option<&BTreeMap>>, + payload_budget: &mut MultipartPayloadBudget, +) -> Result { + if file + .keys() + .any(|key| !matches!(key.as_str(), "data_base64" | "filename" | "content_type")) + { + return Err(RestAdapterError::InvalidBodyContract { + reason: "file object contains unsupported field".to_owned(), + }); + } + let encoded = file + .get("data_base64") + .and_then(Value::as_str) + .ok_or_else(|| RestAdapterError::InvalidBodyContract { + reason: "file data_base64 must be a string".to_owned(), + })?; + if encoded.chars().any(char::is_whitespace) + || encoded.contains('-') + || encoded.contains('_') + || encoded.starts_with("data:") + { + return Err(RestAdapterError::InvalidBodyContract { + reason: "file data_base64 is not standard base64".to_owned(), + }); + } + payload_budget.reserve(decoded_base64_len(encoded)?)?; + let bytes = STANDARD + .decode(encoded) + .map_err(|_| RestAdapterError::InvalidBodyContract { + reason: "file data_base64 is invalid".to_owned(), + })?; + let mut part = reqwest::multipart::Part::bytes(bytes); + if let Some(filename) = file.get("filename") { + let filename = filename + .as_str() + .filter(|value| !value.chars().any(char::is_control)) + .ok_or_else(|| RestAdapterError::InvalidBodyContract { + reason: "filename is invalid".to_owned(), + })?; + part = part.file_name(filename.to_owned()); + } + let allowed_mime_types = source_mime_types.and_then(|fields| fields.get(field_name)); + if let Some(mime) = file.get("content_type") { + let mime = mime + .as_str() + .filter(|value| !value.chars().any(char::is_control)) + .ok_or_else(|| RestAdapterError::InvalidBodyContract { + reason: "content_type is invalid".to_owned(), + })?; + validate_part_mime_type(mime, allowed_mime_types)?; + part = part + .mime_str(mime) + .map_err(|_| RestAdapterError::InvalidBodyContract { + reason: "content_type is invalid".to_owned(), + })?; + } else if let Some(allowed) = allowed_mime_types { + match allowed.as_slice() { + [mime] => { + validate_part_mime_type(mime, Some(allowed))?; + part = part + .mime_str(mime) + .map_err(|_| RestAdapterError::InvalidBodyContract { + reason: "source content_type is invalid".to_owned(), + })?; + } + [] => {} + _ => { + return Err(RestAdapterError::InvalidBodyContract { + reason: "content_type is required for this file field".to_owned(), + }); + } + } + } else { + part = part.mime_str("application/octet-stream").map_err(|_| { + RestAdapterError::InvalidBodyContract { + reason: "default content_type is invalid".to_owned(), + } + })?; + } + Ok(part) +} + +fn decoded_base64_len(encoded: &str) -> Result { + let padding = if encoded.ends_with("==") { + 2 + } else if encoded.ends_with('=') { + 1 + } else { + 0 + }; + encoded + .len() + .checked_div(4) + .and_then(|groups| groups.checked_mul(3)) + .and_then(|bytes| bytes.checked_sub(padding)) + .ok_or_else(|| RestAdapterError::InvalidBodyContract { + reason: "file data_base64 is invalid".to_owned(), + }) +} + +struct MultipartPayloadBudget { + bytes: usize, + limit_bytes: usize, +} + +impl MultipartPayloadBudget { + fn new(limit_bytes: usize) -> Self { + Self { + bytes: 0, + limit_bytes, + } + } + + fn reserve(&mut self, bytes: usize) -> Result<(), RestAdapterError> { + if self.bytes.saturating_add(bytes) > self.limit_bytes { + return Err(RestAdapterError::RequestTooLarge { + limit_bytes: self.limit_bytes, + }); + } + self.bytes += bytes; + Ok(()) + } +} + +struct BoundedBuffer { + bytes: Vec, + limit_bytes: usize, + exceeded: bool, +} + +impl BoundedBuffer { + fn new(limit_bytes: usize) -> Self { + Self { + bytes: Vec::new(), + limit_bytes, + exceeded: false, + } + } + + fn append(&mut self, bytes: &[u8]) -> Result<(), RestAdapterError> { + if self.bytes.len().saturating_add(bytes.len()) > self.limit_bytes { + self.exceeded = true; + return Err(RestAdapterError::RequestTooLarge { + limit_bytes: self.limit_bytes, + }); + } + self.bytes.extend_from_slice(bytes); + Ok(()) + } + + fn into_bytes(self) -> Vec { + self.bytes + } +} + +impl io::Write for BoundedBuffer { + fn write(&mut self, bytes: &[u8]) -> io::Result { + if self.bytes.len().saturating_add(bytes.len()) > self.limit_bytes { + self.exceeded = true; + return Err(io::Error::other("request body exceeds configured limit")); + } + self.bytes.extend_from_slice(bytes); + Ok(bytes.len()) + } + + fn flush(&mut self) -> io::Result<()> { + Ok(()) + } +} + +fn validate_part_mime_type( + value: &str, + allowed: Option<&Vec>, +) -> Result<(), RestAdapterError> { + let normalized = mime_essence(value).ok_or_else(|| RestAdapterError::InvalidBodyContract { + reason: "content_type is invalid".to_owned(), + })?; + if let Some(allowed) = allowed + && !allowed.iter().any(|candidate| { + mime_essence(candidate) + .map(|candidate| candidate.eq_ignore_ascii_case(normalized)) + .unwrap_or(false) + }) + { + return Err(RestAdapterError::InvalidBodyContract { + reason: "content_type is not allowed by the source contract".to_owned(), + }); + } + Ok(()) +} + +fn mime_essence(value: &str) -> Option<&str> { + let essence = value.split(';').next()?.trim(); + (essence.contains('/') + && !essence.starts_with('/') + && !essence.ends_with('/') + && essence + .chars() + .all(|character| character.is_ascii_graphic() && !character.is_control())) + .then_some(essence) +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::{RestAdapterError, form_urlencoded, multipart_form}; + + #[test] + fn form_and_multipart_reject_invalid_contract_before_dispatch() { + assert_eq!( + String::from_utf8(form_urlencoded(&json!({"tag": ["a", "b"]}), 1024).unwrap()).unwrap(), + "tag=a&tag=b" + ); + for invalid in [ + "not base64!", + "SGVs bG8=", + "SGVsbG8_", + "data:text/plain,SGVsbG8=", + ] { + assert!( + multipart_form( + &json!({"file": {"data_base64": invalid}}), + None, + 4 * 1024 * 1024, + ) + .is_err() + ); + } + assert!( + multipart_form( + &json!({"file": {"data_base64": "SGVsbG8=", "path": "/tmp/secret"}}), + None, + 4 * 1024 * 1024, + ) + .is_err() + ); + } + + #[test] + fn form_encoding_escapes_incrementally_and_respects_the_limit() { + assert_eq!( + String::from_utf8(form_urlencoded(&json!({"sp ace": "a+b&/ёж"}), 1024).unwrap()) + .unwrap(), + "sp+ace=a%2Bb%26%2F%D1%91%D0%B6" + ); + assert!(matches!( + form_urlencoded(&json!({"field": "abcdef"}), 8), + Err(RestAdapterError::RequestTooLarge { limit_bytes: 8 }) + )); + } + + #[test] + fn multipart_payload_limit_counts_multiple_decoded_files() { + assert!(matches!( + multipart_form( + &json!({"files": [{"data_base64": "AA=="}, {"data_base64": "AQ=="}]}), + None, + 1, + ), + Err(RestAdapterError::RequestTooLarge { limit_bytes: 1 }) + )); + } +} diff --git a/crates/crank-adapter-rest/src/client.rs b/crates/crank-adapter-rest/src/client.rs index 274d4c0..89057b3 100644 --- a/crates/crank-adapter-rest/src/client.rs +++ b/crates/crank-adapter-rest/src/client.rs @@ -21,11 +21,14 @@ use reqwest::{ header::{HeaderMap, HeaderName, HeaderValue}, redirect, }; -use serde_json::Value; use tracing::{Instrument, Span}; use tracing_opentelemetry::OpenTelemetrySpanExt; -use crate::{ExternalReferenceFetchError, RestAdapterError, RestRequest, RestResponse}; +use crate::{ + ExternalReferenceFetchError, RestAdapterError, RestRequest, RestResponse, + body::{apply_body, apply_legacy_json_body, selected_request_content_type}, + response::{decode_body, normalize_headers, validate_response_contract}, +}; #[derive(Clone, Debug)] pub struct RestAdapter { @@ -128,7 +131,22 @@ impl RestAdapter { let result = async { let url = build_url(target, request)?; self.policy.validate_url(&url)?; - let mut headers = build_headers(target, request)?; + let mut header_request = request.clone(); + let cookie_header = extract_mapped_cookies(&mut header_request.headers)?; + let mut headers = build_headers(target, &header_request)?; + if let Some(cookie_header) = cookie_header { + if headers.contains_key("cookie") { + return Err(RestAdapterError::InvalidBodyContract { + reason: "mapped cookie conflicts with an existing cookie header".to_owned(), + }); + } + let value = HeaderValue::try_from(cookie_header).map_err(|_| { + RestAdapterError::InvalidBodyContract { + reason: "cookie parameter is invalid".to_owned(), + } + })?; + headers.insert("cookie", value); + } if let Some(context) = trusted_context { for (name, value) in context.outbound_headers() { let (Ok(name), Ok(value)) = @@ -152,14 +170,55 @@ impl RestAdapter { .map_err(|details| RestAdapterError::InvalidConfiguration { details: details.to_string(), })?; + if request.body.is_none() + && (request.body_content_type.is_some() + || target + .request_contract + .as_ref() + .is_some_and(|contract| contract.body_required)) + { + return Err(RestAdapterError::InvalidBodyContract { + reason: "request body contract requires a body".to_owned(), + }); + } + + let typed_content_type = if request.body.is_some() && target.request_contract.is_some() + { + selected_request_content_type(target, request)? + } else { + if request.body.is_some() && request.body_content_type.is_some() { + selected_request_content_type(target, request)?; + } + None + }; + if typed_content_type.is_some() { + headers.remove("content-type"); + } + let legacy_has_content_type = headers.contains_key("content-type"); + let mut builder = client .request(to_reqwest_method(target.method), url) .headers(headers) .timeout(Duration::from_millis(request.timeout_ms)); if let Some(body) = &request.body { - enforce_request_body_limit(body, self.policy.max_request_bytes)?; - builder = builder.json(body); + if let Some(content_type) = typed_content_type { + builder = apply_body( + builder, + body, + &content_type, + target.multipart_field_mime_types.get(&content_type), + self.policy.max_request_bytes, + ) + .await?; + } else { + builder = apply_legacy_json_body( + builder, + body, + legacy_has_content_type, + self.policy.max_request_bytes, + )?; + } } if let Some(context) = trusted_context { @@ -171,7 +230,8 @@ impl RestAdapter { if status.is_redirection() { return Err(RestAdapterError::RedirectNotAllowed); } - let body = decode_body(response, self.policy.max_response_bytes).await?; + let (body, has_body, valid_json) = + decode_body(response, self.policy.max_response_bytes).await?; if !status.is_success() { return Err(RestAdapterError::UnexpectedStatus { @@ -179,6 +239,7 @@ impl RestAdapter { body, }); } + validate_response_contract(target, status.as_u16(), &headers, has_body, valid_json)?; Ok(RestResponse { status_code: status.as_u16(), @@ -199,6 +260,43 @@ impl RestAdapter { } } +fn extract_mapped_cookies( + headers: &mut BTreeMap, +) -> Result, RestAdapterError> { + let internal = headers + .keys() + .filter(|name| name.starts_with("x-crank-internal-cookie-")) + .cloned() + .collect::>(); + if internal.is_empty() { + return Ok(None); + } + let mut cookies = Vec::with_capacity(internal.len()); + for key in internal { + let value = headers.remove(&key).unwrap_or_default(); + let (name, value) = + value + .split_once('\t') + .ok_or_else(|| RestAdapterError::InvalidBodyContract { + reason: "cookie parameter is malformed".to_owned(), + })?; + if name.is_empty() + || name + .chars() + .any(|character| character.is_control() || matches!(character, ';' | '=')) + || value + .chars() + .any(|character| character.is_control() || character == ';') + { + return Err(RestAdapterError::InvalidBodyContract { + reason: "cookie parameter is invalid".to_owned(), + }); + } + cookies.push(format!("{name}={value}")); + } + Ok(Some(cookies.join("; "))) +} + impl ExternalReferenceFetcher { pub fn try_new( policy: OutboundHttpPolicy, @@ -363,12 +461,15 @@ fn upstream_outcome(error: &RestAdapterError) -> UpstreamOutcome { UpstreamOutcome::Rejected } RestAdapterError::WindowExpired => UpstreamOutcome::WindowExpired, - RestAdapterError::InvalidSseEvent => UpstreamOutcome::InvalidResponse, + RestAdapterError::InvalidSseEvent | RestAdapterError::InvalidResponseContract { .. } => { + UpstreamOutcome::InvalidResponse + } RestAdapterError::InvalidBaseUrl { .. } | RestAdapterError::InvalidPathParameter { .. } | RestAdapterError::InvalidQueryParameter { .. } | RestAdapterError::InvalidHeaderName { .. } - | RestAdapterError::InvalidHeaderValue { .. } => UpstreamOutcome::InvalidRequest, + | RestAdapterError::InvalidHeaderValue { .. } + | RestAdapterError::InvalidBodyContract { .. } => UpstreamOutcome::InvalidRequest, RestAdapterError::InvalidConfiguration { .. } => UpstreamOutcome::Configuration, } } @@ -494,7 +595,7 @@ impl OutboundHttpPolicy { .any(|pattern| host_matches(pattern, &host)) } - fn is_denied_ip(&self, address: IpAddr) -> bool { + pub(crate) fn is_denied_ip(&self, address: IpAddr) -> bool { ip_match_hosts(address).iter().any(|host| { self.denied_hosts .iter() @@ -502,7 +603,7 @@ impl OutboundHttpPolicy { }) } - fn is_explicitly_allowed(&self, host: &str) -> bool { + pub(crate) fn is_explicitly_allowed(&self, host: &str) -> bool { let host = normalize_host(host); self.allowed_hosts .iter() @@ -601,7 +702,7 @@ fn is_public_ip(address: IpAddr) -> bool { } } -fn ip_match_hosts(address: IpAddr) -> Vec { +pub(crate) fn ip_match_hosts(address: IpAddr) -> Vec { match address { IpAddr::V4(address) => vec![address.to_string()], IpAddr::V6(address) => { @@ -667,11 +768,26 @@ fn build_url(target: &RestTarget, request: &RestRequest) -> Result { } } -async fn decode_body( - response: reqwest::Response, - max_response_bytes: usize, -) -> Result { - if response - .content_length() - .is_some_and(|length| length > max_response_bytes as u64) - { - return Err(RestAdapterError::ResponseTooLarge { - limit_bytes: max_response_bytes, - }); - } - let mut stream = response.bytes_stream(); - let mut bytes = Vec::new(); - while let Some(chunk) = stream.next().await { - let chunk = chunk?; - if bytes.len().saturating_add(chunk.len()) > max_response_bytes { - return Err(RestAdapterError::ResponseTooLarge { - limit_bytes: max_response_bytes, - }); - } - bytes.extend_from_slice(&chunk); - } - - if bytes.is_empty() { - return Ok(Value::Null); - } - - match serde_json::from_slice::(&bytes) { - Ok(value) => Ok(value), - Err(_) => Ok(Value::String( - String::from_utf8_lossy(&bytes).trim().to_owned(), - )), - } -} - -fn enforce_request_body_limit( - body: &Value, - max_request_bytes: usize, -) -> Result<(), RestAdapterError> { - if max_request_bytes == 0 { - return Err(RestAdapterError::InvalidConfiguration { - details: "outbound request limit must be greater than zero".to_owned(), - }); - } - let mut writer = LimitWriter::new(max_request_bytes); - let result = serde_json::to_writer(&mut writer, body); - if writer.exceeded { - return Err(RestAdapterError::RequestTooLarge { - limit_bytes: max_request_bytes, - }); - } - result.map_err(|_| RestAdapterError::InvalidHeaderValue { - header: "body".to_owned(), - })?; - Ok(()) -} - -struct LimitWriter { - written: usize, - limit: usize, - exceeded: bool, -} - -impl LimitWriter { - fn new(limit: usize) -> Self { - Self { - written: 0, - limit, - exceeded: false, - } - } -} - -impl io::Write for LimitWriter { - fn write(&mut self, buf: &[u8]) -> io::Result { - if self.written.saturating_add(buf.len()) > self.limit { - self.exceeded = true; - return Err(io::Error::other("request body exceeds configured limit")); - } - self.written += buf.len(); - Ok(buf.len()) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -fn normalize_headers(headers: &HeaderMap) -> BTreeMap { - headers - .iter() - .filter_map(|(name, value)| { - value - .to_str() - .ok() - .map(|value| (name.as_str().to_owned(), value.to_owned())) - }) - .collect() -} - fn to_reqwest_method(method: HttpMethod) -> reqwest::Method { match method { HttpMethod::Get => reqwest::Method::GET, @@ -950,40 +965,7 @@ fn to_reqwest_method(method: HttpMethod) -> reqwest::Method { HttpMethod::Put => reqwest::Method::PUT, HttpMethod::Patch => reqwest::Method::PATCH, HttpMethod::Delete => reqwest::Method::DELETE, - } -} - -#[cfg(test)] -mod tests { - use super::{OutboundHttpPolicy, ip_match_hosts}; - use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; - - #[test] - fn denied_resolved_ip_overrides_explicitly_allowed_hostname() { - let policy = OutboundHttpPolicy::try_new_with_limits( - vec!["api.example.test".to_owned()], - vec!["169.254.169.254".to_owned()], - 4 * 1024 * 1024, - 4 * 1024 * 1024, - ) - .unwrap(); - - assert!(policy.is_explicitly_allowed("api.example.test")); - assert!(policy.is_denied_ip(IpAddr::V4(Ipv4Addr::new(169, 254, 169, 254)))); - } - - #[test] - fn denied_resolved_ip_checks_ipv4_mapped_ipv6_alias() { - let policy = OutboundHttpPolicy::try_new_with_limits( - vec!["api.example.test".to_owned()], - vec!["127.0.0.1".to_owned()], - 4 * 1024 * 1024, - 4 * 1024 * 1024, - ) - .unwrap(); - let mapped = IpAddr::V6(Ipv6Addr::from(0xffff_7f00_0001u128)); - - assert!(ip_match_hosts(mapped).contains(&"127.0.0.1".to_owned())); - assert!(policy.is_denied_ip(mapped)); + HttpMethod::Head => reqwest::Method::HEAD, + HttpMethod::Options => reqwest::Method::OPTIONS, } } diff --git a/crates/crank-adapter-rest/src/client_tests.rs b/crates/crank-adapter-rest/src/client_tests.rs new file mode 100644 index 0000000..694cec6 --- /dev/null +++ b/crates/crank-adapter-rest/src/client_tests.rs @@ -0,0 +1,32 @@ +use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; + +use crate::client::{OutboundHttpPolicy, ip_match_hosts}; + +#[test] +fn denied_resolved_ip_overrides_explicitly_allowed_hostname() { + let policy = OutboundHttpPolicy::try_new_with_limits( + vec!["api.example.test".to_owned()], + vec!["169.254.169.254".to_owned()], + 4 * 1024 * 1024, + 4 * 1024 * 1024, + ) + .unwrap(); + + assert!(policy.is_explicitly_allowed("api.example.test")); + assert!(policy.is_denied_ip(IpAddr::V4(Ipv4Addr::new(169, 254, 169, 254)))); +} + +#[test] +fn denied_resolved_ip_checks_ipv4_mapped_ipv6_alias() { + let policy = OutboundHttpPolicy::try_new_with_limits( + vec!["api.example.test".to_owned()], + vec!["127.0.0.1".to_owned()], + 4 * 1024 * 1024, + 4 * 1024 * 1024, + ) + .unwrap(); + let mapped = IpAddr::V6(Ipv6Addr::from(0xffff_7f00_0001u128)); + + assert!(ip_match_hosts(mapped).contains(&"127.0.0.1".to_owned())); + assert!(policy.is_denied_ip(mapped)); +} diff --git a/crates/crank-adapter-rest/src/error.rs b/crates/crank-adapter-rest/src/error.rs index 3c739f4..71cb0b6 100644 --- a/crates/crank-adapter-rest/src/error.rs +++ b/crates/crank-adapter-rest/src/error.rs @@ -33,6 +33,8 @@ pub enum RestAdapterError { InvalidHeaderName { header: String }, #[error("invalid header value for {header}")] InvalidHeaderValue { header: String }, + #[error("invalid REST request body contract")] + InvalidBodyContract { reason: String }, #[error("outbound target is not allowed")] TargetNotAllowed { target: String }, #[error("outbound redirects are not allowed")] @@ -49,6 +51,8 @@ pub enum RestAdapterError { WindowExpired, #[error("rest endpoint returned status {status}")] UnexpectedStatus { status: u16, body: Value }, + #[error("rest endpoint response does not match the Operation contract: {reason}")] + InvalidResponseContract { reason: String }, #[error("sse stream produced malformed event payload")] InvalidSseEvent, } diff --git a/crates/crank-adapter-rest/src/lib.rs b/crates/crank-adapter-rest/src/lib.rs index e026041..0a493f4 100644 --- a/crates/crank-adapter-rest/src/lib.rs +++ b/crates/crank-adapter-rest/src/lib.rs @@ -1,6 +1,10 @@ +mod body; mod client; +#[cfg(test)] +mod client_tests; mod error; mod model; +mod response; use async_trait::async_trait; use crank_core::{ @@ -35,6 +39,7 @@ impl ProtocolAdapter for RestAdapter { headers: prepared.headers.clone(), trusted_header_names: prepared.trusted_header_names.clone(), body: prepared.body.clone(), + body_content_type: prepared.body_content_type.clone(), timeout_ms: prepared.timeout_ms, }; let response = self.execute_with_context(target, &request, context).await?; @@ -62,7 +67,8 @@ impl From for ProtocolAdapterError { RestAdapterError::InvalidPathParameter { .. } | RestAdapterError::InvalidQueryParameter { .. } | RestAdapterError::InvalidHeaderName { .. } - | RestAdapterError::InvalidHeaderValue { .. } => Self::InvalidPreparedRequest, + | RestAdapterError::InvalidHeaderValue { .. } + | RestAdapterError::InvalidBodyContract { .. } => Self::InvalidPreparedRequest, RestAdapterError::RedirectNotAllowed => Self::TargetRejected, RestAdapterError::TargetNotAllowed { .. } => Self::TargetRejected, RestAdapterError::RequestTooLarge { .. } => Self::RequestTooLarge, @@ -93,6 +99,9 @@ impl From for ProtocolAdapterError { RestAdapterError::InvalidSseEvent => Self::InvalidResponse { dispatch: DispatchEvidence::MayHaveDispatched, }, + RestAdapterError::InvalidResponseContract { .. } => Self::InvalidResponse { + dispatch: DispatchEvidence::MayHaveDispatched, + }, } } } diff --git a/crates/crank-adapter-rest/src/model.rs b/crates/crank-adapter-rest/src/model.rs index 2dc57f3..f5b9b62 100644 --- a/crates/crank-adapter-rest/src/model.rs +++ b/crates/crank-adapter-rest/src/model.rs @@ -15,6 +15,8 @@ pub struct RestRequest { pub trusted_header_names: BTreeSet, #[serde(skip_serializing_if = "Option::is_none")] pub body: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub body_content_type: Option, pub timeout_ms: u64, } diff --git a/crates/crank-adapter-rest/src/response.rs b/crates/crank-adapter-rest/src/response.rs new file mode 100644 index 0000000..e932b05 --- /dev/null +++ b/crates/crank-adapter-rest/src/response.rs @@ -0,0 +1,127 @@ +use std::collections::BTreeMap; + +use crank_core::RestTarget; +use futures_util::StreamExt; +use reqwest::header::HeaderMap; +use serde_json::Value; + +use crate::RestAdapterError; + +pub(crate) async fn decode_body( + response: reqwest::Response, + max_response_bytes: usize, +) -> Result<(Value, bool, bool), RestAdapterError> { + if response + .content_length() + .is_some_and(|length| length > max_response_bytes as u64) + { + return Err(RestAdapterError::ResponseTooLarge { + limit_bytes: max_response_bytes, + }); + } + let mut stream = response.bytes_stream(); + let mut bytes = Vec::new(); + while let Some(chunk) = stream.next().await { + let chunk = chunk?; + if bytes.len().saturating_add(chunk.len()) > max_response_bytes { + return Err(RestAdapterError::ResponseTooLarge { + limit_bytes: max_response_bytes, + }); + } + bytes.extend_from_slice(&chunk); + } + + if bytes.is_empty() { + return Ok((Value::Null, false, false)); + } + + match serde_json::from_slice::(&bytes) { + Ok(value) => Ok((value, true, true)), + Err(_) => Ok(( + Value::String(String::from_utf8_lossy(&bytes).trim().to_owned()), + true, + false, + )), + } +} + +pub(crate) fn validate_response_contract( + target: &RestTarget, + status_code: u16, + headers: &BTreeMap, + has_body: bool, + valid_json: bool, +) -> Result<(), RestAdapterError> { + if target.response_contract.is_empty() { + return Ok(()); + } + + let matching_status = target + .response_contract + .iter() + .filter(|descriptor| descriptor.status_code == status_code) + .collect::>(); + if matching_status.is_empty() { + return Err(RestAdapterError::UnexpectedStatus { + status: status_code, + body: Value::Null, + }); + } + + if !has_body { + return matching_status + .iter() + .any(|descriptor| descriptor.media_type.is_none()) + .then_some(()) + .ok_or_else(|| RestAdapterError::InvalidResponseContract { + reason: format!("status {status_code} requires a response body"), + }); + } + + let content_type = headers + .get("content-type") + .map(|value| normalized_media_type(value)); + let Some(content_type) = content_type else { + return Err(RestAdapterError::InvalidResponseContract { + reason: format!("status {status_code} has a body without a content-type"), + }); + }; + if matching_status.iter().any(|descriptor| { + descriptor + .media_type + .as_deref() + .is_some_and(|expected| normalized_media_type(expected) == content_type) + }) { + if (content_type == "application/json" || content_type.ends_with("+json")) && !valid_json { + return Err(RestAdapterError::InvalidResponseContract { + reason: format!("status {status_code} has invalid JSON response body"), + }); + } + return Ok(()); + } + + Err(RestAdapterError::InvalidResponseContract { + reason: format!("status {status_code} with content-type {content_type} is not declared"), + }) +} + +fn normalized_media_type(value: &str) -> String { + value + .split(';') + .next() + .unwrap_or_default() + .trim() + .to_ascii_lowercase() +} + +pub(crate) fn normalize_headers(headers: &HeaderMap) -> BTreeMap { + headers + .iter() + .filter_map(|(name, value)| { + value + .to_str() + .ok() + .map(|value| (name.as_str().to_owned(), value.to_owned())) + }) + .collect() +} diff --git a/crates/crank-adapter-rest/tests/integration.rs b/crates/crank-adapter-rest/tests/integration.rs index 1c95304..145f676 100644 --- a/crates/crank-adapter-rest/tests/integration.rs +++ b/crates/crank-adapter-rest/tests/integration.rs @@ -1,5 +1,6 @@ mod integration { mod client; mod external_reference_fetcher; + mod multipart; mod outbound_security; } diff --git a/crates/crank-adapter-rest/tests/integration/client.rs b/crates/crank-adapter-rest/tests/integration/client.rs index 82d2553..4d8f962 100644 --- a/crates/crank-adapter-rest/tests/integration/client.rs +++ b/crates/crank-adapter-rest/tests/integration/client.rs @@ -10,7 +10,7 @@ use axum::{ use crank_adapter_rest::{OutboundHttpPolicy, RestAdapter, RestAdapterError, RestRequest}; use crank_core::{ DispatchEvidence, HttpMethod, PreparedRequest, ProtocolAdapter, ProtocolAdapterError, - RestTarget, RuntimeRequestContext, Target, + RestResponseDescriptor, RestTarget, RuntimeRequestContext, Target, }; use opentelemetry::{ global, @@ -32,6 +32,9 @@ async fn executes_rest_request_and_normalizes_json_response() { method: HttpMethod::Post, path_template: "/users/{user_id}".to_owned(), static_headers: BTreeMap::from([("x-static".to_owned(), "static".to_owned())]), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }; let request = RestRequest { path_params: BTreeMap::from([("user_id".to_owned(), "42".to_owned())]), @@ -57,6 +60,29 @@ async fn executes_rest_request_and_normalizes_json_response() { ); } +#[tokio::test] +async fn legacy_json_field_named_content_type_is_sent_unchanged() { + let base_url = spawn_test_server().await; + let target = RestTarget { + base_url, + method: HttpMethod::Post, + path_template: "/users/{user_id}".to_owned(), + static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), + }; + let request = RestRequest { + path_params: BTreeMap::from([("user_id".to_owned(), "42".to_owned())]), + body: Some(json!({"__content_type": "legacy-value", "name": "Ada"})), + timeout_ms: 1_000, + ..RestRequest::default() + }; + + let response = test_adapter().execute(&target, &request).await.unwrap(); + assert_eq!(response.body["payload"]["__content_type"], "legacy-value"); +} + #[tokio::test] async fn prepared_auth_profile_header_is_allowed_after_runtime_resolution() { let base_url = spawn_test_server().await; @@ -66,6 +92,9 @@ async fn prepared_auth_profile_header_is_allowed_after_runtime_resolution() { method: HttpMethod::Post, path_template: "/users/{user_id}".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }; let request = RestRequest { path_params: BTreeMap::from([("user_id".to_owned(), "42".to_owned())]), @@ -76,6 +105,7 @@ async fn prepared_auth_profile_header_is_allowed_after_runtime_resolution() { )]), trusted_header_names: BTreeSet::from(["authorization".to_owned()]), body: Some(json!({ "name": "Ada" })), + body_content_type: None, timeout_ms: 1_000, }; @@ -96,6 +126,9 @@ async fn untrusted_prepared_credential_header_is_rejected_before_dispatch() { method: HttpMethod::Post, path_template: "/users/{user_id}".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }; let request = RestRequest { path_params: BTreeMap::from([("user_id".to_owned(), "42".to_owned())]), @@ -144,6 +177,9 @@ async fn protocol_context_overrides_mapped_correlation_headers() { ), ("x-trace-id".to_owned(), "static-trace".to_owned()), ]), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }); let prepared = PreparedRequest { path_params: BTreeMap::from([("user_id".to_owned(), "42".to_owned())]), @@ -197,6 +233,9 @@ async fn current_trace_context_overrides_mapped_traceparent() { method: HttpMethod::Post, path_template: "/users/{user_id}".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }; let request = RestRequest { path_params: BTreeMap::from([("user_id".to_owned(), "42".to_owned())]), @@ -238,6 +277,9 @@ async fn user_configured_propagation_headers_are_removed_without_trusted_context ("tracestate".to_owned(), "vendor=value".to_owned()), ("baggage".to_owned(), "secret=must-not-leave".to_owned()), ]), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }; let request = RestRequest { path_params: BTreeMap::from([("user_id".to_owned(), "42".to_owned())]), @@ -264,6 +306,9 @@ async fn returns_unexpected_status_with_normalized_body() { method: HttpMethod::Get, path_template: "/fail".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }; let request = RestRequest { path_params: BTreeMap::new(), @@ -292,6 +337,116 @@ async fn returns_unexpected_status_with_normalized_body() { )); } +#[tokio::test] +async fn enforces_declared_success_status_and_media_type() { + let base_url = spawn_test_server().await; + let request = RestRequest { + path_params: BTreeMap::from([("user_id".to_owned(), "42".to_owned())]), + body: Some(json!({"name": "Ada"})), + timeout_ms: 1_000, + ..RestRequest::default() + }; + let target = RestTarget { + base_url: base_url.clone(), + method: HttpMethod::Post, + path_template: "/users/{user_id}".to_owned(), + static_headers: BTreeMap::new(), + request_contract: None, + response_contract: vec![RestResponseDescriptor { + status_code: 200, + media_type: Some("application/json".to_owned()), + schema_variant: 0, + }], + multipart_field_mime_types: BTreeMap::new(), + }; + assert!(test_adapter().execute(&target, &request).await.is_ok()); + + let unexpected_status = RestTarget { + response_contract: vec![RestResponseDescriptor { + status_code: 201, + media_type: Some("application/json".to_owned()), + schema_variant: 0, + }], + ..target.clone() + }; + assert!(matches!( + test_adapter().execute(&unexpected_status, &request).await, + Err(RestAdapterError::UnexpectedStatus { status: 200, .. }) + )); + + let unexpected_media_type = RestTarget { + response_contract: vec![RestResponseDescriptor { + status_code: 200, + media_type: Some("application/problem+json".to_owned()), + schema_variant: 0, + }], + ..target + }; + assert!(matches!( + test_adapter() + .execute(&unexpected_media_type, &request) + .await, + Err(RestAdapterError::InvalidResponseContract { .. }) + )); +} + +#[tokio::test] +async fn accepts_declared_no_content_response() { + let base_url = spawn_test_server().await; + let target = RestTarget { + base_url, + method: HttpMethod::Get, + path_template: "/no-content".to_owned(), + static_headers: BTreeMap::new(), + request_contract: None, + response_contract: vec![RestResponseDescriptor { + status_code: 204, + media_type: None, + schema_variant: 0, + }], + multipart_field_mime_types: BTreeMap::new(), + }; + + let response = test_adapter() + .execute(&target, &empty_request()) + .await + .unwrap(); + assert_eq!(response.status_code, 204); + assert_eq!(response.body, Value::Null); +} + +#[tokio::test] +async fn typed_json_response_rejects_invalid_json_while_legacy_keeps_text_fallback() { + let base_url = spawn_test_server().await; + let typed = RestTarget { + base_url: base_url.clone(), + method: HttpMethod::Get, + path_template: "/invalid-json".to_owned(), + static_headers: BTreeMap::new(), + request_contract: None, + response_contract: vec![RestResponseDescriptor { + status_code: 200, + media_type: Some("application/json".to_owned()), + schema_variant: 0, + }], + multipart_field_mime_types: BTreeMap::new(), + }; + assert!(matches!( + test_adapter().execute(&typed, &empty_request()).await, + Err(RestAdapterError::InvalidResponseContract { .. }) + )); + + let legacy = RestTarget { + response_contract: Vec::new(), + ..typed + }; + let response = test_adapter() + .execute(&legacy, &empty_request()) + .await + .unwrap(); + assert_eq!(response.body, "not-json"); +} + #[tokio::test] async fn connect_failure_is_known_not_dispatched() { let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); @@ -302,6 +457,9 @@ async fn connect_failure_is_known_not_dispatched() { method: HttpMethod::Post, path_template: "/write".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }; let request = RestRequest { path_params: BTreeMap::new(), @@ -349,6 +507,9 @@ async fn does_not_follow_redirects() { method: HttpMethod::Get, path_template: "/redirect".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }; let error = adapter @@ -370,6 +531,9 @@ async fn rejects_responses_over_the_configured_limit() { method: HttpMethod::Get, path_template: "/large".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }; let error = adapter @@ -402,6 +566,11 @@ async fn spawn_test_server() -> String { let app = Router::new() .route("/users/{user_id}", post(create_user)) .route("/fail", get(fail)) + .route("/no-content", get(|| async { StatusCode::NO_CONTENT })) + .route( + "/invalid-json", + get(|| async { ([("content-type", "application/json")], "not-json") }), + ) .route("/redirect", get(|| async { Redirect::to("/large") })) .route( "/large", diff --git a/crates/crank-adapter-rest/tests/integration/multipart.rs b/crates/crank-adapter-rest/tests/integration/multipart.rs new file mode 100644 index 0000000..e104351 --- /dev/null +++ b/crates/crank-adapter-rest/tests/integration/multipart.rs @@ -0,0 +1,554 @@ +use std::{ + collections::{BTreeMap, BTreeSet}, + sync::{Arc, Mutex}, +}; + +use axum::{ + Json, Router, + body::Bytes, + extract::{Multipart, State}, + http::{HeaderMap, StatusCode}, + routing::{get, post}, +}; +use crank_adapter_rest::{OutboundHttpPolicy, RestAdapter, RestAdapterError, RestRequest}; +use crank_core::{ + HttpMethod, RestRequestContract, RestRequestContractVersion, RestRequestDescriptor, + RestResponseDescriptor, RestTarget, +}; +use serde_json::{Value, json}; +use tokio::net::TcpListener; + +#[derive(Clone, Debug, PartialEq, Eq)] +struct MultipartPart { + name: String, + filename: Option, + content_type: Option, + bytes: Vec, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +struct WireRequest { + content_types: Vec, + cookie: Option, + body: Vec, +} + +#[derive(Default)] +struct CaptureState { + multipart: Mutex>, + wire: Mutex>, +} + +#[tokio::test] +async fn multipart_decodes_base64_and_preserves_filename_and_mime() { + let (base_url, state) = spawn_capture_server().await; + let target = target(&base_url, "/multipart"); + let request = RestRequest { + body: Some(json!({ + "title": "report", + "file": { + "data_base64": "AAEC/w==", + "filename": "report.bin", + "content_type": "application/octet-stream" + } + })), + body_content_type: Some("multipart/form-data".to_owned()), + timeout_ms: 1_000, + ..RestRequest::default() + }; + + let response = test_adapter().execute(&target, &request).await.unwrap(); + + assert_eq!(response.status_code, 200); + let parts = state.multipart.lock().unwrap().clone(); + assert_eq!(parts.len(), 2); + let file = parts.iter().find(|part| part.name == "file").unwrap(); + assert_eq!(file.filename.as_deref(), Some("report.bin")); + assert_eq!( + file.content_type.as_deref(), + Some("application/octet-stream") + ); + assert_eq!(file.bytes, vec![0, 1, 2, 255]); + let title = parts.iter().find(|part| part.name == "title").unwrap(); + assert_eq!(title.filename, None); + assert_eq!(title.content_type, None); + assert_eq!(title.bytes, b"report"); +} + +#[tokio::test] +async fn typed_contract_preserves_server_base_path_on_wire() { + let (base_url, state) = spawn_capture_server().await; + let target = target(&format!("{base_url}/api/v2"), "/multipart"); + let request = RestRequest { + body: Some(json!({"file": {"data_base64": ""}})), + body_content_type: Some("multipart/form-data".to_owned()), + timeout_ms: 1_000, + ..RestRequest::default() + }; + + test_adapter().execute(&target, &request).await.unwrap(); + + assert_eq!(state.multipart.lock().unwrap().len(), 1); +} + +#[tokio::test] +async fn typed_response_only_contract_preserves_server_base_path_on_wire() { + let (base_url, _) = spawn_capture_server().await; + let target = RestTarget { + base_url: format!("{base_url}/api/v2"), + method: HttpMethod::Head, + path_template: "/no-content".to_owned(), + static_headers: BTreeMap::new(), + request_contract: None, + response_contract: vec![RestResponseDescriptor { + status_code: 204, + media_type: None, + schema_variant: 0, + }], + multipart_field_mime_types: BTreeMap::new(), + }; + let response = test_adapter() + .execute( + &target, + &RestRequest { + timeout_ms: 1_000, + ..RestRequest::default() + }, + ) + .await + .unwrap(); + + assert_eq!(response.status_code, 204); +} + +#[tokio::test] +async fn invalid_multipart_base64_is_rejected_before_dispatch() { + let (base_url, state) = spawn_capture_server().await; + let target = target(&base_url, "/multipart"); + let request = RestRequest { + body: Some(json!({ + "file": { "data_base64": "definitely not base64" } + })), + body_content_type: Some("multipart/form-data".to_owned()), + timeout_ms: 1_000, + ..RestRequest::default() + }; + + let error = test_adapter().execute(&target, &request).await.unwrap_err(); + + assert!(matches!( + error, + RestAdapterError::InvalidBodyContract { .. } + )); + assert!(state.multipart.lock().unwrap().is_empty()); + assert!(state.wire.lock().unwrap().is_empty()); +} + +#[tokio::test] +async fn multipart_uses_source_mime_default_or_requires_a_choice() { + let (base_url, state) = spawn_capture_server().await; + let adapter = test_adapter(); + let single = target_with_mime(&base_url, vec!["image/png"]); + adapter + .execute( + &single, + &RestRequest { + body: Some(json!({ + "file": { "data_base64": "" } + })), + body_content_type: Some("multipart/form-data".to_owned()), + timeout_ms: 1_000, + ..RestRequest::default() + }, + ) + .await + .unwrap(); + let default = target(&base_url, "/multipart"); + adapter + .execute( + &default, + &RestRequest { + body: Some(json!({ + "file": { "data_base64": "" } + })), + body_content_type: Some("multipart/form-data".to_owned()), + timeout_ms: 1_000, + ..RestRequest::default() + }, + ) + .await + .unwrap(); + + let parts = state.multipart.lock().unwrap().clone(); + assert_eq!(parts[0].bytes, Vec::::new()); + assert_eq!(parts[0].filename, None); + assert_eq!(parts[0].content_type.as_deref(), Some("image/png")); + assert_eq!( + parts[1].content_type.as_deref(), + Some("application/octet-stream") + ); + + let multiple = target_with_mime(&base_url, vec!["image/png", "image/jpeg"]); + let error = adapter + .execute( + &multiple, + &RestRequest { + body: Some(json!({ + "file": { "data_base64": "AA==" } + })), + body_content_type: Some("multipart/form-data".to_owned()), + timeout_ms: 1_000, + ..RestRequest::default() + }, + ) + .await + .unwrap_err(); + assert!(matches!( + error, + RestAdapterError::InvalidBodyContract { .. } + )); + + let mismatch = target_with_mime(&base_url, vec!["image/png"]); + let error = adapter + .execute( + &mismatch, + &RestRequest { + body: Some(json!({ + "file": { "data_base64": "AA==", "content_type": "image/jpeg" } + })), + body_content_type: Some("multipart/form-data".to_owned()), + timeout_ms: 1_000, + ..RestRequest::default() + }, + ) + .await + .unwrap_err(); + assert!(matches!( + error, + RestAdapterError::InvalidBodyContract { .. } + )); + assert_eq!(state.multipart.lock().unwrap().len(), 2); +} + +#[tokio::test] +async fn multipart_sends_each_file_array_item_as_decoded_part() { + let (base_url, state) = spawn_capture_server().await; + test_adapter() + .execute( + &target(&base_url, "/multipart"), + &RestRequest { + body: Some(json!({ + "files": [ + {"data_base64": ""}, + {"data_base64": "SGk=", "filename": "two.txt"} + ] + })), + body_content_type: Some("multipart/form-data".to_owned()), + timeout_ms: 1_000, + ..RestRequest::default() + }, + ) + .await + .unwrap(); + let parts = state.multipart.lock().unwrap().clone(); + assert_eq!(parts.len(), 2); + assert_eq!(parts[0].name, "files"); + assert_eq!(parts[0].bytes, Vec::::new()); + assert_eq!(parts[1].bytes, b"Hi"); + assert_eq!(parts[1].filename.as_deref(), Some("two.txt")); +} + +#[tokio::test] +async fn multipart_limit_includes_serialized_overhead_before_dispatch() { + let (base_url, state) = spawn_capture_server().await; + let error = RestAdapter::with_policy( + OutboundHttpPolicy::allowing_hosts(["127.0.0.1"]).with_max_request_bytes(32), + ) + .execute( + &target(&base_url, "/multipart"), + &RestRequest { + body: Some(json!({ + "file": { "data_base64": "AA==" } + })), + body_content_type: Some("multipart/form-data".to_owned()), + timeout_ms: 1_000, + ..RestRequest::default() + }, + ) + .await + .unwrap_err(); + assert!(matches!( + error, + RestAdapterError::RequestTooLarge { limit_bytes: 32 } + )); + assert!(state.multipart.lock().unwrap().is_empty()); +} + +#[tokio::test] +async fn content_type_selector_controls_json_and_form_wire_serialization() { + let (base_url, state) = spawn_capture_server().await; + let adapter = test_adapter(); + + let json_target = target(&base_url, "/wire"); + adapter + .execute( + &json_target, + &RestRequest { + body: Some(json!({ + "name": "Ada", + "enabled": true + })), + body_content_type: Some("application/json".to_owned()), + timeout_ms: 1_000, + ..RestRequest::default() + }, + ) + .await + .unwrap(); + + let form_target = target(&base_url, "/wire"); + adapter + .execute( + &form_target, + &RestRequest { + body: Some(json!({ + "name": "Ada Lovelace", + "tag": ["math", "programming"] + })), + body_content_type: Some("application/x-www-form-urlencoded".to_owned()), + timeout_ms: 1_000, + ..RestRequest::default() + }, + ) + .await + .unwrap(); + + adapter + .execute( + &target(&base_url, "/wire"), + &RestRequest { + body: Some(json!({"file": {"data_base64": "AA=="}})), + body_content_type: Some("multipart/form-data".to_owned()), + timeout_ms: 1_000, + ..RestRequest::default() + }, + ) + .await + .unwrap(); + + let requests = state.wire.lock().unwrap().clone(); + assert_eq!(requests.len(), 3); + assert_eq!(requests[0].content_types, vec!["application/json"]); + assert_eq!( + serde_json::from_slice::(&requests[0].body).unwrap(), + json!({"enabled": true, "name": "Ada"}) + ); + assert_eq!( + requests[1].content_types, + vec!["application/x-www-form-urlencoded"] + ); + let query = reqwest::Url::parse(&format!( + "https://wire.invalid/?{}", + String::from_utf8(requests[1].body.clone()).unwrap() + )) + .unwrap() + .query_pairs() + .into_owned() + .collect::>(); + assert_eq!( + query, + vec![ + ("name".to_owned(), "Ada Lovelace".to_owned()), + ("tag".to_owned(), "math".to_owned()), + ("tag".to_owned(), "programming".to_owned()), + ] + ); + assert_eq!(requests[2].content_types.len(), 1); + assert!(requests[2].content_types[0].starts_with("multipart/form-data; boundary=")); +} + +#[tokio::test] +async fn legacy_configured_content_type_keeps_json_wire_serialization() { + let (base_url, state) = spawn_capture_server().await; + for content_type in [ + "application/json; charset=utf-8", + "application/x-www-form-urlencoded; charset=utf-8", + ] { + let target = RestTarget { + static_headers: BTreeMap::from([("content-type".to_owned(), content_type.to_owned())]), + request_contract: None, + ..target(&base_url, "/wire") + }; + test_adapter() + .execute( + &target, + &RestRequest { + body: Some(json!({"name": "Ada", "tag": ["math", "programming"]})), + timeout_ms: 1_000, + ..RestRequest::default() + }, + ) + .await + .unwrap(); + } + + let requests = state.wire.lock().unwrap().clone(); + assert_eq!(requests.len(), 2); + for (request, content_type) in requests.iter().zip([ + "application/json; charset=utf-8", + "application/x-www-form-urlencoded; charset=utf-8", + ]) { + assert_eq!(request.content_types, vec![content_type]); + assert_eq!( + serde_json::from_slice::(&request.body).unwrap(), + json!({"name": "Ada", "tag": ["math", "programming"]}) + ); + } +} + +#[tokio::test] +async fn mapped_cookie_conflicting_with_trusted_cookie_is_rejected_before_dispatch() { + let (base_url, state) = spawn_capture_server().await; + let legacy_target = RestTarget { + request_contract: None, + ..target(&base_url, "/wire") + }; + let conflict = RestRequest { + headers: BTreeMap::from([ + ("cookie".to_owned(), "auth=trusted".to_owned()), + ( + "x-crank-internal-cookie-session".to_owned(), + "session\tmapped".to_owned(), + ), + ]), + trusted_header_names: BTreeSet::from(["cookie".to_owned()]), + timeout_ms: 1_000, + ..RestRequest::default() + }; + assert!(matches!( + test_adapter().execute(&legacy_target, &conflict).await, + Err(RestAdapterError::InvalidBodyContract { .. }) + )); + assert!(state.wire.lock().unwrap().is_empty()); + + test_adapter() + .execute( + &legacy_target, + &RestRequest { + headers: BTreeMap::from([("cookie".to_owned(), "auth=trusted".to_owned())]), + trusted_header_names: BTreeSet::from(["cookie".to_owned()]), + timeout_ms: 1_000, + ..RestRequest::default() + }, + ) + .await + .unwrap(); + assert_eq!( + state.wire.lock().unwrap()[0].cookie.as_deref(), + Some("auth=trusted") + ); +} + +fn target(base_url: &str, path: &str) -> RestTarget { + RestTarget { + base_url: base_url.to_owned(), + method: HttpMethod::Post, + path_template: path.to_owned(), + static_headers: BTreeMap::new(), + request_contract: Some(RestRequestContract { + version: RestRequestContractVersion::V1, + body_field: "body".to_owned(), + selector_field: Some("content_type".to_owned()), + body_required: true, + variants: [ + "application/json", + "application/x-www-form-urlencoded", + "multipart/form-data", + ] + .into_iter() + .enumerate() + .map(|(schema_variant, media_type)| RestRequestDescriptor { + media_type: media_type.to_owned(), + schema_variant, + }) + .collect(), + }), + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), + } +} + +fn target_with_mime(base_url: &str, allowed_mime_types: Vec<&str>) -> RestTarget { + RestTarget { + multipart_field_mime_types: BTreeMap::from([( + "multipart/form-data".to_owned(), + BTreeMap::from([( + "file".to_owned(), + allowed_mime_types + .into_iter() + .map(ToOwned::to_owned) + .collect(), + )]), + )]), + ..target(base_url, "/multipart") + } +} + +fn test_adapter() -> RestAdapter { + RestAdapter::with_policy(OutboundHttpPolicy::allowing_hosts(["127.0.0.1"])) +} + +async fn spawn_capture_server() -> (String, Arc) { + let state = Arc::new(CaptureState::default()); + let app = Router::new() + .route("/multipart", post(capture_multipart)) + .route("/api/v2/multipart", post(capture_multipart)) + .route( + "/api/v2/no-content", + get(|| async { StatusCode::NO_CONTENT }), + ) + .route("/wire", post(capture_wire)) + .with_state(Arc::clone(&state)); + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + tokio::spawn(async move { + axum::serve(listener, app).await.unwrap(); + }); + (format!("http://{address}"), state) +} + +async fn capture_multipart( + State(state): State>, + mut multipart: Multipart, +) -> (StatusCode, Json) { + while let Some(field) = multipart.next_field().await.unwrap() { + let part = MultipartPart { + name: field.name().unwrap_or_default().to_owned(), + filename: field.file_name().map(ToOwned::to_owned), + content_type: field.content_type().map(ToOwned::to_owned), + bytes: field.bytes().await.unwrap().to_vec(), + }; + state.multipart.lock().unwrap().push(part); + } + (StatusCode::OK, Json(json!({"ok": true}))) +} + +async fn capture_wire( + State(state): State>, + headers: HeaderMap, + body: Bytes, +) -> (StatusCode, Json) { + state.wire.lock().unwrap().push(WireRequest { + content_types: headers + .get_all("content-type") + .iter() + .filter_map(|value| value.to_str().ok().map(ToOwned::to_owned)) + .collect(), + cookie: headers + .get("cookie") + .and_then(|value| value.to_str().ok()) + .map(ToOwned::to_owned), + body: body.to_vec(), + }); + (StatusCode::OK, Json(json!({"ok": true}))) +} diff --git a/crates/crank-adapter-rest/tests/integration/outbound_security.rs b/crates/crank-adapter-rest/tests/integration/outbound_security.rs index d324946..46214c0 100644 --- a/crates/crank-adapter-rest/tests/integration/outbound_security.rs +++ b/crates/crank-adapter-rest/tests/integration/outbound_security.rs @@ -38,6 +38,9 @@ async fn forbidden_credential_and_framing_headers_fail_before_bytes_leave() { ), ("host".to_owned(), "metadata.internal".to_owned()), ]), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }; let error = adapter @@ -64,6 +67,9 @@ async fn request_body_limit_fails_before_bytes_leave() { method: HttpMethod::Post, path_template: "/capture".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }; let error = adapter @@ -101,6 +107,9 @@ async fn proxy_environment_is_ignored_by_default() { method: HttpMethod::Post, path_template: "/capture".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }; let _ = adapter.execute(&rest_target, &request).await.expect_err( "unresolvable target should fail locally instead of being sent through proxy env", diff --git a/crates/crank-community-mcp/src/manifest.rs b/crates/crank-community-mcp/src/manifest.rs index bb15e73..7289981 100644 --- a/crates/crank-community-mcp/src/manifest.rs +++ b/crates/crank-community-mcp/src/manifest.rs @@ -108,8 +108,9 @@ fn search_mode_tool_definitions(policy: &ToolSelectionPolicy) -> Vec { pub fn tool_definitions(tool: &PublishedAgentTool) -> Vec { let safety = effective_safety_policy(tool); let requires_confirmation = safety.class.requires_confirmation(); + let input_schema = operation_input_json_schema(tool); let input_schema = if requires_confirmation { - add_confirmation_token(schema_to_json_schema(&tool.operation.input_schema)) + add_confirmation_token(input_schema) } else { schema_to_json_schema(&tool.operation.input_schema) }; @@ -130,6 +131,26 @@ pub fn tool_definitions(tool: &PublishedAgentTool) -> Vec { )] } +fn operation_input_json_schema(tool: &PublishedAgentTool) -> Value { + let mut projected = schema_to_json_schema(&tool.operation.input_schema); + if matches!(&tool.operation.target, Target::Rest(target) if target.request_contract.is_some()) { + close_request_objects(&mut projected); + } + projected +} + +fn close_request_objects(schema: &mut Value) { + if let Some(variants) = schema.get_mut("anyOf").and_then(Value::as_array_mut) { + for variant in variants { + close_request_objects(variant); + } + return; + } + if schema.get("type").and_then(Value::as_str) == Some("object") { + schema["additionalProperties"] = Value::Bool(false); + } +} + pub fn analyze_published_tool_catalog( tools: &[PublishedAgentTool], ) -> Result { @@ -187,13 +208,25 @@ fn infer_safety_class(tool: &PublishedAgentTool) -> OperationSafetyClass { HttpMethod::Get => OperationSafetyClass::Read, HttpMethod::Delete => OperationSafetyClass::Destructive, HttpMethod::Post | HttpMethod::Put | HttpMethod::Patch => OperationSafetyClass::Write, + HttpMethod::Head | HttpMethod::Options => OperationSafetyClass::Read, }, } } fn add_confirmation_token(mut schema: Value) -> Value { - let Some(object) = schema.as_object_mut() else { + if let Some(variants) = schema.get_mut("anyOf").and_then(Value::as_array_mut) { + for variant in variants { + add_confirmation_token_to_object(variant); + } return schema; + } + add_confirmation_token_to_object(&mut schema); + schema +} + +fn add_confirmation_token_to_object(schema: &mut Value) { + let Some(object) = schema.as_object_mut() else { + return; }; let properties = object.entry("properties").or_insert_with(|| json!({})); if let Some(properties) = properties.as_object_mut() { @@ -205,11 +238,10 @@ fn add_confirmation_token(mut schema: Value) -> Value { }), ); } - schema } pub fn schema_to_json_schema(schema: &crank_schema::Schema) -> Value { - match schema.kind { + let mut projected = match schema.kind { crank_schema::SchemaKind::Object => { let mut properties = serde_json::Map::new(); let mut required = Vec::new(); @@ -242,11 +274,55 @@ pub fn schema_to_json_schema(schema: &crank_schema::Schema) -> Value { crank_schema::SchemaKind::Boolean => json!({ "type": "boolean" }), crank_schema::SchemaKind::Enum => json!({ "type": "string", - "enum": schema.enum_values + "enum": schema.enum_values.clone() }), crank_schema::SchemaKind::Null => json!({ "type": "null" }), crank_schema::SchemaKind::Oneof => json!({ "anyOf": schema.variants.iter().map(schema_to_json_schema).collect::>() }), + }; + if schema.kind == crank_schema::SchemaKind::Object + && matches!( + schema.format.as_deref(), + Some("binary" | crank_schema::CLOSED_OBJECT_SCHEMA_FORMAT) + ) + { + projected["additionalProperties"] = Value::Bool(false); } + if let Some(format) = &schema.format + && format != crank_schema::CLOSED_OBJECT_SCHEMA_FORMAT + { + projected["format"] = Value::String(format.clone()); + } + if schema.nullable { + if schema.kind == crank_schema::SchemaKind::Enum + && let Some(values) = projected.get_mut("enum").and_then(Value::as_array_mut) + && !values.iter().any(Value::is_null) + { + values.push(Value::Null); + } + if let Some(kind) = projected.get_mut("type") { + match kind { + Value::String(name) => { + *kind = Value::Array(vec![ + Value::String(name.clone()), + Value::String("null".to_owned()), + ]); + } + Value::Array(kinds) if !kinds.iter().any(|kind| kind.as_str() == Some("null")) => { + kinds.push(Value::String("null".to_owned())); + } + _ => {} + } + } else if let Some(variants) = projected.get_mut("anyOf").and_then(Value::as_array_mut) { + variants.push(json!({"type": "null"})); + } + } + if let Some(default) = &schema.default_value { + projected["default"] = default.clone(); + } + if let Some(description) = &schema.description { + projected["description"] = Value::String(description.clone()); + } + projected } diff --git a/crates/crank-community-mcp/tests/unit/manifest.rs b/crates/crank-community-mcp/tests/unit/manifest.rs index d525a68..4ceaad2 100644 --- a/crates/crank-community-mcp/tests/unit/manifest.rs +++ b/crates/crank-community-mcp/tests/unit/manifest.rs @@ -2,12 +2,13 @@ use std::collections::BTreeMap; use std::time::Instant; use crank_community_mcp::manifest::{ - analyze_published_tool_catalog, catalog_tool_definitions, tool_definitions, + analyze_published_tool_catalog, catalog_tool_definitions, schema_to_json_schema, + tool_definitions, }; use crank_core::{ ExecutionConfig, HttpMethod, Operation, OperationId, OperationSecurityLevel, OperationStatus, - Protocol, RestTarget, Target, ToolAccessMode, ToolDescription, ToolSelectionPolicy, - WorkspaceId, + Protocol, RestRequestContract, RestRequestContractVersion, RestRequestDescriptor, RestTarget, + Target, ToolAccessMode, ToolDescription, ToolSelectionPolicy, WorkspaceId, }; use crank_mapping::MappingSet; use crank_registry::{PublishedAgentCatalog, PublishedAgentTool, RegistryOperation}; @@ -61,6 +62,107 @@ fn marks_destructive_tools_as_two_step_confirmation_calls() { assert_eq!(definition["inputSchema"]["required"], json!(["base"])); } +#[test] +fn projects_nullable_and_binary_as_valid_closed_json_schema() { + let nullable = Schema { + kind: SchemaKind::String, + nullable: true, + ..empty_schema(SchemaKind::String) + }; + let projected = schema_to_json_schema(&nullable); + assert_eq!(projected["type"], json!(["string", "null"])); + assert!(projected.get("nullable").is_none()); + + let nullable_enum = Schema { + kind: SchemaKind::Enum, + nullable: true, + enum_values: vec!["draft".to_owned()], + ..empty_schema(SchemaKind::Enum) + }; + let projected = schema_to_json_schema(&nullable_enum); + assert_eq!(projected["type"], json!(["string", "null"])); + assert_eq!(projected["enum"], json!(["draft", null])); + + let binary = Schema { + kind: SchemaKind::Object, + format: Some("binary".to_owned()), + fields: BTreeMap::from([( + "data_base64".to_owned(), + Schema { + required: true, + ..empty_schema(SchemaKind::String) + }, + )]), + ..empty_schema(SchemaKind::Object) + }; + let projected = schema_to_json_schema(&binary); + assert_eq!(projected["additionalProperties"], false); + assert_eq!(projected["format"], "binary"); +} + +#[test] +fn optional_request_pair_uses_closed_presence_and_absence_branches() { + let mut tool = published_tool(); + let selected = Schema { + kind: SchemaKind::Object, + format: Some(crank_schema::CLOSED_OBJECT_SCHEMA_FORMAT.to_owned()), + fields: BTreeMap::from([ + ( + "body".to_owned(), + Schema { + required: true, + ..empty_schema(SchemaKind::Object) + }, + ), + ( + "content_type".to_owned(), + Schema { + kind: SchemaKind::Enum, + required: true, + enum_values: vec!["application/json".to_owned()], + ..empty_schema(SchemaKind::Enum) + }, + ), + ]), + ..empty_schema(SchemaKind::Object) + }; + let absent = Schema { + kind: SchemaKind::Object, + format: Some(crank_schema::CLOSED_OBJECT_SCHEMA_FORMAT.to_owned()), + ..empty_schema(SchemaKind::Object) + }; + tool.operation.input_schema = Schema { + kind: SchemaKind::Oneof, + variants: vec![selected, absent], + ..empty_schema(SchemaKind::Oneof) + }; + let Target::Rest(target) = &mut tool.operation.target; + target.request_contract = Some(RestRequestContract { + version: RestRequestContractVersion::V1, + body_field: "body".to_owned(), + selector_field: Some("content_type".to_owned()), + body_required: false, + variants: vec![RestRequestDescriptor { + media_type: "application/json".to_owned(), + schema_variant: 0, + }], + }); + + let schema = &tool_definitions(&tool)[0]["inputSchema"]; + assert_eq!(schema["anyOf"][0]["additionalProperties"], false); + assert_eq!( + schema["anyOf"][0]["required"], + json!(["body", "content_type"]) + ); + assert_eq!(schema["anyOf"][1]["additionalProperties"], false); + assert!( + schema["anyOf"][1]["properties"] + .as_object() + .unwrap() + .is_empty() + ); +} + #[test] fn catalog_budget_uses_the_same_definitions_as_tools_list() { let tool = published_tool(); @@ -154,10 +256,14 @@ fn operation() -> RegistryOperation { method: HttpMethod::Get, path_template: "/v2/rates".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: input_schema(), output_schema: Schema { kind: SchemaKind::Object, + format: None, description: None, required: false, nullable: false, @@ -201,6 +307,7 @@ fn input_schema() -> Schema { "base".to_owned(), Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, @@ -215,6 +322,7 @@ fn input_schema() -> Schema { "mode".to_owned(), Schema { kind: SchemaKind::Enum, + format: None, description: None, required: false, nullable: false, @@ -228,6 +336,7 @@ fn input_schema() -> Schema { Schema { kind: SchemaKind::Object, + format: None, description: None, required: false, nullable: false, @@ -239,6 +348,21 @@ fn input_schema() -> Schema { } } +fn empty_schema(kind: SchemaKind) -> Schema { + Schema { + kind, + format: None, + description: None, + required: false, + nullable: false, + default_value: None, + fields: BTreeMap::new(), + items: None, + enum_values: Vec::new(), + variants: Vec::new(), + } +} + fn timestamp(value: &str) -> OffsetDateTime { OffsetDateTime::parse(value, &Rfc3339).unwrap() } diff --git a/crates/crank-core/src/ext/protocol.rs b/crates/crank-core/src/ext/protocol.rs index f2d8c84..6ec8885 100644 --- a/crates/crank-core/src/ext/protocol.rs +++ b/crates/crank-core/src/ext/protocol.rs @@ -150,6 +150,7 @@ pub struct PreparedRequest { pub headers: BTreeMap, pub trusted_header_names: BTreeSet, pub body: Option, + pub body_content_type: Option, pub timeout_ms: u64, } @@ -162,6 +163,10 @@ impl std::fmt::Debug for PreparedRequest { .field("header_count", &self.headers.len()) .field("trusted_header_count", &self.trusted_header_names.len()) .field("body_configured", &self.body.is_some()) + .field( + "body_content_type_configured", + &self.body_content_type.is_some(), + ) .field("timeout_ms", &self.timeout_ms) .finish() } @@ -333,6 +338,9 @@ mod tests { method: crate::HttpMethod::Get, path_template: "/health".to_owned(), static_headers: Default::default(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: Default::default(), }); let response = adapter diff --git a/crates/crank-core/src/lib.rs b/crates/crank-core/src/lib.rs index 51d6582..e6283fb 100644 --- a/crates/crank-core/src/lib.rs +++ b/crates/crank-core/src/lib.rs @@ -169,7 +169,8 @@ pub use operation::{ OperationApprovalPayloadPreviewMode, OperationApprovalPolicy, OperationApprovalRiskLevel, OperationAvailability, OperationLifecycle, OperationLifecycleAction, OperationLifecycleError, OperationSafetyClass, OperationSafetyPolicy, OperationStatus, OperationVersionState, - ResponseCachePolicy, RestTarget, RetryPolicy, Samples, Target, ToolDescription, ToolExample, + ResponseCachePolicy, RestRequestContract, RestRequestContractVersion, RestRequestDescriptor, + RestResponseDescriptor, RestTarget, RetryPolicy, Samples, Target, ToolDescription, ToolExample, WizardState, }; pub use product_event::{ diff --git a/crates/crank-core/src/operation.rs b/crates/crank-core/src/operation.rs index c0f7131..33c4680 100644 --- a/crates/crank-core/src/operation.rs +++ b/crates/crank-core/src/operation.rs @@ -101,6 +101,62 @@ pub struct RestTarget { pub path_template: String, #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] pub static_headers: BTreeMap, + /// Typed request-body metadata used by Operations generated by the HTTP + /// contract importer. `None` preserves the preparation and JSON wire + /// behavior of Operations persisted before this contract existed. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub request_contract: Option, + /// The successful HTTP responses accepted by this Operation. An empty + /// contract retains the permissive behavior of Operations persisted + /// before response variants were made explicit. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub response_contract: Vec, + /// Source-declared MIME choices for multipart file fields, keyed first by + /// request media type and then by field name. Empty retains the behavior + /// of Operations persisted before multipart contracts were explicit. + #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] + pub multipart_field_mime_types: BTreeMap>>, +} + +/// A single successful REST response branch. +/// +/// `media_type: None` represents the explicit no-content branch. A response +/// with a body must select a branch with the exact status and media type. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct RestResponseDescriptor { + pub status_code: u16, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub media_type: Option, + /// Index of the matching branch in `Operation.output_schema`. A scalar + /// output schema uses index zero. + pub schema_variant: usize, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub enum RestRequestContractVersion { + #[serde(rename = "1")] + V1, +} + +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct RestRequestContract { + pub version: RestRequestContractVersion, + pub body_field: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub selector_field: Option, + pub body_required: bool, + pub variants: Vec, +} + +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct RestRequestDescriptor { + pub media_type: String, + /// Index of the matching top-level `Operation.input_schema` branch. A + /// request contract without a top-level union uses index zero. + pub schema_variant: usize, } #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] @@ -406,6 +462,9 @@ mod tests { method: HttpMethod::Post, path_template: "/v1/leads".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }); let value = serde_json::to_value(target).unwrap(); @@ -571,6 +630,8 @@ updated_at: 2026-03-25T08:10:00Z assert_eq!(restored.security_level, OperationSecurityLevel::Standard); assert_eq!(restored.published_at, None); + let Target::Rest(target) = restored.target; + assert!(target.response_contract.is_empty()); } fn test_operation(status: OperationStatus) -> Operation { @@ -588,6 +649,9 @@ updated_at: 2026-03-25T08:10:00Z method: HttpMethod::Post, path_template: "/v1/leads".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: json!({"type":"object","fields":{"email":{"type":"string","required":true}}}), output_schema: json!({"type":"object","fields":{"id":{"type":"string","required":true}}}), diff --git a/crates/crank-core/src/protocol.rs b/crates/crank-core/src/protocol.rs index 20cc0e6..76d6bab 100644 --- a/crates/crank-core/src/protocol.rs +++ b/crates/crank-core/src/protocol.rs @@ -14,6 +14,8 @@ pub enum HttpMethod { Put, Patch, Delete, + Head, + Options, } #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] diff --git a/crates/crank-import/Cargo.toml b/crates/crank-import/Cargo.toml index c19dc00..1c13ebe 100644 --- a/crates/crank-import/Cargo.toml +++ b/crates/crank-import/Cargo.toml @@ -14,4 +14,4 @@ serde.workspace = true serde_json.workspace = true serde_yaml.workspace = true thiserror.workspace = true - +url.workspace = true diff --git a/crates/crank-import/src/rest/http_methods.rs b/crates/crank-import/src/rest/http_methods.rs new file mode 100644 index 0000000..3633857 --- /dev/null +++ b/crates/crank-import/src/rest/http_methods.rs @@ -0,0 +1,25 @@ +use crank_core::HttpMethod; + +use crate::rest::model::{ImportFinding, ImportFindingSeverity}; + +pub(super) fn from_lower(value: &str) -> Option { + match value { + "get" => Some(HttpMethod::Get), + "post" => Some(HttpMethod::Post), + "put" => Some(HttpMethod::Put), + "patch" => Some(HttpMethod::Patch), + "delete" => Some(HttpMethod::Delete), + "head" => Some(HttpMethod::Head), + "options" => Some(HttpMethod::Options), + _ => None, + } +} + +pub(super) fn invalid_path_item() -> ImportFinding { + ImportFinding { + code: "invalid_path_item".to_owned(), + severity: ImportFindingSeverity::Error, + message: "Path Item имеет неверную структуру и не был интерпретирован.".to_owned(), + operation_key: None, + } +} diff --git a/crates/crank-import/src/rest/legacy_mapping.rs b/crates/crank-import/src/rest/legacy_mapping.rs new file mode 100644 index 0000000..0bc20b2 --- /dev/null +++ b/crates/crank-import/src/rest/legacy_mapping.rs @@ -0,0 +1,81 @@ +// Frozen pre-v4 projection for historical legacy-v1 jobs. +use crank_mapping::{MappingRule, MappingSet}; +use crank_schema::{Schema, SchemaKind}; + +use crate::rest::model::{RestImportParameter, RestParameterLocation}; + +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct BodyFieldMapping { + pub input_name: String, + pub body_path: String, + pub required: bool, +} + +pub fn input_mapping( + parameters: &[RestImportParameter], + body_fields: &[BodyFieldMapping], +) -> MappingSet { + let mut rules = Vec::new(); + for parameter in parameters { + let target_root = match parameter.location { + RestParameterLocation::Path => "$.request.path", + RestParameterLocation::Query => "$.request.query", + RestParameterLocation::Header => "$.request.headers", + RestParameterLocation::Cookie => "$.request.cookies", + }; + rules.push(MappingRule { + source: format!("$.mcp.{}", parameter.name), + target: format!("{target_root}.{}", parameter.name), + required: parameter.required, + default_value: None, + transform: None, + condition: None, + notes: None, + }); + } + for field in body_fields { + let target = if field.body_path.is_empty() { + "$.request.body".to_owned() + } else { + format!("$.request.body.{}", field.body_path) + }; + rules.push(MappingRule { + source: format!("$.mcp.{}", field.input_name), + target, + required: field.required, + default_value: None, + transform: None, + condition: None, + notes: None, + }); + } + MappingSet { rules } +} + +pub fn output_mapping(output_schema: &Schema) -> MappingSet { + let mut rules = Vec::new(); + if output_schema.kind == SchemaKind::Object && !output_schema.fields.is_empty() { + for (name, field) in &output_schema.fields { + rules.push(MappingRule { + source: format!("$.response.body.{name}"), + target: format!("$.output.{name}"), + required: field.required, + default_value: None, + transform: None, + condition: None, + notes: None, + }); + } + } else { + rules.push(MappingRule { + source: "$.response.body".to_owned(), + target: "$.output".to_owned(), + required: true, + default_value: None, + transform: None, + condition: None, + notes: None, + }); + } + MappingSet { rules } +} diff --git a/crates/crank-import/src/rest/legacy_payload.rs b/crates/crank-import/src/rest/legacy_payload.rs new file mode 100644 index 0000000..888f6c2 --- /dev/null +++ b/crates/crank-import/src/rest/legacy_payload.rs @@ -0,0 +1,238 @@ +// Frozen pre-v4 projection for historical legacy-v1 jobs. +use std::collections::{BTreeMap, BTreeSet}; + +use crank_core::{ + ExecutionConfig, HttpMethod, OperationSafetyClass, OperationSafetyPolicy, Protocol, RestTarget, + ToolDescription, ToolExample, WizardState, +}; +use serde_json::json; + +use crate::rest::{ + legacy_mapping::{BodyFieldMapping, input_mapping, output_mapping}, + legacy_schema::{any_object, field_count, object_with_fields, schema_from_openapi}, + model::{ + ImportOperationCandidate, RestImportCandidate, RestImportOperation, RestParameterLocation, + }, + naming::{fallback_operation_seed, title_from_name, unique_name}, + recommendations::{candidate_recommendations, operation_recommendations}, +}; + +pub fn candidate_from_operation( + operation: &RestImportOperation, + document_servers: &[String], + used_names: &mut BTreeSet, +) -> ImportOperationCandidate { + let method_name = method_as_str(operation.method); + let seed = operation + .operation_id + .as_deref() + .filter(|value| !value.trim().is_empty()) + .map(ToOwned::to_owned) + .unwrap_or_else(|| fallback_operation_seed(method_name, &operation.path)); + let name = unique_name(&seed, used_names); + let display_name = operation + .summary + .as_deref() + .filter(|value| !value.trim().is_empty()) + .map(ToOwned::to_owned) + .unwrap_or_else(|| title_from_name(&name)); + let description = operation + .description + .as_deref() + .or(operation.summary.as_deref()) + .filter(|value| !value.trim().is_empty()) + .map(ToOwned::to_owned) + .unwrap_or_else(|| format!("Выполняет {method_name} {}", operation.path)); + let category = operation + .tags + .first() + .cloned() + .unwrap_or_else(|| "imported".to_owned()); + let server_urls = if operation.servers.is_empty() { + document_servers.to_vec() + } else { + operation.servers.clone() + }; + let base_url = server_urls.first().cloned().unwrap_or_default(); + let mut input_fields = BTreeMap::new(); + let mut used_input_field_names = BTreeSet::new(); + for parameter in &operation.parameters { + used_input_field_names.insert(parameter.name.clone()); + input_fields.insert( + parameter.name.clone(), + schema_from_openapi( + parameter.schema.as_ref(), + parameter.required || parameter.location == RestParameterLocation::Path, + parameter.description.clone(), + ), + ); + } + let body_fields = body_input_fields( + operation.request_body_schema.as_ref(), + &mut used_input_field_names, + &mut input_fields, + ); + let input_schema = object_with_fields( + Some("Входные параметры MCP-инструмента".to_owned()), + input_fields, + ); + let output_schema = operation + .response_schema + .as_ref() + .map(|schema| schema_from_openapi(Some(schema), true, Some("Ответ API".to_owned()))) + .unwrap_or_else(|| any_object(Some("Ответ API".to_owned()))); + let input_mapping = input_mapping(&operation.parameters, &body_fields); + let output_mapping = output_mapping(&output_schema); + let mut findings = operation_recommendations(operation); + findings.extend(candidate_recommendations( + operation, + &name, + &description, + &input_schema, + &output_schema, + )); + + let draft = RestImportCandidate { + name: name.clone(), + display_name: display_name.clone(), + category: category.clone(), + target: RestTarget { + base_url, + method: operation.method, + path_template: operation.path.clone(), + static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), + }, + input_schema: input_schema.clone(), + output_schema: output_schema.clone(), + input_mapping, + output_mapping, + tool_description: ToolDescription { + title: display_name.clone(), + description: description.clone(), + tags: operation.tags.clone(), + examples: vec![ToolExample { input: json!({}) }], + }, + wizard_state: Some(WizardState { + input_sample: None, + output_sample: None, + test_input: None, + import_findings: Vec::new(), + }), + }; + + ImportOperationCandidate { + key: operation.key.clone(), + method: operation.method, + path: operation.path.clone(), + operation_id: operation.operation_id.clone(), + suggested_name: name, + suggested_display_name: display_name, + description, + category, + input_fields: field_count(&input_schema), + output_fields: field_count(&output_schema), + server_urls, + findings, + draft, + } +} + +fn body_input_fields( + request_body_schema: Option<&serde_json::Value>, + used_names: &mut BTreeSet, + input_fields: &mut BTreeMap, +) -> Vec { + let Some(request_body_schema) = request_body_schema else { + return Vec::new(); + }; + let body_schema = schema_from_openapi( + Some(request_body_schema), + true, + Some("Тело запроса".to_owned()), + ); + if body_schema.kind != crank_schema::SchemaKind::Object || body_schema.fields.is_empty() { + let input_name = unique_body_input_name("body", used_names); + input_fields.insert(input_name.clone(), body_schema); + return vec![BodyFieldMapping { + input_name, + body_path: String::new(), + required: true, + }]; + } + + let mut mappings = Vec::new(); + for (field_name, field_schema) in body_schema.fields { + let input_name = unique_body_input_name(&field_name, used_names); + mappings.push(BodyFieldMapping { + input_name: input_name.clone(), + body_path: field_name, + required: field_schema.required, + }); + input_fields.insert(input_name, field_schema); + } + mappings +} + +fn unique_body_input_name(name: &str, used_names: &mut BTreeSet) -> String { + if used_names.insert(name.to_owned()) { + return name.to_owned(); + } + let prefixed = format!("body_{name}"); + if used_names.insert(prefixed.clone()) { + return prefixed; + } + for index in 2.. { + let candidate = format!("body_{name}_{index}"); + if used_names.insert(candidate.clone()) { + return candidate; + } + } + unreachable!() +} + +fn method_as_str(method: HttpMethod) -> &'static str { + match method { + HttpMethod::Get => "GET", + HttpMethod::Head => "HEAD", + HttpMethod::Options => "OPTIONS", + HttpMethod::Post => "POST", + HttpMethod::Put => "PUT", + HttpMethod::Patch => "PATCH", + HttpMethod::Delete => "DELETE", + } +} + +#[allow(dead_code)] +fn safety_for_method(method: HttpMethod) -> OperationSafetyPolicy { + let class = match method { + HttpMethod::Get | HttpMethod::Head | HttpMethod::Options => OperationSafetyClass::Read, + HttpMethod::Post | HttpMethod::Put | HttpMethod::Patch => OperationSafetyClass::Write, + HttpMethod::Delete => OperationSafetyClass::Destructive, + }; + OperationSafetyPolicy { + class, + confirmation: None, + } +} + +#[allow(dead_code)] +fn default_execution_config() -> ExecutionConfig { + ExecutionConfig { + timeout_ms: 10_000, + retry_policy: None, + response_cache: None, + idempotency: None, + safety: None, + approval_policy: None, + auth_profile_ref: None, + headers: BTreeMap::new(), + } +} + +#[allow(dead_code)] +fn _protocol() -> Protocol { + Protocol::Rest +} diff --git a/crates/crank-import/src/rest/legacy_schema.rs b/crates/crank-import/src/rest/legacy_schema.rs new file mode 100644 index 0000000..56a1bc5 --- /dev/null +++ b/crates/crank-import/src/rest/legacy_schema.rs @@ -0,0 +1,238 @@ +// Frozen pre-v4 projection for historical legacy-v1 jobs. +use std::collections::BTreeMap; + +use crank_schema::{Schema, SchemaKind}; +use serde_json::Value; + +pub fn any_object(description: Option) -> Schema { + Schema { + format: None, + kind: SchemaKind::Object, + description, + required: true, + nullable: false, + default_value: None, + fields: BTreeMap::new(), + items: None, + enum_values: Vec::new(), + variants: Vec::new(), + } +} + +pub fn field_count(schema: &Schema) -> usize { + match schema.kind { + SchemaKind::Object => schema.fields.len(), + _ => 0, + } +} + +pub fn schema_from_openapi( + value: Option<&Value>, + required: bool, + description: Option, +) -> Schema { + let Some(value) = value else { + return primitive(SchemaKind::String, required, description); + }; + // Only v3 NormalizedIR emits the private marker. Pending legacy-v1 jobs + // retain their historical first-branch behavior, while modern oneOf/anyOf + // is projected losslessly through crank-schema's existing Oneof shape. + if value + .get("x-crank-lossless-composition") + .and_then(Value::as_bool) + == Some(true) + && let Some(items) = value + .get("oneOf") + .or_else(|| value.get("anyOf")) + .and_then(Value::as_array) + { + return Schema { + format: None, + kind: SchemaKind::Oneof, + description: description.or_else(|| text(value, "description")), + required, + nullable: nullable(value), + default_value: value.get("default").cloned(), + fields: BTreeMap::new(), + items: None, + enum_values: Vec::new(), + variants: items + .iter() + .map(|item| schema_from_openapi(Some(item), true, None)) + .collect(), + }; + } + let resolved = collapse_composition(value); + + if let Some(values) = resolved.get("enum").and_then(Value::as_array) { + let enum_values = values + .iter() + .filter_map(Value::as_str) + .map(ToOwned::to_owned) + .collect::>(); + if !enum_values.is_empty() { + return Schema { + format: None, + kind: SchemaKind::Enum, + description: description.or_else(|| text(&resolved, "description")), + required, + nullable: nullable(&resolved), + default_value: resolved.get("default").cloned(), + fields: BTreeMap::new(), + items: None, + enum_values, + variants: Vec::new(), + }; + } + } + + match type_name(&resolved).unwrap_or("object") { + "object" => object_schema(&resolved, required, description), + "array" => Schema { + format: None, + kind: SchemaKind::Array, + description: description.or_else(|| text(&resolved, "description")), + required, + nullable: nullable(&resolved), + default_value: resolved.get("default").cloned(), + fields: BTreeMap::new(), + items: Some(Box::new(schema_from_openapi( + resolved.get("items"), + true, + None, + ))), + enum_values: Vec::new(), + variants: Vec::new(), + }, + "integer" => primitive( + SchemaKind::Integer, + required, + description.or_else(|| text(&resolved, "description")), + ), + "number" => primitive( + SchemaKind::Number, + required, + description.or_else(|| text(&resolved, "description")), + ), + "boolean" => primitive( + SchemaKind::Boolean, + required, + description.or_else(|| text(&resolved, "description")), + ), + "null" => primitive( + SchemaKind::Null, + required, + description.or_else(|| text(&resolved, "description")), + ), + _ => primitive( + SchemaKind::String, + required, + description.or_else(|| text(&resolved, "description")), + ), + } +} + +fn collapse_composition(value: &Value) -> Value { + for key in ["allOf", "oneOf", "anyOf"] { + if let Some(items) = value.get(key).and_then(Value::as_array) + && let Some(first) = items.first() + { + return first.clone(); + } + } + value.clone() +} + +pub fn object_with_fields(description: Option, fields: BTreeMap) -> Schema { + Schema { + format: None, + kind: SchemaKind::Object, + description, + required: true, + nullable: false, + default_value: None, + fields, + items: None, + enum_values: Vec::new(), + variants: Vec::new(), + } +} + +fn object_schema(value: &Value, required: bool, description: Option) -> Schema { + let required_fields = value + .get("required") + .and_then(Value::as_array) + .map(|items| { + items + .iter() + .filter_map(Value::as_str) + .collect::>() + }) + .unwrap_or_default(); + let mut fields = BTreeMap::new(); + + if let Some(properties) = value.get("properties").and_then(Value::as_object) { + for (name, schema) in properties { + fields.insert( + name.clone(), + schema_from_openapi( + Some(schema), + required_fields.contains(name.as_str()), + text(schema, "description"), + ), + ); + } + } + + Schema { + format: None, + kind: SchemaKind::Object, + description: description.or_else(|| text(value, "description")), + required, + nullable: nullable(value), + default_value: value.get("default").cloned(), + fields, + items: None, + enum_values: Vec::new(), + variants: Vec::new(), + } +} + +fn primitive(kind: SchemaKind, required: bool, description: Option) -> Schema { + Schema { + format: None, + kind, + description, + required, + nullable: false, + default_value: None, + fields: BTreeMap::new(), + items: None, + enum_values: Vec::new(), + variants: Vec::new(), + } +} + +fn type_name(value: &Value) -> Option<&str> { + match value.get("type") { + Some(Value::String(value)) => Some(value.as_str()), + Some(Value::Array(values)) => values.iter().find_map(Value::as_str), + _ if value.get("properties").is_some() => Some("object"), + _ if value.get("items").is_some() => Some("array"), + _ => None, + } +} + +fn nullable(value: &Value) -> bool { + value + .get("nullable") + .and_then(Value::as_bool) + .unwrap_or(false) +} + +fn text(value: &Value, key: &str) -> Option { + value + .get(key) + .and_then(Value::as_str) + .map(ToOwned::to_owned) +} diff --git a/crates/crank-import/src/rest/mapping.rs b/crates/crank-import/src/rest/mapping.rs index 12d4b38..c3e89c5 100644 --- a/crates/crank-import/src/rest/mapping.rs +++ b/crates/crank-import/src/rest/mapping.rs @@ -1,7 +1,7 @@ use crank_mapping::{MappingRule, MappingSet}; use crank_schema::{Schema, SchemaKind}; -use crate::rest::model::{RestImportParameter, RestParameterLocation}; +use crate::rest::model::RestParameterLocation; #[derive(Clone, Debug, PartialEq, Eq)] pub struct BodyFieldMapping { @@ -10,8 +10,17 @@ pub struct BodyFieldMapping { pub required: bool, } +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct ParameterFieldMapping { + pub input_name: String, + pub wire_name: String, + pub location: RestParameterLocation, + pub required: bool, + pub default_value: Option, +} + pub fn input_mapping( - parameters: &[RestImportParameter], + parameters: &[ParameterFieldMapping], body_fields: &[BodyFieldMapping], ) -> MappingSet { let mut rules = Vec::new(); @@ -20,19 +29,25 @@ pub fn input_mapping( RestParameterLocation::Path => "$.request.path", RestParameterLocation::Query => "$.request.query", RestParameterLocation::Header => "$.request.headers", + // Cookies travel through a distinct mapping root. Runtime turns + // this object into the single wire `Cookie` header at the adapter + // boundary; source values cannot inject an arbitrary header. + RestParameterLocation::Cookie => "$.request.cookies", }; rules.push(MappingRule { - source: format!("$.mcp.{}", parameter.name), - target: format!("{target_root}.{}", parameter.name), + source: format!("$.mcp.{}", parameter.input_name), + target: format!("{target_root}.{}", parameter.wire_name), required: parameter.required, - default_value: None, + default_value: parameter.default_value.clone(), transform: None, condition: None, notes: None, }); } for field in body_fields { - let target = if field.body_path.is_empty() { + let target = if field.body_path == "__content_type" { + "$.request.body_content_type".to_owned() + } else if field.body_path.is_empty() || field.body_path == "__body" { "$.request.body".to_owned() } else { format!("$.request.body.{}", field.body_path) diff --git a/crates/crank-import/src/rest/metadata_findings.rs b/crates/crank-import/src/rest/metadata_findings.rs new file mode 100644 index 0000000..5d23e00 --- /dev/null +++ b/crates/crank-import/src/rest/metadata_findings.rs @@ -0,0 +1,70 @@ +use serde_json::Value; + +use crate::rest::{ + model::{ImportFinding, SourceLocation}, + recommendations::document_finding, +}; + +pub(super) fn collect_secret_like_examples( + value: &Value, + pointer: &str, + inside_example: bool, + findings: &mut Vec, + locations: &mut Vec>, +) { + match value { + Value::Object(fields) => { + for (key, child) in fields { + let child_pointer = format!( + "{pointer}/{}", + super::normalize_coverage::escape_pointer(key) + ); + collect_secret_like_examples( + child, + &child_pointer, + inside_example || matches!(key.as_str(), "example" | "examples"), + findings, + locations, + ); + } + } + Value::Array(items) => { + for (index, child) in items.iter().enumerate() { + collect_secret_like_examples( + child, + &format!("{pointer}/{index}"), + inside_example, + findings, + locations, + ); + } + } + Value::String(value) if inside_example && looks_secret_like(pointer, value) => { + findings.push(document_finding( + "secret_like_example", + "Example содержит значение, похожее на секрет, и не включается в executable contract.", + )); + locations.push(Some(SourceLocation { + pointer: pointer.to_owned(), + })); + } + _ => {} + } +} + +fn looks_secret_like(pointer: &str, value: &str) -> bool { + let pointer = pointer.to_ascii_lowercase(); + let value = value.to_ascii_lowercase(); + [ + "token", + "secret", + "password", + "api_key", + "apikey", + "authorization", + ] + .iter() + .any(|marker| pointer.contains(marker) || value.contains(marker)) + || value.starts_with("bearer ") + || value.starts_with("sk-") +} diff --git a/crates/crank-import/src/rest/mod.rs b/crates/crank-import/src/rest/mod.rs index a919347..532536a 100644 --- a/crates/crank-import/src/rest/mod.rs +++ b/crates/crank-import/src/rest/mod.rs @@ -1,25 +1,35 @@ +mod http_methods; +mod legacy_mapping; +mod legacy_payload; +mod legacy_schema; mod mapping; +mod metadata_findings; pub mod model; mod naming; mod normalize; mod normalize_coverage; +mod normalize_finding_validation; mod normalize_limits; +mod normalize_projection; mod normalize_schema; mod openapi3; +mod openapi3_findings; mod payload; mod recommendations; mod reference; mod schema; mod swagger2; +mod swagger2_findings; pub use model::{ ExternalDocumentSnapshot, ImportFinding, ImportFindingSeverity, ImportGroupPreview, ImportOperationCandidate, ImportPreview, ImportSourcePreview, NORMALIZER_VERSION, NormalizationConfig, NormalizedFinding, NormalizedIr, NormalizedOperation, NormalizedParameter, - NormalizedReference, NormalizedSchema, NormalizedSchemaConstraints, NormalizedSchemaKind, - PROJECTION_VERSION, ResolvedReferenceEdge, ResolvedReferenceGraph, ResolvedReferenceNode, - RestImportCandidate, RestImportDocument, RestImportOperation, RestImportParameter, - RestParameterLocation, SourceDigest, SourceIdentity, SourceLocation, UnresolvedReference, + NormalizedReference, NormalizedRequestBodyVariant, NormalizedResponseVariant, NormalizedSchema, + NormalizedSchemaConstraints, NormalizedSchemaKind, PROJECTION_VERSION, ResolvedReferenceEdge, + ResolvedReferenceGraph, ResolvedReferenceNode, RestImportCandidate, RestImportDocument, + RestImportOperation, RestImportParameter, RestParameterLocation, RestRequestBodyVariant, + RestResponseVariant, SourceDigest, SourceIdentity, SourceLocation, UnresolvedReference, }; pub use normalize::{ ImportParseError, external_reference_uris, normalize_verified_bundle, diff --git a/crates/crank-import/src/rest/model.rs b/crates/crank-import/src/rest/model.rs index 11b19fa..dc75cbe 100644 --- a/crates/crank-import/src/rest/model.rs +++ b/crates/crank-import/src/rest/model.rs @@ -9,8 +9,8 @@ use serde_json::Value; /// The immutable contract used to normalize an OpenAPI source. These names /// deliberately travel with an import job: changing either contract must not /// silently reinterpret a pending preview. -pub const NORMALIZER_VERSION: &str = "normalized-ir-v3"; -pub const PROJECTION_VERSION: &str = "preview-v3"; +pub const NORMALIZER_VERSION: &str = "normalized-ir-v4"; +pub const PROJECTION_VERSION: &str = "preview-v4"; #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)] pub struct SourceDigest(String); @@ -242,11 +242,35 @@ pub struct NormalizedOperation { pub request_body_schema: Option, pub response_schema: Option, #[serde(default)] + pub request_body_variants: Vec, + #[serde(default)] + pub response_variants: Vec, + #[serde(default)] pub servers: Vec, #[serde(default)] pub findings: Vec, } +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +pub struct NormalizedRequestBodyVariant { + pub content_type: String, + pub required: bool, + pub schema: Option, + /// MIME types allowed for individual multipart fields, keyed by source + /// property name. Empty when the source does not constrain a field. + #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] + pub multipart_field_mime_types: BTreeMap>, + pub source_location: SourceLocation, +} + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +pub struct NormalizedResponseVariant { + pub status_code: u16, + pub content_type: Option, + pub schema: Option, + pub source_location: SourceLocation, +} + #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct NormalizedParameter { pub name: String, @@ -306,9 +330,13 @@ pub enum NormalizedSchemaKind { Object { properties: BTreeMap, required: Vec, + nullable: bool, + default_value: Option, }, Array { items: Option>, + nullable: bool, + default_value: Option, }, Reference { reference: UnresolvedReference, @@ -468,11 +496,21 @@ pub struct RestImportOperation { pub request_body_schema: Option, #[serde(skip)] pub request_body_schema_location: Option, + /// Every executable request variant. `request_body_schema` remains for + /// legacy replay only; modern projection must use this complete list. + #[serde(default)] + pub request_body_variants: Vec, pub response_schema: Option, #[serde(skip)] pub response_schema_location: Option, + /// All successful response branches, including explicit no-content + /// outcomes. The old singular field is retained for legacy-v1 jobs. + #[serde(default)] + pub response_variants: Vec, pub servers: Vec, pub findings: Vec, + #[serde(skip)] + pub internal_finding_locations: Vec, } #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] @@ -488,6 +526,37 @@ pub struct RestImportParameter { pub schema_source_location: Option, } +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +pub struct RestRequestBodyVariant { + pub content_type: String, + pub required: bool, + pub schema: Option, + /// MIME types from OpenAPI's multipart `encoding.*.contentType`. + #[serde(default, skip_serializing_if = "BTreeMap::is_empty")] + pub multipart_field_mime_types: BTreeMap>, + #[serde(skip, default = "empty_source_location")] + pub source_location: SourceLocation, + #[serde(skip, default)] + pub schema_source_location: Option, + /// Swagger 2 formData schemas are assembled from independent parameters. + /// This keeps each generated property tied to its original parameter. + #[serde(skip, default)] + pub schema_property_source_locations: BTreeMap, +} + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +pub struct RestResponseVariant { + pub status_code: u16, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub content_type: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub schema: Option, + #[serde(skip, default = "empty_source_location")] + pub source_location: SourceLocation, + #[serde(skip, default)] + pub schema_source_location: Option, +} + fn empty_source_location() -> SourceLocation { SourceLocation { pointer: String::new(), @@ -500,4 +569,5 @@ pub enum RestParameterLocation { Path, Query, Header, + Cookie, } diff --git a/crates/crank-import/src/rest/normalize.rs b/crates/crank-import/src/rest/normalize.rs index 5ccaf00..72a6f29 100644 --- a/crates/crank-import/src/rest/normalize.rs +++ b/crates/crank-import/src/rest/normalize.rs @@ -8,10 +8,9 @@ use crate::rest::{ CoverageDisposition, CoverageEntry, ExternalDocumentSnapshot, ImportFinding, ImportFindingSeverity, ImportGroupPreview, ImportPreview, ImportSourcePreview, NORMALIZER_VERSION, NormalizationConfig, NormalizedApiMetadata, NormalizedFinding, - NormalizedIr, NormalizedLiteral, NormalizedOperation, NormalizedParameter, - NormalizedScalarKind, NormalizedSchema, NormalizedSchemaKind, PROJECTION_VERSION, - RestImportDocument, RestImportOperation, RestImportParameter, SourceDigest, SourceIdentity, - SourceLocation, SourceSyntax, + NormalizedIr, NormalizedOperation, NormalizedParameter, NormalizedRequestBodyVariant, + NormalizedResponseVariant, NormalizedSchema, NormalizedSchemaKind, PROJECTION_VERSION, + RestImportDocument, SourceDigest, SourceIdentity, SourceLocation, SourceSyntax, }, openapi3, payload::candidate_from_operation, @@ -139,7 +138,7 @@ pub fn normalize_verified_bundle( let root = resolution.root; validate_value_limits(&root, config)?; - let parsed = match root.get("openapi").and_then(Value::as_str) { + let mut parsed = match root.get("openapi").and_then(Value::as_str) { Some(version) if supported_oas_version(version) => openapi3::parse_document(&root)?, Some(_) => return Err(ImportParseError::UnsupportedDocument), None if root.get("swagger").and_then(Value::as_str) == Some("2.0") => { @@ -147,8 +146,20 @@ pub fn normalize_verified_bundle( } None => return Err(ImportParseError::UnsupportedDocument), }; + super::metadata_findings::collect_secret_like_examples( + &root, + "", + false, + &mut parsed.findings, + &mut parsed.internal_finding_locations, + ); - if parsed.operations.is_empty() { + if parsed.operations.is_empty() + && !parsed + .findings + .iter() + .any(|finding| finding.code == "unsupported_http_method") + { return Err(ImportParseError::NoMethods); } canonicalize( @@ -166,7 +177,7 @@ pub fn preview_from_ir(ir: &NormalizedIr) -> ImportPreview { let operations = ir .operations .iter() - .map(legacy_operation_from_normalized) + .map(super::normalize_projection::operation_from_normalized) .collect::>(); let findings = ir .findings @@ -178,7 +189,7 @@ pub fn preview_from_ir(ir: &NormalizedIr) -> ImportPreview { operation_key: finding.operation_key.clone(), }) .collect(); - preview_from_operations(&ir.source, operations.iter(), findings) + preview_from_operations(&ir.source, operations.iter(), findings, false) } fn preview_from_document(document: RestImportDocument) -> ImportPreview { @@ -188,19 +199,28 @@ fn preview_from_document(document: RestImportDocument) -> ImportPreview { title: document.title, servers: document.servers, }; - preview_from_operations(&source, document.operations.iter(), document.findings) + preview_from_operations(&source, document.operations.iter(), document.findings, true) } fn preview_from_operations<'a>( source: &ImportSourcePreview, operations: impl Iterator, mut findings: Vec, + legacy: bool, ) -> ImportPreview { let mut groups: BTreeMap = BTreeMap::new(); let mut used_names = BTreeSet::new(); for operation in operations { - let candidate = candidate_from_operation(operation, &source.servers, &mut used_names); + let candidate = if legacy { + super::legacy_payload::candidate_from_operation( + operation, + &source.servers, + &mut used_names, + ) + } else { + candidate_from_operation(operation, &source.servers, &mut used_names) + }; let group_title = operation .tags .first() @@ -379,14 +399,27 @@ fn canonicalize( disposition: CoverageDisposition::Mapped, }); } - operation_findings.extend(operation.findings.iter().map(|finding| NormalizedFinding { - code: finding.code.clone(), - severity: finding.severity.clone(), - message: finding.message.clone(), - construct_id: stable_id.clone(), - location: location.clone(), - operation_key: Some(operation.key.clone()), - })); + operation_findings.extend(operation.findings.iter().enumerate().map( + |(index, finding)| { + let finding_location = operation + .internal_finding_locations + .get(index) + .cloned() + .unwrap_or_else(|| location.clone()); + NormalizedFinding { + code: finding.code.clone(), + severity: finding.severity.clone(), + message: finding.message.clone(), + construct_id: if finding_location == location { + stable_id.clone() + } else { + format!("{version}:{}", finding_location.pointer) + }, + location: finding_location, + operation_key: Some(operation.key.clone()), + } + }, + )); let parameters = operation .parameters .into_iter() @@ -465,6 +498,52 @@ fn canonicalize( &mut coverage, ) }); + let request_body_variants = operation + .request_body_variants + .iter() + .map(|variant| NormalizedRequestBodyVariant { + content_type: variant.content_type.clone(), + required: variant.required, + schema: variant.schema.as_ref().map(|schema| { + let schema_location = variant + .schema_source_location + .as_ref() + .unwrap_or(&variant.source_location); + normalize_coverage::typed_schema_with_property_locations( + schema, + &schema_location.pointer, + &variant.schema_property_source_locations, + &mut coverage, + ) + }), + multipart_field_mime_types: variant.multipart_field_mime_types.clone(), + source_location: variant.source_location.clone(), + }) + .collect(); + let response_variants = operation + .response_variants + .iter() + .map(|variant| NormalizedResponseVariant { + status_code: variant.status_code, + content_type: variant.content_type.clone(), + schema: variant.schema.as_ref().map(|schema| { + let schema_location = variant + .schema_source_location + .as_ref() + .unwrap_or(&variant.source_location); + normalize_coverage::typed_schema( + schema, + &schema_location.pointer, + &format!( + "{stable_id}:response_variant:{}", + normalize_coverage::escape_pointer(&schema_location.pointer) + ), + &mut coverage, + ) + }), + source_location: variant.source_location.clone(), + }) + .collect(); if normalize_coverage::has_reference_schema(request_body_schema.as_ref()) || normalize_coverage::has_reference_schema(response_schema.as_ref()) || parameters.iter().any(|parameter| { @@ -499,6 +578,8 @@ fn canonicalize( parameters, request_body_schema, response_schema, + request_body_variants, + response_variants, servers: operation.servers, findings: operation_findings, }) @@ -599,6 +680,18 @@ fn canonicalize( .filter_map(|parameter| parameter.schema.as_ref()) .chain(operation.request_body_schema.iter()) .chain(operation.response_schema.iter()) + .chain( + operation + .request_body_variants + .iter() + .filter_map(|variant| variant.schema.as_ref()), + ) + .chain( + operation + .response_variants + .iter() + .filter_map(|variant| variant.schema.as_ref()), + ) .any(|schema| schema_contains_reference(schema, &reference.location)) }) }) @@ -738,115 +831,13 @@ fn coverage_disposition_rank(disposition: &CoverageDisposition) -> u8 { } } -fn legacy_operation_from_normalized(operation: &NormalizedOperation) -> RestImportOperation { - RestImportOperation { - key: operation.key.clone(), - method: operation.method, - path: operation.path.clone(), - operation_id: operation.operation_id.clone(), - summary: operation.summary.clone(), - description: operation.description.clone(), - tags: operation.tags.clone(), - parameters: operation - .parameters - .iter() - .map(|parameter| RestImportParameter { - name: parameter.name.clone(), - location: parameter.location, - required: parameter.required, - description: parameter.description.clone(), - schema: parameter.schema.as_ref().map(legacy_schema_value), - source_location: parameter.source_location.clone(), - schema_source_location: None, - }) - .collect(), - request_body_schema: operation - .request_body_schema - .as_ref() - .map(legacy_schema_value), - request_body_schema_location: None, - response_schema: operation.response_schema.as_ref().map(legacy_schema_value), - response_schema_location: None, - servers: operation.servers.clone(), - findings: operation - .findings - .iter() - .map(|finding| ImportFinding { - code: finding.code.clone(), - severity: finding.severity.clone(), - message: finding.message.clone(), - operation_key: finding.operation_key.clone(), - }) - .collect(), - } -} - -fn legacy_schema_value(schema: &NormalizedSchema) -> Value { - let mut value = match &schema.kind { - NormalizedSchemaKind::Reference { reference } => serde_json::json!({"$ref": reference.uri}), - NormalizedSchemaKind::Composition { operator, variants } => { - serde_json::json!({ - operator: variants.iter().map(legacy_schema_value).collect::>(), - "x-crank-lossless-composition": true, - }) - } - NormalizedSchemaKind::Object { - properties, - required, - } => { - serde_json::json!({"type":"object", "properties": properties.iter().map(|(name, schema)| (name.clone(), legacy_schema_value(schema))).collect::>(), "required": required}) - } - NormalizedSchemaKind::Array { items } => { - let mut value = serde_json::json!({"type":"array"}); - if let Some(items) = items { - value["items"] = legacy_schema_value(items); - } - value - } - NormalizedSchemaKind::Scalar { - scalar_type, - format, - nullable, - default_value, - enum_values, - } => { - let scalar_type = match scalar_type { - NormalizedScalarKind::String => "string", - NormalizedScalarKind::Integer => "integer", - NormalizedScalarKind::Number => "number", - NormalizedScalarKind::Boolean => "boolean", - NormalizedScalarKind::Null => "null", - }; - serde_json::json!({"type":scalar_type, "format":format, "nullable":nullable, "default":default_value.as_ref().map(legacy_literal_value), "enum":enum_values.iter().map(legacy_literal_value).collect::>()}) - } - NormalizedSchemaKind::Unknown => serde_json::json!({}), - }; - if let Some(description) = &schema.description { - value["description"] = Value::String(description.clone()); - } - value -} - -fn legacy_literal_value(value: &NormalizedLiteral) -> Value { - match value { - NormalizedLiteral::String(value) => Value::String(value.clone()), - NormalizedLiteral::Integer(value) => Value::Number((*value).into()), - NormalizedLiteral::Unsigned(value) => Value::Number((*value).into()), - NormalizedLiteral::Number(value) => serde_json::Number::from_f64(*value) - .map(Value::Number) - .unwrap_or(Value::Null), - NormalizedLiteral::Boolean(value) => Value::Bool(*value), - NormalizedLiteral::Null => Value::Null, - } -} - fn schema_contains_reference(schema: &NormalizedSchema, location: &SourceLocation) -> bool { match &schema.kind { NormalizedSchemaKind::Reference { reference } => reference.location == *location, NormalizedSchemaKind::Object { properties, .. } => properties .values() .any(|schema| schema_contains_reference(schema, location)), - NormalizedSchemaKind::Array { items } => items + NormalizedSchemaKind::Array { items, .. } => items .as_deref() .is_some_and(|schema| schema_contains_reference(schema, location)), NormalizedSchemaKind::Composition { variants, .. } => variants @@ -908,6 +899,8 @@ fn method_name(method: crank_core::HttpMethod) -> &'static str { crank_core::HttpMethod::Put => "PUT", crank_core::HttpMethod::Patch => "PATCH", crank_core::HttpMethod::Delete => "DELETE", + crank_core::HttpMethod::Head => "HEAD", + crank_core::HttpMethod::Options => "OPTIONS", } } @@ -918,6 +911,8 @@ fn method_rank(method: crank_core::HttpMethod) -> u8 { crank_core::HttpMethod::Put => 2, crank_core::HttpMethod::Patch => 3, crank_core::HttpMethod::Delete => 4, + crank_core::HttpMethod::Head => 5, + crank_core::HttpMethod::Options => 6, } } diff --git a/crates/crank-import/src/rest/normalize_coverage.rs b/crates/crank-import/src/rest/normalize_coverage.rs index f734c65..ff34f36 100644 --- a/crates/crank-import/src/rest/normalize_coverage.rs +++ b/crates/crank-import/src/rest/normalize_coverage.rs @@ -11,7 +11,9 @@ use crate::rest::model::{ use super::ImportParseError; -pub(super) use super::normalize_schema::{has_reference_schema, typed_schema}; +pub(super) use super::normalize_schema::{ + has_reference_schema, typed_schema, typed_schema_with_property_locations, +}; pub(super) fn validate_coverage(ir: &NormalizedIr) -> Result<(), ImportParseError> { if ir.normalizer_version != NORMALIZER_VERSION || ir.projection_version != PROJECTION_VERSION { @@ -92,6 +94,19 @@ pub(super) fn validate_coverage(ir: &NormalizedIr) -> Result<(), ImportParseErro .flat_map(|operation| &operation.findings), ) .collect::>(); + for finding in &findings { + if super::normalize_finding_validation::matches_source(finding, ir, &source_nodes) + && finding.construct_id == format!("{version}:{}", finding.location.pointer) + { + insert_real_expected( + &mut expected, + &source_nodes, + finding.construct_id.clone(), + finding.location.clone(), + CoverageDisposition::Finding, + )?; + } + } for finding in &findings { let Some(target) = expected.get(&finding.construct_id) else { return Err(ImportParseError::InvalidDocument); @@ -342,6 +357,9 @@ fn openapi_servers( let CanonicalSourceValue::String(url) = &fields.get("url")?.value else { return None; }; + if !super::openapi3_findings::valid_http_server_url(url) { + return None; + } Some((url.trim_end_matches('/').to_owned(), item.location.clone())) }) .unzip() @@ -413,6 +431,8 @@ fn method_rank(method: crank_core::HttpMethod) -> u8 { crank_core::HttpMethod::Put => 2, crank_core::HttpMethod::Patch => 3, crank_core::HttpMethod::Delete => 4, + crank_core::HttpMethod::Head => 5, + crank_core::HttpMethod::Options => 6, } } @@ -423,6 +443,8 @@ fn method_name(method: crank_core::HttpMethod) -> &'static str { crank_core::HttpMethod::Put => "put", crank_core::HttpMethod::Patch => "patch", crank_core::HttpMethod::Delete => "delete", + crank_core::HttpMethod::Head => "head", + crank_core::HttpMethod::Options => "options", } } @@ -518,6 +540,16 @@ fn collect_operation_expectations( if let Some(schema) = &operation.response_schema { collect_schema_expectations(schema, source_nodes, expected)?; } + for variant in &operation.request_body_variants { + if let Some(schema) = &variant.schema { + collect_schema_expectations(schema, source_nodes, expected)?; + } + } + for variant in &operation.response_variants { + if let Some(schema) = &variant.schema { + collect_schema_expectations(schema, source_nodes, expected)?; + } + } Ok(()) } @@ -578,7 +610,9 @@ fn collect_schema_expectations( collect_schema_expectations(child, source_nodes, expected)?; } } - NormalizedSchemaKind::Array { items: Some(child) } => { + NormalizedSchemaKind::Array { + items: Some(child), .. + } => { collect_schema_expectations(child, source_nodes, expected)?; } NormalizedSchemaKind::Composition { variants, .. } => { @@ -639,12 +673,27 @@ fn collect_finding_only_expectations( expected, )?; } - for method in ["head", "options", "trace", "connect"] { + for method in methods.keys().filter(|method| { + let non_method = if ir.source.format == "openapi" { + matches!( + method.as_str(), + "$ref" | "summary" | "description" | "servers" | "parameters" + ) + } else { + matches!(method.as_str(), "$ref" | "parameters") + }; + !method.starts_with("x-") + && !non_method + && !matches!( + method.as_str(), + "get" | "post" | "put" | "patch" | "delete" | "head" | "options" + ) + }) { if let Some(node) = methods.get(method) { insert_finding_pointer(version, node, expected)?; } } - for method in ["get", "post", "put", "patch", "delete"] { + for method in ["get", "post", "put", "patch", "delete", "head", "options"] { if let Some(node) = methods.get(method) { match &node.value { CanonicalSourceValue::Object(operation) => { @@ -682,13 +731,16 @@ fn collect_invalid_openapi_server_findings( return Ok(()); }; for server in items { - let valid = matches!( - &server.value, - CanonicalSourceValue::Object(fields) - if matches!(fields.get("url").map(|node| &node.value), Some(CanonicalSourceValue::String(_))) - ); - if !valid { - insert_finding_pointer(version, server, expected)?; + match &server.value { + CanonicalSourceValue::Object(fields) => match fields.get("url") { + Some(url) if matches!(&url.value, CanonicalSourceValue::String(value) if !super::openapi3_findings::valid_http_server_url(value)) => + { + insert_finding_pointer(version, url, expected)?; + } + Some(url) if matches!(url.value, CanonicalSourceValue::String(_)) => {} + _ => insert_finding_pointer(version, server, expected)?, + }, + _ => insert_finding_pointer(version, server, expected)?, } } Ok(()) @@ -746,8 +798,11 @@ fn collect_dropped_parameter_findings( return Err(ImportParseError::InvalidDocument); }; let supported = match format { - "openapi" => matches!(location.as_str(), "path" | "query" | "header"), - "swagger" => matches!(location.as_str(), "path" | "query" | "header" | "body"), + "openapi" => matches!(location.as_str(), "path" | "query" | "header" | "cookie"), + "swagger" => matches!( + location.as_str(), + "path" | "query" | "header" | "body" | "formData" + ), _ => false, }; if !supported { diff --git a/crates/crank-import/src/rest/normalize_finding_validation.rs b/crates/crank-import/src/rest/normalize_finding_validation.rs new file mode 100644 index 0000000..002ec27 --- /dev/null +++ b/crates/crank-import/src/rest/normalize_finding_validation.rs @@ -0,0 +1,218 @@ +use std::collections::BTreeMap; + +use crate::rest::model::{ + CanonicalSourceNode, CanonicalSourceValue, ImportFindingSeverity, NormalizedFinding, + NormalizedIr, +}; + +pub(super) fn matches_source( + finding: &NormalizedFinding, + ir: &NormalizedIr, + nodes: &BTreeMap, +) -> bool { + let pointer = finding.location.pointer.as_str(); + let Some(node) = nodes.get(pointer).copied() else { + return false; + }; + let is_error = finding.severity == ImportFindingSeverity::Error; + match finding.code.as_str() { + "unsupported_parameter_style" if is_error => parameter_style(pointer, node, nodes), + "unsupported_parameter_content" if is_error => pointer.ends_with("/content"), + "missing_parameter_schema" if is_error => { + matches!(&node.value, CanonicalSourceValue::Object(fields) if !fields.contains_key("schema") && !fields.contains_key("content")) + } + "unsupported_request_body" if is_error => pointer.ends_with("/requestBody"), + "unsupported_request_media_type" | "unsupported_xml_request_media_type" if is_error => { + media_from_pointer(pointer).is_some_and(|media| !supported_request_media(&media)) + } + "unsupported_response_media_type" | "unsupported_xml_response_media_type" if is_error => { + media_from_pointer(pointer).is_some_and(|media| !supported_response_media(&media)) + } + "unsupported_multipart_encoding" | "unsupported_form_encoding" if is_error => { + pointer.contains("/encoding") + } + "unsupported_form_schema" if is_error => form_schema_shape(pointer, node), + "missing_request_media_schema" | "missing_response_media_schema" if is_error => { + matches!(&node.value, CanonicalSourceValue::Object(fields) if !fields.contains_key("schema")) + } + "unsupported_consumes" if is_error => { + matches!(&node.value, CanonicalSourceValue::String(media) if !supported_request_media(media)) + } + "unsupported_produces" if is_error => { + matches!(&node.value, CanonicalSourceValue::String(media) if !supported_response_media(media)) + } + "path_parameter_not_required" if is_error => { + matches!(&node.value, CanonicalSourceValue::Object(fields) if !matches!(fields.get("required").map(|node| &node.value), Some(CanonicalSourceValue::Boolean(true)))) + } + "path_parameter_placeholder_missing" if is_error => ir.operations.iter().any(|operation| { + finding.operation_key.as_deref() == Some(operation.key.as_str()) + && matches!(&node.value, CanonicalSourceValue::Object(fields) if matches!(fields.get("name").map(|node| &node.value), Some(CanonicalSourceValue::String(name)) if !operation.path.contains(&format!("{{{name}}}")))) + }), + "unsupported_schema_keyword" if is_error => schema_keyword(pointer, node), + "unsupported_schema_enum" if is_error => { + pointer.ends_with("/enum") + && matches!(&node.value, CanonicalSourceValue::Array(items) if items.iter().any(|item| !matches!(item.value, CanonicalSourceValue::String(_)))) + } + "secret_like_example" if finding.severity == ImportFindingSeverity::Warning => { + pointer.contains("/example") && matches!(&node.value, CanonicalSourceValue::String(value) if secret_like(pointer, value)) + } + "invalid_server" if is_error => invalid_server(pointer, node), + _ => false, + } +} + +fn parameter_style( + pointer: &str, + node: &CanonicalSourceNode, + nodes: &BTreeMap, +) -> bool { + if pointer.ends_with("/schema") { + return compound_parameter(node); + } + if pointer.ends_with("/collectionFormat") { + return true; + } + if compound_parameter(node) { + return true; + } + let Some((parameter_pointer, field)) = pointer.rsplit_once('/') else { + return false; + }; + let location = nodes + .get(&format!("{parameter_pointer}/in")) + .and_then(|node| match &node.value { + CanonicalSourceValue::String(value) => Some(value.as_str()), + _ => None, + }); + match (field, &node.value, location) { + ("style", CanonicalSourceValue::String(style), Some("path" | "header")) => { + style != "simple" + } + ("style", CanonicalSourceValue::String(style), Some("query" | "cookie")) => style != "form", + ("style", _, Some(_)) => true, + ("explode", CanonicalSourceValue::Boolean(value), Some("path" | "header")) => *value, + ("explode", CanonicalSourceValue::Boolean(value), Some("query" | "cookie")) => !*value, + ("explode", _, Some(_)) => true, + ("allowReserved", value, _) => !matches!(value, CanonicalSourceValue::Boolean(false)), + _ => false, + } +} + +fn compound_parameter(node: &CanonicalSourceNode) -> bool { + matches!(&node.value, CanonicalSourceValue::Object(fields) if matches!(fields.get("type").map(|node| &node.value), Some(CanonicalSourceValue::String(value)) if matches!(value.as_str(), "array" | "object"))) +} + +fn schema_keyword(pointer: &str, node: &CanonicalSourceNode) -> bool { + const UNSUPPORTED: &[&str] = &[ + "additionalProperties", + "unevaluatedProperties", + "prefixItems", + "contains", + "dependentSchemas", + "if", + "then", + "else", + "not", + "propertyNames", + "minimum", + "maximum", + "exclusiveMinimum", + "exclusiveMaximum", + "minLength", + "maxLength", + "pattern", + "minItems", + "maxItems", + "uniqueItems", + "const", + "multipleOf", + "minProperties", + "maxProperties", + "dependentRequired", + ]; + let field = pointer.rsplit('/').next().unwrap_or_default(); + if UNSUPPORTED.contains(&field) { + return true; + } + field == "type" + && matches!(&node.value, CanonicalSourceValue::Array(items) if { + let concrete = items.iter().filter(|item| matches!(&item.value, CanonicalSourceValue::String(value) if value != "null")).count(); + items.len() != 2 || concrete != 1 || !items.iter().any(|item| matches!(&item.value, CanonicalSourceValue::String(value) if value == "null")) + }) +} + +fn form_schema_shape(pointer: &str, node: &CanonicalSourceNode) -> bool { + if !pointer.contains("/requestBody/content/application~1x-www-form-urlencoded/schema") + && !pointer.contains("/requestBody/content/multipart~1form-data/schema") + && !pointer.contains("/parameters/") + { + return false; + } + let object = matches!( + &node.value, + CanonicalSourceValue::Object(fields) + if fields.contains_key("properties") + || matches!(fields.get("type").map(|field| &field.value), Some(CanonicalSourceValue::String(value)) if value == "object") + ); + let nested_array = pointer.ends_with("/items") + && matches!( + &node.value, + CanonicalSourceValue::Object(fields) + if matches!(fields.get("type").map(|field| &field.value), Some(CanonicalSourceValue::String(value)) if value == "array") + ); + pointer.ends_with("/schema") || object || nested_array +} + +fn media_from_pointer(pointer: &str) -> Option { + Some( + pointer + .rsplit('/') + .next()? + .replace("~1", "/") + .replace("~0", "~"), + ) +} + +fn supported_request_media(media: &str) -> bool { + matches!( + media, + "application/json" | "application/x-www-form-urlencoded" | "multipart/form-data" + ) || media.ends_with("+json") +} + +fn supported_response_media(media: &str) -> bool { + media == "application/json" || media.ends_with("+json") +} + +fn secret_like(pointer: &str, value: &str) -> bool { + let pointer = pointer.to_ascii_lowercase(); + let value = value.to_ascii_lowercase(); + [ + "token", + "secret", + "password", + "api_key", + "apikey", + "authorization", + ] + .iter() + .any(|marker| pointer.contains(marker) || value.contains(marker)) + || value.starts_with("bearer ") + || value.starts_with("sk-") +} + +fn invalid_server(pointer: &str, node: &CanonicalSourceNode) -> bool { + if pointer == "/host" { + return !matches!(&node.value, CanonicalSourceValue::String(host) if !host.is_empty() && !host.contains('@') && !host.chars().any(char::is_whitespace)); + } + if pointer == "/basePath" { + return !matches!(&node.value, CanonicalSourceValue::String(path) if (path.is_empty() || path.starts_with('/')) && !path.chars().any(char::is_control)); + } + if pointer.starts_with("/schemes/") { + return !matches!(&node.value, CanonicalSourceValue::String(scheme) if matches!(scheme.as_str(), "http" | "https")); + } + if pointer.ends_with("/url") { + return matches!(&node.value, CanonicalSourceValue::String(url) if !super::openapi3_findings::valid_http_server_url(url)); + } + !matches!(&node.value, CanonicalSourceValue::Object(fields) if matches!(fields.get("url").map(|node| &node.value), Some(CanonicalSourceValue::String(_)))) +} diff --git a/crates/crank-import/src/rest/normalize_projection.rs b/crates/crank-import/src/rest/normalize_projection.rs new file mode 100644 index 0000000..3807065 --- /dev/null +++ b/crates/crank-import/src/rest/normalize_projection.rs @@ -0,0 +1,159 @@ +use std::collections::BTreeMap; + +use serde_json::Value; + +use crate::rest::model::{ + ImportFinding, NormalizedLiteral, NormalizedOperation, NormalizedScalarKind, NormalizedSchema, + NormalizedSchemaKind, RestImportOperation, RestImportParameter, RestRequestBodyVariant, + RestResponseVariant, +}; + +pub(super) fn operation_from_normalized(operation: &NormalizedOperation) -> RestImportOperation { + RestImportOperation { + key: operation.key.clone(), + method: operation.method, + path: operation.path.clone(), + operation_id: operation.operation_id.clone(), + summary: operation.summary.clone(), + description: operation.description.clone(), + tags: operation.tags.clone(), + parameters: operation + .parameters + .iter() + .map(|parameter| RestImportParameter { + name: parameter.name.clone(), + location: parameter.location, + required: parameter.required, + description: parameter.description.clone(), + schema: parameter.schema.as_ref().map(schema_value), + source_location: parameter.source_location.clone(), + schema_source_location: None, + }) + .collect(), + request_body_schema: operation.request_body_schema.as_ref().map(schema_value), + request_body_schema_location: None, + request_body_variants: operation + .request_body_variants + .iter() + .map(|variant| RestRequestBodyVariant { + content_type: variant.content_type.clone(), + required: variant.required, + schema: variant.schema.as_ref().map(schema_value), + multipart_field_mime_types: variant.multipart_field_mime_types.clone(), + source_location: variant.source_location.clone(), + schema_source_location: None, + schema_property_source_locations: BTreeMap::new(), + }) + .collect(), + response_schema: operation.response_schema.as_ref().map(schema_value), + response_schema_location: None, + response_variants: operation + .response_variants + .iter() + .map(|variant| RestResponseVariant { + status_code: variant.status_code, + content_type: variant.content_type.clone(), + schema: variant.schema.as_ref().map(schema_value), + source_location: variant.source_location.clone(), + schema_source_location: None, + }) + .collect(), + servers: operation.servers.clone(), + findings: operation + .findings + .iter() + .map(|finding| ImportFinding { + code: finding.code.clone(), + severity: finding.severity.clone(), + message: finding.message.clone(), + operation_key: finding.operation_key.clone(), + }) + .collect(), + internal_finding_locations: Vec::new(), + } +} + +fn schema_value(schema: &NormalizedSchema) -> Value { + let mut value = match &schema.kind { + NormalizedSchemaKind::Reference { reference } => serde_json::json!({"$ref": reference.uri}), + NormalizedSchemaKind::Composition { operator, variants } => serde_json::json!({ + operator: variants.iter().map(schema_value).collect::>(), + "x-crank-lossless-composition": true, + }), + NormalizedSchemaKind::Object { + properties, + required, + nullable, + default_value, + } => { + let mut value = serde_json::json!({ + "type": "object", + "properties": properties.iter().map(|(name, schema)| (name.clone(), schema_value(schema))).collect::>(), + "required": required, + "nullable": nullable, + }); + insert_default(&mut value, default_value.as_ref()); + value + } + NormalizedSchemaKind::Array { + items, + nullable, + default_value, + } => { + let mut value = serde_json::json!({"type": "array", "nullable": nullable}); + if let Some(items) = items { + value["items"] = schema_value(items); + } + insert_default(&mut value, default_value.as_ref()); + value + } + NormalizedSchemaKind::Scalar { + scalar_type, + format, + nullable, + default_value, + enum_values, + } => { + let scalar_type = match scalar_type { + NormalizedScalarKind::String => "string", + NormalizedScalarKind::Integer => "integer", + NormalizedScalarKind::Number => "number", + NormalizedScalarKind::Boolean => "boolean", + NormalizedScalarKind::Null => "null", + }; + let mut value = serde_json::json!({"type": scalar_type, "nullable": nullable}); + if let Some(format) = format { + value["format"] = Value::String(format.clone()); + } + if !enum_values.is_empty() { + value["enum"] = Value::Array(enum_values.iter().map(literal_value).collect()); + } + insert_default(&mut value, default_value.as_ref()); + value + } + NormalizedSchemaKind::Unknown => serde_json::json!({}), + }; + if let Some(description) = &schema.description { + value["description"] = Value::String(description.clone()); + } + value +} + +fn insert_default(value: &mut Value, default: Option<&NormalizedLiteral>) { + if let Some(default) = default { + value["default"] = literal_value(default); + } +} + +fn literal_value(value: &NormalizedLiteral) -> Value { + match value { + NormalizedLiteral::String(value) => Value::String(value.clone()), + NormalizedLiteral::Integer(value) => Value::Number((*value).into()), + NormalizedLiteral::Unsigned(value) => Value::Number((*value).into()), + NormalizedLiteral::Number(value) => serde_json::Number::from_f64(*value) + .map(Value::Number) + .unwrap_or(Value::Null), + NormalizedLiteral::Boolean(value) => Value::Bool(*value), + NormalizedLiteral::Null => Value::Null, + } +} diff --git a/crates/crank-import/src/rest/normalize_schema.rs b/crates/crank-import/src/rest/normalize_schema.rs index 776b481..ec9dd60 100644 --- a/crates/crank-import/src/rest/normalize_schema.rs +++ b/crates/crank-import/src/rest/normalize_schema.rs @@ -8,12 +8,71 @@ use crate::rest::model::{ use super::normalize_coverage::escape_pointer; +pub(super) fn typed_schema_with_property_locations( + value: &Value, + pointer: &str, + property_locations: &std::collections::BTreeMap, + coverage: &mut Vec, +) -> NormalizedSchema { + if property_locations.is_empty() { + return typed_schema(value, pointer, "", coverage); + } + let mut root_value = value.clone(); + if let Some(object) = root_value.as_object_mut() { + object.remove("properties"); + } + let mut normalized = typed_schema(&root_value, pointer, "", coverage); + let Some(properties) = value.get("properties").and_then(Value::as_object) else { + return normalized; + }; + let NormalizedSchemaKind::Object { + properties: normalized_properties, + .. + } = &mut normalized.kind + else { + return normalized; + }; + for (name, schema) in properties { + let Some(location) = property_locations.get(name) else { + continue; + }; + normalized_properties.insert( + name.clone(), + typed_schema(schema, &location.pointer, "", coverage), + ); + } + normalized +} + pub(super) fn typed_schema( value: &Value, pointer: &str, _id: &str, coverage: &mut Vec, ) -> NormalizedSchema { + let normalized_type_value; + let value = if let Some(types) = value.get("type").and_then(Value::as_array) { + let concrete = types + .iter() + .filter_map(Value::as_str) + .filter(|value| *value != "null") + .collect::>(); + if types.iter().any(|value| value.as_str() == Some("null")) && concrete.len() == 1 { + normalized_type_value = { + let mut normalized = value.clone(); + if let Some(object) = normalized.as_object_mut() { + object.insert("type".to_owned(), Value::String(concrete[0].to_owned())); + object.insert("nullable".to_owned(), Value::Bool(true)); + } + normalized + }; + &normalized_type_value + } else { + value + } + } else { + value + }; // IDs are derived from RFC 6901 locations rather than user-controlled // property names, so escaped keys cannot collide with one another. let id = format!("schema:{}", escape_pointer(pointer)); @@ -105,6 +164,11 @@ pub(super) fn typed_schema( NormalizedSchemaKind::Object { properties, required, + nullable: value + .get("nullable") + .and_then(Value::as_bool) + .unwrap_or(false), + default_value: value.get("default").and_then(normalized_literal), } } else if value.get("type").and_then(Value::as_str) == Some("array") { NormalizedSchemaKind::Array { @@ -116,6 +180,11 @@ pub(super) fn typed_schema( coverage, )) }), + nullable: value + .get("nullable") + .and_then(Value::as_bool) + .unwrap_or(false), + default_value: value.get("default").and_then(normalized_literal), } } else if let Some(raw_type) = value.get("type").and_then(Value::as_str) { NormalizedSchemaKind::Scalar { @@ -190,7 +259,7 @@ pub(super) fn has_reference_schema(schema: Option<&NormalizedSchema>) -> bool { Some(NormalizedSchemaKind::Object { properties, .. }) => properties .values() .any(|schema| has_reference_schema(Some(schema))), - Some(NormalizedSchemaKind::Array { items }) => has_reference_schema(items.as_deref()), + Some(NormalizedSchemaKind::Array { items, .. }) => has_reference_schema(items.as_deref()), Some(NormalizedSchemaKind::Composition { variants, .. }) => variants .iter() .any(|schema| has_reference_schema(Some(schema))), diff --git a/crates/crank-import/src/rest/openapi3.rs b/crates/crank-import/src/rest/openapi3.rs index 66e8206..758e2cd 100644 --- a/crates/crank-import/src/rest/openapi3.rs +++ b/crates/crank-import/src/rest/openapi3.rs @@ -3,8 +3,8 @@ use serde_json::Value; use crate::rest::{ model::{ - ImportFinding, ImportFindingSeverity, RestImportDocument, RestImportOperation, - RestImportParameter, RestParameterLocation, + ImportFinding, RestImportDocument, RestImportOperation, RestImportParameter, + RestParameterLocation, RestRequestBodyVariant, RestResponseVariant, }, normalize::ImportParseError, recommendations::{document_blocker, document_finding}, @@ -59,13 +59,13 @@ fn parse_document_v2(root: &Value) -> Result Result Result Result Result Result Result, base_pointer: &str) -> ParsedServers { findings.push(server_blocker(&pointer)); return None; }; + if !super::openapi3_findings::valid_http_server_url(url) { + findings.push(server_blocker(&format!("{pointer}/url"))); + return None; + } Some(url.trim_end_matches('/').to_owned()) }) .collect() @@ -559,14 +578,7 @@ fn parameters(value: Option<&Value>, base_pointer: &str) -> ParsedParameters { "path" => RestParameterLocation::Path, "query" => RestParameterLocation::Query, "header" => RestParameterLocation::Header, - "cookie" => { - findings.push(parameter_blocker( - "unsupported_cookie_parameter", - "Cookie parameter пока не поддерживается и не был импортирован.", - &pointer, - )); - return None; - } + "cookie" => RestParameterLocation::Cookie, _ => { findings.push(parameter_blocker( "unsupported_parameter_location", @@ -576,14 +588,81 @@ fn parameters(value: Option<&Value>, base_pointer: &str) -> ParsedParameters { return None; } }; + let expected_style = match location { + RestParameterLocation::Path | RestParameterLocation::Header => "simple", + RestParameterLocation::Query | RestParameterLocation::Cookie => "form", + }; + if item + .get("style") + .is_some_and(|style| style.as_str() != Some(expected_style)) + { + findings.push(parameter_blocker( + "unsupported_parameter_style", + "Параметр использует style, который текущий REST mapping не сериализует без потерь.", + &format!("{pointer}/style"), + )); + } + let default_explode = matches!( + location, + RestParameterLocation::Query | RestParameterLocation::Cookie + ); + if item + .get("explode") + .is_some_and(|explode| explode.as_bool() != Some(default_explode)) + { + findings.push(parameter_blocker( + "unsupported_parameter_style", + "Параметр использует explode, который текущий REST mapping не сериализует без потерь.", + &format!("{pointer}/explode"), + )); + } + if item + .get("allowReserved") + .is_some_and(|value| value.as_bool() != Some(false)) + { + findings.push(parameter_blocker( + "unsupported_parameter_style", + "allowReserved=true не поддерживается текущим REST mapping.", + &format!("{pointer}/allowReserved"), + )); + } + if item.get("content").is_some() { + findings.push(parameter_blocker( + "unsupported_parameter_content", + "Parameter content не поддерживается текущим REST mapping.", + &format!("{pointer}/content"), + )); + } + if item.get("schema").is_none() && item.get("content").is_none() { + findings.push(parameter_blocker( + "missing_parameter_schema", + "Параметр не содержит schema.", + &pointer, + )); + } + if item.get("schema").is_some_and(|schema| { + matches!(schema.get("type").and_then(Value::as_str), Some("array" | "object")) + }) { + findings.push(parameter_blocker( + "unsupported_parameter_style", + "Array/object parameter serialization не поддерживается текущим REST mapping.", + &format!("{pointer}/schema"), + )); + } + if let Some(schema) = item.get("schema") { + super::openapi3_findings::schema_findings( + schema, + &format!("{pointer}/schema"), + &mut findings, + ); + } Some(RestImportParameter { name: item.get("name").and_then(Value::as_str)?.to_owned(), location, required: item .get("required") .and_then(Value::as_bool) - .unwrap_or(false) - || location == RestParameterLocation::Path, + .unwrap_or(false), description: item .get("description") .and_then(Value::as_str) @@ -672,6 +751,87 @@ fn request_body_schema( }) } +fn request_body_variants( + operation: &Value, + operation_pointer: &str, +) -> Vec { + let Some(body) = operation.get("requestBody") else { + return Vec::new(); + }; + let required = body + .get("required") + .and_then(Value::as_bool) + .unwrap_or(false); + let Some(content) = body.get("content").and_then(Value::as_object) else { + return Vec::new(); + }; + content + .iter() + .filter(|(content_type, media)| { + supported_request_content_type(content_type) && media.get("schema").is_some() + }) + .map(|(content_type, media)| RestRequestBodyVariant { + content_type: content_type.clone(), + required, + schema: media.get("schema").cloned(), + multipart_field_mime_types: if content_type == "multipart/form-data" { + multipart_field_mime_types(media) + } else { + Default::default() + }, + source_location: crate::rest::model::SourceLocation { + pointer: format!( + "{operation_pointer}/requestBody/content/{}", + content_type.replace('~', "~0").replace('/', "~1") + ), + }, + schema_source_location: media.get("schema").map(|_| { + crate::rest::model::SourceLocation { + pointer: format!( + "{operation_pointer}/requestBody/content/{}/schema", + content_type.replace('~', "~0").replace('/', "~1") + ), + } + }), + schema_property_source_locations: Default::default(), + }) + .collect() +} + +fn multipart_field_mime_types(media: &Value) -> std::collections::BTreeMap> { + media + .get("encoding") + .and_then(Value::as_object) + .map(|encoding| { + encoding + .iter() + .filter_map(|(field, value)| { + let mime_types = value + .get("contentType") + .and_then(Value::as_str) + .map(|value| { + value + .split(',') + .map(str::trim) + .filter(|value| !value.is_empty()) + .map(ToOwned::to_owned) + .collect::>() + }) + .unwrap_or_default(); + (!mime_types.is_empty()).then(|| (field.clone(), mime_types)) + }) + .collect() + }) + .unwrap_or_default() +} + +fn supported_request_content_type(content_type: &str) -> bool { + content_type == "application/x-www-form-urlencoded" + || content_type == "multipart/form-data" + || content_type == "application/json" + || content_type.ends_with("+json") +} + fn response_schema( operation: &Value, operation_pointer: &str, @@ -752,33 +912,85 @@ fn response_json_schema( }) } -fn operation_findings(operation: &Value) -> Vec { - let mut findings = Vec::new(); - if operation.get("requestBody").is_some() && request_body_schema(operation, "").is_none() { - findings.push(document_finding( - "unsupported_request_body", - "У метода есть requestBody, но JSON schema не найдена.", - )); - } - findings -} - -fn method_from_lower(value: &str) -> Option { - match value { - "get" => Some(HttpMethod::Get), - "post" => Some(HttpMethod::Post), - "put" => Some(HttpMethod::Put), - "patch" => Some(HttpMethod::Patch), - "delete" => Some(HttpMethod::Delete), - _ => None, - } -} - -fn path_item_blocker(_path: &str) -> ImportFinding { - ImportFinding { - code: "invalid_path_item".to_owned(), - severity: ImportFindingSeverity::Error, - message: "Path Item имеет неверную структуру и не был интерпретирован.".to_owned(), - operation_key: None, - } +fn response_variants( + operation: &Value, + operation_pointer: &str, + method: HttpMethod, +) -> Vec { + let Some(responses) = operation.get("responses").and_then(Value::as_object) else { + return Vec::new(); + }; + let mut variants = responses + .iter() + .filter_map(|(code, response)| { + let status_code = code + .parse::() + .ok() + .filter(|code| (200..300).contains(code))?; + let base = format!( + "{operation_pointer}/responses/{}", + code.replace('~', "~0").replace('/', "~1") + ); + if method == HttpMethod::Head { + return Some(vec![RestResponseVariant { + status_code, + content_type: None, + schema: None, + source_location: crate::rest::model::SourceLocation { pointer: base }, + schema_source_location: None, + }]); + } + let content = response.get("content").and_then(Value::as_object); + Some(match content { + None => vec![RestResponseVariant { + status_code, + content_type: None, + schema: None, + source_location: crate::rest::model::SourceLocation { pointer: base }, + schema_source_location: None, + }], + Some(content) if content.is_empty() => vec![RestResponseVariant { + status_code, + content_type: None, + schema: None, + source_location: crate::rest::model::SourceLocation { pointer: base }, + schema_source_location: None, + }], + Some(content) => content + .iter() + .filter(|(content_type, _)| { + *content_type == "application/json" || content_type.ends_with("+json") + }) + .filter(|(_, media)| media.get("schema").is_some()) + .map(|(content_type, media)| RestResponseVariant { + status_code, + content_type: Some(content_type.clone()), + schema: media.get("schema").cloned(), + source_location: crate::rest::model::SourceLocation { + pointer: format!( + "{base}/content/{}", + content_type.replace('~', "~0").replace('/', "~1") + ), + }, + schema_source_location: media.get("schema").map(|_| { + crate::rest::model::SourceLocation { + pointer: format!( + "{base}/content/{}/schema", + content_type.replace('~', "~0").replace('/', "~1") + ), + } + }), + }) + .collect(), + }) + }) + .flatten() + .collect::>(); + variants.sort_by(|left, right| { + (left.status_code, left.content_type.as_deref().unwrap_or("")).cmp(&( + right.status_code, + right.content_type.as_deref().unwrap_or(""), + )) + }); + variants } diff --git a/crates/crank-import/src/rest/openapi3_findings.rs b/crates/crank-import/src/rest/openapi3_findings.rs new file mode 100644 index 0000000..b9dd4d3 --- /dev/null +++ b/crates/crank-import/src/rest/openapi3_findings.rs @@ -0,0 +1,485 @@ +use serde_json::Value; + +use crate::rest::{ + model::{ImportFinding, RestImportParameter, RestParameterLocation, SourceLocation}, + recommendations::document_blocker, +}; + +pub(super) fn operation( + operation: &Value, + operation_pointer: &str, +) -> Vec<(ImportFinding, SourceLocation)> { + let mut findings = Vec::new(); + if operation.get("requestBody").is_some() && supported_request_variants(operation) == 0 { + push( + &mut findings, + "unsupported_request_body", + "У requestBody нет поддерживаемой schema.", + &format!("{operation_pointer}/requestBody"), + ); + } + if let Some(content) = operation + .pointer("/requestBody/content") + .and_then(Value::as_object) + { + for (content_type, media) in content { + let media_pointer = format!( + "{operation_pointer}/requestBody/content/{}", + escape(content_type) + ); + if !supported_request_media(content_type) { + let code = if content_type.contains("xml") { + "unsupported_xml_request_media_type" + } else { + "unsupported_request_media_type" + }; + push( + &mut findings, + code, + "Request media type не поддерживается без fallback.", + &media_pointer, + ); + } + if supported_request_media(content_type) && media.get("schema").is_none() { + push( + &mut findings, + "missing_request_media_schema", + "Request media type не содержит schema.", + &media_pointer, + ); + } + if let Some(schema) = media.get("schema") { + schema_findings(schema, &format!("{media_pointer}/schema"), &mut findings); + } + if matches!( + content_type.as_str(), + "application/x-www-form-urlencoded" | "multipart/form-data" + ) && let Some(schema) = media.get("schema") + { + form_schema_findings(schema, &format!("{media_pointer}/schema"), &mut findings); + } + if content_type == "application/x-www-form-urlencoded" { + form_encoding_findings(media, &media_pointer, &mut findings); + } + if content_type == "multipart/form-data" { + multipart_encoding_findings(media, &media_pointer, &mut findings); + } + } + } + if let Some(responses) = operation.get("responses").and_then(Value::as_object) { + for (status, response) in responses { + let Some(content) = response.get("content").and_then(Value::as_object) else { + continue; + }; + for (content_type, media) in content { + let media_pointer = format!( + "{operation_pointer}/responses/{}/content/{}", + escape(status), + escape(content_type) + ); + if !supported_response_media(content_type) { + let code = if content_type.contains("xml") { + "unsupported_xml_response_media_type" + } else { + "unsupported_response_media_type" + }; + push( + &mut findings, + code, + "Response media type не поддерживается без fallback.", + &media_pointer, + ); + } else if let Some(schema) = media.get("schema") { + schema_findings(schema, &format!("{media_pointer}/schema"), &mut findings); + } else { + push( + &mut findings, + "missing_response_media_schema", + "Response media type не содержит schema.", + &media_pointer, + ); + } + } + } + } + findings +} + +fn form_encoding_findings( + media: &Value, + media_pointer: &str, + findings: &mut Vec<(ImportFinding, SourceLocation)>, +) { + let Some(encoding_value) = media.get("encoding") else { + return; + }; + let Some(encoding) = encoding_value.as_object() else { + push( + findings, + "unsupported_form_encoding", + "Form encoding должен быть объектом.", + &format!("{media_pointer}/encoding"), + ); + return; + }; + for (field, settings) in encoding { + let field_pointer = format!("{media_pointer}/encoding/{}", escape(field)); + let Some(settings) = settings.as_object() else { + push( + findings, + "unsupported_form_encoding", + "Form encoding имеет неподдерживаемую структуру.", + &field_pointer, + ); + continue; + }; + for (key, value) in settings { + let supported = match key.as_str() { + "style" => value.as_str() == Some("form"), + "explode" => value.as_bool() == Some(true), + _ => false, + }; + if !supported { + push( + findings, + "unsupported_form_encoding", + "Form encoding metadata не поддерживается wire contract.", + &format!("{field_pointer}/{}", escape(key)), + ); + } + } + } +} + +pub(super) fn form_schema_findings( + schema: &Value, + pointer: &str, + findings: &mut Vec<(ImportFinding, SourceLocation)>, +) { + if !object_schema(schema) { + push( + findings, + "unsupported_form_schema", + "Form body должен быть object со scalar, file или array полями.", + pointer, + ); + return; + } + if let Some(properties) = schema.get("properties").and_then(Value::as_object) { + for (name, property) in properties { + form_field_schema_findings( + property, + &format!("{pointer}/properties/{}", escape(name)), + findings, + ); + } + } +} + +pub(super) fn form_field_schema_findings( + schema: &Value, + pointer: &str, + findings: &mut Vec<(ImportFinding, SourceLocation)>, +) { + form_field_schema_findings_inner(schema, pointer, true, findings); +} + +fn form_field_schema_findings_inner( + schema: &Value, + pointer: &str, + array_allowed: bool, + findings: &mut Vec<(ImportFinding, SourceLocation)>, +) { + if object_schema(schema) { + push( + findings, + "unsupported_form_schema", + "Вложенный object field не поддерживается form wire contract.", + pointer, + ); + return; + } + if schema.get("type").and_then(Value::as_str) == Some("array") { + if !array_allowed { + push( + findings, + "unsupported_form_schema", + "Вложенные arrays не поддерживаются form wire contract.", + pointer, + ); + return; + } + if let Some(items) = schema.get("items") { + form_field_schema_findings_inner(items, &format!("{pointer}/items"), false, findings); + } + } + for operator in ["allOf", "oneOf", "anyOf"] { + if let Some(variants) = schema.get(operator).and_then(Value::as_array) { + for (index, variant) in variants.iter().enumerate() { + form_field_schema_findings_inner( + variant, + &format!("{pointer}/{operator}/{index}"), + array_allowed, + findings, + ); + } + } + } +} + +fn object_schema(schema: &Value) -> bool { + schema.get("properties").is_some() + || schema.get("type").and_then(Value::as_str) == Some("object") +} + +fn multipart_encoding_findings( + media: &Value, + media_pointer: &str, + findings: &mut Vec<(ImportFinding, SourceLocation)>, +) { + let Some(encoding_value) = media.get("encoding") else { + return; + }; + let Some(encoding) = encoding_value.as_object() else { + push( + findings, + "unsupported_multipart_encoding", + "Multipart encoding должен быть объектом.", + &format!("{media_pointer}/encoding"), + ); + return; + }; + for (field, settings) in encoding { + let field_pointer = format!("{media_pointer}/encoding/{}", escape(field)); + let Some(settings) = settings.as_object() else { + push( + findings, + "unsupported_multipart_encoding", + "Multipart encoding имеет неподдерживаемую структуру.", + &field_pointer, + ); + continue; + }; + for key in settings.keys().filter(|key| key.as_str() != "contentType") { + push( + findings, + "unsupported_multipart_encoding", + "Multipart encoding metadata не поддерживается wire contract.", + &format!("{field_pointer}/{}", escape(key)), + ); + } + if let Some(content_type) = settings.get("contentType") { + let source_field = media.pointer(&format!("/schema/properties/{}", escape(field))); + let invalid_mime = content_type.as_str().is_none_or(|value| { + value.split(',').map(str::trim).any(|mime| { + mime.is_empty() || !mime.contains('/') || mime.chars().any(char::is_control) + }) + }); + if invalid_mime || !source_field.is_some_and(binary_schema) { + push( + findings, + "unsupported_multipart_encoding", + "Multipart contentType поддерживается только для binary/file field с валидным MIME.", + &format!("{field_pointer}/contentType"), + ); + } + } + } +} + +fn binary_schema(schema: &Value) -> bool { + schema.get("type").and_then(Value::as_str) == Some("string") + && schema.get("format").and_then(Value::as_str) == Some("binary") + || schema.get("type").and_then(Value::as_str) == Some("array") + && schema.get("items").is_some_and(binary_schema) +} + +pub(super) fn schema_findings( + schema: &Value, + pointer: &str, + findings: &mut Vec<(ImportFinding, SourceLocation)>, +) { + if let Some(types) = schema.get("type").and_then(Value::as_array) { + let concrete = types + .iter() + .filter_map(Value::as_str) + .filter(|value| *value != "null") + .count(); + let supported = types.len() == 2 + && concrete == 1 + && types.iter().any(|value| value.as_str() == Some("null")); + if !supported { + push( + findings, + "unsupported_schema_keyword", + "Schema type array содержит неподдерживаемую комбинацию.", + &format!("{pointer}/type"), + ); + } + } + if schema + .get("enum") + .and_then(Value::as_array) + .is_some_and(|values| values.iter().any(|value| !value.is_string())) + { + push( + findings, + "unsupported_schema_enum", + "Non-string enum не поддерживается executable schema.", + &format!("{pointer}/enum"), + ); + } + for keyword in [ + "additionalProperties", + "unevaluatedProperties", + "prefixItems", + "contains", + "dependentSchemas", + "if", + "then", + "else", + "not", + "propertyNames", + "minimum", + "maximum", + "exclusiveMinimum", + "exclusiveMaximum", + "minLength", + "maxLength", + "pattern", + "minItems", + "maxItems", + "uniqueItems", + "const", + "multipleOf", + "minProperties", + "maxProperties", + "dependentRequired", + ] { + if schema.get(keyword).is_some() { + push( + findings, + "unsupported_schema_keyword", + "Schema keyword не поддерживается executable schema.", + &format!("{pointer}/{keyword}"), + ); + } + } + if let Some(properties) = schema.get("properties").and_then(Value::as_object) { + for (name, child) in properties { + schema_findings( + child, + &format!("{pointer}/properties/{}", escape(name)), + findings, + ); + } + } + if let Some(items) = schema.get("items") { + schema_findings(items, &format!("{pointer}/items"), findings); + } + for operator in ["allOf", "oneOf", "anyOf"] { + if let Some(variants) = schema.get(operator).and_then(Value::as_array) { + for (index, variant) in variants.iter().enumerate() { + schema_findings(variant, &format!("{pointer}/{operator}/{index}"), findings); + } + } + } +} + +pub(super) fn path_parameters( + path: &str, + parameters: &[RestImportParameter], +) -> Vec<(ImportFinding, SourceLocation)> { + parameters + .iter() + .filter(|parameter| parameter.location == RestParameterLocation::Path) + .filter_map(|parameter| { + let finding = if !parameter.required { + Some(( + "path_parameter_not_required", + format!("Path parameter {} должен быть required.", parameter.name), + )) + } else if !path.contains(&format!("{{{}}}", parameter.name)) { + Some(( + "path_parameter_placeholder_missing", + format!( + "Path parameter {} не имеет placeholder в пути.", + parameter.name + ), + )) + } else { + None + }?; + Some(( + document_blocker(finding.0, finding.1), + parameter.source_location.clone(), + )) + }) + .collect() +} + +pub(super) fn unsupported_methods(path_item: &Value) -> Vec<&str> { + const NON_METHOD: &[&str] = &["$ref", "summary", "description", "servers", "parameters"]; + const SUPPORTED: &[&str] = &["get", "post", "put", "patch", "delete", "head", "options"]; + path_item + .as_object() + .into_iter() + .flat_map(|item| item.keys()) + .map(String::as_str) + .filter(|name| { + !name.starts_with("x-") && !NON_METHOD.contains(name) && !SUPPORTED.contains(name) + }) + .collect() +} + +fn supported_request_variants(operation: &Value) -> usize { + operation + .pointer("/requestBody/content") + .and_then(Value::as_object) + .into_iter() + .flat_map(|content| content.iter()) + .filter(|(media, value)| supported_request_media(media) && value.get("schema").is_some()) + .count() +} + +fn supported_request_media(media: &str) -> bool { + matches!( + media, + "application/json" | "application/x-www-form-urlencoded" | "multipart/form-data" + ) || media.ends_with("+json") +} + +fn supported_response_media(media: &str) -> bool { + media == "application/json" || media.ends_with("+json") +} + +pub(super) fn valid_http_server_url(url: &str) -> bool { + if url.chars().any(char::is_control) { + return false; + } + let Ok(parsed) = url::Url::parse(url) else { + return false; + }; + matches!(parsed.scheme(), "http" | "https") + && parsed.host().is_some() + && parsed.username().is_empty() + && parsed.password().is_none() +} + +fn push( + findings: &mut Vec<(ImportFinding, SourceLocation)>, + code: &str, + message: impl Into, + pointer: &str, +) { + findings.push(( + document_blocker(code, message), + SourceLocation { + pointer: pointer.to_owned(), + }, + )); +} + +fn escape(value: &str) -> String { + value.replace('~', "~0").replace('/', "~1") +} diff --git a/crates/crank-import/src/rest/payload.rs b/crates/crank-import/src/rest/payload.rs index 8a8e9e2..cd51b54 100644 --- a/crates/crank-import/src/rest/payload.rs +++ b/crates/crank-import/src/rest/payload.rs @@ -1,19 +1,22 @@ use std::collections::{BTreeMap, BTreeSet}; use crank_core::{ - ExecutionConfig, HttpMethod, OperationSafetyClass, OperationSafetyPolicy, Protocol, RestTarget, - ToolDescription, ToolExample, WizardState, + ExecutionConfig, HttpMethod, OperationSafetyClass, OperationSafetyPolicy, Protocol, + RestRequestContract, RestRequestContractVersion, RestRequestDescriptor, RestResponseDescriptor, + RestTarget, ToolDescription, ToolExample, WizardState, }; use serde_json::json; use crate::rest::{ - mapping::{BodyFieldMapping, input_mapping, output_mapping}, + mapping::{BodyFieldMapping, ParameterFieldMapping, input_mapping, output_mapping}, model::{ ImportOperationCandidate, RestImportCandidate, RestImportOperation, RestParameterLocation, }, naming::{fallback_operation_seed, title_from_name, unique_name}, recommendations::{candidate_recommendations, operation_recommendations}, - schema::{any_object, field_count, object_with_fields, schema_from_openapi}, + schema::{ + any_object, field_count, object_with_fields, schema_from_multipart, schema_from_openapi, + }, }; pub fn candidate_from_operation( @@ -55,32 +58,37 @@ pub fn candidate_from_operation( let base_url = server_urls.first().cloned().unwrap_or_default(); let mut input_fields = BTreeMap::new(); let mut used_input_field_names = BTreeSet::new(); - for parameter in &operation.parameters { - used_input_field_names.insert(parameter.name.clone()); - input_fields.insert( - parameter.name.clone(), - schema_from_openapi( - parameter.schema.as_ref(), - parameter.required || parameter.location == RestParameterLocation::Path, - parameter.description.clone(), - ), - ); - } - let body_fields = body_input_fields( - operation.request_body_schema.as_ref(), - &mut used_input_field_names, - &mut input_fields, - ); - let input_schema = object_with_fields( - Some("Входные параметры MCP-инструмента".to_owned()), - input_fields, - ); - let output_schema = operation - .response_schema - .as_ref() - .map(|schema| schema_from_openapi(Some(schema), true, Some("Ответ API".to_owned()))) - .unwrap_or_else(|| any_object(Some("Ответ API".to_owned()))); - let input_mapping = input_mapping(&operation.parameters, &body_fields); + let parameter_mappings = operation + .parameters + .iter() + .map(|parameter| { + let input_name = unique_parameter_input_name(parameter, &mut used_input_field_names); + let default_value = parameter + .schema + .as_ref() + .and_then(|schema| schema.get("default")) + .cloned(); + input_fields.insert( + input_name.clone(), + schema_from_openapi( + parameter.schema.as_ref(), + parameter.required || parameter.location == RestParameterLocation::Path, + parameter.description.clone(), + ), + ); + ParameterFieldMapping { + input_name, + wire_name: parameter.name.clone(), + location: parameter.location, + required: parameter.required || parameter.location == RestParameterLocation::Path, + default_value, + } + }) + .collect::>(); + let body_fields = body_input_fields(operation, &mut used_input_field_names, &mut input_fields); + let input_schema = input_schema_for_body_variants(operation, input_fields, &body_fields); + let output_schema = output_schema_from_operation(operation); + let input_mapping = input_mapping(¶meter_mappings, &body_fields); let output_mapping = output_mapping(&output_schema); let mut findings = operation_recommendations(operation); findings.extend(candidate_recommendations( @@ -100,6 +108,29 @@ pub fn candidate_from_operation( method: operation.method, path_template: operation.path.clone(), static_headers: BTreeMap::new(), + request_contract: request_contract(operation, &body_fields), + response_contract: operation + .response_variants + .iter() + .enumerate() + .map(|(schema_variant, variant)| RestResponseDescriptor { + status_code: variant.status_code, + media_type: variant.content_type.clone(), + schema_variant, + }) + .collect(), + multipart_field_mime_types: operation + .request_body_variants + .iter() + .filter(|variant| variant.content_type == "multipart/form-data") + .filter(|variant| !variant.multipart_field_mime_types.is_empty()) + .map(|variant| { + ( + variant.content_type.clone(), + variant.multipart_field_mime_types.clone(), + ) + }) + .collect(), }, input_schema: input_schema.clone(), output_schema: output_schema.clone(), @@ -136,7 +167,274 @@ pub fn candidate_from_operation( } } +fn output_schema_from_operation(operation: &RestImportOperation) -> crank_schema::Schema { + if operation.response_variants.is_empty() { + return operation + .response_schema + .as_ref() + .map(|schema| schema_from_openapi(Some(schema), true, Some("Ответ API".to_owned()))) + .unwrap_or_else(|| any_object(Some("Ответ API".to_owned()))); + } + let mut variants = operation + .response_variants + .iter() + .map(|variant| match &variant.schema { + Some(schema) => schema_from_openapi(Some(schema), true, Some("Ответ API".to_owned())), + None => crank_schema::Schema { + kind: crank_schema::SchemaKind::Null, + format: None, + description: Some("Успешный ответ без тела".to_owned()), + required: true, + nullable: false, + default_value: None, + fields: BTreeMap::new(), + items: None, + enum_values: Vec::new(), + variants: Vec::new(), + }, + }) + .collect::>(); + if variants.len() == 1 { + return variants + .pop() + .unwrap_or_else(|| any_object(Some("Ответ API".to_owned()))); + } + crank_schema::Schema { + kind: crank_schema::SchemaKind::Oneof, + format: None, + description: Some("Варианты успешного ответа API".to_owned()), + required: true, + nullable: false, + default_value: None, + fields: BTreeMap::new(), + items: None, + enum_values: Vec::new(), + variants, + } +} + fn body_input_fields( + operation: &RestImportOperation, + used_names: &mut BTreeSet, + input_fields: &mut BTreeMap, +) -> Vec { + let variants = &operation.request_body_variants; + if variants.is_empty() { + return legacy_body_input_fields( + operation.request_body_schema.as_ref(), + used_names, + input_fields, + ); + } + let required = variants.iter().any(|variant| variant.required); + let body_variants = variants + .iter() + .map(|variant| { + let description = Some(format!("Тело запроса ({})", variant.content_type)); + if variant.content_type == "multipart/form-data" { + schema_from_multipart(variant.schema.as_ref(), required, description) + } else { + schema_from_openapi(variant.schema.as_ref(), required, description) + } + }) + .collect::>(); + let body_schema = if body_variants.len() == 1 { + body_variants + .into_iter() + .next() + .expect("single body variant exists") + } else { + crank_schema::Schema { + kind: crank_schema::SchemaKind::Oneof, + format: None, + description: Some("Тело запроса для выбранного формата".to_owned()), + required, + nullable: body_variants.iter().any(|variant| variant.nullable), + default_value: None, + fields: BTreeMap::new(), + items: None, + enum_values: Vec::new(), + variants: body_variants, + } + }; + let body_name = unique_body_input_name("body", used_names); + input_fields.insert(body_name.clone(), body_schema); + if variants.len() > 1 { + let selector = unique_body_input_name("content_type", used_names); + input_fields.insert( + selector.clone(), + crank_schema::Schema { + kind: crank_schema::SchemaKind::Enum, + format: None, + description: Some("Выбирает формат тела запроса".to_owned()), + required, + nullable: false, + default_value: None, + fields: BTreeMap::new(), + items: None, + enum_values: variants + .iter() + .map(|variant| variant.content_type.clone()) + .collect(), + variants: Vec::new(), + }, + ); + // The adapter obtains the selector from the mapped body envelope. + return vec![ + BodyFieldMapping { + input_name: body_name, + // Keep selector and value in an internal envelope so that a + // selected nullable body can remain JSON null on the wire. + body_path: "__body".to_owned(), + required, + }, + BodyFieldMapping { + input_name: selector, + body_path: "__content_type".to_owned(), + required, + }, + ]; + } + vec![BodyFieldMapping { + input_name: body_name, + body_path: String::new(), + required, + }] +} + +fn input_schema_for_body_variants( + operation: &RestImportOperation, + input_fields: BTreeMap, + body_fields: &[BodyFieldMapping], +) -> crank_schema::Schema { + if operation.request_body_variants.len() <= 1 { + return object_with_fields( + Some("Входные параметры MCP-инструмента".to_owned()), + input_fields, + ); + } + let Some(body_name) = body_fields + .iter() + .find(|field| field.body_path == "__body") + .map(|field| field.input_name.as_str()) + else { + return object_with_fields( + Some("Входные параметры MCP-инструмента".to_owned()), + input_fields, + ); + }; + let Some(selector_name) = body_fields + .iter() + .find(|field| field.body_path == "__content_type") + .map(|field| field.input_name.as_str()) + else { + return object_with_fields( + Some("Входные параметры MCP-инструмента".to_owned()), + input_fields, + ); + }; + let Some(body_schema) = input_fields.get(body_name) else { + return object_with_fields( + Some("Входные параметры MCP-инструмента".to_owned()), + input_fields, + ); + }; + let Some(selector_schema) = input_fields.get(selector_name) else { + return object_with_fields( + Some("Входные параметры MCP-инструмента".to_owned()), + input_fields, + ); + }; + let variants = operation + .request_body_variants + .iter() + .zip(&body_schema.variants) + .map(|(request_variant, body_schema)| { + let mut fields = input_fields.clone(); + let mut body_schema = body_schema.clone(); + body_schema.required = true; + fields.insert(body_name.to_owned(), body_schema); + let mut selector = selector_schema.clone(); + selector.required = true; + selector.enum_values = vec![request_variant.content_type.clone()]; + fields.insert(selector_name.to_owned(), selector); + closed_object_with_fields(Some("Входные параметры MCP-инструмента".to_owned()), fields) + }) + .collect::>(); + let mut variants = variants; + if !operation + .request_body_variants + .iter() + .any(|variant| variant.required) + { + let mut absent_fields = input_fields; + absent_fields.remove(body_name); + absent_fields.remove(selector_name); + variants.push(closed_object_with_fields( + Some("Входные параметры без HTTP body".to_owned()), + absent_fields, + )); + } + crank_schema::Schema { + kind: crank_schema::SchemaKind::Oneof, + format: None, + description: Some("Входные параметры для выбранного формата тела запроса".to_owned()), + required: true, + nullable: false, + default_value: None, + fields: BTreeMap::new(), + items: None, + enum_values: Vec::new(), + variants, + } +} + +fn closed_object_with_fields( + description: Option, + fields: BTreeMap, +) -> crank_schema::Schema { + let mut schema = object_with_fields(description, fields); + schema.format = Some(crank_schema::CLOSED_OBJECT_SCHEMA_FORMAT.to_owned()); + schema +} + +fn request_contract( + operation: &RestImportOperation, + body_fields: &[BodyFieldMapping], +) -> Option { + if operation.request_body_variants.is_empty() { + return None; + } + let body_field = body_fields + .iter() + .find(|field| field.body_path.is_empty() || field.body_path == "__body")? + .input_name + .clone(); + let selector_field = body_fields + .iter() + .find(|field| field.body_path == "__content_type") + .map(|field| field.input_name.clone()); + Some(RestRequestContract { + version: RestRequestContractVersion::V1, + body_field, + selector_field, + body_required: operation + .request_body_variants + .iter() + .any(|variant| variant.required), + variants: operation + .request_body_variants + .iter() + .enumerate() + .map(|(schema_variant, variant)| RestRequestDescriptor { + media_type: variant.content_type.clone(), + schema_variant, + }) + .collect(), + }) +} + +fn legacy_body_input_fields( request_body_schema: Option<&serde_json::Value>, used_names: &mut BTreeSet, input_fields: &mut BTreeMap, @@ -158,7 +456,6 @@ fn body_input_fields( required: true, }]; } - let mut mappings = Vec::new(); for (field_name, field_schema) in body_schema.fields { let input_name = unique_body_input_name(&field_name, used_names); @@ -172,6 +469,33 @@ fn body_input_fields( mappings } +fn unique_parameter_input_name( + parameter: &crate::rest::model::RestImportParameter, + used_names: &mut BTreeSet, +) -> String { + let reserved = matches!(parameter.name.as_str(), "body" | "content_type"); + if !reserved && used_names.insert(parameter.name.clone()) { + return parameter.name.clone(); + } + unique_body_input_name( + &format!( + "{}_{}", + parameter_location_name(parameter.location), + parameter.name + ), + used_names, + ) +} + +fn parameter_location_name(location: RestParameterLocation) -> &'static str { + match location { + RestParameterLocation::Path => "path", + RestParameterLocation::Query => "query", + RestParameterLocation::Header => "header", + RestParameterLocation::Cookie => "cookie", + } +} + fn unique_body_input_name(name: &str, used_names: &mut BTreeSet) -> String { if used_names.insert(name.to_owned()) { return name.to_owned(); @@ -207,6 +531,8 @@ fn method_as_str(method: HttpMethod) -> &'static str { HttpMethod::Put => "PUT", HttpMethod::Patch => "PATCH", HttpMethod::Delete => "DELETE", + HttpMethod::Head => "HEAD", + HttpMethod::Options => "OPTIONS", } } @@ -216,6 +542,7 @@ fn safety_for_method(method: HttpMethod) -> OperationSafetyPolicy { HttpMethod::Get => OperationSafetyClass::Read, HttpMethod::Post | HttpMethod::Put | HttpMethod::Patch => OperationSafetyClass::Write, HttpMethod::Delete => OperationSafetyClass::Destructive, + HttpMethod::Head | HttpMethod::Options => OperationSafetyClass::Read, }; OperationSafetyPolicy { class, diff --git a/crates/crank-import/src/rest/schema.rs b/crates/crank-import/src/rest/schema.rs index e2b5abb..d84297d 100644 --- a/crates/crank-import/src/rest/schema.rs +++ b/crates/crank-import/src/rest/schema.rs @@ -6,6 +6,7 @@ use serde_json::Value; pub fn any_object(description: Option) -> Schema { Schema { kind: SchemaKind::Object, + format: None, description, required: true, nullable: false, @@ -28,9 +29,26 @@ pub fn schema_from_openapi( value: Option<&Value>, required: bool, description: Option, +) -> Schema { + schema_from_openapi_context(value, required, description, false) +} + +pub fn schema_from_multipart( + value: Option<&Value>, + required: bool, + description: Option, +) -> Schema { + schema_from_openapi_context(value, required, description, true) +} + +fn schema_from_openapi_context( + value: Option<&Value>, + required: bool, + description: Option, + binary_envelopes: bool, ) -> Schema { let Some(value) = value else { - return primitive(SchemaKind::String, required, description); + return primitive(SchemaKind::String, required, description, None); }; // Only v3 NormalizedIR emits the private marker. Pending legacy-v1 jobs // retain their historical first-branch behavior, while modern oneOf/anyOf @@ -46,6 +64,7 @@ pub fn schema_from_openapi( { return Schema { kind: SchemaKind::Oneof, + format: text(value, "format"), description: description.or_else(|| text(value, "description")), required, nullable: nullable(value), @@ -55,7 +74,7 @@ pub fn schema_from_openapi( enum_values: Vec::new(), variants: items .iter() - .map(|item| schema_from_openapi(Some(item), true, None)) + .map(|item| schema_from_openapi_context(Some(item), true, None, binary_envelopes)) .collect(), }; } @@ -70,6 +89,7 @@ pub fn schema_from_openapi( if !enum_values.is_empty() { return Schema { kind: SchemaKind::Enum, + format: text(&resolved, "format"), description: description.or_else(|| text(&resolved, "description")), required, nullable: nullable(&resolved), @@ -82,19 +102,31 @@ pub fn schema_from_openapi( } } + // OpenAPI binary/file fields use the frozen multipart envelope rather + // than a path, URL, or base64 string. Arrays recurse through this branch + // for each item and therefore expose the same object contract. + if binary_envelopes && is_binary_file(&resolved) { + return file_schema( + required, + description.or_else(|| text(&resolved, "description")), + ); + } + match type_name(&resolved).unwrap_or("object") { - "object" => object_schema(&resolved, required, description), + "object" => object_schema(&resolved, required, description, binary_envelopes), "array" => Schema { kind: SchemaKind::Array, + format: text(&resolved, "format"), description: description.or_else(|| text(&resolved, "description")), required, nullable: nullable(&resolved), default_value: resolved.get("default").cloned(), fields: BTreeMap::new(), - items: Some(Box::new(schema_from_openapi( + items: Some(Box::new(schema_from_openapi_context( resolved.get("items"), true, None, + binary_envelopes, ))), enum_values: Vec::new(), variants: Vec::new(), @@ -103,26 +135,31 @@ pub fn schema_from_openapi( SchemaKind::Integer, required, description.or_else(|| text(&resolved, "description")), + Some(&resolved), ), "number" => primitive( SchemaKind::Number, required, description.or_else(|| text(&resolved, "description")), + Some(&resolved), ), "boolean" => primitive( SchemaKind::Boolean, required, description.or_else(|| text(&resolved, "description")), + Some(&resolved), ), "null" => primitive( SchemaKind::Null, required, description.or_else(|| text(&resolved, "description")), + Some(&resolved), ), _ => primitive( SchemaKind::String, required, description.or_else(|| text(&resolved, "description")), + Some(&resolved), ), } } @@ -141,6 +178,7 @@ fn collapse_composition(value: &Value) -> Value { pub fn object_with_fields(description: Option, fields: BTreeMap) -> Schema { Schema { kind: SchemaKind::Object, + format: None, description, required: true, nullable: false, @@ -152,7 +190,12 @@ pub fn object_with_fields(description: Option, fields: BTreeMap) -> Schema { +fn object_schema( + value: &Value, + required: bool, + description: Option, + binary_envelopes: bool, +) -> Schema { let required_fields = value .get("required") .and_then(Value::as_array) @@ -169,10 +212,11 @@ fn object_schema(value: &Value, required: bool, description: Option) -> for (name, schema) in properties { fields.insert( name.clone(), - schema_from_openapi( + schema_from_openapi_context( Some(schema), required_fields.contains(name.as_str()), text(schema, "description"), + binary_envelopes, ), ); } @@ -180,6 +224,7 @@ fn object_schema(value: &Value, required: bool, description: Option) -> Schema { kind: SchemaKind::Object, + format: text(value, "format"), description: description.or_else(|| text(value, "description")), required, nullable: nullable(value), @@ -191,14 +236,54 @@ fn object_schema(value: &Value, required: bool, description: Option) -> } } -fn primitive(kind: SchemaKind, required: bool, description: Option) -> Schema { +fn primitive( + kind: SchemaKind, + required: bool, + description: Option, + value: Option<&Value>, +) -> Schema { Schema { kind, + format: value.and_then(|value| text(value, "format")), + description, + required, + nullable: value.is_some_and(nullable), + default_value: value.and_then(|value| value.get("default").cloned()), + fields: BTreeMap::new(), + items: None, + enum_values: Vec::new(), + variants: Vec::new(), + } +} + +fn is_binary_file(value: &Value) -> bool { + matches!(type_name(value), Some("file")) + || matches!(type_name(value), Some("string")) + && matches!(text(value, "format").as_deref(), Some("binary" | "file")) +} + +fn file_schema(required: bool, description: Option) -> Schema { + let mut fields = BTreeMap::new(); + fields.insert( + "data_base64".to_owned(), + primitive(SchemaKind::String, true, None, None), + ); + fields.insert( + "filename".to_owned(), + primitive(SchemaKind::String, false, None, None), + ); + fields.insert( + "content_type".to_owned(), + primitive(SchemaKind::String, false, None, None), + ); + Schema { + kind: SchemaKind::Object, + format: Some("binary".to_owned()), description, required, nullable: false, default_value: None, - fields: BTreeMap::new(), + fields, items: None, enum_values: Vec::new(), variants: Vec::new(), diff --git a/crates/crank-import/src/rest/swagger2.rs b/crates/crank-import/src/rest/swagger2.rs index cffe9c9..db510e0 100644 --- a/crates/crank-import/src/rest/swagger2.rs +++ b/crates/crank-import/src/rest/swagger2.rs @@ -3,11 +3,11 @@ use serde_json::Value; use crate::rest::{ model::{ - ImportFinding, ImportFindingSeverity, RestImportDocument, RestImportOperation, - RestImportParameter, RestParameterLocation, + ImportFinding, RestImportDocument, RestImportOperation, RestImportParameter, + RestParameterLocation, RestRequestBodyVariant, RestResponseVariant, }, normalize::ImportParseError, - recommendations::{document_blocker, document_finding, operation_finding}, + recommendations::{document_blocker, document_finding}, }; pub fn parse_document(root: &Value) -> Result { @@ -23,6 +23,11 @@ fn parse_document_v2(root: &Value) -> Result Result Result Result Result Result Result>(); + let operation_pointer = format!("{path_pointer}/{method_name}"); + let mut located_operation_findings = + super::swagger2_findings::operation(root, operation_value, &operation_pointer); + located_operation_findings.extend(parsed_parameter_findings); + located_operation_findings.extend(super::swagger2_findings::path_parameters( + path, + &operation_parameters, + )); + let (operation_findings, internal_finding_locations) = + located_operation_findings.into_iter().unzip(); + let response_schema = (method != HttpMethod::Head) + .then(|| response_schema(operation_value, &operation_pointer)) + .flatten(); operations.push(RestImportOperation { key: format!("{} {}", method_name.to_uppercase(), path), method, @@ -157,18 +178,18 @@ fn parse_document_v2(root: &Value) -> Result Result Result Vec { return Vec::new(); }; let base_path = root.get("basePath").and_then(Value::as_str).unwrap_or(""); + if host.is_empty() + || host.contains('@') + || host.chars().any(char::is_whitespace) + || (!base_path.is_empty() && !base_path.starts_with('/')) + || base_path.chars().any(char::is_control) + { + return Vec::new(); + } let schemes = root .get("schemes") .and_then(Value::as_array) - .map(|items| items.iter().filter_map(Value::as_str).collect::>()) + .map(|items| { + items + .iter() + .filter_map(Value::as_str) + .filter(|scheme| matches!(*scheme, "http" | "https")) + .collect::>() + }) .filter(|items| !items.is_empty()) .unwrap_or_else(|| vec!["https"]); @@ -450,6 +488,14 @@ fn parameters(_root: &Value, value: Option<&Value>, base_pointer: &str) -> Parse } let item = item.clone(); let raw_location = item.get("in").and_then(Value::as_str)?; + let parameter_schema = swagger_parameter_schema(_root, &item); + if parameter_schema.is_none() { + findings.push(parameter_blocker( + "missing_parameter_schema", + "Swagger parameter не содержит schema/type.", + &pointer, + )); + } if raw_location == "body" { return Some(RestImportParameter { name: "body".to_owned(), @@ -473,6 +519,14 @@ fn parameters(_root: &Value, value: Option<&Value>, base_pointer: &str) -> Parse }, }); } + if raw_location == "formData" { + findings.extend(super::swagger2_findings::form_data_parameter( + &item, + parameter_schema.as_ref(), + &pointer, + )); + return None; + } let location = match raw_location { "path" => RestParameterLocation::Path, "query" => RestParameterLocation::Query, @@ -494,14 +548,35 @@ fn parameters(_root: &Value, value: Option<&Value>, base_pointer: &str) -> Parse return None; } }; + if parameter_schema.as_ref().is_some_and(|schema| { + matches!(schema.get("type").and_then(Value::as_str), Some("array" | "object")) + }) || item.get("collectionFormat").is_some() + { + let finding_pointer = if item.get("collectionFormat").is_some() { + format!("{pointer}/collectionFormat") + } else { + pointer.clone() + }; + findings.push(parameter_blocker( + "unsupported_parameter_style", + "Swagger array/object parameter serialization не поддерживается текущим REST mapping.", + &finding_pointer, + )); + } + if let Some(schema) = swagger_parameter_schema(_root, &item) { + super::openapi3_findings::schema_findings( + &schema, + &pointer, + &mut findings, + ); + } Some(RestImportParameter { name: item.get("name").and_then(Value::as_str)?.to_owned(), location, required: item .get("required") .and_then(Value::as_bool) - .unwrap_or(false) - || location == RestParameterLocation::Path, + .unwrap_or(false), description: item .get("description") .and_then(Value::as_str) @@ -597,6 +672,10 @@ fn swagger_parameter_schema(_root: &Value, parameter: &Value) -> Option { schema.insert(key.to_owned(), value.clone()); } } + if schema.get("type").and_then(Value::as_str) == Some("file") { + schema.insert("type".to_owned(), Value::String("string".to_owned())); + schema.insert("format".to_owned(), Value::String("binary".to_owned())); + } if schema.is_empty() { None } else { @@ -630,6 +709,266 @@ fn response_schema( .and_then(|response| response_schema_at(response, operation_pointer, "default")) } +fn swagger_request_body_variants( + root: &Value, + path_item: &Value, + operation: &Value, + path_pointer: &str, + operation_pointer: &str, +) -> Vec { + let parameters = + effective_swagger_parameters(path_item, operation, path_pointer, operation_pointer); + let body = parameters + .iter() + .find(|(parameter, _)| parameter.get("in").and_then(Value::as_str) == Some("body")); + let form = swagger_form_data_schema(¶meters); + let (schema, schema_source_location, schema_property_source_locations) = + if let Some((body, pointer)) = body { + let Some(schema) = body.get("schema").cloned() else { + return Vec::new(); + }; + ( + schema, + Some(crate::rest::model::SourceLocation { + pointer: format!("{pointer}/schema"), + }), + Default::default(), + ) + } else if let Some(form) = form { + form + } else { + return Vec::new(); + }; + let required = body + .and_then(|(parameter, _)| parameter.get("required").and_then(Value::as_bool)) + .unwrap_or_else(|| { + parameters.iter().any(|(parameter, _)| { + parameter.get("in").and_then(Value::as_str) == Some("formData") + && parameter + .get("required") + .and_then(Value::as_bool) + .unwrap_or(false) + }) + }); + let content_types = effective_media_types(root, operation, "consumes", "application/json"); + content_types + .into_iter() + .filter(|content_type| supported_request_content_type(content_type)) + .map(|content_type| RestRequestBodyVariant { + content_type, + required, + schema: Some(schema.clone()), + multipart_field_mime_types: Default::default(), + source_location: crate::rest::model::SourceLocation { + pointer: schema_source_location + .as_ref() + .map(|location| location.pointer.trim_end_matches("/schema").to_owned()) + .unwrap_or_else(|| format!("{operation_pointer}/parameters")), + }, + schema_source_location: schema_source_location.clone(), + schema_property_source_locations: schema_property_source_locations.clone(), + }) + .collect() +} + +fn effective_swagger_parameters( + path_item: &Value, + operation: &Value, + path_pointer: &str, + operation_pointer: &str, +) -> Vec<(Value, String)> { + let mut parameters = Vec::new(); + for (owner, pointer) in [ + (path_item, format!("{path_pointer}/parameters")), + (operation, format!("{operation_pointer}/parameters")), + ] { + let Some(items) = owner.get("parameters").and_then(Value::as_array) else { + continue; + }; + for (index, parameter) in items.iter().enumerate() { + let Some(name) = parameter.get("name").and_then(Value::as_str) else { + continue; + }; + let Some(location) = parameter.get("in").and_then(Value::as_str) else { + continue; + }; + parameters.retain(|(existing, _): &(Value, String)| { + existing.get("name").and_then(Value::as_str) != Some(name) + || existing.get("in").and_then(Value::as_str) != Some(location) + }); + parameters.push((parameter.clone(), format!("{pointer}/{index}"))); + } + } + parameters +} + +fn swagger_form_data_schema( + parameters: &[(Value, String)], +) -> Option<( + Value, + Option, + std::collections::BTreeMap, +)> { + let form_parameters = parameters + .iter() + .filter(|(parameter, _)| parameter.get("in").and_then(Value::as_str) == Some("formData")); + let mut properties = serde_json::Map::new(); + let mut required = Vec::new(); + let mut property_locations = std::collections::BTreeMap::new(); + let mut root_pointer = None; + for (parameter, pointer) in form_parameters { + let Some(name) = parameter.get("name").and_then(Value::as_str) else { + continue; + }; + root_pointer.get_or_insert_with(|| { + pointer + .rsplit_once('/') + .map(|(parent, _)| parent.to_owned()) + .unwrap_or_else(|| pointer.clone()) + }); + property_locations.insert( + name.to_owned(), + crate::rest::model::SourceLocation { + pointer: pointer.clone(), + }, + ); + properties.insert( + name.to_owned(), + swagger_parameter_schema(&Value::Null, parameter) + .unwrap_or_else(|| Value::Object(serde_json::Map::new())), + ); + if parameter + .get("required") + .and_then(Value::as_bool) + .unwrap_or(false) + { + required.push(Value::String(name.to_owned())); + } + } + if properties.is_empty() { + return None; + } + let mut schema = serde_json::Map::new(); + schema.insert("type".to_owned(), Value::String("object".to_owned())); + schema.insert("properties".to_owned(), Value::Object(properties)); + if !required.is_empty() { + schema.insert("required".to_owned(), Value::Array(required)); + } + Some(( + Value::Object(schema), + root_pointer.map(|pointer| crate::rest::model::SourceLocation { pointer }), + property_locations, + )) +} + +fn supported_request_content_type(content_type: &str) -> bool { + content_type == "application/x-www-form-urlencoded" + || content_type == "multipart/form-data" + || content_type == "application/json" + || content_type.ends_with("+json") +} + +fn effective_media_types( + root: &Value, + operation: &Value, + field: &str, + default: &str, +) -> Vec { + operation + .get(field) + .or_else(|| root.get(field)) + .and_then(Value::as_array) + .map(|items| { + items + .iter() + .filter_map(Value::as_str) + .map(ToOwned::to_owned) + .collect::>() + }) + .filter(|items| !items.is_empty()) + .unwrap_or_else(|| vec![default.to_owned()]) +} + +fn swagger_response_variants( + root: &Value, + operation: &Value, + operation_pointer: &str, + method: HttpMethod, +) -> Vec { + let Some(responses) = operation.get("responses").and_then(Value::as_object) else { + return Vec::new(); + }; + let produces = effective_media_types(root, operation, "produces", "application/json"); + let supported_produces = produces + .iter() + .filter(|content_type| supported_response_content_type(content_type)) + .cloned() + .collect::>(); + let mut variants = responses + .iter() + .filter_map(|(code, response)| { + let status_code = code + .parse::() + .ok() + .filter(|code| (200..300).contains(code))?; + let schema = response.get("schema").cloned(); + let pointer = format!( + "{operation_pointer}/responses/{}", + code.replace('~', "~0").replace('/', "~1") + ); + if method == HttpMethod::Head { + return Some(vec![RestResponseVariant { + status_code, + content_type: None, + schema: None, + source_location: crate::rest::model::SourceLocation { pointer }, + schema_source_location: None, + }]); + } + if schema.is_none() { + return Some(vec![RestResponseVariant { + status_code, + content_type: None, + schema, + source_location: crate::rest::model::SourceLocation { pointer }, + schema_source_location: None, + }]); + } + if supported_produces.is_empty() { + return Some(Vec::new()); + } + Some( + supported_produces + .iter() + .map(|content_type| RestResponseVariant { + status_code, + content_type: Some(content_type.clone()), + schema: schema.clone(), + source_location: crate::rest::model::SourceLocation { + pointer: pointer.clone(), + }, + schema_source_location: Some(crate::rest::model::SourceLocation { + pointer: format!("{pointer}/schema"), + }), + }) + .collect(), + ) + }) + .flatten() + .collect::>(); + variants.sort_by(|left, right| { + (left.status_code, left.content_type.as_deref().unwrap_or("")).cmp(&( + right.status_code, + right.content_type.as_deref().unwrap_or(""), + )) + }); + variants +} + +fn supported_response_content_type(content_type: &str) -> bool { + content_type == "application/json" || content_type.ends_with("+json") +} + fn response_schema_at( response: &Value, operation_pointer: &str, @@ -647,46 +986,3 @@ fn response_schema_at( ) }) } - -fn swagger_operation_findings( - path: &str, - operation: &Value, -) -> Vec { - let mut findings = Vec::new(); - if operation - .get("consumes") - .and_then(Value::as_array) - .is_some_and(|items| { - !items - .iter() - .any(|item| item.as_str().is_some_and(|value| value.contains("json"))) - }) - { - findings.push(operation_finding( - path, - "unsupported_consumes", - "Метод использует content type без JSON. Проверьте настройки тела запроса после импорта.", - )); - } - findings -} - -fn method_from_lower(value: &str) -> Option { - match value { - "get" => Some(HttpMethod::Get), - "post" => Some(HttpMethod::Post), - "put" => Some(HttpMethod::Put), - "patch" => Some(HttpMethod::Patch), - "delete" => Some(HttpMethod::Delete), - _ => None, - } -} - -fn path_item_blocker(_path: &str) -> ImportFinding { - ImportFinding { - code: "invalid_path_item".to_owned(), - severity: ImportFindingSeverity::Error, - message: "Path Item имеет неверную структуру и не был интерпретирован.".to_owned(), - operation_key: None, - } -} diff --git a/crates/crank-import/src/rest/swagger2_findings.rs b/crates/crank-import/src/rest/swagger2_findings.rs new file mode 100644 index 0000000..0873268 --- /dev/null +++ b/crates/crank-import/src/rest/swagger2_findings.rs @@ -0,0 +1,248 @@ +use serde_json::Value; + +use crate::rest::{ + model::{ImportFinding, RestImportParameter, RestParameterLocation, SourceLocation}, + recommendations::{document_blocker, operation_finding}, +}; + +pub(super) fn servers(root: &Value) -> Vec<(ImportFinding, SourceLocation)> { + let mut findings = Vec::new(); + if let Some(host) = root.get("host") + && (!host.is_string() + || host.as_str().is_some_and(|host| { + host.is_empty() || host.contains('@') || host.chars().any(char::is_whitespace) + })) + { + push( + &mut findings, + "invalid_server", + "Swagger host неверен или содержит userinfo.", + "/host", + ); + } + if let Some(base_path) = root.get("basePath") + && (!base_path.is_string() + || base_path.as_str().is_some_and(|path| { + (!path.is_empty() && !path.starts_with('/')) || path.chars().any(char::is_control) + })) + { + push( + &mut findings, + "invalid_server", + "Swagger basePath имеет неверный формат.", + "/basePath", + ); + } + if let Some(schemes) = root.get("schemes").and_then(Value::as_array) { + for (index, scheme) in schemes.iter().enumerate() { + if !scheme + .as_str() + .is_some_and(|scheme| matches!(scheme, "http" | "https")) + { + push( + &mut findings, + "invalid_server", + "Swagger scheme должен быть http или https.", + &format!("/schemes/{index}"), + ); + } + } + } + findings +} + +pub(super) fn operation( + root: &Value, + operation: &Value, + operation_pointer: &str, +) -> Vec<(ImportFinding, SourceLocation)> { + let mut findings = Vec::new(); + for (media, location) in media_with_locations(root, operation, operation_pointer, "consumes") { + if !supported_request_media(&media) { + findings.push(( + document_blocker( + "unsupported_consumes", + format!("Content type запроса {media} не поддерживается."), + ), + location, + )); + } + } + for (media, location) in media_with_locations(root, operation, operation_pointer, "produces") { + if !supported_response_media(&media) { + findings.push(( + document_blocker( + "unsupported_produces", + format!("Content type ответа {media} не поддерживается."), + ), + location, + )); + } + } + if let Some(responses) = operation.get("responses").and_then(Value::as_object) { + for (status, response) in responses { + if let Some(schema) = response.get("schema") { + super::openapi3_findings::schema_findings( + schema, + &format!("{operation_pointer}/responses/{}/schema", escape(status)), + &mut findings, + ); + } + } + } + findings +} + +pub(super) fn form_data_parameter( + parameter: &Value, + schema: Option<&Value>, + pointer: &str, +) -> Vec<(ImportFinding, SourceLocation)> { + let Some(schema) = schema else { + return Vec::new(); + }; + let mut findings = Vec::new(); + super::openapi3_findings::schema_findings(schema, pointer, &mut findings); + super::openapi3_findings::form_field_schema_findings(schema, pointer, &mut findings); + if schema.get("type").and_then(Value::as_str) == Some("array") + && parameter.get("collectionFormat").and_then(Value::as_str) != Some("multi") + { + let finding_pointer = parameter + .get("collectionFormat") + .map(|_| format!("{pointer}/collectionFormat")) + .unwrap_or_else(|| pointer.to_owned()); + push( + &mut findings, + "unsupported_parameter_style", + "Swagger formData array требует collectionFormat: multi; csv/default не соответствует repeat-key wire contract.", + &finding_pointer, + ); + } + findings +} + +fn media_with_locations( + root: &Value, + operation: &Value, + operation_pointer: &str, + field: &str, +) -> Vec<(String, SourceLocation)> { + let (value, pointer) = if let Some(value) = operation.get(field) { + (value, format!("{operation_pointer}/{field}")) + } else if let Some(value) = root.get(field) { + (value, format!("/{field}")) + } else { + return Vec::new(); + }; + value + .as_array() + .into_iter() + .flatten() + .enumerate() + .filter_map(|(index, value)| { + value.as_str().map(|value| { + ( + value.to_owned(), + SourceLocation { + pointer: format!("{pointer}/{index}"), + }, + ) + }) + }) + .collect() +} + +pub(super) fn legacy_operation(path: &str, operation: &Value) -> Vec { + if operation + .get("consumes") + .and_then(Value::as_array) + .is_some_and(|items| { + !items + .iter() + .any(|item| item.as_str().is_some_and(|value| value.contains("json"))) + }) + { + vec![operation_finding( + path, + "unsupported_consumes", + "Метод использует content type без JSON. Проверьте настройки тела запроса после импорта.", + )] + } else { + Vec::new() + } +} + +pub(super) fn path_parameters( + path: &str, + parameters: &[RestImportParameter], +) -> Vec<(ImportFinding, SourceLocation)> { + parameters + .iter() + .filter(|parameter| parameter.location == RestParameterLocation::Path) + .filter_map(|parameter| { + let finding = if !parameter.required { + Some(( + "path_parameter_not_required", + format!("Path parameter {} должен быть required.", parameter.name), + )) + } else if !path.contains(&format!("{{{}}}", parameter.name)) { + Some(( + "path_parameter_placeholder_missing", + format!( + "Path parameter {} не имеет placeholder в пути.", + parameter.name + ), + )) + } else { + None + }?; + Some(( + document_blocker(finding.0, finding.1), + parameter.source_location.clone(), + )) + }) + .collect() +} + +pub(super) fn unsupported_methods(path_item: &Value) -> Vec<&str> { + const NON_METHOD: &[&str] = &["$ref", "parameters"]; + const SUPPORTED: &[&str] = &["get", "post", "put", "patch", "delete", "head", "options"]; + path_item + .as_object() + .into_iter() + .flat_map(|item| item.keys()) + .map(String::as_str) + .filter(|name| { + !name.starts_with("x-") && !NON_METHOD.contains(name) && !SUPPORTED.contains(name) + }) + .collect() +} + +fn supported_request_media(media: &str) -> bool { + matches!( + media, + "application/json" | "application/x-www-form-urlencoded" | "multipart/form-data" + ) || media.ends_with("+json") +} + +fn supported_response_media(media: &str) -> bool { + media == "application/json" || media.ends_with("+json") +} + +fn push( + findings: &mut Vec<(ImportFinding, SourceLocation)>, + code: &str, + message: &str, + pointer: &str, +) { + findings.push(( + document_blocker(code, message), + SourceLocation { + pointer: pointer.to_owned(), + }, + )); +} + +fn escape(value: &str) -> String { + value.replace('~', "~0").replace('/', "~1") +} diff --git a/crates/crank-import/tests/coverage.rs b/crates/crank-import/tests/coverage.rs index 002b60f..10f6ec2 100644 --- a/crates/crank-import/tests/coverage.rs +++ b/crates/crank-import/tests/coverage.rs @@ -221,10 +221,10 @@ paths: #[test] fn unsupported_method_has_exact_finding_pointer_and_coverage() { let ir = normalize( - "openapi: 3.1.0\ninfo: { title: Unsupported }\npaths: { /ok: { get: { responses: { '200': { description: ok } } }, head: { responses: {} } } }", + "openapi: 3.1.0\ninfo: { title: Unsupported }\npaths: { /ok: { get: { responses: { '200': { description: ok } } }, trace: { responses: {} } } }", ); validate_normalized_ir(&ir).unwrap(); - let pointer = "/paths/~1ok/head"; + let pointer = "/paths/~1ok/trace"; let construct_id = format!("3.1.0:{pointer}"); assert!(ir.findings.iter().any(|finding| { finding.code == "unsupported_http_method" diff --git a/crates/crank-import/tests/http_contract_regressions.rs b/crates/crank-import/tests/http_contract_regressions.rs new file mode 100644 index 0000000..c1d7966 --- /dev/null +++ b/crates/crank-import/tests/http_contract_regressions.rs @@ -0,0 +1,382 @@ +use crank_core::HttpMethod; +use crank_import::rest::model::NormalizedScalarKind; +use crank_import::rest::{ + ImportFindingSeverity, NormalizationConfig, NormalizedSchemaKind, SourceDigest, + normalize_verified_document, validate_normalized_ir, +}; + +fn normalize(document: &str) -> crank_import::rest::NormalizedIr { + normalize_verified_document( + document, + SourceDigest::parse("5".repeat(64)).unwrap(), + &NormalizationConfig::default(), + ) + .unwrap() +} + +#[test] +fn variants_keep_exact_schema_coverage_and_reject_tampered_provenance() { + let document = r#" +openapi: 3.1.0 +info: {title: Exact variants, version: '1'} +servers: [{url: https://example.test}] +paths: + /items: + post: + operationId: createItem + requestBody: + content: + application/json: + schema: + type: object + properties: + name: {type: string} + responses: + '201': + description: ok + content: + application/json: + schema: {type: object, properties: {id: {type: integer}}} +"#; + let mut ir = normalize(document); + let request = ir.operations[0].request_body_variants[0] + .schema + .as_ref() + .unwrap(); + assert_eq!( + request.location.pointer, + "/paths/~1items/post/requestBody/content/application~1json/schema" + ); + assert!(ir.coverage.iter().any(|entry| { + entry.location.pointer + == "/paths/~1items/post/requestBody/content/application~1json/schema/properties/name" + })); + + ir.operations[0].request_body_variants[0] + .schema + .as_mut() + .unwrap() + .location + .pointer = "/paths/~1items/post/requestBody/content/application~1json".into(); + assert!(validate_normalized_ir(&ir).is_err()); +} + +#[test] +fn exact_blockers_cover_unknown_method_style_media_and_missing_schema() { + let ir = normalize( + r#" +openapi: 3.0.3 +info: {title: Findings, version: '1'} +servers: [{url: https://example.test}] +paths: + /items/{id}: + propfind: {responses: {'200': {description: nope}}} + get: + operationId: getItem + parameters: + - {name: id, in: path, required: false, style: matrix, schema: {type: string}} + requestBody: + content: + text/plain: {schema: {type: string}} + responses: + '200': + description: ok + content: + application/json: {} +"#, + ); + let findings = ir + .findings + .iter() + .chain( + ir.operations + .iter() + .flat_map(|operation| &operation.findings), + ) + .collect::>(); + for (code, pointer) in [ + ("unsupported_http_method", "/paths/~1items~1{id}/propfind"), + ( + "unsupported_parameter_style", + "/paths/~1items~1{id}/get/parameters/0/style", + ), + ( + "path_parameter_not_required", + "/paths/~1items~1{id}/get/parameters/0", + ), + ( + "unsupported_request_media_type", + "/paths/~1items~1{id}/get/requestBody/content/text~1plain", + ), + ( + "missing_response_media_schema", + "/paths/~1items~1{id}/get/responses/200/content/application~1json", + ), + ] { + assert!( + findings.iter().any(|finding| { + finding.code == code + && finding.location.pointer == pointer + && finding.severity == ImportFindingSeverity::Error + }), + "missing {code} at {pointer}" + ); + } +} + +#[test] +fn form_encoding_and_unserializable_shapes_are_exact_blockers() { + let ir = normalize( + r#" +openapi: 3.1.0 +info: {title: Form blockers, version: '1'} +servers: [{url: https://example.test}] +paths: + /forms: + post: + operationId: sendForm + requestBody: + content: + application/x-www-form-urlencoded: + schema: {type: string} + encoding: + tag: {style: form, explode: false} + multipart/form-data: + schema: + type: object + properties: + metadata: {type: object, properties: {name: {type: string}}} + nested_tags: {type: array, items: {type: array, items: {type: string}}} + composed_metadata: + oneOf: + - {type: object, properties: {name: {type: string}}} + responses: {'204': {description: Empty}} +"#, + ); + let findings = &ir.operations[0].findings; + for (code, pointer) in [ + ( + "unsupported_form_schema", + "/paths/~1forms/post/requestBody/content/application~1x-www-form-urlencoded/schema", + ), + ( + "unsupported_form_encoding", + "/paths/~1forms/post/requestBody/content/application~1x-www-form-urlencoded/encoding/tag/explode", + ), + ( + "unsupported_form_schema", + "/paths/~1forms/post/requestBody/content/multipart~1form-data/schema/properties/metadata", + ), + ( + "unsupported_form_schema", + "/paths/~1forms/post/requestBody/content/multipart~1form-data/schema/properties/nested_tags/items", + ), + ( + "unsupported_form_schema", + "/paths/~1forms/post/requestBody/content/multipart~1form-data/schema/properties/composed_metadata/oneOf/0", + ), + ] { + assert!( + findings.iter().any(|finding| { + finding.code == code + && finding.location.pointer == pointer + && finding.severity == ImportFindingSeverity::Error + }), + "missing {code} at {pointer}" + ); + } + validate_normalized_ir(&ir).unwrap(); +} + +#[test] +fn swagger_form_data_arrays_require_multi_collection_format() { + let ir = normalize( + r#" +swagger: '2.0' +info: {title: Swagger form arrays, version: '1'} +host: example.test +schemes: [https] +consumes: [application/x-www-form-urlencoded] +paths: + /forms: + post: + operationId: sendForm + parameters: + - {name: default_csv, in: formData, type: array, items: {type: string}} + - {name: explicit_csv, in: formData, type: array, collectionFormat: csv, items: {type: string}} + - {name: repeat_keys, in: formData, type: array, collectionFormat: multi, items: {type: string}} + responses: {'204': {description: Empty}} +"#, + ); + let findings = &ir.operations[0].findings; + for pointer in [ + "/paths/~1forms/post/parameters/0", + "/paths/~1forms/post/parameters/1/collectionFormat", + ] { + assert!( + findings.iter().any(|finding| { + finding.code == "unsupported_parameter_style" + && finding.location.pointer == pointer + && finding.severity == ImportFindingSeverity::Error + }), + "missing CSV blocker at {pointer}" + ); + } + assert!(!findings.iter().any(|finding| { + finding.code == "unsupported_parameter_style" + && finding.location.pointer == "/paths/~1forms/post/parameters/2/collectionFormat" + })); + validate_normalized_ir(&ir).unwrap(); +} + +#[test] +fn unsupported_schema_keywords_and_invalid_server_port_are_exact_blockers() { + let ir = normalize( + r#" +openapi: 3.1.0 +info: {title: Schema and server blockers, version: '1'} +servers: + - {url: 'https://example.test:not-a-port'} + - {url: "https://control.test/\n"} +paths: + /items: + post: + operationId: createItem + requestBody: + content: + application/json: + schema: + type: object + const: {kind: item} + minProperties: 1 + maxProperties: 2 + dependentRequired: {kind: [name]} + properties: + quantity: {type: number, multipleOf: 0.5} + responses: {'204': {description: Empty}} +"#, + ); + let findings = ir + .findings + .iter() + .chain(ir.operations[0].findings.iter()) + .collect::>(); + for (code, pointer) in [ + ("invalid_server", "/servers/0/url"), + ("invalid_server", "/servers/1/url"), + ( + "unsupported_schema_keyword", + "/paths/~1items/post/requestBody/content/application~1json/schema/const", + ), + ( + "unsupported_schema_keyword", + "/paths/~1items/post/requestBody/content/application~1json/schema/minProperties", + ), + ( + "unsupported_schema_keyword", + "/paths/~1items/post/requestBody/content/application~1json/schema/maxProperties", + ), + ( + "unsupported_schema_keyword", + "/paths/~1items/post/requestBody/content/application~1json/schema/dependentRequired", + ), + ( + "unsupported_schema_keyword", + "/paths/~1items/post/requestBody/content/application~1json/schema/properties/quantity/multipleOf", + ), + ] { + assert!( + findings.iter().any(|finding| { + finding.code == code + && finding.location.pointer == pointer + && finding.severity == ImportFindingSeverity::Error + }), + "missing {code} at {pointer}" + ); + } + validate_normalized_ir(&ir).unwrap(); +} + +#[test] +fn swagger_merges_path_form_data_and_preserves_file_type() { + let ir = normalize( + r#" +swagger: '2.0' +info: {title: Upload, version: '1'} +host: example.test +schemes: [https] +consumes: [multipart/form-data] +paths: + /upload: + parameters: + - {name: file, in: formData, type: file, required: true} + - {name: title, in: formData, type: string} + post: + operationId: upload + parameters: + - {name: title, in: formData, type: integer, required: true} + responses: + '204': {description: done} +"#, + ); + let operation = &ir.operations[0]; + let variant = &operation.request_body_variants[0]; + let NormalizedSchemaKind::Object { + properties, + required, + .. + } = &variant.schema.as_ref().unwrap().kind + else { + panic!("formData must normalize to an object"); + }; + assert_eq!(required, &["file".to_owned(), "title".to_owned()]); + assert!(matches!( + properties["file"].kind, + NormalizedSchemaKind::Scalar { + scalar_type: NormalizedScalarKind::String, + ref format, + .. + } if format.as_deref() == Some("binary") + )); + assert!(matches!( + properties["title"].kind, + NormalizedSchemaKind::Scalar { + scalar_type: NormalizedScalarKind::Integer, + .. + } + )); + assert_eq!( + properties["file"].location.pointer, + "/paths/~1upload/parameters/0" + ); + assert_eq!( + properties["title"].location.pointer, + "/paths/~1upload/post/parameters/0" + ); +} + +#[test] +fn head_declared_body_is_normalized_as_no_content() { + let ir = normalize( + r#" +openapi: 3.0.3 +info: {title: Head, version: '1'} +servers: [{url: https://example.test}] +paths: + /health: + head: + operationId: health + responses: + '200': + description: ok + content: + application/json: {schema: {type: object}} +"#, + ); + let operation = &ir.operations[0]; + assert_eq!(operation.method, HttpMethod::Head); + assert!(operation.response_schema.is_none()); + assert_eq!(operation.response_variants.len(), 1); + assert!(operation.response_variants[0].schema.is_none()); + assert!(operation.response_variants[0].content_type.is_none()); +} diff --git a/crates/crank-import/tests/http_replay.rs b/crates/crank-import/tests/http_replay.rs new file mode 100644 index 0000000..77e8c07 --- /dev/null +++ b/crates/crank-import/tests/http_replay.rs @@ -0,0 +1,68 @@ +use crank_import::rest::{ + NormalizationConfig, NormalizedIr, SourceDigest, normalize_verified_document, preview_from_ir, + validate_normalized_ir, +}; +use serde_json::json; + +#[test] +fn serialized_http_ir_preserves_variants_mime_aliases_and_mapping_without_parser_state() { + let document = r#" +openapi: 3.0.3 +info: {title: Replay} +servers: [{url: 'https://example.test/api/v2'}] +paths: + /upload: + post: + operationId: upload + parameters: + - {in: query, name: body, schema: {type: string}} + - {in: header, name: content_type, schema: {type: string}} + requestBody: + required: true + content: + application/json: + schema: {type: object, required: [name], properties: {name: {type: string}}} + multipart/form-data: + schema: {type: object, required: [file], properties: {file: {type: string, format: binary}}} + encoding: {file: {contentType: 'image/png, image/jpeg'}} + responses: + '200': {description: OK, content: {application/json: {schema: {type: string}}}} + '204': {description: Empty} +"#; + let ir = normalize_verified_document( + document, + SourceDigest::parse("0".repeat(64)).unwrap(), + &NormalizationConfig::default(), + ) + .unwrap(); + let restored: NormalizedIr = serde_json::from_slice(&serde_json::to_vec(&ir).unwrap()).unwrap(); + validate_normalized_ir(&restored).unwrap(); + let first = preview_from_ir(&ir); + let second = preview_from_ir(&restored); + assert_eq!(first, second); + assert_eq!(second.groups[0].operations.len(), 1); + let candidate = &second.groups[0].operations[0]; + let draft = &candidate.draft; + let draft_value = serde_json::to_value(draft).unwrap(); + let persisted: crank_import::rest::RestImportCandidate = + serde_json::from_value(draft_value.clone()).unwrap(); + assert_eq!(serde_json::to_value(persisted).unwrap(), draft_value); + for arguments in [ + json!({"query_body": "query", "header_content_type": "header", "content_type": "application/json", "body": {"name": "Ada"}}), + json!({"query_body": "query", "header_content_type": "header", "content_type": "multipart/form-data", "body": {"file": {"data_base64": "AA==", "content_type": "image/png"}}}), + ] { + draft.input_schema.validate_shape(&arguments).unwrap(); + let mapped = draft + .input_mapping + .apply(&json!({"mcp": arguments})) + .unwrap(); + assert_eq!(mapped["request"]["query"]["body"], "query"); + assert_eq!(mapped["request"]["headers"]["content_type"], "header"); + } + assert_eq!(draft.target.base_url, "https://example.test/api/v2"); + assert_eq!(draft.target.response_contract.len(), 2); + assert_eq!( + draft.target.multipart_field_mime_types["multipart/form-data"]["file"], + ["image/png", "image/jpeg"] + ); +} diff --git a/crates/crank-import/tests/legacy_http_contract.rs b/crates/crank-import/tests/legacy_http_contract.rs new file mode 100644 index 0000000..ebfea6d --- /dev/null +++ b/crates/crank-import/tests/legacy_http_contract.rs @@ -0,0 +1,49 @@ +use crank_import::rest::preview_document_legacy_v1; +use crank_schema::SchemaKind; +use serde_json::json; + +#[test] +fn legacy_v1_keeps_reserved_names_flattening_and_scalar_semantics() { + let preview = preview_document_legacy_v1( + r#" +openapi: 3.0.3 +info: {title: Legacy contract} +servers: [{url: 'https://example.test'}] +paths: + /items/{id}: + head: + responses: {'204': {description: Empty}} + post: + operationId: createItem + parameters: + - {in: path, name: id, schema: {type: string}} + - {in: query, name: body, schema: {type: string, default: old, nullable: true}} + requestBody: + content: + application/json: + schema: + type: object + properties: + file: {type: string, format: binary} + responses: + '200': {description: OK, content: {application/json: {schema: {type: string}}}} + '204': {description: Empty} +"#, + ) + .unwrap(); + assert_eq!(preview.groups[0].operations.len(), 1); + let draft = &preview.groups[0].operations[0].draft; + assert!(draft.input_schema.fields["id"].required); + assert_eq!(draft.input_schema.fields["file"].kind, SchemaKind::String); + assert_eq!(draft.input_schema.fields["file"].format, None); + assert!(!draft.input_schema.fields["body"].nullable); + assert_eq!(draft.input_schema.fields["body"].default_value, None); + assert!(draft.target.response_contract.is_empty()); + let mapped = draft + .input_mapping + .apply(&json!({"mcp": {"id": "1", "body": "query-value", "file": "legacy-string"}})) + .unwrap(); + assert_eq!(mapped["request"]["query"]["body"], "query-value"); + assert_eq!(mapped["request"]["body"], json!({"file": "legacy-string"})); + assert_eq!(draft.output_schema.kind, SchemaKind::String); +} diff --git a/crates/crank-import/tests/normalization_details.rs b/crates/crank-import/tests/normalization_details.rs index 26a5922..b02d6e8 100644 --- a/crates/crank-import/tests/normalization_details.rs +++ b/crates/crank-import/tests/normalization_details.rs @@ -246,7 +246,7 @@ components: .iter() .map(|parameter| parameter.name.as_str()) .collect::>(), - vec!["id", "query"] + vec!["path_cookie", "id", "operation_cookie", "query"] ); let errors = ir .findings @@ -257,7 +257,6 @@ components: "missing_parameter_name", "missing_parameter_location", "unsupported_parameter_location", - "unsupported_cookie_parameter", "unresolved_parameter_reference", ] .contains(&finding.code.as_str()) @@ -267,10 +266,6 @@ components: assert_eq!( errors, std::collections::BTreeSet::from([ - ( - "unsupported_cookie_parameter", - "/paths/~1items~1{id}/parameters/1", - ), ("invalid_parameter", "/paths/~1items~1{id}/parameters/2",), ( "missing_parameter_name", @@ -284,10 +279,6 @@ components: "unsupported_parameter_location", "/paths/~1items~1{id}/get/parameters/2", ), - ( - "unsupported_cookie_parameter", - "/paths/~1items~1{id}/get/parameters/3", - ), ]) ); assert!( @@ -299,7 +290,6 @@ components: "missing_parameter_name", "missing_parameter_location", "unsupported_parameter_location", - "unsupported_cookie_parameter", "unresolved_parameter_reference", ] .contains(&finding.code.as_str()) @@ -363,12 +353,12 @@ parameters: let errors = ir .findings .iter() + .chain(ir.operations[0].findings.iter()) .filter(|finding| { [ "invalid_parameter", "missing_parameter_name", "missing_parameter_location", - "unsupported_parameter_location", "unsupported_cookie_parameter", "unresolved_parameter_reference", ] @@ -392,10 +382,6 @@ parameters: "missing_parameter_location", "/paths/~1items~1{id}/get/parameters/1", ), - ( - "unsupported_parameter_location", - "/paths/~1items~1{id}/get/parameters/2", - ), ( "unsupported_cookie_parameter", "/paths/~1items~1{id}/get/parameters/3", @@ -405,12 +391,12 @@ parameters: assert!( ir.findings .iter() + .chain(ir.operations[0].findings.iter()) .filter(|finding| { [ "invalid_parameter", "missing_parameter_name", "missing_parameter_location", - "unsupported_parameter_location", "unsupported_cookie_parameter", "unresolved_parameter_reference", ] @@ -418,6 +404,13 @@ parameters: }) .all(|finding| finding.severity == ImportFindingSeverity::Error) ); + assert!( + ir.operations[0].findings.iter().any(|finding| { + finding.code == "missing_parameter_name" + && finding.location.pointer == "/paths/~1items~1{id}/get/parameters/0" + }), + "operation parameter errors must remain scoped to the affected operation" + ); } #[test] diff --git a/crates/crank-import/tests/preview.rs b/crates/crank-import/tests/preview.rs index 4107901..9edde77 100644 --- a/crates/crank-import/tests/preview.rs +++ b/crates/crank-import/tests/preview.rs @@ -1,6 +1,9 @@ mod unit { use crank_core::HttpMethod; - use crank_import::rest::{ImportParseError, preview_document, preview_document_legacy_v1}; + use crank_import::rest::{ + ImportParseError, NormalizationConfig, SourceDigest, normalize_verified_document, + preview_document, preview_document_legacy_v1, + }; use crank_schema::SchemaKind; use serde_json::json; @@ -174,7 +177,8 @@ paths: assert_eq!(labels.kind, SchemaKind::Array); assert_eq!(labels.items.as_ref().unwrap().kind, SchemaKind::String); - let payload = operation.draft.input_schema.field("payload").unwrap(); + let body = operation.draft.input_schema.field("body").unwrap(); + let payload = body.field("payload").unwrap(); assert_eq!(payload.description.as_deref(), Some("Request payload")); assert_eq!( payload.field("enabled").unwrap().description.as_deref(), @@ -214,7 +218,7 @@ paths: let v2 = preview_document(document).unwrap(); assert_eq!( v2.groups[0].operations[0].draft.output_schema.kind, - SchemaKind::String + SchemaKind::Oneof ); let legacy = preview_document_legacy_v1(document).unwrap(); @@ -555,10 +559,10 @@ paths: .map(|rule| rule.target.as_str()) .collect::>(); - assert!(input_fields.contains_key("email")); - assert!(input_fields.contains_key("name")); - assert!(targets.contains(&"$.request.body.email")); - assert!(targets.contains(&"$.request.body.name")); + assert!(input_fields.contains_key("body")); + assert!(input_fields["body"].fields.contains_key("email")); + assert!(input_fields["body"].fields.contains_key("name")); + assert!(targets.contains(&"$.request.body")); } #[test] @@ -612,4 +616,344 @@ paths: assert!(codes.contains(&"weak_tool_name")); assert!(codes.contains(&"too_many_output_fields")); } + + #[test] + fn previews_head_and_options_operations_and_rejects_trace_connect() { + let document = r#" +openapi: 3.0.3 +info: { title: Method coverage } +paths: + /health: + head: + operationId: healthHead + responses: { '204': { description: Empty } } + options: + operationId: healthOptions + responses: { '204': { description: Empty } } + trace: + responses: { '200': { description: Unsupported } } + connect: + responses: { '200': { description: Unsupported } } +"#; + + let preview = preview_document(document).unwrap(); + let operations = preview + .groups + .iter() + .flat_map(|group| group.operations.iter()) + .collect::>(); + assert_eq!(operations.len(), 2); + assert!(operations.iter().any(|operation| { + operation.key == "HEAD /health" && operation.method == HttpMethod::Head + })); + assert!(operations.iter().any(|operation| { + operation.key == "OPTIONS /health" && operation.method == HttpMethod::Options + })); + + let unsupported = preview + .findings + .iter() + .filter(|finding| finding.code == "unsupported_http_method") + .count(); + assert_eq!(unsupported, 2); + } + + #[test] + fn preserves_cookie_location_and_does_not_collapse_same_name_parameters() { + let document = r#" +openapi: 3.0.3 +info: { title: Cookie parameters } +paths: + /sessions: + get: + operationId: listSessions + parameters: + - name: token + in: query + schema: { type: string } + - name: token + in: cookie + required: true + schema: { type: string } + responses: + '200': { description: OK } +"#; + + let preview = preview_document(document).unwrap(); + let candidate = &preview.groups[0].operations[0]; + let cookie_and_query_rules = candidate + .draft + .input_mapping + .rules + .iter() + .filter(|rule| { + rule.target == "$.request.query.token" || rule.target == "$.request.cookies.token" + }) + .collect::>(); + assert_eq!(cookie_and_query_rules.len(), 2); + assert_ne!( + cookie_and_query_rules[0].source, + cookie_and_query_rules[1].source + ); + + let ir = normalize_verified_document( + document, + SourceDigest::parse("0".repeat(64)).unwrap(), + &NormalizationConfig::default(), + ) + .unwrap(); + let operation = &ir.operations[0]; + assert_eq!(operation.parameters.len(), 2); + assert!(operation.parameters.iter().any(|parameter| { + parameter.name == "token" + && parameter.location == crank_import::rest::RestParameterLocation::Query + })); + assert!(operation.parameters.iter().any(|parameter| { + parameter.name == "token" + && parameter.location == crank_import::rest::RestParameterLocation::Cookie + && parameter.required + })); + } + + #[test] + fn preserves_all_supported_request_media_variants() { + let document = r#" +openapi: 3.0.3 +info: { title: Request media variants } +paths: + /imports: + post: + operationId: importPayload + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [json_name] + properties: { json_name: { type: string } } + application/x-www-form-urlencoded: + schema: + type: object + required: [form_name] + properties: { form_name: { type: string } } + multipart/form-data: + schema: + type: object + required: [file] + properties: { file: { type: string, format: binary } } + encoding: + file: { contentType: "image/png, image/jpeg" } + responses: + '202': { description: Accepted } +"#; + + let ir = normalize_verified_document( + document, + SourceDigest::parse("0".repeat(64)).unwrap(), + &NormalizationConfig::default(), + ) + .unwrap(); + let variants = &ir.operations[0].request_body_variants; + let content_types = variants + .iter() + .map(|variant| variant.content_type.as_str()) + .collect::>(); + assert_eq!( + content_types, + vec![ + "application/json", + "application/x-www-form-urlencoded", + "multipart/form-data" + ] + ); + assert!(variants.iter().all(|variant| variant.required)); + assert!(variants.iter().all(|variant| variant.schema.is_some())); + assert_eq!( + variants[2].multipart_field_mime_types.get("file"), + Some(&vec!["image/png".to_owned(), "image/jpeg".to_owned()]) + ); + + let preview = preview_document(document).unwrap(); + let input_schema = &preview.groups[0].operations[0].draft.input_schema; + assert_eq!(input_schema.kind, SchemaKind::Oneof); + assert_eq!(input_schema.variants.len(), 3); + assert!( + input_schema + .validate_shape(&json!({ + "content_type": "application/json", + "body": {"json_name": "Ada"} + })) + .is_ok() + ); + assert!( + input_schema + .validate_shape(&json!({ + "content_type": "application/json", + "body": {"form_name": "Ada"} + })) + .is_err() + ); + assert!( + input_schema + .validate_shape(&json!({ + "content_type": "multipart/form-data", + "body": {"file": {"data_base64": "SGVsbG8="}} + })) + .is_ok() + ); + assert!( + input_schema + .validate_shape(&json!({ + "content_type": "multipart/form-data", + "body": {"file": {"data_base64": "SGVsbG8=", "extra": true}} + })) + .is_err() + ); + assert!( + input_schema + .validate_shape(&json!({ + "content_type": "multipart/form-data", + "body": {} + })) + .is_err() + ); + assert_eq!( + preview.groups[0].operations[0] + .draft + .target + .multipart_field_mime_types + .get("multipart/form-data") + .and_then(|fields| fields.get("file")), + Some(&vec!["image/png".to_owned(), "image/jpeg".to_owned()]) + ); + } + + #[test] + fn optional_variant_pair_preserves_omission_and_nullable_null_in_mapping() { + let document = r#" +openapi: 3.0.3 +info: { title: Optional variants } +paths: + /events: + post: + operationId: createEvent + requestBody: + required: false + content: + application/json: + schema: { type: object, nullable: true, properties: { name: { type: string } } } + application/x-www-form-urlencoded: + schema: { type: object, properties: { title: { type: string } } } + responses: { '204': { description: Empty } } +"#; + let preview = preview_document(document).unwrap(); + let draft = &preview.groups[0].operations[0].draft; + assert!(draft.input_schema.validate_shape(&json!({})).is_ok()); + assert!( + draft + .input_schema + .validate_shape(&json!({"content_type": "application/json", "body": null})) + .is_ok() + ); + assert!( + draft + .input_schema + .validate_shape( + &json!({"content_type": "application/x-www-form-urlencoded", "body": null}) + ) + .is_err() + ); + // Omission is represented by its own closed branch, so an incomplete + // selector/body pair is rejected by the portable schema as well. + assert!( + draft + .input_schema + .validate_shape(&json!({"content_type": "application/json"})) + .is_err() + ); + let mapped = draft + .input_mapping + .apply(&json!({"mcp": {"content_type": "application/json", "body": null}})) + .unwrap(); + assert_eq!(mapped["request"]["body"], json!(null)); + assert_eq!(mapped["request"]["body_content_type"], "application/json"); + } + + #[test] + fn preserves_multiple_success_responses_and_explicit_no_content() { + let document = r#" +openapi: 3.0.3 +info: { title: Response variants } +paths: + /items: + get: + operationId: getItems + responses: + '200': + description: JSON result + content: + application/json: + schema: { type: object, properties: { id: { type: string } } } + '204': { description: No content } + '206': + description: Partial result + content: + application/json: + schema: { type: array, items: { type: string } } +"#; + + let preview = preview_document(document).unwrap(); + let output_schema = &preview.groups[0].operations[0].draft.output_schema; + let response_contract = &preview.groups[0].operations[0] + .draft + .target + .response_contract; + assert_eq!(output_schema.kind, SchemaKind::Oneof); + assert_eq!(output_schema.variants.len(), 3); + assert_eq!( + response_contract + .iter() + .map(|descriptor| (descriptor.status_code, descriptor.media_type.as_deref())) + .collect::>(), + vec![ + (200, Some("application/json")), + (204, None), + (206, Some("application/json")), + ] + ); + assert!( + output_schema + .variants + .iter() + .any(|variant| variant.kind == SchemaKind::Null) + ); + + let ir = normalize_verified_document( + document, + SourceDigest::parse("0".repeat(64)).unwrap(), + &NormalizationConfig::default(), + ) + .unwrap(); + let variants = &ir.operations[0].response_variants; + assert_eq!( + variants + .iter() + .map(|variant| variant.status_code) + .collect::>(), + vec![200, 204, 206] + ); + assert_eq!( + variants[0].content_type.as_deref(), + Some("application/json") + ); + assert!(variants[0].schema.is_some()); + assert_eq!(variants[1].content_type, None); + assert!(variants[1].schema.is_none()); + assert_eq!( + variants[2].content_type.as_deref(), + Some("application/json") + ); + assert!(variants[2].schema.is_some()); + } } diff --git a/crates/crank-import/tests/reference_resolution.rs b/crates/crank-import/tests/reference_resolution.rs index 5293c44..0edfaec 100644 --- a/crates/crank-import/tests/reference_resolution.rs +++ b/crates/crank-import/tests/reference_resolution.rs @@ -243,7 +243,11 @@ paths: let ir = normalize(compatible); assert!(matches!( ir.operations[0].request_body_schema.as_ref().map(|schema| &schema.kind), - Some(NormalizedSchemaKind::Object { properties, required }) + Some(NormalizedSchemaKind::Object { + properties, + required, + .. + }) if properties.len() == 2 && required == &vec!["id".to_owned(), "name".to_owned()] )); diff --git a/crates/crank-import/tests/schema_projection.rs b/crates/crank-import/tests/schema_projection.rs new file mode 100644 index 0000000..842fc98 --- /dev/null +++ b/crates/crank-import/tests/schema_projection.rs @@ -0,0 +1,64 @@ +use crank_import::rest::preview_document; +use crank_schema::SchemaKind; +use serde_json::json; + +#[test] +fn preserves_format_default_nullable_and_string_enum_in_rest_projection() { + let document = r#" +openapi: 3.1.0 +info: { title: Schema metadata } +paths: + /metadata: + get: + operationId: metadata + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + identifier: + type: string + format: uuid + default: 00000000-0000-0000-0000-000000000000 + nullable: true + state: + type: string + enum: [draft, published] + default: draft + ratio: + type: number + format: double + default: 1.5 + nullable: true +"#; + + let preview = preview_document(document).unwrap(); + let schema = &preview.groups[0].operations[0].draft.output_schema; + + let identifier = schema.field("identifier").unwrap(); + assert_eq!(identifier.kind, SchemaKind::String); + assert_eq!(identifier.format.as_deref(), Some("uuid")); + assert_eq!( + identifier.default_value, + Some(json!("00000000-0000-0000-0000-000000000000")) + ); + assert!(identifier.nullable); + + let state = schema.field("state").unwrap(); + assert_eq!(state.kind, SchemaKind::Enum); + assert_eq!(state.enum_values, vec!["draft", "published"]); + assert_eq!(state.default_value, Some(json!("draft"))); + + let ratio = schema.field("ratio").unwrap(); + assert_eq!(ratio.kind, SchemaKind::Number); + assert_eq!(ratio.format.as_deref(), Some("double")); + assert_eq!(ratio.default_value, Some(json!(1.5))); + assert!(ratio.nullable); + + let serialized = serde_json::to_value(schema).unwrap(); + assert_eq!(serialized["fields"]["identifier"]["format"], "uuid"); + assert_eq!(serialized["fields"]["identifier"]["nullable"], true); +} diff --git a/crates/crank-import/tests/swagger2_contract.rs b/crates/crank-import/tests/swagger2_contract.rs new file mode 100644 index 0000000..6390bd8 --- /dev/null +++ b/crates/crank-import/tests/swagger2_contract.rs @@ -0,0 +1,161 @@ +use crank_core::HttpMethod; +use crank_import::rest::{ + NormalizationConfig, NormalizedSchemaKind, SourceDigest, normalize_verified_document, +}; + +fn normalize(document: &str) -> crank_import::rest::NormalizedIr { + normalize_verified_document( + document, + SourceDigest::parse("0".repeat(64)).unwrap(), + &NormalizationConfig::default(), + ) + .unwrap() +} + +#[test] +fn swagger2_form_data_uses_effective_consumes_and_builds_body_schema() { + let document = r#" +swagger: '2.0' +info: { title: Forms } +host: example.test +schemes: [https] +consumes: [application/json, multipart/form-data] +produces: [application/json] +paths: + /upload: + post: + operationId: upload + consumes: [application/x-www-form-urlencoded, multipart/form-data] + parameters: + - { name: title, in: formData, type: string, required: true } + - { name: count, in: formData, type: integer } + - { name: file, in: formData, type: file } + responses: + '200': { description: OK, schema: { type: object, properties: { id: { type: string } } } } + '204': { description: Empty } + "#; + + let ir = normalize(document); + let operation = &ir.operations[0]; + assert_eq!(operation.method, HttpMethod::Post); + assert_eq!( + operation + .request_body_variants + .iter() + .map(|variant| variant.content_type.as_str()) + .collect::>(), + vec!["application/x-www-form-urlencoded", "multipart/form-data"] + ); + assert!( + operation + .request_body_variants + .iter() + .all(|variant| variant.required) + ); + let Some(NormalizedSchemaKind::Object { properties, .. }) = operation + .request_body_variants + .first() + .and_then(|variant| variant.schema.as_ref()) + .map(|schema| &schema.kind) + else { + panic!("formData must become an object request schema"); + }; + assert!(properties.contains_key("title")); + assert!(properties.contains_key("count")); + assert!(properties.contains_key("file")); + assert!( + operation + .findings + .iter() + .all(|finding| finding.code != "unsupported_consumes") + ); + assert_eq!( + operation + .response_variants + .iter() + .map(|variant| (variant.status_code, variant.content_type.as_deref())) + .collect::>(), + vec![(200, Some("application/json")), (204, None)] + ); +} + +#[test] +fn swagger2_operation_produces_overrides_global_and_preserves_json_variants() { + let document = r#" +swagger: '2.0' +info: { title: Responses } +host: example.test +schemes: [https] +produces: [application/json] +paths: + /items: + get: + operationId: listItems + produces: [application/problem+json, application/xml] + responses: + '200': { description: OK, schema: { type: array, items: { type: string } } } +"#; + + let ir = normalize(document); + let operation = &ir.operations[0]; + assert_eq!( + operation + .response_variants + .iter() + .map(|variant| variant.content_type.as_deref()) + .collect::>(), + vec![Some("application/problem+json")] + ); + assert!( + operation + .findings + .iter() + .any(|finding| finding.code == "unsupported_produces") + ); +} + +#[test] +fn swagger2_imports_head_options_and_reports_path_blockers() { + let document = r#" +swagger: '2.0' +info: { title: Methods } +host: example.test +schemes: [https] +paths: + /health: + head: + operationId: healthHead + responses: { '204': { description: Empty } } + options: + operationId: healthOptions + responses: { '204': { description: Empty } } + /broken/{id}: + get: + parameters: + - { name: other, in: path, required: true, type: string } + responses: { '200': { description: OK } } + /malformed: invalid +"#; + + let ir = normalize(document); + assert!( + ir.operations + .iter() + .any(|operation| operation.method == HttpMethod::Head) + ); + assert!( + ir.operations + .iter() + .any(|operation| operation.method == HttpMethod::Options) + ); + assert!(ir.operations.iter().any(|operation| { + operation.findings.iter().any(|finding| { + finding.code == "path_parameter_placeholder_missing" + && finding.severity == crank_import::rest::ImportFindingSeverity::Error + }) + })); + assert!(ir.findings.iter().any(|finding| { + finding.code == "invalid_path_item" + && finding.severity == crank_import::rest::ImportFindingSeverity::Error + })); +} diff --git a/crates/crank-mapping/src/execute.rs b/crates/crank-mapping/src/execute.rs index 86c7d6d..ad26041 100644 --- a/crates/crank-mapping/src/execute.rs +++ b/crates/crank-mapping/src/execute.rs @@ -55,6 +55,7 @@ fn empty_target_context(context: MappingTargetContext) -> Value { ("path".to_owned(), Value::Object(Map::new())), ("query".to_owned(), Value::Object(Map::new())), ("headers".to_owned(), Value::Object(Map::new())), + ("cookies".to_owned(), Value::Object(Map::new())), ("body".to_owned(), Value::Object(Map::new())), ])), )])), diff --git a/crates/crank-mapping/src/jsonpath.rs b/crates/crank-mapping/src/jsonpath.rs index 522cbc9..2c9cbfe 100644 --- a/crates/crank-mapping/src/jsonpath.rs +++ b/crates/crank-mapping/src/jsonpath.rs @@ -8,7 +8,9 @@ pub enum JsonPathRoot { RequestPath, RequestQuery, RequestHeaders, + RequestCookies, RequestBody, + RequestBodyContentType, ResponseBody, ResponseData, Output, @@ -21,7 +23,9 @@ impl JsonPathRoot { Self::RequestPath => "request.path", Self::RequestQuery => "request.query", Self::RequestHeaders => "request.headers", + Self::RequestCookies => "request.cookies", Self::RequestBody => "request.body", + Self::RequestBodyContentType => "request.body_content_type", Self::ResponseBody => "response.body", Self::ResponseData => "response.data", Self::Output => "output", @@ -34,7 +38,9 @@ impl JsonPathRoot { Self::RequestPath => &["request", "path"], Self::RequestQuery => &["request", "query"], Self::RequestHeaders => &["request", "headers"], + Self::RequestCookies => &["request", "cookies"], Self::RequestBody => &["request", "body"], + Self::RequestBodyContentType => &["request", "body_content_type"], Self::ResponseBody => &["response", "body"], Self::ResponseData => &["response", "data"], Self::Output => &["output"], @@ -116,8 +122,13 @@ impl JsonPath { } fn match_root(input: &str) -> Option<(JsonPathRoot, &str)> { - const ROOTS: [(&str, JsonPathRoot); 8] = [ + const ROOTS: [(&str, JsonPathRoot); 10] = [ + ( + "request.body_content_type", + JsonPathRoot::RequestBodyContentType, + ), ("request.headers", JsonPathRoot::RequestHeaders), + ("request.cookies", JsonPathRoot::RequestCookies), ("response.body", JsonPathRoot::ResponseBody), ("response.data", JsonPathRoot::ResponseData), ("request.path", JsonPathRoot::RequestPath), diff --git a/crates/crank-mapping/src/model.rs b/crates/crank-mapping/src/model.rs index 2cdedef..79a3835 100644 --- a/crates/crank-mapping/src/model.rs +++ b/crates/crank-mapping/src/model.rs @@ -122,6 +122,8 @@ fn target_root_context(root: JsonPathRoot) -> Option { JsonPathRoot::RequestPath | JsonPathRoot::RequestQuery | JsonPathRoot::RequestHeaders + | JsonPathRoot::RequestCookies + | JsonPathRoot::RequestBodyContentType | JsonPathRoot::RequestBody => Some(MappingTargetContext::Input), JsonPathRoot::Output => Some(MappingTargetContext::Output), _ => None, @@ -165,6 +167,8 @@ fn validate_target_root( JsonPathRoot::RequestPath | JsonPathRoot::RequestQuery | JsonPathRoot::RequestHeaders + | JsonPathRoot::RequestCookies + | JsonPathRoot::RequestBodyContentType | JsonPathRoot::RequestBody ), MappingTargetContext::Output => root == JsonPathRoot::Output, diff --git a/crates/crank-registry/src/postgres/mod.rs b/crates/crank-registry/src/postgres/mod.rs index e516250..239e2f5 100644 --- a/crates/crank-registry/src/postgres/mod.rs +++ b/crates/crank-registry/src/postgres/mod.rs @@ -448,6 +448,8 @@ fn target_summary(target: &Target) -> (String, String) { HttpMethod::Put => "PUT", HttpMethod::Patch => "PATCH", HttpMethod::Delete => "DELETE", + HttpMethod::Head => "HEAD", + HttpMethod::Options => "OPTIONS", } .to_owned(), ), diff --git a/crates/crank-registry/tests/integration/common.rs b/crates/crank-registry/tests/integration/common.rs index 5320b30..7dd6096 100644 --- a/crates/crank-registry/tests/integration/common.rs +++ b/crates/crank-registry/tests/integration/common.rs @@ -49,9 +49,13 @@ pub(super) fn test_operation(id: &str, version: u32, status: OperationStatus) -> method: HttpMethod::Post, path_template: "/v1/leads".to_owned(), static_headers: BTreeMap::from([("X-Static".to_owned(), "true".to_owned())]), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: Schema { kind: SchemaKind::Object, + format: None, description: Some("input".to_owned()), required: true, nullable: false, @@ -60,6 +64,7 @@ pub(super) fn test_operation(id: &str, version: u32, status: OperationStatus) -> "email".to_owned(), Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, @@ -76,6 +81,7 @@ pub(super) fn test_operation(id: &str, version: u32, status: OperationStatus) -> }, output_schema: Schema { kind: SchemaKind::Object, + format: None, description: Some("output".to_owned()), required: true, nullable: false, @@ -84,6 +90,7 @@ pub(super) fn test_operation(id: &str, version: u32, status: OperationStatus) -> "id".to_owned(), Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, diff --git a/crates/crank-registry/tests/integration/operations_artifacts.rs b/crates/crank-registry/tests/integration/operations_artifacts.rs index 6f49980..a690007 100644 --- a/crates/crank-registry/tests/integration/operations_artifacts.rs +++ b/crates/crank-registry/tests/integration/operations_artifacts.rs @@ -251,6 +251,9 @@ async fn published_version_is_not_rewritten_by_a_later_save() { method: HttpMethod::Post, path_template: "/mutated".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }); changed.updated_at = timestamp("2026-03-25T12:20:00Z"); diff --git a/crates/crank-runtime/Cargo.toml b/crates/crank-runtime/Cargo.toml index 707a90b..712cc55 100644 --- a/crates/crank-runtime/Cargo.toml +++ b/crates/crank-runtime/Cargo.toml @@ -35,6 +35,7 @@ uuid.workspace = true [dev-dependencies] axum.workspace = true +crank-import = { path = "../crank-import" } futures-util = "0.3" metrics.workspace = true metrics-util = "0.20.4" diff --git a/crates/crank-runtime/src/confirmation.rs b/crates/crank-runtime/src/confirmation.rs index f977bd0..decf4c4 100644 --- a/crates/crank-runtime/src/confirmation.rs +++ b/crates/crank-runtime/src/confirmation.rs @@ -85,6 +85,7 @@ fn infer_safety_class(operation: &RuntimeOperation) -> OperationSafetyClass { match &operation.target { Target::Rest(target) => match target.method { HttpMethod::Get => OperationSafetyClass::Read, + HttpMethod::Head | HttpMethod::Options => OperationSafetyClass::Read, HttpMethod::Delete => OperationSafetyClass::Destructive, HttpMethod::Post | HttpMethod::Put | HttpMethod::Patch => OperationSafetyClass::Write, }, diff --git a/crates/crank-runtime/src/execution_request.rs b/crates/crank-runtime/src/execution_request.rs index fe31dd6..3962376 100644 --- a/crates/crank-runtime/src/execution_request.rs +++ b/crates/crank-runtime/src/execution_request.rs @@ -185,6 +185,7 @@ mod tests { fn operation() -> RuntimeOperation { let schema = Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -204,6 +205,9 @@ mod tests { method: HttpMethod::Post, path_template: "/".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: schema.clone(), output_schema: schema, diff --git a/crates/crank-runtime/src/executor.rs b/crates/crank-runtime/src/executor.rs index f75efa8..2df1a97 100644 --- a/crates/crank-runtime/src/executor.rs +++ b/crates/crank-runtime/src/executor.rs @@ -6,7 +6,7 @@ use std::time::{Duration, Instant}; use crank_core::{ AdapterRegistry, CoordinationStateStore, ExecutionMode, InvocationSource, InvocationStatus, - MeteringEvent, ResponseCacheStore, SharedMeteringSink, SharedProtocolAdapter, + MeteringEvent, ResponseCacheStore, SharedMeteringSink, SharedProtocolAdapter, Target, }; use crank_metrics::{ CacheOutcome, ConfirmationOutcome, IdempotencyOutcome, InFlightGuard, @@ -24,7 +24,7 @@ use crate::{ AdapterResponse, ExecutionAuthorization, PreparedRequest, RuntimeError, RuntimeExecutionRequest, RuntimeLimits, RuntimeOperation, RuntimeRequestContext, auth::apply_resolved_auth, - request_preparation::adapter_prepared_request, + request_preparation::{adapter_prepared_request, validate_selected_body_variant}, response_cache::{ adapter_response_from_cached, cached_response_from_adapter, response_cache_key, response_cache_ttl, @@ -284,6 +284,7 @@ impl RuntimeExecutor { .input_schema .validate_shape(input) .map_err(RuntimeError::InputSchema)?; + validate_selected_body_variant(operation, input)?; if operation.input_mapping.is_empty() { return Ok(PreparedRequest::default()); @@ -293,7 +294,16 @@ impl RuntimeExecutor { .input_mapping .apply(&json!({ "mcp": input })) .map_err(RuntimeError::InputMapping)?; - PreparedRequest::from_mapping_output(&mapped_input) + let mut prepared = PreparedRequest::from_mapping_output(&mapped_input, &operation.target)?; + let Target::Rest(target) = &operation.target; + if let Some(contract) = &target.request_contract + && input.get(&contract.body_field).is_none() + { + // Mapping initializes an empty body object for legacy field mappings. + // A typed optional body is absent unless its public argument was supplied. + prepared.body = None; + } + Ok(prepared) } async fn execute_prepared( @@ -838,8 +848,7 @@ fn transform_response( let span = Stage::RuntimeResponseTransform.span(); let result = span.in_scope(|| { let finalized_output = finalize_output(operation, response)?; - operation - .output_schema + output_schema_for_response(operation, response)? .validate_shape(&finalized_output) .map_err(RuntimeError::OutputSchema)?; Ok(finalized_output) @@ -854,6 +863,43 @@ fn transform_response( result } +fn output_schema_for_response<'a>( + operation: &'a RuntimeOperation, + response: &AdapterResponse, +) -> Result<&'a crank_schema::Schema, RuntimeError> { + let Target::Rest(target) = &operation.target; + if target.response_contract.is_empty() { + return Ok(&operation.output_schema); + } + let media_type = response + .headers + .get("content-type") + .and_then(|value| value.split(';').next()) + .map(str::trim); + let descriptor = target + .response_contract + .iter() + .filter(|descriptor| descriptor.status_code == response.status_code) + .find(|descriptor| match (&descriptor.media_type, media_type) { + (Some(expected), Some(actual)) => expected.eq_ignore_ascii_case(actual), + (None, _) => response.body.is_null(), + _ => false, + }) + .ok_or(RuntimeError::InvalidExecutionRequest)?; + if target.response_contract.len() > 1 + && operation.output_schema.kind == crank_schema::SchemaKind::Oneof + { + return operation + .output_schema + .variants + .get(descriptor.schema_variant) + .ok_or(RuntimeError::InvalidExecutionRequest); + } + (descriptor.schema_variant == 0) + .then_some(&operation.output_schema) + .ok_or(RuntimeError::InvalidExecutionRequest) +} + fn record_runtime_result(span: &Span, result: &Result) { match result { Ok(_) => StageOutcome::Success.record(span), diff --git a/crates/crank-runtime/src/idempotency.rs b/crates/crank-runtime/src/idempotency.rs index 39f0a20..eb2fd3e 100644 --- a/crates/crank-runtime/src/idempotency.rs +++ b/crates/crank-runtime/src/idempotency.rs @@ -262,8 +262,14 @@ async fn resolve_existing( } pub fn policy(operation: &RuntimeOperation) -> Option<&IdempotencyPolicy> { - let is_mutating_rest = - matches!(&operation.target, Target::Rest(target) if target.method != HttpMethod::Get); + let is_mutating_rest = matches!( + &operation.target, + Target::Rest(target) + if matches!( + target.method, + HttpMethod::Post | HttpMethod::Put | HttpMethod::Patch | HttpMethod::Delete + ) + ); if !is_mutating_rest { return None; } @@ -398,9 +404,13 @@ mod tests { method: HttpMethod::Post, path_template: "/orders".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -412,6 +422,7 @@ mod tests { }, output_schema: Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, diff --git a/crates/crank-runtime/src/model.rs b/crates/crank-runtime/src/model.rs index 7684082..d7efa7c 100644 --- a/crates/crank-runtime/src/model.rs +++ b/crates/crank-runtime/src/model.rs @@ -51,6 +51,8 @@ pub struct PreparedRequest { pub trusted_header_names: BTreeSet, #[serde(skip_serializing_if = "Option::is_none")] pub body: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub body_content_type: Option, #[serde(default)] pub timeout_ms: u64, } @@ -72,6 +74,7 @@ impl From for crank_core::PreparedRequest { headers: value.headers, trusted_header_names: value.trusted_header_names, body: value.body, + body_content_type: value.body_content_type, timeout_ms: value.timeout_ms, } } @@ -85,6 +88,7 @@ impl From for PreparedRequest { headers: value.headers, trusted_header_names: value.trusted_header_names, body: value.body, + body_content_type: value.body_content_type, timeout_ms: value.timeout_ms, } } diff --git a/crates/crank-runtime/src/request_preparation.rs b/crates/crank-runtime/src/request_preparation.rs index 6e78bec..afd390b 100644 --- a/crates/crank-runtime/src/request_preparation.rs +++ b/crates/crank-runtime/src/request_preparation.rs @@ -1,12 +1,85 @@ use std::collections::BTreeMap; use crank_core::Target; +use crank_schema::{SchemaError, SchemaKind}; use serde_json::Value; use crate::{PreparedRequest, RuntimeError, RuntimeOperation}; +/// Validates the imported `content_type`/`body` pair before mapping. The +/// public schema exposes the union of supported body shapes, while this check +/// binds the selected media type to its corresponding branch. +pub(crate) fn validate_selected_body_variant( + operation: &RuntimeOperation, + input: &Value, +) -> Result<(), RuntimeError> { + let Target::Rest(target) = &operation.target; + let Some(contract) = &target.request_contract else { + return Ok(()); + }; + let Some(input) = input.as_object() else { + return Ok(()); + }; + let body_field = contract.body_field.as_str(); + let Some(selector_field) = contract.selector_field.as_deref() else { + if contract.body_required && !input.contains_key(body_field) { + return Err(RuntimeError::InputSchema(SchemaError::missing_field( + format!("$.{body_field}"), + ))); + } + return Ok(()); + }; + match (input.get(selector_field), input.get(body_field)) { + (None, None) if !contract.body_required => Ok(()), + (_, None) => Err(RuntimeError::InputSchema(SchemaError::missing_field( + format!("$.{body_field}"), + ))), + (None, Some(_)) => Err(RuntimeError::InputSchema(SchemaError::missing_field( + format!("$.{selector_field}"), + ))), + (Some(selector), Some(_)) => { + let Some(selector) = selector.as_str() else { + return Err(RuntimeError::InputSchema(SchemaError::invalid_type( + format!("$.{selector_field}"), + "enum", + "non-string", + ))); + }; + let Some(descriptor) = contract + .variants + .iter() + .find(|variant| variant.media_type == selector) + else { + return Err(RuntimeError::InputSchema(SchemaError::invalid_enum_value( + format!("$.{selector_field}"), + contract + .variants + .iter() + .map(|variant| variant.media_type.clone()) + .collect(), + selector, + ))); + }; + let selected_schema = if operation.input_schema.kind == SchemaKind::Oneof { + operation + .input_schema + .variants + .get(descriptor.schema_variant) + .ok_or(RuntimeError::InvalidExecutionRequest)? + } else if descriptor.schema_variant == 0 { + &operation.input_schema + } else { + return Err(RuntimeError::InvalidExecutionRequest); + }; + selected_schema + .validate_shape(&Value::Object(input.clone())) + .map_err(RuntimeError::InputSchema) + } + } +} + impl PreparedRequest { - pub fn from_mapping_output(mapped: &Value) -> Result { + pub fn from_mapping_output(mapped: &Value, target: &Target) -> Result { let request = mapped .get("request") @@ -15,12 +88,40 @@ impl PreparedRequest { reason: "mapped input must contain request root".to_owned(), })?; + let mut headers = read_string_map(request.get("headers"), "request.headers")?; + for (index, (name, value)) in read_string_map(request.get("cookies"), "request.cookies")? + .into_iter() + .enumerate() + { + headers.insert( + format!("x-crank-internal-cookie-{index}"), + format!("{name}\t{value}"), + ); + } + let typed_body_contract = + matches!(target, Target::Rest(target) if target.request_contract.is_some()); + let body = if typed_body_contract { + request.get("body").cloned() + } else { + request.get("body").and_then(non_empty_legacy_body).cloned() + }; + let body_content_type = match request.get("body_content_type") { + Some(Value::String(value)) => Some(value.clone()), + Some(_) => { + return Err(RuntimeError::InvalidPreparedRequest { + field: "request.body_content_type".to_owned(), + reason: "must be a string".to_owned(), + }); + } + None => None, + }; Ok(Self { path_params: read_string_map(request.get("path"), "request.path")?, query_params: read_string_map(request.get("query"), "request.query")?, - headers: read_string_map(request.get("headers"), "request.headers")?, + headers, trusted_header_names: Default::default(), - body: request.get("body").and_then(non_empty_body).cloned(), + body, + body_content_type, timeout_ms: 0, }) } @@ -93,10 +194,74 @@ fn stringify_value(value: &Value) -> Result { } } -fn non_empty_body(value: &Value) -> Option<&Value> { +fn non_empty_legacy_body(value: &Value) -> Option<&Value> { match value { Value::Null => None, Value::Object(object) if object.is_empty() => None, _ => Some(value), } } + +#[cfg(test)] +mod tests { + use std::collections::BTreeMap; + + use crank_core::{ + HttpMethod, RestRequestContract, RestRequestContractVersion, RestRequestDescriptor, + RestTarget, Target, + }; + use serde_json::json; + + use crate::PreparedRequest; + + #[test] + fn legacy_empty_and_null_bodies_remain_absent() { + let target = legacy_target(); + for body in [json!(null), json!({})] { + let mapped = json!({"request": {"body": body}}); + assert_eq!( + PreparedRequest::from_mapping_output(&mapped, &target) + .unwrap() + .body, + None + ); + } + } + + #[test] + fn typed_contract_preserves_explicit_empty_and_null_bodies() { + let mut target = legacy_target(); + let Target::Rest(rest) = &mut target; + rest.request_contract = Some(RestRequestContract { + version: RestRequestContractVersion::V1, + body_field: "body".to_owned(), + selector_field: None, + body_required: true, + variants: vec![RestRequestDescriptor { + media_type: "application/json".to_owned(), + schema_variant: 0, + }], + }); + for body in [json!(null), json!({})] { + let mapped = json!({"request": {"body": body}}); + assert_eq!( + PreparedRequest::from_mapping_output(&mapped, &target) + .unwrap() + .body, + Some(body) + ); + } + } + + fn legacy_target() -> Target { + Target::Rest(RestTarget { + base_url: "https://example.invalid".to_owned(), + method: HttpMethod::Post, + path_template: "/".to_owned(), + static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), + }) + } +} diff --git a/crates/crank-runtime/tests/http_contract.rs b/crates/crank-runtime/tests/http_contract.rs new file mode 100644 index 0000000..747c5a1 --- /dev/null +++ b/crates/crank-runtime/tests/http_contract.rs @@ -0,0 +1,355 @@ +mod support; + +use support::RuntimeExecutorTestExt; + +use std::{ + collections::BTreeMap, + sync::{ + Arc, Mutex, + atomic::{AtomicUsize, Ordering}, + }, +}; + +use async_trait::async_trait; +use crank_core::{ + AdapterResponse, ExecutionConfig, ExecutionMode, OperationId, Protocol, ProtocolAdapter, + ProtocolAdapterError, Target, ToolDescription, +}; +use crank_import::rest::{RestImportCandidate, preview_document}; +use crank_runtime::{RuntimeExecutorBuilder, RuntimeOperation}; +use serde_json::{Value, json}; + +#[derive(Clone)] +struct CaptureAdapter { + calls: Arc, + prepared: Arc>>, + response: AdapterResponse, +} + +#[async_trait] +impl ProtocolAdapter for CaptureAdapter { + fn protocol(&self) -> Protocol { + Protocol::Rest + } + + fn supports_mode(&self, mode: ExecutionMode) -> bool { + mode == ExecutionMode::Unary + } + + async fn invoke_unary( + &self, + _target: &Target, + prepared: &crank_core::PreparedRequest, + _context: &crank_core::RuntimeRequestContext, + ) -> Result { + self.calls.fetch_add(1, Ordering::SeqCst); + *self.prepared.lock().expect("prepared lock") = Some(prepared.clone()); + Ok(self.response.clone()) + } +} + +#[tokio::test] +async fn imported_media_selector_is_validated_before_adapter_and_travels_out_of_band() { + let operation = imported_operation( + r#" +openapi: 3.0.3 +info: { title: Media } +servers: [{ url: https://example.invalid }] +paths: + /events: + post: + requestBody: + required: true + content: + application/json: + schema: { type: object, required: [name], properties: { name: { type: string } } } + application/x-www-form-urlencoded: + schema: { type: object, required: [title], properties: { title: { type: string } } } + responses: { '204': { description: Empty } } +"#, + ); + let calls = Arc::new(AtomicUsize::new(0)); + let prepared = Arc::new(Mutex::new(None)); + let executor = RuntimeExecutorBuilder::new() + .register_adapter(Arc::new(CaptureAdapter { + calls: Arc::clone(&calls), + prepared: Arc::clone(&prepared), + response: response(204, BTreeMap::new(), Value::Null), + })) + .build(); + + for invalid in [ + json!({"body": {"name": "Ada"}}), + json!({"content_type": "text/plain", "body": {"name": "Ada"}}), + json!({"content_type": "application/json", "body": {"title": "wrong branch"}}), + ] { + assert!(executor.execute(&operation, &invalid).await.is_err()); + } + assert_eq!(calls.load(Ordering::SeqCst), 0); + + assert!( + executor + .execute( + &operation, + &json!({"content_type": "application/json", "body": {"name": "Ada"}}), + ) + .await + .is_ok() + ); + let prepared = prepared.lock().expect("prepared lock").clone().unwrap(); + assert_eq!(prepared.body, Some(json!({"name": "Ada"}))); + assert_eq!( + prepared.body_content_type.as_deref(), + Some("application/json") + ); +} + +#[tokio::test] +async fn imported_single_body_preserves_empty_object_and_required_file_fails_before_adapter() { + let empty_operation = imported_operation( + r#" +openapi: 3.0.3 +info: { title: Empty } +servers: [{ url: https://example.invalid }] +paths: + /empty: + post: + requestBody: + required: true + content: + application/json: { schema: { type: object } } + responses: { '204': { description: Empty } } +"#, + ); + let calls = Arc::new(AtomicUsize::new(0)); + let prepared = Arc::new(Mutex::new(None)); + let executor = RuntimeExecutorBuilder::new() + .register_adapter(Arc::new(CaptureAdapter { + calls: Arc::clone(&calls), + prepared: Arc::clone(&prepared), + response: response(204, BTreeMap::new(), Value::Null), + })) + .build(); + assert!( + executor + .execute(&empty_operation, &json!({"body": {}})) + .await + .is_ok() + ); + assert_eq!( + prepared + .lock() + .expect("prepared lock") + .as_ref() + .unwrap() + .body, + Some(json!({})) + ); + + let file_operation = imported_operation( + r#" +openapi: 3.0.3 +info: { title: Upload } +servers: [{ url: https://example.invalid }] +paths: + /upload: + post: + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + required: [file] + properties: { file: { type: string, format: binary } } + responses: { '204': { description: Empty } } +"#, + ); + assert!( + executor + .execute(&file_operation, &json!({"body": {}})) + .await + .is_err() + ); + assert_eq!(calls.load(Ordering::SeqCst), 1); +} + +#[tokio::test] +async fn response_status_selects_its_linked_output_schema_branch() { + let operation = imported_operation( + r#" +openapi: 3.0.3 +info: { title: Responses } +servers: [{ url: https://example.invalid }] +paths: + /items: + get: + responses: + '200': + description: Full + content: + application/json: + schema: { type: object, required: [id], properties: { id: { type: string } } } + '206': + description: Partial + content: + application/json: + schema: { type: array, items: { type: string } } +"#, + ); + let executor = RuntimeExecutorBuilder::new() + .register_adapter(Arc::new(CaptureAdapter { + calls: Arc::new(AtomicUsize::new(0)), + prepared: Arc::new(Mutex::new(None)), + response: response( + 200, + BTreeMap::from([("content-type".to_owned(), "application/json".to_owned())]), + json!(["schema-for-206"]), + ), + })) + .build(); + + assert!(executor.execute(&operation, &json!({})).await.is_err()); + + for (status, body) in [(200, json!({"id": "full"})), (206, json!(["partial"]))] { + let executor = RuntimeExecutorBuilder::new() + .register_adapter(Arc::new(CaptureAdapter { + calls: Arc::new(AtomicUsize::new(0)), + prepared: Arc::new(Mutex::new(None)), + response: response( + status, + BTreeMap::from([("content-type".to_owned(), "application/json".to_owned())]), + body.clone(), + ), + })) + .build(); + assert_eq!( + executor.execute(&operation, &json!({})).await.unwrap(), + body + ); + } +} + +#[tokio::test] +async fn single_response_preserves_all_source_composition_branches() { + let operation = imported_operation( + r#" +openapi: 3.0.3 +info: {title: Response union} +servers: [{url: https://example.invalid}] +paths: + /items: + get: + responses: + '200': + description: Either + content: + application/json: + schema: + oneOf: + - {type: string} + - {type: integer} +"#, + ); + let Target::Rest(target) = &operation.target; + assert_eq!(target.response_contract.len(), 1); + assert_eq!(operation.output_schema.variants.len(), 2); + for body in [json!("text"), json!(42)] { + let executor = RuntimeExecutorBuilder::new() + .register_adapter(Arc::new(CaptureAdapter { + calls: Arc::new(AtomicUsize::new(0)), + prepared: Arc::new(Mutex::new(None)), + response: response( + 200, + BTreeMap::from([("content-type".to_owned(), "application/json".to_owned())]), + body.clone(), + ), + })) + .build(); + assert_eq!( + executor.execute(&operation, &json!({})).await.unwrap(), + body + ); + } +} + +#[tokio::test] +async fn optional_single_body_distinguishes_omission_empty_object_and_null() { + let operation = imported_operation( + r#" +openapi: 3.0.3 +info: {title: Optional body} +servers: [{url: https://example.invalid}] +paths: + /items: + post: + requestBody: + required: false + content: + application/json: + schema: {type: object, nullable: true} + responses: {'204': {description: Empty}} +"#, + ); + let prepared = Arc::new(Mutex::new(None)); + let executor = RuntimeExecutorBuilder::new() + .register_adapter(Arc::new(CaptureAdapter { + calls: Arc::new(AtomicUsize::new(0)), + prepared: Arc::clone(&prepared), + response: response(204, BTreeMap::new(), Value::Null), + })) + .build(); + for (input, expected) in [ + (json!({}), None), + (json!({"body": {}}), Some(json!({}))), + (json!({"body": null}), Some(Value::Null)), + ] { + executor.execute(&operation, &input).await.unwrap(); + assert_eq!(prepared.lock().unwrap().as_ref().unwrap().body, expected); + } +} + +fn imported_operation(document: &str) -> RuntimeOperation { + let preview = preview_document(document).expect("preview"); + let draft = preview.groups[0].operations[0].draft.clone(); + runtime_operation(draft) +} + +fn runtime_operation(draft: RestImportCandidate) -> RuntimeOperation { + RuntimeOperation { + operation_id: OperationId::new("op_http_contract"), + operation_version: 1, + tool_name: draft.name, + protocol: Protocol::Rest, + target: Target::Rest(draft.target), + input_schema: draft.input_schema, + output_schema: draft.output_schema, + input_mapping: draft.input_mapping, + output_mapping: draft.output_mapping, + execution_config: ExecutionConfig { + timeout_ms: 1_000, + retry_policy: None, + response_cache: None, + idempotency: None, + safety: None, + approval_policy: None, + auth_profile_ref: None, + headers: BTreeMap::new(), + }, + tool_description: ToolDescription { + title: draft.tool_description.title, + description: draft.tool_description.description, + tags: draft.tool_description.tags, + examples: draft.tool_description.examples, + }, + } +} + +fn response(status_code: u16, headers: BTreeMap, body: Value) -> AdapterResponse { + AdapterResponse { + status_code, + headers, + data: body.clone(), + body, + } +} diff --git a/crates/crank-runtime/tests/http_contract_wire.rs b/crates/crank-runtime/tests/http_contract_wire.rs new file mode 100644 index 0000000..f56b289 --- /dev/null +++ b/crates/crank-runtime/tests/http_contract_wire.rs @@ -0,0 +1,170 @@ +mod support; + +use support::RuntimeExecutorTestExt; + +use std::{ + collections::BTreeMap, + sync::{Arc, Mutex}, +}; + +use axum::{ + Router, + body::Bytes, + extract::{OriginalUri, State}, + http::{HeaderMap, StatusCode}, + routing::post, +}; +use crank_adapter_rest::{OutboundHttpPolicy, RestAdapter}; +use crank_core::{ExecutionConfig, OperationId, Protocol, Target}; +use crank_import::rest::preview_document; +use crank_runtime::{RuntimeExecutorBuilder, RuntimeOperation}; +use serde_json::json; +use tokio::net::TcpListener; + +type Requests = Arc>>; + +async fn capture( + State(requests): State, + OriginalUri(uri): OriginalUri, + headers: HeaderMap, + body: Bytes, +) -> StatusCode { + requests + .lock() + .unwrap() + .push((headers, uri.to_string(), body)); + StatusCode::NO_CONTENT +} + +#[tokio::test] +async fn imported_variants_execute_on_wire_and_reject_invalid_inputs_before_dispatch() { + let requests: Requests = Arc::new(Mutex::new(Vec::new())); + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let base_url = format!("http://{}", listener.local_addr().unwrap()); + let app = Router::new() + .route("/events", post(capture)) + .with_state(Arc::clone(&requests)); + let server = tokio::spawn(async move { + axum::serve(listener, app).await.unwrap(); + }); + let source = r#" +openapi: 3.0.3 +info: {title: Wire contract} +servers: [{url: 'http://wire.invalid'}] +paths: + /events: + post: + operationId: createEvent + parameters: + - {name: body, in: query, schema: {type: string}} + - {name: content_type, in: cookie, schema: {type: string}} + requestBody: + required: false + content: + application/json: + schema: {type: object, nullable: true, required: [name], properties: {name: {type: string}}} + application/x-www-form-urlencoded: + schema: {type: object, required: [title], properties: {title: {type: string}}} + multipart/form-data: + schema: {type: object, required: [file], properties: {file: {type: string, format: binary}}} + encoding: {file: {contentType: 'image/png, image/jpeg'}} + responses: {'204': {description: Empty}} +"#.replace("http://wire.invalid", &base_url); + let preview = preview_document(&source).unwrap(); + assert_eq!(preview.groups[0].operations.len(), 1); + assert!( + !preview + .findings + .iter() + .any(|finding| finding.severity == crank_import::rest::ImportFindingSeverity::Error) + ); + let draft = preview.groups[0].operations[0].draft.clone(); + let operation = RuntimeOperation { + operation_id: OperationId::new("op_http_wire"), + operation_version: 1, + tool_name: draft.name, + protocol: Protocol::Rest, + target: Target::Rest(draft.target), + input_schema: draft.input_schema, + output_schema: draft.output_schema, + input_mapping: draft.input_mapping, + output_mapping: draft.output_mapping, + execution_config: ExecutionConfig { + timeout_ms: 2000, + retry_policy: None, + response_cache: None, + idempotency: None, + safety: None, + approval_policy: None, + auth_profile_ref: None, + headers: BTreeMap::new(), + }, + tool_description: draft.tool_description, + }; + let executor = RuntimeExecutorBuilder::new() + .register_adapter(Arc::new(RestAdapter::with_policy( + OutboundHttpPolicy::allowing_hosts(["127.0.0.1"]), + ))) + .build(); + for invalid in [ + json!({"body": {"name": "Ada"}}), + json!({"content_type": "application/json"}), + json!({"content_type": "text/plain", "body": {"name": "Ada"}}), + json!({"content_type": "application/json", "body": {"title": "wrong"}}), + json!({"content_type": "multipart/form-data", "body": {}}), + json!({"content_type": "multipart/form-data", "body": {"file": {"data_base64": "AA==", "filename": "bad\r\nname"}}}), + json!({"content_type": "multipart/form-data", "body": {"file": {"data_base64": "AA==", "content_type": "text/plain"}}}), + json!({"content_type": "multipart/form-data", "body": {"file": {"data_base64": "AA=="}}}), + json!({"content_type": "application/x-www-form-urlencoded", "body": null}), + ] { + assert!( + executor.execute(&operation, &invalid).await.is_err(), + "accepted {invalid}" + ); + } + for invalid_base64 in [ + "AA==\n", + "_w==", + "data:application/octet-stream;base64,AA==", + "AA", + "%%%", + ] { + let invalid = json!({"content_type":"multipart/form-data", "body":{"file":{"data_base64":invalid_base64,"content_type":"image/png"}}}); + assert!(executor.execute(&operation, &invalid).await.is_err()); + } + assert!(requests.lock().unwrap().is_empty()); + for valid in [ + json!({"query_body": "wire-query", "cookie_content_type": "wire-cookie", "content_type": "application/json", "body": {"name": "Ada"}}), + json!({"content_type": "application/x-www-form-urlencoded", "body": {"title": "A B"}}), + json!({"content_type": "multipart/form-data", "body": {"file": {"data_base64": "AAH/", "filename": "image.png", "content_type": "image/png"}}}), + json!({"content_type": "application/json", "body": null}), + json!({}), + ] { + executor.execute(&operation, &valid).await.unwrap(); + } + let captured = requests.lock().unwrap(); + assert_eq!(captured.len(), 5); + assert_eq!(captured[0].0["content-type"], "application/json"); + assert_eq!(captured[0].0["cookie"], "content_type=wire-cookie"); + assert_eq!(captured[0].1, "/events?body=wire-query"); + assert_eq!( + serde_json::from_slice::(&captured[0].2).unwrap(), + json!({"name":"Ada"}) + ); + assert_eq!(&captured[1].2[..], b"title=A+B"); + assert!( + captured[2].0["content-type"] + .to_str() + .unwrap() + .starts_with("multipart/form-data; boundary=") + ); + assert!( + captured[2] + .2 + .windows(9) + .any(|bytes| bytes == b"\r\n\r\n\0\x01\xff\r\n") + ); + assert_eq!(&captured[3].2[..], b"null"); + assert!(captured[4].2.is_empty()); + server.abort(); +} diff --git a/crates/crank-runtime/tests/integration/confirmation.rs b/crates/crank-runtime/tests/integration/confirmation.rs index 290b9a7..c764aa1 100644 --- a/crates/crank-runtime/tests/integration/confirmation.rs +++ b/crates/crank-runtime/tests/integration/confirmation.rs @@ -296,6 +296,9 @@ fn destructive_delete_operation() -> Operation { method: HttpMethod::Delete, path_template: "/orders/{order_id}".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: object_schema(BTreeMap::from([("order_id".to_owned(), string_schema())])), output_schema: object_schema(BTreeMap::from([("deleted".to_owned(), bool_schema())])), @@ -353,6 +356,7 @@ fn destructive_delete_operation() -> Operation { fn object_schema(fields: BTreeMap) -> Schema { Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -367,6 +371,7 @@ fn object_schema(fields: BTreeMap) -> Schema { fn string_schema() -> Schema { Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, @@ -381,6 +386,7 @@ fn string_schema() -> Schema { fn bool_schema() -> Schema { Schema { kind: SchemaKind::Boolean, + format: None, description: None, required: true, nullable: false, diff --git a/crates/crank-runtime/tests/integration/idempotency.rs b/crates/crank-runtime/tests/integration/idempotency.rs index d390b56..11886ea 100644 --- a/crates/crank-runtime/tests/integration/idempotency.rs +++ b/crates/crank-runtime/tests/integration/idempotency.rs @@ -310,6 +310,9 @@ fn idempotent_post_operation() -> Operation { method: HttpMethod::Post, path_template: "/orders".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: object_schema(BTreeMap::from([("request_id".to_owned(), string_schema())])), output_schema: object_schema(BTreeMap::from([("result".to_owned(), string_schema())])), @@ -359,6 +362,7 @@ fn idempotent_post_operation() -> Operation { fn object_schema(fields: BTreeMap) -> Schema { Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -373,6 +377,7 @@ fn object_schema(fields: BTreeMap) -> Schema { fn string_schema() -> Schema { Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, diff --git a/crates/crank-runtime/tests/integration/no_input_get.rs b/crates/crank-runtime/tests/integration/no_input_get.rs index 05a6ba0..0954e38 100644 --- a/crates/crank-runtime/tests/integration/no_input_get.rs +++ b/crates/crank-runtime/tests/integration/no_input_get.rs @@ -72,9 +72,13 @@ fn no_input_get_operation() -> Operation { method: HttpMethod::Get, path_template: "/health".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -86,6 +90,7 @@ fn no_input_get_operation() -> Operation { }, output_schema: Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, diff --git a/crates/crank-runtime/tests/product_metrics.rs b/crates/crank-runtime/tests/product_metrics.rs index 1992a03..275a2c1 100644 --- a/crates/crank-runtime/tests/product_metrics.rs +++ b/crates/crank-runtime/tests/product_metrics.rs @@ -322,6 +322,9 @@ fn operation( method, path_template: "/resource".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: object_schema("key"), output_schema: object_schema("result"), @@ -366,6 +369,7 @@ fn operation( fn object_schema(field: &str) -> Schema { Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -374,6 +378,7 @@ fn object_schema(field: &str) -> Schema { field.to_owned(), Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, diff --git a/crates/crank-runtime/tests/stages.rs b/crates/crank-runtime/tests/stages.rs index 72ff1a5..5450939 100644 --- a/crates/crank-runtime/tests/stages.rs +++ b/crates/crank-runtime/tests/stages.rs @@ -597,6 +597,9 @@ fn operation() -> Operation { method: HttpMethod::Post, path_template: "/test".to_owned(), static_headers: BTreeMap::new(), + request_contract: None, + response_contract: Vec::new(), + multipart_field_mime_types: BTreeMap::new(), }), input_schema: object_schema(BTreeMap::from([("name".to_owned(), string_schema())])), output_schema: object_schema(BTreeMap::from([("accepted".to_owned(), bool_schema())])), @@ -651,6 +654,7 @@ fn operation() -> Operation { fn object_schema(fields: BTreeMap) -> Schema { Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -665,6 +669,7 @@ fn object_schema(fields: BTreeMap) -> Schema { fn string_schema() -> Schema { Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, @@ -679,6 +684,7 @@ fn string_schema() -> Schema { fn bool_schema() -> Schema { Schema { kind: SchemaKind::Boolean, + format: None, ..string_schema() } } diff --git a/crates/crank-schema/src/error.rs b/crates/crank-schema/src/error.rs index 2bc176c..d3c52f2 100644 --- a/crates/crank-schema/src/error.rs +++ b/crates/crank-schema/src/error.rs @@ -4,6 +4,8 @@ use thiserror::Error; pub enum SchemaError { #[error("missing required field at {path}")] MissingField { path: String }, + #[error("unexpected field at {path}")] + UnexpectedField { path: String }, #[error("invalid value at {path}: expected {expected}, got {actual}")] InvalidType { path: String, @@ -25,6 +27,10 @@ impl SchemaError { Self::MissingField { path: path.into() } } + pub fn unexpected_field(path: impl Into) -> Self { + Self::UnexpectedField { path: path.into() } + } + pub fn invalid_type( path: impl Into, expected: &'static str, diff --git a/crates/crank-schema/src/lib.rs b/crates/crank-schema/src/lib.rs index effa1ad..8365ad3 100644 --- a/crates/crank-schema/src/lib.rs +++ b/crates/crank-schema/src/lib.rs @@ -4,4 +4,7 @@ mod normalize; mod validate; pub use error::SchemaError; -pub use model::{Schema, SchemaKind, XmlNodeKind, XmlQualifiedName, XmlSchemaBinding}; +pub use model::{ + CLOSED_OBJECT_SCHEMA_FORMAT, Schema, SchemaKind, XmlNodeKind, XmlQualifiedName, + XmlSchemaBinding, +}; diff --git a/crates/crank-schema/src/model.rs b/crates/crank-schema/src/model.rs index 8f42ccc..a944f19 100644 --- a/crates/crank-schema/src/model.rs +++ b/crates/crank-schema/src/model.rs @@ -3,6 +3,8 @@ use std::collections::BTreeMap; use serde::{Deserialize, Serialize}; use serde_json::Value; +pub const CLOSED_OBJECT_SCHEMA_FORMAT: &str = "crank-closed-object-v1"; + #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum XmlNodeKind { @@ -50,6 +52,9 @@ pub enum SchemaKind { pub struct Schema { #[serde(rename = "type")] pub kind: SchemaKind, + /// OpenAPI/JSON Schema format hint, preserved for REST projections. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub format: Option, #[serde(default, skip_serializing_if = "Option::is_none")] pub description: Option, #[serde(default)] @@ -109,6 +114,7 @@ mod tests { "email".to_owned(), Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, @@ -122,6 +128,7 @@ mod tests { let schema = Schema { kind: SchemaKind::Object, + format: None, description: Some("User input".to_owned()), required: true, nullable: false, @@ -144,6 +151,7 @@ mod tests { fn schema_serializes_type_field() { let schema = Schema { kind: SchemaKind::Array, + format: None, description: None, required: false, nullable: false, @@ -151,6 +159,7 @@ mod tests { fields: BTreeMap::new(), items: Some(Box::new(Schema { kind: SchemaKind::String, + format: None, description: None, required: false, nullable: false, @@ -174,6 +183,7 @@ mod tests { fn schema_roundtrips_through_yaml() { let schema = Schema { kind: SchemaKind::Object, + format: None, description: Some("Lead output".to_owned()), required: true, nullable: false, @@ -182,6 +192,7 @@ mod tests { "id".to_owned(), Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, diff --git a/crates/crank-schema/src/normalize.rs b/crates/crank-schema/src/normalize.rs index 8247296..d73b828 100644 --- a/crates/crank-schema/src/normalize.rs +++ b/crates/crank-schema/src/normalize.rs @@ -9,6 +9,7 @@ impl Schema { match value { Value::Null => Self { kind: SchemaKind::Null, + format: None, description: None, required: true, nullable: true, @@ -33,6 +34,7 @@ impl Schema { fn scalar_schema(kind: SchemaKind) -> Schema { Schema { kind, + format: None, description: None, required: true, nullable: false, @@ -47,6 +49,7 @@ fn scalar_schema(kind: SchemaKind) -> Schema { fn array_schema(items: &[Value]) -> Schema { Schema { kind: SchemaKind::Array, + format: None, description: None, required: true, nullable: false, @@ -63,6 +66,7 @@ fn array_schema(items: &[Value]) -> Schema { fn object_schema(fields: &Map) -> Schema { Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -149,6 +153,7 @@ mod tests { schema, Schema { kind: SchemaKind::Null, + format: None, description: None, required: true, nullable: true, diff --git a/crates/crank-schema/src/validate.rs b/crates/crank-schema/src/validate.rs index 0075f92..5ce5255 100644 --- a/crates/crank-schema/src/validate.rs +++ b/crates/crank-schema/src/validate.rs @@ -57,6 +57,20 @@ fn validate_object(schema: &Schema, value: &Value, path: &str) -> Result<(), Sch } } + // The inline-file envelope is a closed contract. In particular paths, + // URLs, and artifact references must not be smuggled beside `data_base64`. + if matches!( + schema.format.as_deref(), + Some("binary" | crate::CLOSED_OBJECT_SCHEMA_FORMAT) + ) && let Some(unexpected) = object + .keys() + .find(|field| !schema.fields.contains_key(*field)) + { + return Err(SchemaError::unexpected_field(format!( + "{path}.{unexpected}" + ))); + } + Ok(()) } @@ -162,6 +176,7 @@ mod tests { fn validates_nested_object_shape() { let schema = Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -170,6 +185,7 @@ mod tests { "lead".to_owned(), Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -178,6 +194,7 @@ mod tests { "email".to_owned(), Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, @@ -211,6 +228,7 @@ mod tests { fn rejects_missing_required_field() { let schema = Schema { kind: SchemaKind::Object, + format: None, description: None, required: true, nullable: false, @@ -219,6 +237,7 @@ mod tests { "email".to_owned(), Schema { kind: SchemaKind::String, + format: None, description: None, required: true, nullable: false, @@ -243,6 +262,7 @@ mod tests { fn rejects_invalid_scalar_type() { let schema = Schema { kind: SchemaKind::Boolean, + format: None, description: None, required: true, nullable: false, diff --git a/docs/openapi-import.md b/docs/openapi-import.md index 5bbaeae..b4c885e 100644 --- a/docs/openapi-import.md +++ b/docs/openapi-import.md @@ -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-импорт не входят. diff --git a/docs/operation-lifecycle.md b/docs/operation-lifecycle.md index 24cf0b0..c0de512 100644 --- a/docs/operation-lifecycle.md +++ b/docs/operation-lifecycle.md @@ -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` diff --git a/docs/protocols/rest.md b/docs/protocols/rest.md index c2cbf43..6d75423 100644 --- a/docs/protocols/rest.md +++ b/docs/protocols/rest.md @@ -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-логику. diff --git a/docs/schemas/operation-export-v2.schema.json b/docs/schemas/operation-export-v2.schema.json index 9f0e91a..8a420c7 100644 --- a/docs/schemas/operation-export-v2.schema.json +++ b/docs/schemas/operation-export-v2.schema.json @@ -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 } },