use std::borrow::Cow;
use thiserror::Error;
use utoipa::openapi::{
Components, OpenApi, RefOr, Required,
path::{Operation, Parameter, ParameterIn, PathItem},
};
use crate::{
http::{
EndpointContract, EndpointContractRegistry, EndpointContractSnapshot,
EndpointContractValidationError, EndpointPagination, IDEMPOTENCY_KEY_HEADER_NAME,
IdempotencyRequestPolicy,
},
result::{ClassifyError, ErrorKind},
};
pub const CONTRACT_EXTENSION: &str = "x-footing-contract";
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum OpenApiContractError {
#[error(transparent)]
InvalidContracts(#[from] EndpointContractValidationError),
#[error("endpoint contract {method} {path} has no OpenAPI operation")]
UndocumentedEndpoint {
method: &'static str,
path: String,
},
#[error("OpenAPI operation {method} {path} has no endpoint contract")]
OperationWithoutContract {
method: &'static str,
path: String,
},
#[error("OpenAPI path {path} contains no operations")]
EmptyPathItem {
path: String,
},
#[error("OpenAPI path {path}: {reason}")]
UnsupportedPathItem {
path: String,
reason: &'static str,
},
#[error("OpenAPI operation {method} {path} has conflicting footing metadata")]
ConflictingMetadata {
method: &'static str,
path: String,
},
#[error("OpenAPI operation {method} {path}: parameter {name} {reason}")]
InvalidParameter {
method: &'static str,
path: String,
name: &'static str,
reason: &'static str,
},
#[error("failed to serialize OpenAPI contract metadata")]
Serialization(#[from] serde_json::Error),
}
impl ClassifyError for OpenApiContractError {
fn error_kind(&self) -> ErrorKind {
match self {
Self::Serialization(_) => ErrorKind::Internal,
_ => ErrorKind::Validation,
}
}
fn error_code(&self) -> crate::result::ErrorCode {
crate::result::ErrorCode::internal(match self {
Self::InvalidContracts(_) => "openapi_invalid_contracts",
Self::UndocumentedEndpoint { .. } => "openapi_undocumented_endpoint",
Self::OperationWithoutContract { .. } => "openapi_operation_without_contract",
Self::EmptyPathItem { .. } => "openapi_empty_path_item",
Self::UnsupportedPathItem { .. } => "openapi_unsupported_path_item",
Self::ConflictingMetadata { .. } => "openapi_conflicting_metadata",
Self::InvalidParameter { .. } => "openapi_invalid_contract_parameter",
Self::Serialization(_) => "openapi_contract_serialization_failed",
})
}
}
pub fn validate_contracts<P: Copy + 'static>(
document: &OpenApi,
registry: &EndpointContractRegistry<'_, P>,
) -> Result<(), OpenApiContractError> {
registry.validate()?;
for (path, item) in &document.paths.paths {
validate_supported_path_item(item).map_err(|reason| {
OpenApiContractError::UnsupportedPathItem {
path: path.clone(),
reason,
}
})?;
}
for endpoint in registry.endpoints() {
let method = endpoint.method().as_str();
let path = endpoint.path().as_str();
let (item, operation) = document
.paths
.paths
.get(path)
.and_then(|item| {
operations(item)
.into_iter()
.find_map(|(candidate, operation)| {
(candidate == method)
.then_some(operation)
.flatten()
.map(|operation| (item, operation))
})
})
.ok_or_else(|| OpenApiContractError::UndocumentedEndpoint {
method,
path: path.to_owned(),
})?;
validate_parameters(endpoint, item, operation, document.components.as_ref())?;
}
for (path, item) in &document.paths.paths {
let operations = operations(item);
if operations.iter().all(|(_, operation)| operation.is_none()) {
return Err(OpenApiContractError::EmptyPathItem { path: path.clone() });
}
for (method, operation) in operations {
if operation.is_some()
&& !registry.endpoints().iter().any(|endpoint| {
endpoint.method().as_str() == method && endpoint.path().as_str() == path
})
{
return Err(OpenApiContractError::OperationWithoutContract {
method,
path: path.clone(),
});
}
}
}
Ok(())
}
pub fn annotate_contracts<P: Copy + 'static>(
mut document: OpenApi,
registry: &EndpointContractRegistry<'_, P>,
permission_to_string: impl Fn(P) -> String,
) -> Result<OpenApi, OpenApiContractError> {
validate_contracts(&document, registry)?;
for endpoint in registry.endpoints() {
let method = endpoint.method().as_str();
let path = endpoint.path().as_str();
let contract = serde_json::to_value(endpoint.document(&permission_to_string))?;
let metadata = serde_json::Value::Object(serde_json::Map::from_iter([
(
"schema_version".to_owned(),
EndpointContractSnapshot::SCHEMA_VERSION.into(),
),
("contract".to_owned(), contract),
]));
let operation = document
.paths
.paths
.get_mut(path)
.and_then(|item| operation_mut(item, method))
.ok_or_else(|| OpenApiContractError::UndocumentedEndpoint {
method,
path: path.to_owned(),
})?;
let extensions = operation.extensions.get_or_insert_default();
if extensions
.get(CONTRACT_EXTENSION)
.is_some_and(|existing| existing != &metadata)
{
return Err(OpenApiContractError::ConflictingMetadata {
method,
path: path.to_owned(),
});
}
extensions.insert(CONTRACT_EXTENSION.to_owned(), metadata);
}
Ok(document)
}
pub(super) fn validate_supported_path_item(item: &PathItem) -> Result<(), &'static str> {
if item.ref_path.is_some() || item.query.is_some() || !item.additional_operations.is_empty() {
return Err("registered paths must inline supported HTTP operations");
}
Ok(())
}
pub(super) fn operations(item: &PathItem) -> [(&'static str, Option<&Operation>); 8] {
[
("GET", item.get.as_ref()),
("PUT", item.put.as_ref()),
("POST", item.post.as_ref()),
("DELETE", item.delete.as_ref()),
("OPTIONS", item.options.as_ref()),
("HEAD", item.head.as_ref()),
("PATCH", item.patch.as_ref()),
("TRACE", item.trace.as_ref()),
]
}
pub(super) fn operations_mut(item: &mut PathItem) -> impl Iterator<Item = &mut Operation> {
let PathItem {
get,
put,
post,
delete,
options,
head,
patch,
trace,
query,
additional_operations,
..
} = item;
[get, put, post, delete, options, head, patch, trace, query]
.into_iter()
.filter_map(Option::as_mut)
.chain(additional_operations.values_mut())
}
fn validate_parameters<P: Copy + 'static>(
endpoint: &EndpointContract<P>,
item: &PathItem,
operation: &Operation,
components: Option<&Components>,
) -> Result<(), OpenApiContractError> {
let check = |name: &'static str, location: ParameterIn, required: Option<Required>| {
let invalid = |reason| OpenApiContractError::InvalidParameter {
method: endpoint.method().as_str(),
path: endpoint.path().as_str().to_owned(),
name,
reason,
};
let matches = |parameter: &Cow<'_, Parameter>| {
parameter.parameter_in == location
&& if location == ParameterIn::Header {
parameter.name.eq_ignore_ascii_case(name)
} else {
parameter.name == name
}
};
let find = |parameters: Option<&Vec<RefOr<Parameter>>>| {
let parameters = parameters
.into_iter()
.flatten()
.map(|parameter| resolve_parameter(parameter, components).map_err(invalid))
.collect::<Result<Vec<_>, _>>()?;
let mut matching = parameters.into_iter().filter(matches);
let found = matching.next();
if matching.next().is_some() {
Err(invalid("is duplicated"))
} else {
Ok(found.map(|parameter| parameter.required.clone()))
}
};
let inherited = find(item.parameters.as_ref())?;
let actual = find(operation.parameters.as_ref())?.or(inherited);
match (actual, required) {
(None, None) => Ok(()),
(Some(_), None) => Err(invalid("is documented for a disabled contract")),
(None, Some(_)) => Err(invalid("is missing")),
(Some(actual), Some(required)) if actual == required => Ok(()),
(Some(_), Some(Required::True)) => Err(invalid("must be required")),
(Some(_), Some(Required::False)) => Err(invalid("must be optional")),
}
};
let required = match endpoint.idempotency() {
IdempotencyRequestPolicy::Disabled => None,
IdempotencyRequestPolicy::HeaderOptional => Some(Required::False),
IdempotencyRequestPolicy::Required => Some(Required::True),
};
check(IDEMPOTENCY_KEY_HEADER_NAME, ParameterIn::Header, required)?;
let pagination: &[&str] = match endpoint.pagination() {
EndpointPagination::None => &[],
EndpointPagination::Cursor => &["page_size", "cursor", "include_total"],
EndpointPagination::Offset => &["page", "page_size"],
};
for &name in pagination {
check(name, ParameterIn::Query, Some(Required::False))?;
}
Ok(())
}
pub(super) fn resolve_parameter<'a>(
mut parameter: &'a RefOr<Parameter>,
components: Option<&'a Components>,
) -> Result<Cow<'a, Parameter>, &'static str> {
let mut description = None;
for _ in 0..=components.map_or(0, |components| components.parameters.len()) {
match parameter {
RefOr::T(parameter) => {
let mut parameter = Cow::Borrowed(parameter);
if let Some(description) = description {
parameter.to_mut().description = Some(description);
}
return Ok(parameter);
}
RefOr::Ref(reference) => {
if description.is_none() && !reference.description.is_empty() {
description = Some(reference.description.clone());
}
let name = parameter_component_name(&reference.ref_location)?;
parameter = components
.and_then(|components| components.parameters.get(&name))
.ok_or("references a missing parameter component")?;
}
}
}
Err("contains a cyclic parameter reference")
}
fn parameter_component_name(reference: &str) -> Result<String, &'static str> {
let fragment = reference
.strip_prefix('#')
.ok_or("must reference a local parameter component")?;
for (index, byte) in fragment.bytes().enumerate() {
if byte == b'%'
&& !fragment
.as_bytes()
.get(index + 1..index + 3)
.is_some_and(|hex| hex.iter().all(u8::is_ascii_hexdigit))
{
return Err("contains invalid percent encoding in a parameter reference");
}
}
let pointer = percent_encoding::percent_decode_str(fragment)
.decode_utf8()
.map_err(|_| "contains invalid UTF-8 in a parameter reference")?;
let token = pointer
.strip_prefix("/components/parameters/")
.filter(|token| !token.contains('/'))
.ok_or("must reference a local parameter component")?;
if !token
.split('~')
.skip(1)
.all(|part| part.starts_with(['0', '1']))
{
return Err("contains invalid JSON Pointer escaping in a parameter reference");
}
Ok(token.replace("~1", "/").replace("~0", "~"))
}
fn operation_mut<'a>(item: &'a mut PathItem, method: &str) -> Option<&'a mut Operation> {
match method {
"GET" => item.get.as_mut(),
"PUT" => item.put.as_mut(),
"POST" => item.post.as_mut(),
"DELETE" => item.delete.as_mut(),
"OPTIONS" => item.options.as_mut(),
"HEAD" => item.head.as_mut(),
"PATCH" => item.patch.as_mut(),
_ => None,
}
}