spikard 0.3.6 → 0.6.1

data/vendor/crates/spikard-core/src/metadata.rs

@@ -0,0 +1,389 @@
+//! Route metadata extraction and validation
+//!
+//! This module handles the validation and normalization of route metadata,
+//! including schema validation and parameter extraction. It serves as the
+//! bridge between language bindings and the core HTTP server.
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::collections::HashMap;
+
+/// Metadata for a single route parameter
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct ParameterMetadata {
+    /// Parameter name
+    pub name: String,
+    /// Parameter source (path, query, header, cookie)
+    pub source: ParameterSource,
+    /// Expected JSON type
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub schema_type: Option<String>,
+    /// Whether parameter is required
+    pub required: bool,
+    /// Optional validation schema
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub schema: Option<Value>,
+}
+
+/// Parameter source type
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum ParameterSource {
+    /// Path parameter (from URL path)
+    Path,
+    /// Query parameter (from query string)
+    Query,
+    /// Header parameter
+    Header,
+    /// Cookie parameter
+    Cookie,
+}
+
+impl std::fmt::Display for ParameterSource {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Path => write!(f, "path"),
+            Self::Query => write!(f, "query"),
+            Self::Header => write!(f, "header"),
+            Self::Cookie => write!(f, "cookie"),
+        }
+    }
+}
+
+impl std::str::FromStr for ParameterSource {
+    type Err = String;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.to_lowercase().as_str() {
+            "path" => Ok(Self::Path),
+            "query" => Ok(Self::Query),
+            "header" => Ok(Self::Header),
+            "cookie" => Ok(Self::Cookie),
+            _ => Err(format!("Unknown parameter source: {}", s)),
+        }
+    }
+}
+
+/// Route-level metadata extracted from handler signatures
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ExtractedRouteMetadata {
+    /// Extracted parameters from function signature
+    pub parameters: Vec<ParameterMetadata>,
+    /// Request body schema
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub request_schema: Option<Value>,
+    /// Response schema
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub response_schema: Option<Value>,
+}
+
+/// Builder for extracting and validating route metadata
+pub struct MetadataBuilder {
+    parameters: Vec<ParameterMetadata>,
+    request_schema: Option<Value>,
+    response_schema: Option<Value>,
+}
+
+impl Default for MetadataBuilder {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl MetadataBuilder {
+    /// Create a new metadata builder
+    pub fn new() -> Self {
+        Self {
+            parameters: Vec::new(),
+            request_schema: None,
+            response_schema: None,
+        }
+    }
+
+    /// Add a parameter to the metadata
+    pub fn with_parameter(mut self, param: ParameterMetadata) -> Self {
+        self.parameters.push(param);
+        self
+    }
+
+    /// Add multiple parameters
+    pub fn with_parameters(mut self, params: Vec<ParameterMetadata>) -> Self {
+        self.parameters.extend(params);
+        self
+    }
+
+    /// Set the request schema
+    pub fn with_request_schema(mut self, schema: Option<Value>) -> Self {
+        self.request_schema = schema;
+        self
+    }
+
+    /// Set the response schema
+    pub fn with_response_schema(mut self, schema: Option<Value>) -> Self {
+        self.response_schema = schema;
+        self
+    }
+
+    /// Build the extracted metadata
+    pub fn build(self) -> ExtractedRouteMetadata {
+        ExtractedRouteMetadata {
+            parameters: self.parameters,
+            request_schema: self.request_schema,
+            response_schema: self.response_schema,
+        }
+    }
+}
+
+/// Extract path parameters from a URL pattern
+///
+/// Given a URL pattern like "/users/{user_id}/posts/{post_id}", extracts
+/// the parameter names and creates path parameter metadata.
+pub fn extract_path_parameters(path: &str) -> Vec<ParameterMetadata> {
+    let mut params = Vec::new();
+    let mut in_brace = false;
+    let mut current_param = String::new();
+
+    for ch in path.chars() {
+        match ch {
+            '{' => in_brace = true,
+            '}' => {
+                if !current_param.is_empty() {
+                    params.push(ParameterMetadata {
+                        name: current_param.clone(),
+                        source: ParameterSource::Path,
+                        schema_type: Some("string".to_string()),
+                        required: true,
+                        schema: None,
+                    });
+                    current_param.clear();
+                }
+                in_brace = false;
+            }
+            _ if in_brace => current_param.push(ch),
+            _ => {}
+        }
+    }
+
+    params
+}
+
+/// Parse parameter schema from a JSON Schema
+///
+/// Extracts parameter definitions from a JSON Schema object that follows the
+/// parameter schema format with "properties" and "required" keys.
+pub fn parse_parameter_schema(schema: &Value) -> Result<Vec<ParameterMetadata>, String> {
+    let mut params = Vec::new();
+
+    let Some(props) = schema.get("properties").and_then(|p| p.as_object()) else {
+        return Ok(params);
+    };
+
+    let required: Vec<String> = schema
+        .get("required")
+        .and_then(|r| r.as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|v| v.as_str().map(String::from))
+                .collect()
+        })
+        .unwrap_or_default();
+
+    for (param_name, param_schema) in props {
+        let is_required = required.contains(param_name);
+
+        let source = param_schema
+            .get("source")
+            .and_then(|s| s.as_str())
+            .and_then(|s| s.parse().ok())
+            .unwrap_or(ParameterSource::Query);
+
+        let schema_type = param_schema
+            .get("type")
+            .and_then(|t| t.as_str())
+            .map(String::from);
+
+        params.push(ParameterMetadata {
+            name: param_name.clone(),
+            source,
+            schema_type,
+            required: is_required,
+            schema: Some(param_schema.clone()),
+        });
+    }
+
+    Ok(params)
+}
+
+/// Validate that extracted metadata conforms to expected structure
+pub fn validate_metadata(metadata: &ExtractedRouteMetadata) -> Result<(), Vec<String>> {
+    let mut errors = Vec::new();
+
+    for param in &metadata.parameters {
+        if param.name.is_empty() {
+            errors.push("Parameter name cannot be empty".to_string());
+        }
+
+        if let Some(schema) = &param.schema {
+            if !schema.is_object() {
+                errors.push(format!("Parameter schema for '{}' must be an object", param.name));
+            }
+        }
+    }
+
+    if let Some(schema) = &metadata.request_schema {
+        if !schema.is_object() {
+            errors.push("Request schema must be an object".to_string());
+        }
+    }
+
+    if let Some(schema) = &metadata.response_schema {
+        if !schema.is_object() {
+            errors.push("Response schema must be an object".to_string());
+        }
+    }
+
+    if errors.is_empty() {
+        Ok(())
+    } else {
+        Err(errors)
+    }
+}
+
+/// Merge path parameters with parameter schema
+///
+/// Combines path parameters extracted from the URL pattern with parameters
+/// defined in the schema, giving precedence to explicit schema definitions.
+pub fn merge_parameters(
+    path_params: Vec<ParameterMetadata>,
+    schema: Option<&Value>,
+) -> Result<Vec<ParameterMetadata>, String> {
+    let mut merged: HashMap<String, ParameterMetadata> = HashMap::new();
+
+    for param in path_params {
+        merged.insert(param.name.clone(), param);
+    }
+
+    if let Some(schema_obj) = schema {
+        let schema_params = parse_parameter_schema(schema_obj)?;
+        for param in schema_params {
+            merged.insert(param.name.clone(), param);
+        }
+    }
+
+    Ok(merged.into_values().collect())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn test_extract_path_parameters() {
+        let params = extract_path_parameters("/users/{user_id}/posts/{post_id}");
+        assert_eq!(params.len(), 2);
+        assert_eq!(params[0].name, "user_id");
+        assert_eq!(params[1].name, "post_id");
+        assert!(params.iter().all(|p| p.source == ParameterSource::Path));
+    }
+
+    #[test]
+    fn test_extract_no_path_parameters() {
+        let params = extract_path_parameters("/users");
+        assert!(params.is_empty());
+    }
+
+    #[test]
+    fn test_parse_parameter_schema() {
+        let schema = json!({
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "source": "query"},
+                "age": {"type": "integer", "source": "query"}
+            },
+            "required": ["name"]
+        });
+
+        let params = parse_parameter_schema(&schema).unwrap();
+        assert_eq!(params.len(), 2);
+
+        let name_param = params.iter().find(|p| p.name == "name").unwrap();
+        assert!(name_param.required);
+
+        let age_param = params.iter().find(|p| p.name == "age").unwrap();
+        assert!(!age_param.required);
+    }
+
+    #[test]
+    fn test_merge_parameters() {
+        let path_params = vec![ParameterMetadata {
+            name: "user_id".to_string(),
+            source: ParameterSource::Path,
+            schema_type: Some("string".to_string()),
+            required: true,
+            schema: None,
+        }];
+
+        let schema = json!({
+            "type": "object",
+            "properties": {
+                "limit": {"type": "integer", "source": "query"}
+            },
+            "required": []
+        });
+
+        let merged = merge_parameters(path_params, Some(&schema)).unwrap();
+        assert_eq!(merged.len(), 2);
+        assert!(merged.iter().any(|p| p.name == "user_id"));
+        assert!(merged.iter().any(|p| p.name == "limit"));
+    }
+
+    #[test]
+    fn test_parameter_source_display() {
+        assert_eq!(ParameterSource::Path.to_string(), "path");
+        assert_eq!(ParameterSource::Query.to_string(), "query");
+        assert_eq!(ParameterSource::Header.to_string(), "header");
+        assert_eq!(ParameterSource::Cookie.to_string(), "cookie");
+    }
+
+    #[test]
+    fn test_parameter_source_from_str() {
+        assert_eq!("path".parse(), Ok(ParameterSource::Path));
+        assert_eq!("query".parse(), Ok(ParameterSource::Query));
+    }
+
+    #[test]
+    fn test_validate_metadata_success() {
+        let metadata = ExtractedRouteMetadata {
+            parameters: vec![ParameterMetadata {
+                name: "id".to_string(),
+                source: ParameterSource::Path,
+                schema_type: Some("string".to_string()),
+                required: true,
+                schema: None,
+            }],
+            request_schema: None,
+            response_schema: None,
+        };
+
+        assert!(validate_metadata(&metadata).is_ok());
+    }
+
+    #[test]
+    fn test_validate_metadata_empty_param_name() {
+        let metadata = ExtractedRouteMetadata {
+            parameters: vec![ParameterMetadata {
+                name: String::new(),
+                source: ParameterSource::Query,
+                schema_type: None,
+                required: false,
+                schema: None,
+            }],
+            request_schema: None,
+            response_schema: None,
+        };
+
+        let result = validate_metadata(&metadata);
+        assert!(result.is_err());
+    }
+}