spikard 0.2.0 → 0.2.5

data/vendor/crates/spikard-http/src/middleware/validation.rs

@@ -0,0 +1,287 @@
+//! JSON schema validation middleware
+
+use crate::problem::{CONTENT_TYPE_PROBLEM_JSON, ProblemDetails};
+use axum::http::{HeaderMap, StatusCode};
+use axum::response::{IntoResponse, Response};
+use serde_json::json;
+
+/// Check if a media type is JSON or has a +json suffix
+pub fn is_json_content_type(mime: &mime::Mime) -> bool {
+    (mime.type_() == mime::APPLICATION && mime.subtype() == mime::JSON) || mime.suffix() == Some(mime::JSON)
+}
+
+/// Validate that Content-Type is JSON-compatible when route expects JSON
+#[allow(clippy::result_large_err)]
+pub fn validate_json_content_type(headers: &HeaderMap) -> Result<(), Response> {
+    if let Some(content_type_header) = headers.get(axum::http::header::CONTENT_TYPE)
+        && let Ok(content_type_str) = content_type_header.to_str()
+        && let Ok(parsed_mime) = content_type_str.parse::<mime::Mime>()
+    {
+        let is_json = (parsed_mime.type_() == mime::APPLICATION && parsed_mime.subtype() == mime::JSON)
+            || parsed_mime.suffix() == Some(mime::JSON);
+
+        let is_form = (parsed_mime.type_() == mime::APPLICATION && parsed_mime.subtype() == "x-www-form-urlencoded")
+            || (parsed_mime.type_() == mime::MULTIPART && parsed_mime.subtype() == "form-data");
+
+        if !is_json && !is_form {
+            let problem = ProblemDetails::new(
+                "https://spikard.dev/errors/unsupported-media-type",
+                "Unsupported Media Type",
+                StatusCode::UNSUPPORTED_MEDIA_TYPE,
+            )
+            .with_detail("Unsupported media type");
+
+            let body = problem.to_json().unwrap_or_else(|_| "{}".to_string());
+            return Err((
+                StatusCode::UNSUPPORTED_MEDIA_TYPE,
+                [(axum::http::header::CONTENT_TYPE, CONTENT_TYPE_PROBLEM_JSON)],
+                body,
+            )
+                .into_response());
+        }
+    }
+    Ok(())
+}
+
+/// Validate Content-Length header matches actual body size
+#[allow(clippy::result_large_err, clippy::collapsible_if)]
+pub fn validate_content_length(headers: &HeaderMap, actual_size: usize) -> Result<(), Response> {
+    if let Some(content_length_header) = headers.get(axum::http::header::CONTENT_LENGTH) {
+        if let Ok(content_length_str) = content_length_header.to_str() {
+            if let Ok(declared_length) = content_length_str.parse::<usize>() {
+                if declared_length != actual_size {
+                    let problem = ProblemDetails::bad_request(format!(
+                        "Content-Length header ({}) does not match actual body size ({})",
+                        declared_length, actual_size
+                    ));
+
+                    let body = problem.to_json().unwrap_or_else(|_| "{}".to_string());
+                    return Err((
+                        StatusCode::BAD_REQUEST,
+                        [(axum::http::header::CONTENT_TYPE, CONTENT_TYPE_PROBLEM_JSON)],
+                        body,
+                    )
+                        .into_response());
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+/// Validate Content-Type header and related requirements
+#[allow(clippy::result_large_err)]
+pub fn validate_content_type_headers(headers: &HeaderMap, _declared_body_size: usize) -> Result<(), Response> {
+    if let Some(content_type_str) = headers
+        .get(axum::http::header::CONTENT_TYPE)
+        .and_then(|h| h.to_str().ok())
+    {
+        let parsed_mime = match content_type_str.parse::<mime::Mime>() {
+            Ok(m) => m,
+            Err(_) => {
+                let error_body = json!({
+                    "error": format!("Invalid Content-Type header: {}", content_type_str)
+                });
+                return Err((StatusCode::BAD_REQUEST, axum::Json(error_body)).into_response());
+            }
+        };
+
+        let is_json = is_json_content_type(&parsed_mime);
+        let is_multipart = parsed_mime.type_() == mime::MULTIPART && parsed_mime.subtype() == "form-data";
+
+        if is_multipart && parsed_mime.get_param(mime::BOUNDARY).is_none() {
+            let error_body = json!({
+                "error": "multipart/form-data requires 'boundary' parameter"
+            });
+            return Err((StatusCode::BAD_REQUEST, axum::Json(error_body)).into_response());
+        }
+
+        #[allow(clippy::collapsible_if)]
+        if is_json {
+            if let Some(charset) = parsed_mime.get_param(mime::CHARSET).map(|c| c.as_str()) {
+                if !charset.eq_ignore_ascii_case("utf-8") && !charset.eq_ignore_ascii_case("utf8") {
+                    let problem = ProblemDetails::new(
+                        "https://spikard.dev/errors/unsupported-charset",
+                        "Unsupported Charset",
+                        StatusCode::UNSUPPORTED_MEDIA_TYPE,
+                    )
+                    .with_detail(format!(
+                        "Unsupported charset '{}' for JSON. Only UTF-8 is supported.",
+                        charset
+                    ));
+
+                    let body = problem.to_json().unwrap_or_else(|_| "{}".to_string());
+                    return Err((
+                        StatusCode::UNSUPPORTED_MEDIA_TYPE,
+                        [(axum::http::header::CONTENT_TYPE, CONTENT_TYPE_PROBLEM_JSON)],
+                        body,
+                    )
+                        .into_response());
+                }
+            }
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use axum::http::HeaderValue;
+
+    #[test]
+    fn validate_content_length_accepts_matching_sizes() {
+        let mut headers = HeaderMap::new();
+        headers.insert(axum::http::header::CONTENT_LENGTH, HeaderValue::from_static("5"));
+
+        assert!(validate_content_length(&headers, 5).is_ok());
+    }
+
+    #[test]
+    fn validate_content_length_rejects_mismatched_sizes() {
+        let mut headers = HeaderMap::new();
+        headers.insert(axum::http::header::CONTENT_LENGTH, HeaderValue::from_static("10"));
+
+        let err = validate_content_length(&headers, 4).expect_err("expected mismatch");
+        assert_eq!(err.status(), StatusCode::BAD_REQUEST);
+        assert_eq!(
+            err.headers()
+                .get(axum::http::header::CONTENT_TYPE)
+                .and_then(|value| value.to_str().ok()),
+            Some(CONTENT_TYPE_PROBLEM_JSON)
+        );
+    }
+
+    #[test]
+    fn test_multipart_without_boundary() {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            axum::http::header::CONTENT_TYPE,
+            HeaderValue::from_static("multipart/form-data"),
+        );
+
+        let result = validate_content_type_headers(&headers, 0);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_multipart_with_boundary() {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            axum::http::header::CONTENT_TYPE,
+            HeaderValue::from_static("multipart/form-data; boundary=----WebKitFormBoundary"),
+        );
+
+        let result = validate_content_type_headers(&headers, 0);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_json_with_utf16_charset() {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            axum::http::header::CONTENT_TYPE,
+            HeaderValue::from_static("application/json; charset=utf-16"),
+        );
+
+        let result = validate_content_type_headers(&headers, 0);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_json_with_utf8_charset() {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            axum::http::header::CONTENT_TYPE,
+            HeaderValue::from_static("application/json; charset=utf-8"),
+        );
+
+        let result = validate_content_type_headers(&headers, 0);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_json_without_charset() {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            axum::http::header::CONTENT_TYPE,
+            HeaderValue::from_static("application/json"),
+        );
+
+        let result = validate_content_type_headers(&headers, 0);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_vendor_json_accepted() {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            axum::http::header::CONTENT_TYPE,
+            HeaderValue::from_static("application/vnd.api+json"),
+        );
+
+        let result = validate_content_type_headers(&headers, 0);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_problem_json_accepted() {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            axum::http::header::CONTENT_TYPE,
+            HeaderValue::from_static("application/problem+json"),
+        );
+
+        let result = validate_content_type_headers(&headers, 0);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_vendor_json_with_utf16_charset_rejected() {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            axum::http::header::CONTENT_TYPE,
+            HeaderValue::from_static("application/vnd.api+json; charset=utf-16"),
+        );
+
+        let result = validate_content_type_headers(&headers, 0);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_vendor_json_with_utf8_charset_accepted() {
+        let mut headers = HeaderMap::new();
+        headers.insert(
+            axum::http::header::CONTENT_TYPE,
+            HeaderValue::from_static("application/vnd.api+json; charset=utf-8"),
+        );
+
+        let result = validate_content_type_headers(&headers, 0);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_is_json_content_type() {
+        let mime = "application/json".parse::<mime::Mime>().unwrap();
+        assert!(is_json_content_type(&mime));
+
+        let mime = "application/vnd.api+json".parse::<mime::Mime>().unwrap();
+        assert!(is_json_content_type(&mime));
+
+        let mime = "application/problem+json".parse::<mime::Mime>().unwrap();
+        assert!(is_json_content_type(&mime));
+
+        let mime = "application/hal+json".parse::<mime::Mime>().unwrap();
+        assert!(is_json_content_type(&mime));
+
+        let mime = "text/plain".parse::<mime::Mime>().unwrap();
+        assert!(!is_json_content_type(&mime));
+
+        let mime = "application/xml".parse::<mime::Mime>().unwrap();
+        assert!(!is_json_content_type(&mime));
+
+        let mime = "application/x-www-form-urlencoded".parse::<mime::Mime>().unwrap();
+        assert!(!is_json_content_type(&mime));
+    }
+}

data/vendor/crates/spikard-http/src/openapi/mod.rs

@@ -0,0 +1,309 @@
+//! OpenAPI 3.1.0 specification generation
+//!
+//! Generates OpenAPI specs from route definitions using existing JSON Schema infrastructure.
+//! OpenAPI 3.1.0 is fully compatible with JSON Schema Draft 2020-12.
+
+pub mod parameter_extraction;
+pub mod schema_conversion;
+pub mod spec_generation;
+
+use crate::SchemaRegistry;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use utoipa::openapi::security::SecurityScheme;
+
+/// OpenAPI configuration
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct OpenApiConfig {
+    /// Enable OpenAPI generation (default: false for zero overhead)
+    pub enabled: bool,
+
+    /// API title
+    pub title: String,
+
+    /// API version
+    pub version: String,
+
+    /// API description (supports markdown)
+    #[serde(default)]
+    pub description: Option<String>,
+
+    /// Path to serve Swagger UI (default: "/docs")
+    #[serde(default = "default_swagger_path")]
+    pub swagger_ui_path: String,
+
+    /// Path to serve Redoc (default: "/redoc")
+    #[serde(default = "default_redoc_path")]
+    pub redoc_path: String,
+
+    /// Path to serve OpenAPI JSON spec (default: "/openapi.json")
+    #[serde(default = "default_openapi_json_path")]
+    pub openapi_json_path: String,
+
+    /// Contact information
+    #[serde(default)]
+    pub contact: Option<ContactInfo>,
+
+    /// License information
+    #[serde(default)]
+    pub license: Option<LicenseInfo>,
+
+    /// Server definitions
+    #[serde(default)]
+    pub servers: Vec<ServerInfo>,
+
+    /// Security schemes (auto-detected from middleware if not provided)
+    #[serde(default)]
+    pub security_schemes: HashMap<String, SecuritySchemeInfo>,
+}
+
+impl Default for OpenApiConfig {
+    fn default() -> Self {
+        Self {
+            enabled: false,
+            title: "API".to_string(),
+            version: "1.0.0".to_string(),
+            description: None,
+            swagger_ui_path: default_swagger_path(),
+            redoc_path: default_redoc_path(),
+            openapi_json_path: default_openapi_json_path(),
+            contact: None,
+            license: None,
+            servers: Vec::new(),
+            security_schemes: HashMap::new(),
+        }
+    }
+}
+
+fn default_swagger_path() -> String {
+    "/docs".to_string()
+}
+
+fn default_redoc_path() -> String {
+    "/redoc".to_string()
+}
+
+fn default_openapi_json_path() -> String {
+    "/openapi.json".to_string()
+}
+
+/// Contact information
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ContactInfo {
+    pub name: Option<String>,
+    pub email: Option<String>,
+    pub url: Option<String>,
+}
+
+/// License information
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LicenseInfo {
+    pub name: String,
+    pub url: Option<String>,
+}
+
+/// Server information
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ServerInfo {
+    pub url: String,
+    pub description: Option<String>,
+}
+
+/// Security scheme types
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "lowercase")]
+pub enum SecuritySchemeInfo {
+    #[serde(rename = "http")]
+    Http {
+        scheme: String,
+        #[serde(rename = "bearerFormat")]
+        bearer_format: Option<String>,
+    },
+    #[serde(rename = "apiKey")]
+    ApiKey {
+        #[serde(rename = "in")]
+        location: String,
+        name: String,
+    },
+}
+
+/// Convert SecuritySchemeInfo to OpenAPI SecurityScheme
+pub fn security_scheme_info_to_openapi(info: &SecuritySchemeInfo) -> SecurityScheme {
+    match info {
+        SecuritySchemeInfo::Http { scheme, bearer_format } => {
+            let mut http_scheme = SecurityScheme::Http(utoipa::openapi::security::Http::new(
+                utoipa::openapi::security::HttpAuthScheme::Bearer,
+            ));
+            if let (SecurityScheme::Http(http), "bearer") = (&mut http_scheme, scheme.as_str()) {
+                http.scheme = utoipa::openapi::security::HttpAuthScheme::Bearer;
+                if let Some(format) = bearer_format {
+                    http.bearer_format = Some(format.clone());
+                }
+            }
+            http_scheme
+        }
+        SecuritySchemeInfo::ApiKey { location, name } => {
+            use utoipa::openapi::security::ApiKey;
+
+            let api_key = match location.as_str() {
+                "header" => ApiKey::Header(utoipa::openapi::security::ApiKeyValue::new(name)),
+                "query" => ApiKey::Query(utoipa::openapi::security::ApiKeyValue::new(name)),
+                "cookie" => ApiKey::Cookie(utoipa::openapi::security::ApiKeyValue::new(name)),
+                _ => ApiKey::Header(utoipa::openapi::security::ApiKeyValue::new(name)),
+            };
+            SecurityScheme::ApiKey(api_key)
+        }
+    }
+}
+
+/// Generate OpenAPI specification from routes with auto-detection of security schemes
+pub fn generate_openapi_spec(
+    routes: &[crate::RouteMetadata],
+    config: &OpenApiConfig,
+    _schema_registry: &SchemaRegistry,
+    server_config: Option<&crate::ServerConfig>,
+) -> Result<utoipa::openapi::OpenApi, String> {
+    spec_generation::assemble_openapi_spec(routes, config, server_config)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_openapi_config_default() {
+        let config = OpenApiConfig::default();
+        assert!(!config.enabled);
+        assert_eq!(config.title, "API");
+        assert_eq!(config.version, "1.0.0");
+        assert_eq!(config.swagger_ui_path, "/docs");
+        assert_eq!(config.redoc_path, "/redoc");
+        assert_eq!(config.openapi_json_path, "/openapi.json");
+    }
+
+    #[test]
+    fn test_generate_minimal_spec() {
+        let config = OpenApiConfig {
+            enabled: true,
+            title: "Test API".to_string(),
+            version: "1.0.0".to_string(),
+            ..Default::default()
+        };
+
+        let routes = vec![];
+        let registry = SchemaRegistry::new();
+
+        let spec = generate_openapi_spec(&routes, &config, &registry, None).unwrap();
+        assert_eq!(spec.info.title, "Test API");
+        assert_eq!(spec.info.version, "1.0.0");
+    }
+
+    #[test]
+    fn test_generate_spec_with_contact() {
+        let config = OpenApiConfig {
+            enabled: true,
+            title: "Test API".to_string(),
+            version: "1.0.0".to_string(),
+            contact: Some(ContactInfo {
+                name: Some("API Team".to_string()),
+                email: Some("api@example.com".to_string()),
+                url: Some("https://example.com".to_string()),
+            }),
+            ..Default::default()
+        };
+
+        let routes = vec![];
+        let registry = SchemaRegistry::new();
+
+        let spec = generate_openapi_spec(&routes, &config, &registry, None).unwrap();
+        assert!(spec.info.contact.is_some());
+        let contact = spec.info.contact.unwrap();
+        assert_eq!(contact.name, Some("API Team".to_string()));
+        assert_eq!(contact.email, Some("api@example.com".to_string()));
+    }
+
+    #[test]
+    fn test_generate_spec_with_license() {
+        let config = OpenApiConfig {
+            enabled: true,
+            title: "Test API".to_string(),
+            version: "1.0.0".to_string(),
+            license: Some(LicenseInfo {
+                name: "MIT".to_string(),
+                url: Some("https://opensource.org/licenses/MIT".to_string()),
+            }),
+            ..Default::default()
+        };
+
+        let routes = vec![];
+        let registry = SchemaRegistry::new();
+
+        let spec = generate_openapi_spec(&routes, &config, &registry, None).unwrap();
+        assert!(spec.info.license.is_some());
+        let license = spec.info.license.unwrap();
+        assert_eq!(license.name, "MIT");
+    }
+
+    #[test]
+    fn test_generate_spec_with_servers() {
+        let config = OpenApiConfig {
+            enabled: true,
+            title: "Test API".to_string(),
+            version: "1.0.0".to_string(),
+            servers: vec![
+                ServerInfo {
+                    url: "https://api.example.com".to_string(),
+                    description: Some("Production".to_string()),
+                },
+                ServerInfo {
+                    url: "http://localhost:8080".to_string(),
+                    description: Some("Development".to_string()),
+                },
+            ],
+            ..Default::default()
+        };
+
+        let routes = vec![];
+        let registry = SchemaRegistry::new();
+
+        let spec = generate_openapi_spec(&routes, &config, &registry, None).unwrap();
+        assert!(spec.servers.is_some());
+        let servers = spec.servers.unwrap();
+        assert_eq!(servers.len(), 2);
+        assert_eq!(servers[0].url, "https://api.example.com");
+        assert_eq!(servers[1].url, "http://localhost:8080");
+    }
+
+    #[test]
+    fn test_security_scheme_http_bearer() {
+        let scheme_info = SecuritySchemeInfo::Http {
+            scheme: "bearer".to_string(),
+            bearer_format: Some("JWT".to_string()),
+        };
+
+        let scheme = security_scheme_info_to_openapi(&scheme_info);
+        match scheme {
+            SecurityScheme::Http(http) => {
+                assert!(matches!(http.scheme, utoipa::openapi::security::HttpAuthScheme::Bearer));
+                assert_eq!(http.bearer_format, Some("JWT".to_string()));
+            }
+            _ => panic!("Expected Http security scheme"),
+        }
+    }
+
+    #[test]
+    fn test_security_scheme_api_key() {
+        let scheme_info = SecuritySchemeInfo::ApiKey {
+            location: "header".to_string(),
+            name: "X-API-Key".to_string(),
+        };
+
+        let scheme = security_scheme_info_to_openapi(&scheme_info);
+        match scheme {
+            SecurityScheme::ApiKey(api_key) => {
+                assert!(matches!(api_key, utoipa::openapi::security::ApiKey::Header(_)));
+            }
+            _ => panic!("Expected ApiKey security scheme"),
+        }
+    }
+}