feat(import): preserve supported HTTP contracts

This commit is contained in:
bsodfather committed 2026-09-13 03:30:31 +03:00
1 parent 083974c27f
commit f8ee7c9bfe
87 files changed
+7496 -534

No files matched your search

Generated
+3
View File
@@ -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",
+6
View File
@@ -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,
+3
View File
@@ -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),
+6 -1
View File
@@ -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"));
}
@@ -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();
@@ -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,
@@ -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());
@@ -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();
@@ -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);
}
@@ -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::<Vec<_>>();
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,
}
}
@@ -489,6 +489,9 @@ pub(super) fn test_operation(base_url: &str, name: &str) -> Operation<Schema, Ma
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"),
@@ -543,6 +546,7 @@ pub(super) fn test_operation(base_url: &str, name: &str) -> Operation<Schema, Ma
pub(super) fn object_schema(field_name: &str) -> 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,
+1
View File
@@ -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" }
+488
View File
@@ -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<String, Vec<String>>>,
max_request_bytes: usize,
) -> Result<reqwest::RequestBuilder, RestAdapterError> {
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<reqwest::RequestBuilder, RestAdapterError> {
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<Option<String>, 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<Vec<u8>, 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<Vec<u8>, 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<String, RestAdapterError> {
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<String, Vec<String>>>,
max_request_bytes: usize,
) -> Result<reqwest::multipart::Form, RestAdapterError> {
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<String, Value>,
source_mime_types: Option<&BTreeMap<String, Vec<String>>>,
payload_budget: &mut MultipartPayloadBudget,
) -> Result<reqwest::multipart::Part, RestAdapterError> {
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<usize, RestAdapterError> {
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<u8>,
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<u8> {
self.bytes
}
}
impl io::Write for BoundedBuffer {
fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
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<String>>,
) -> 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 })
));
}
}
+134 -152
View File
@@ -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<String, String>,
) -> Result<Option<String>, RestAdapterError> {
let internal = headers
.keys()
.filter(|name| name.starts_with("x-crank-internal-cookie-"))
.cloned()
.collect::<Vec<_>>();
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<String> {
pub(crate) fn ip_match_hosts(address: IpAddr) -> Vec<String> {
match address {
IpAddr::V4(address) => vec![address.to_string()],
IpAddr::V6(address) => {
@@ -667,11 +768,26 @@ fn build_url(target: &RestTarget, request: &RestRequest) -> Result<reqwest::Url,
url: "url".to_owned(),
})?;
let path = substitute_path_params(&target.path_template, &request.path_params);
let mut url = base_url.join(path.trim_start_matches('/')).map_err(|_| {
RestAdapterError::InvalidBaseUrl {
url: "url".to_owned(),
}
})?;
let mut url = if target.request_contract.is_some() || !target.response_contract.is_empty() {
let base_path = base_url.path().trim_end_matches('/');
let target_path = path.trim_start_matches('/');
let combined_path = if target_path.is_empty() {
base_path.to_owned()
} else if base_path.is_empty() {
format!("/{target_path}")
} else {
format!("{base_path}/{target_path}")
};
let mut url = base_url;
url.set_path(&combined_path);
url
} else {
base_url.join(path.trim_start_matches('/')).map_err(|_| {
RestAdapterError::InvalidBaseUrl {
url: "url".to_owned(),
}
})?
};
{
let mut query = url.query_pairs_mut();
@@ -842,107 +958,6 @@ impl Injector for ReqwestHeaderInjector<'_> {
}
}
async fn decode_body(
response: reqwest::Response,
max_response_bytes: usize,
) -> Result<Value, 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);
}
match serde_json::from_slice::<Value>(&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<usize> {
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<String, String> {
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,
}
}
@@ -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));
}
+4
View File
@@ -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,
}
+10 -1
View File
@@ -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<RestAdapterError> 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<RestAdapterError> for ProtocolAdapterError {
RestAdapterError::InvalidSseEvent => Self::InvalidResponse {
dispatch: DispatchEvidence::MayHaveDispatched,
},
RestAdapterError::InvalidResponseContract { .. } => Self::InvalidResponse {
dispatch: DispatchEvidence::MayHaveDispatched,
},
}
}
}
+2
View File
@@ -15,6 +15,8 @@ pub struct RestRequest {
pub trusted_header_names: BTreeSet<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub body: Option<Value>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub body_content_type: Option<String>,
pub timeout_ms: u64,
}
+127
View File
@@ -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::<Value>(&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<String, String>,
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::<Vec<_>>();
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<String, String> {
headers
.iter()
.filter_map(|(name, value)| {
value
.to_str()
.ok()
.map(|value| (name.as_str().to_owned(), value.to_owned()))
})
.collect()
}
@@ -1,5 +1,6 @@
mod integration {
mod client;
mod external_reference_fetcher;
mod multipart;
mod outbound_security;
}
@@ -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",
@@ -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<String>,
content_type: Option<String>,
bytes: Vec<u8>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
struct WireRequest {
content_types: Vec<String>,
cookie: Option<String>,
body: Vec<u8>,
}
#[derive(Default)]
struct CaptureState {
multipart: Mutex<Vec<MultipartPart>>,
wire: Mutex<Vec<WireRequest>>,
}
#[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::<u8>::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::<u8>::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::<Value>(&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::<Vec<_>>();
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::<Value>(&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<CaptureState>) {
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<Arc<CaptureState>>,
mut multipart: Multipart,
) -> (StatusCode, Json<Value>) {
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<Arc<CaptureState>>,
headers: HeaderMap,
body: Bytes,
) -> (StatusCode, Json<Value>) {
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})))
}
@@ -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",
+81 -5
View File
@@ -108,8 +108,9 @@ fn search_mode_tool_definitions(policy: &ToolSelectionPolicy) -> Vec<Value> {
pub fn tool_definitions(tool: &PublishedAgentTool) -> Vec<Value> {
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<Value> {
)]
}
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<ToolCatalogAnalysis, ToolCatalogAnalysisError> {
@@ -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::<Vec<_>>()
}),
};
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
}
@@ -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()
}
+8
View File
@@ -150,6 +150,7 @@ pub struct PreparedRequest {
pub headers: BTreeMap<String, String>,
pub trusted_header_names: BTreeSet<String>,
pub body: Option<Value>,
pub body_content_type: Option<String>,
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
+2 -1
View File
@@ -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::{
+64
View File
@@ -101,6 +101,62 @@ pub struct RestTarget {
pub path_template: String,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub static_headers: BTreeMap<String, String>,
/// 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<RestRequestContract>,
/// 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<RestResponseDescriptor>,
/// 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<String, BTreeMap<String, Vec<String>>>,
}
/// 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<String>,
/// 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<String>,
pub body_required: bool,
pub variants: Vec<RestRequestDescriptor>,
}
#[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<serde_json::Value, serde_json::Value> {
@@ -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}}}),
+2
View File
@@ -14,6 +14,8 @@ pub enum HttpMethod {
Put,
Patch,
Delete,
Head,
Options,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+1 -1
View File
@@ -14,4 +14,4 @@ serde.workspace = true
serde_json.workspace = true
serde_yaml.workspace = true
thiserror.workspace = true
url.workspace = true
@@ -0,0 +1,25 @@
use crank_core::HttpMethod;
use crate::rest::model::{ImportFinding, ImportFindingSeverity};
pub(super) fn from_lower(value: &str) -> Option<HttpMethod> {
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,
}
}
@@ -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 }
}
@@ -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<String>,
) -> 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<String>,
input_fields: &mut BTreeMap<String, crank_schema::Schema>,
) -> Vec<BodyFieldMapping> {
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>) -> 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
}
@@ -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<String>) -> 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<String>,
) -> 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::<Vec<_>>();
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<String>, fields: BTreeMap<String, Schema>) -> 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<String>) -> Schema {
let required_fields = value
.get("required")
.and_then(Value::as_array)
.map(|items| {
items
.iter()
.filter_map(Value::as_str)
.collect::<std::collections::BTreeSet<_>>()
})
.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<String>) -> 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<String> {
value
.get(key)
.and_then(Value::as_str)
.map(ToOwned::to_owned)
}
+21 -6
View File
@@ -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<serde_json::Value>,
}
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)
@@ -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<ImportFinding>,
locations: &mut Vec<Option<SourceLocation>>,
) {
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-")
}
+14 -4
View File
@@ -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,
+72 -2
View File
@@ -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<NormalizedSchema>,
pub response_schema: Option<NormalizedSchema>,
#[serde(default)]
pub request_body_variants: Vec<NormalizedRequestBodyVariant>,
#[serde(default)]
pub response_variants: Vec<NormalizedResponseVariant>,
#[serde(default)]
pub servers: Vec<String>,
#[serde(default)]
pub findings: Vec<NormalizedFinding>,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct NormalizedRequestBodyVariant {
pub content_type: String,
pub required: bool,
pub schema: Option<NormalizedSchema>,
/// 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<String, Vec<String>>,
pub source_location: SourceLocation,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct NormalizedResponseVariant {
pub status_code: u16,
pub content_type: Option<String>,
pub schema: Option<NormalizedSchema>,
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<String, NormalizedSchema>,
required: Vec<String>,
nullable: bool,
default_value: Option<NormalizedLiteral>,
},
Array {
items: Option<Box<NormalizedSchema>>,
nullable: bool,
default_value: Option<NormalizedLiteral>,
},
Reference {
reference: UnresolvedReference,
@@ -468,11 +496,21 @@ pub struct RestImportOperation {
pub request_body_schema: Option<Value>,
#[serde(skip)]
pub request_body_schema_location: Option<SourceLocation>,
/// 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<RestRequestBodyVariant>,
pub response_schema: Option<Value>,
#[serde(skip)]
pub response_schema_location: Option<SourceLocation>,
/// 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<RestResponseVariant>,
pub servers: Vec<String>,
pub findings: Vec<ImportFinding>,
#[serde(skip)]
pub internal_finding_locations: Vec<SourceLocation>,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
@@ -488,6 +526,37 @@ pub struct RestImportParameter {
pub schema_source_location: Option<SourceLocation>,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct RestRequestBodyVariant {
pub content_type: String,
pub required: bool,
pub schema: Option<Value>,
/// MIME types from OpenAPI's multipart `encoding.*.contentType`.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub multipart_field_mime_types: BTreeMap<String, Vec<String>>,
#[serde(skip, default = "empty_source_location")]
pub source_location: SourceLocation,
#[serde(skip, default)]
pub schema_source_location: Option<SourceLocation>,
/// 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<String, SourceLocation>,
}
#[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<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub schema: Option<Value>,
#[serde(skip, default = "empty_source_location")]
pub source_location: SourceLocation,
#[serde(skip, default)]
pub schema_source_location: Option<SourceLocation>,
}
fn empty_source_location() -> SourceLocation {
SourceLocation {
pointer: String::new(),
@@ -500,4 +569,5 @@ pub enum RestParameterLocation {
Path,
Query,
Header,
Cookie,
}
+116 -121
View File
@@ -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::<Vec<_>>();
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<Item = &'a crate::rest::model::RestImportOperation>,
mut findings: Vec<ImportFinding>,
legacy: bool,
) -> ImportPreview {
let mut groups: BTreeMap<String, ImportGroupPreview> = 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::<Vec<_>>(),
"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::<serde_json::Map<_, _>>(), "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::<Vec<_>>()})
}
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,
}
}
@@ -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::<Vec<_>>();
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 {
@@ -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<String, &CanonicalSourceNode>,
) -> 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<String, &CanonicalSourceNode>,
) -> 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<String> {
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(_))))
}
@@ -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::<Vec<_>>(),
"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::<serde_json::Map<_, _>>(),
"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,
}
}
@@ -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<String, SourceLocation>,
coverage: &mut Vec<CoverageEntry>,
) -> 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<CoverageEntry>,
) -> 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::<Vec<_>>();
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))),
+263 -51
View File
@@ -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<RestImportDocument, ImportParseErro
for (path, path_item) in paths {
if !path_item.is_object() {
findings.push(path_item_blocker(path));
findings.push(super::http_methods::invalid_path_item());
internal_finding_locations.push(Some(crate::rest::model::SourceLocation {
pointer: format!("/paths/{}", path.replace('~', "~0").replace('/', "~1")),
}));
continue;
}
for method_name in ["head", "options", "trace", "connect"] {
for method_name in super::openapi3_findings::unsupported_methods(path_item) {
if path_item.get(method_name).is_some() {
findings.push(document_blocker(
"unsupported_http_method",
@@ -99,7 +99,7 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
path_servers.findings,
);
let path_servers = path_servers.servers;
for method_name in ["get", "post", "put", "patch", "delete"] {
for method_name in ["get", "post", "put", "patch", "delete", "head", "options"] {
let Some(operation_value) = path_item.get(method_name) else {
continue;
};
@@ -117,7 +117,7 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
}));
continue;
}
let Some(method) = method_from_lower(method_name) else {
let Some(method) = super::http_methods::from_lower(method_name) else {
continue;
};
let operation_pointer = format!("{path_pointer}/{method_name}");
@@ -154,6 +154,17 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
tags.findings,
);
let mut located_operation_findings =
super::openapi3_findings::operation(operation_value, &operation_pointer);
located_operation_findings.extend(super::openapi3_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,
@@ -179,16 +190,17 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
&operation_pointer,
)
.map(|(_, location)| location),
response_schema: response_schema(operation_value, &operation_pointer)
.map(|(schema, _)| schema),
response_schema_location: response_schema(operation_value, &operation_pointer)
.map(|(_, location)| location),
request_body_variants: request_body_variants(operation_value, &operation_pointer),
response_schema: response_schema.as_ref().map(|(schema, _)| schema.clone()),
response_schema_location: response_schema.map(|(_, location)| location),
response_variants: response_variants(operation_value, &operation_pointer, method),
servers: if operation_servers.is_empty() {
path_servers.clone()
} else {
operation_servers
},
findings: operation_findings(operation_value),
findings: operation_findings,
internal_finding_locations,
});
}
}
@@ -251,7 +263,7 @@ pub fn parse_document_legacy_v1(root: &Value) -> Result<RestImportDocument, Impo
let Some(operation) = path_item.get(method_name) else {
continue;
};
let Some(method) = method_from_lower(method_name) else {
let Some(method) = super::http_methods::from_lower(method_name) else {
continue;
};
let operation_pointer = format!("{path_pointer}/{method_name}");
@@ -281,10 +293,13 @@ pub fn parse_document_legacy_v1(root: &Value) -> Result<RestImportDocument, Impo
parameters,
request_body_schema: legacy_request_body_schema(root, operation),
request_body_schema_location: None,
request_body_variants: Vec::new(),
response_schema: legacy_response_schema(root, operation),
response_schema_location: None,
response_variants: Vec::new(),
servers: legacy_servers(operation.get("servers")),
findings: legacy_operation_findings(operation),
internal_finding_locations: Vec::new(),
});
}
}
@@ -458,6 +473,10 @@ fn parse_servers(value: Option<&Value>, 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<RestRequestBodyVariant> {
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<String, Vec<String>> {
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::<Vec<_>>()
})
.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<ImportFinding> {
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<HttpMethod> {
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<RestResponseVariant> {
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::<u16>()
.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::<Vec<_>>();
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
}
@@ -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<String>,
pointer: &str,
) {
findings.push((
document_blocker(code, message),
SourceLocation {
pointer: pointer.to_owned(),
},
));
}
fn escape(value: &str) -> String {
value.replace('~', "~0").replace('/', "~1")
}
+358 -31
View File
@@ -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::<Vec<_>>();
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(&parameter_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::<Vec<_>>();
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<String>,
input_fields: &mut BTreeMap<String, crank_schema::Schema>,
) -> Vec<BodyFieldMapping> {
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::<Vec<_>>();
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<String, crank_schema::Schema>,
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::<Vec<_>>();
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<String>,
fields: BTreeMap<String, crank_schema::Schema>,
) -> 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<RestRequestContract> {
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<String>,
input_fields: &mut BTreeMap<String, crank_schema::Schema>,
@@ -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>,
) -> 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>) -> 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,
+93 -8
View File
@@ -6,6 +6,7 @@ use serde_json::Value;
pub fn any_object(description: Option<String>) -> 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<String>,
) -> Schema {
schema_from_openapi_context(value, required, description, false)
}
pub fn schema_from_multipart(
value: Option<&Value>,
required: bool,
description: Option<String>,
) -> Schema {
schema_from_openapi_context(value, required, description, true)
}
fn schema_from_openapi_context(
value: Option<&Value>,
required: bool,
description: Option<String>,
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<String>, fields: BTreeMap<String, Schema>) -> Schema {
Schema {
kind: SchemaKind::Object,
format: None,
description,
required: true,
nullable: false,
@@ -152,7 +190,12 @@ pub fn object_with_fields(description: Option<String>, fields: BTreeMap<String,
}
}
fn object_schema(value: &Value, required: bool, description: Option<String>) -> Schema {
fn object_schema(
value: &Value,
required: bool,
description: Option<String>,
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<String>) ->
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<String>) ->
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<String>) ->
}
}
fn primitive(kind: SchemaKind, required: bool, description: Option<String>) -> Schema {
fn primitive(
kind: SchemaKind,
required: bool,
description: Option<String>,
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<String>) -> 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(),
+366 -70
View File
@@ -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<RestImportDocument, ImportParseError> {
@@ -23,6 +23,11 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
let servers = swagger_servers(root);
let mut findings = Vec::new();
let mut internal_finding_locations = Vec::new();
append_parameter_findings(
&mut findings,
&mut internal_finding_locations,
super::swagger2_findings::servers(root),
);
if servers.is_empty() {
findings.push(document_finding(
"missing_servers",
@@ -41,13 +46,13 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
for (path, path_item) in paths {
if !path_item.is_object() {
findings.push(path_item_blocker(path));
findings.push(super::http_methods::invalid_path_item());
internal_finding_locations.push(Some(crate::rest::model::SourceLocation {
pointer: format!("/paths/{}", path.replace('~', "~0").replace('/', "~1")),
}));
continue;
}
for method_name in ["head", "options", "trace", "connect"] {
for method_name in super::swagger2_findings::unsupported_methods(path_item) {
if path_item.get(method_name).is_some() {
findings.push(document_blocker(
"unsupported_http_method",
@@ -74,7 +79,7 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
path_parameters.findings,
);
let path_parameters = path_parameters.parameters;
for method_name in ["get", "post", "put", "patch", "delete"] {
for method_name in ["get", "post", "put", "patch", "delete", "head", "options"] {
let Some(operation_value) = path_item.get(method_name) else {
continue;
};
@@ -92,7 +97,7 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
}));
continue;
}
let Some(method) = method_from_lower(method_name) else {
let Some(method) = super::http_methods::from_lower(method_name) else {
continue;
};
let mut operation_parameters = path_parameters.clone();
@@ -101,11 +106,7 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
operation_value.get("parameters"),
&format!("{path_pointer}/{method_name}/parameters"),
);
append_parameter_findings(
&mut findings,
&mut internal_finding_locations,
parsed_parameters.findings,
);
let parsed_parameter_findings = parsed_parameters.findings;
operation_parameters.extend(parsed_parameters.parameters);
deduplicate_parameters(&mut operation_parameters);
let tags = tags(
@@ -117,6 +118,13 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
&mut internal_finding_locations,
tags.findings,
);
let request_body_variants = swagger_request_body_variants(
root,
path_item,
operation_value,
&path_pointer,
&format!("{path_pointer}/{method_name}"),
);
let request_body_schema = operation_parameters
.iter()
.find(|parameter| parameter.name == "body")
@@ -135,6 +143,19 @@ fn parse_document_v2(root: &Value) -> Result<RestImportDocument, ImportParseErro
.filter(|parameter| parameter.name != "body")
.collect::<Vec<_>>();
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<RestImportDocument, ImportParseErro
.as_ref()
.map(|(schema, _)| schema.clone()),
request_body_schema_location: request_body_schema.map(|(_, location)| location),
response_schema: response_schema(
request_body_variants,
response_schema: response_schema.as_ref().map(|(schema, _)| schema.clone()),
response_schema_location: response_schema.map(|(_, location)| location),
response_variants: swagger_response_variants(
root,
operation_value,
&format!("{path_pointer}/{method_name}"),
)
.map(|(schema, _)| schema),
response_schema_location: response_schema(
operation_value,
&format!("{path_pointer}/{method_name}"),
)
.map(|(_, location)| location),
&operation_pointer,
method,
),
servers: Vec::new(),
findings: swagger_operation_findings(path, operation_value),
findings: operation_findings,
internal_finding_locations,
});
}
}
@@ -221,7 +242,7 @@ pub fn parse_document_legacy_v1(root: &Value) -> Result<RestImportDocument, Impo
let Some(operation) = path_item.get(method_name) else {
continue;
};
let Some(method) = method_from_lower(method_name) else {
let Some(method) = super::http_methods::from_lower(method_name) else {
continue;
};
let operation_pointer = format!("{path_pointer}/{method_name}");
@@ -259,10 +280,13 @@ pub fn parse_document_legacy_v1(root: &Value) -> Result<RestImportDocument, Impo
parameters,
request_body_schema,
request_body_schema_location: None,
request_body_variants: Vec::new(),
response_schema: legacy_response_schema(root, operation),
response_schema_location: None,
response_variants: Vec::new(),
servers: Vec::new(),
findings: swagger_operation_findings(path, operation),
findings: super::swagger2_findings::legacy_operation(path, operation),
internal_finding_locations: Vec::new(),
});
}
}
@@ -387,10 +411,24 @@ fn swagger_servers(root: &Value) -> Vec<String> {
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::<Vec<_>>())
.map(|items| {
items
.iter()
.filter_map(Value::as_str)
.filter(|scheme| matches!(*scheme, "http" | "https"))
.collect::<Vec<_>>()
})
.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<Value> {
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<RestRequestBodyVariant> {
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(&parameters);
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<crate::rest::model::SourceLocation>,
std::collections::BTreeMap<String, crate::rest::model::SourceLocation>,
)> {
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<String> {
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::<Vec<_>>()
})
.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<RestResponseVariant> {
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::<Vec<_>>();
let mut variants = responses
.iter()
.filter_map(|(code, response)| {
let status_code = code
.parse::<u16>()
.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::<Vec<_>>();
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<crate::rest::model::ImportFinding> {
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<HttpMethod> {
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,
}
}
@@ -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<ImportFinding> {
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")
}
+2 -2
View File
@@ -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"
@@ -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::<Vec<_>>();
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::<Vec<_>>();
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());
}
+68
View File
@@ -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"]
);
}
@@ -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);
}
@@ -246,7 +246,7 @@ components:
.iter()
.map(|parameter| parameter.name.as_str())
.collect::<Vec<_>>(),
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]
+351 -7
View File
@@ -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::<Vec<_>>();
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::<Vec<_>>();
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::<Vec<_>>();
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::<Vec<_>>();
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<_>>(),
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<_>>(),
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());
}
}
@@ -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()]
));
@@ -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);
}
@@ -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<_>>(),
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<_>>(),
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<_>>(),
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
}));
}
+1
View File
@@ -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())),
])),
)])),
+12 -1
View File
@@ -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),
+4
View File
@@ -122,6 +122,8 @@ fn target_root_context(root: JsonPathRoot) -> Option<MappingTargetContext> {
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,
@@ -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(),
),
@@ -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,
@@ -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");
+1
View File
@@ -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"
+1
View File
@@ -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,
},
@@ -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,
+51 -5
View File
@@ -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<T>(span: &Span, result: &Result<T, RuntimeError>) {
match result {
Ok(_) => StageOutcome::Success.record(span),
+13 -2
View File
@@ -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,
+4
View File
@@ -51,6 +51,8 @@ pub struct PreparedRequest {
pub trusted_header_names: BTreeSet<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub body: Option<serde_json::Value>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub body_content_type: Option<String>,
#[serde(default)]
pub timeout_ms: u64,
}
@@ -72,6 +74,7 @@ impl From<PreparedRequest> 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<crank_core::PreparedRequest> 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,
}
}
+169 -4
View File
@@ -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<Self, RuntimeError> {
pub fn from_mapping_output(mapped: &Value, target: &Target) -> Result<Self, RuntimeError> {
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<String, String> {
}
}
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(),
})
}
}
+355
View File
@@ -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<AtomicUsize>,
prepared: Arc<Mutex<Option<crank_core::PreparedRequest>>>,
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<AdapterResponse, ProtocolAdapterError> {
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<String, String>, body: Value) -> AdapterResponse {
AdapterResponse {
status_code,
headers,
data: body.clone(),
body,
}
}
@@ -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<Mutex<Vec<(HeaderMap, String, Bytes)>>>;
async fn capture(
State(requests): State<Requests>,
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::<serde_json::Value>(&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();
}
@@ -296,6 +296,9 @@ fn destructive_delete_operation() -> Operation<Schema, MappingSet> {
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<Schema, MappingSet> {
fn object_schema(fields: BTreeMap<String, Schema>) -> Schema {
Schema {
kind: SchemaKind::Object,
format: None,
description: None,
required: true,
nullable: false,
@@ -367,6 +371,7 @@ fn object_schema(fields: BTreeMap<String, Schema>) -> 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,
@@ -310,6 +310,9 @@ fn idempotent_post_operation() -> Operation<Schema, MappingSet> {
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<Schema, MappingSet> {
fn object_schema(fields: BTreeMap<String, Schema>) -> Schema {
Schema {
kind: SchemaKind::Object,
format: None,
description: None,
required: true,
nullable: false,
@@ -373,6 +377,7 @@ fn object_schema(fields: BTreeMap<String, Schema>) -> Schema {
fn string_schema() -> Schema {
Schema {
kind: SchemaKind::String,
format: None,
description: None,
required: true,
nullable: false,
@@ -72,9 +72,13 @@ fn no_input_get_operation() -> Operation<Schema, MappingSet> {
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<Schema, MappingSet> {
},
output_schema: Schema {
kind: SchemaKind::Object,
format: None,
description: None,
required: true,
nullable: false,
@@ -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,
+6
View File
@@ -597,6 +597,9 @@ fn operation() -> Operation<Schema, MappingSet> {
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<Schema, MappingSet> {
fn object_schema(fields: BTreeMap<String, Schema>) -> Schema {
Schema {
kind: SchemaKind::Object,
format: None,
description: None,
required: true,
nullable: false,
@@ -665,6 +669,7 @@ fn object_schema(fields: BTreeMap<String, Schema>) -> 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()
}
}
+6
View File
@@ -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<String>) -> Self {
Self::UnexpectedField { path: path.into() }
}
pub fn invalid_type(
path: impl Into<String>,
expected: &'static str,
+4 -1
View File
@@ -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,
};
+11
View File
@@ -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<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
#[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,
+5
View File
@@ -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<String, Value>) -> 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,
+20
View File
@@ -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,
+16 -7
View File
@@ -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-импорт не входят.
+4
View File
@@ -22,6 +22,10 @@ Aggregate reads return a strong state `ETag` bound to workspace, Operation ident
Canonical export uses `format_version: "2"`. Legacy version 1 is import-only and is normalized into v2. The body limit is 256 KiB; one document, depth 64, at most 20,000 nodes, 4,096 collection items and 64 KiB line/scalar values are accepted. Credentials, URL userinfo, storage paths and persistence/runtime-only metadata are never portable.
Portable REST targets use the uppercase HTTP method names `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` and `OPTIONS`. The optional versioned `request_contract` records supported media types and their input-schema branches. A multi-media request exposes a `content_type` selector alongside the typed `body`; selecting a media type also selects its validation schema. Multipart field MIME choices remain in `multipart_field_mime_types`.
`response_contract` preserves successful status/media branches and their output-schema association. A branch without a media type represents an explicit no-content outcome, with `null` as its output. Schema `format`, defaults and nullability survive export/import. Existing documents without HTTP descriptors retain their legacy execution semantics; their bodies are not interpreted as internal media-selector envelopes.
## Stable failure codes
- `operation_precondition_required`
+16 -9
View File
@@ -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-логику.
+40 -2
View File
@@ -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 } },