spikard 0.3.0 → 0.3.2

data/vendor/crates/spikard-http/src/handler_trait.rs

@@ -0,0 +1,228 @@
+//! Handler trait for language-agnostic request handling
+//!
+//! This module defines the core trait that all language bindings must implement.
+//! It's completely language-agnostic - no Python, Node, or WASM knowledge.
+
+use axum::{
+    body::Body,
+    http::{Request, Response, StatusCode},
+};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::collections::HashMap;
+use std::future::Future;
+use std::pin::Pin;
+
+/// Request data extracted from HTTP request
+/// This is the language-agnostic representation passed to handlers
+///
+/// Uses Arc for HashMaps to enable cheap cloning without duplicating data.
+/// When RequestData is cloned, only the Arc pointers are cloned, not the underlying data.
+///
+/// Performance optimization: raw_body stores the unparsed request body bytes.
+/// Language bindings should use raw_body when possible to avoid double-parsing.
+/// The body field is lazily parsed only when needed for validation.
+#[derive(Debug, Clone)]
+pub struct RequestData {
+    pub path_params: std::sync::Arc<HashMap<String, String>>,
+    pub query_params: Value,
+    pub raw_query_params: std::sync::Arc<HashMap<String, Vec<String>>>,
+    pub body: Value,
+    pub raw_body: Option<bytes::Bytes>,
+    pub headers: std::sync::Arc<HashMap<String, String>>,
+    pub cookies: std::sync::Arc<HashMap<String, String>>,
+    pub method: String,
+    pub path: String,
+    /// Resolved dependencies for this request (populated by DependencyInjectingHandler)
+    #[cfg(feature = "di")]
+    pub dependencies: Option<std::sync::Arc<spikard_core::di::ResolvedDependencies>>,
+}
+
+impl Serialize for RequestData {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        use serde::ser::SerializeStruct;
+        #[cfg(feature = "di")]
+        let field_count = 10;
+        #[cfg(not(feature = "di"))]
+        let field_count = 9;
+
+        let mut state = serializer.serialize_struct("RequestData", field_count)?;
+        state.serialize_field("path_params", &*self.path_params)?;
+        state.serialize_field("query_params", &self.query_params)?;
+        state.serialize_field("raw_query_params", &*self.raw_query_params)?;
+        state.serialize_field("body", &self.body)?;
+        state.serialize_field("raw_body", &self.raw_body.as_ref().map(|b| b.as_ref()))?;
+        state.serialize_field("headers", &*self.headers)?;
+        state.serialize_field("cookies", &*self.cookies)?;
+        state.serialize_field("method", &self.method)?;
+        state.serialize_field("path", &self.path)?;
+
+        #[cfg(feature = "di")]
+        {
+            // Dependencies field is not serialized (contains Arc<dyn Any>)
+            // We just serialize a marker indicating whether dependencies exist
+            state.serialize_field("has_dependencies", &self.dependencies.is_some())?;
+        }
+
+        state.end()
+    }
+}
+
+impl<'de> Deserialize<'de> for RequestData {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        #[derive(Deserialize)]
+        #[serde(field_identifier, rename_all = "snake_case")]
+        enum Field {
+            PathParams,
+            QueryParams,
+            RawQueryParams,
+            Body,
+            RawBody,
+            Headers,
+            Cookies,
+            Method,
+            Path,
+            #[cfg(feature = "di")]
+            HasDependencies,
+        }
+
+        struct RequestDataVisitor;
+
+        impl<'de> serde::de::Visitor<'de> for RequestDataVisitor {
+            type Value = RequestData;
+
+            fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
+                formatter.write_str("struct RequestData")
+            }
+
+            fn visit_map<V>(self, mut map: V) -> Result<RequestData, V::Error>
+            where
+                V: serde::de::MapAccess<'de>,
+            {
+                let mut path_params = None;
+                let mut query_params = None;
+                let mut raw_query_params = None;
+                let mut body = None;
+                let mut raw_body = None;
+                let mut headers = None;
+                let mut cookies = None;
+                let mut method = None;
+                let mut path = None;
+
+                while let Some(key) = map.next_key()? {
+                    match key {
+                        Field::PathParams => {
+                            path_params = Some(std::sync::Arc::new(map.next_value()?));
+                        }
+                        Field::QueryParams => {
+                            query_params = Some(map.next_value()?);
+                        }
+                        Field::RawQueryParams => {
+                            raw_query_params = Some(std::sync::Arc::new(map.next_value()?));
+                        }
+                        Field::Body => {
+                            body = Some(map.next_value()?);
+                        }
+                        Field::RawBody => {
+                            let bytes_vec: Option<Vec<u8>> = map.next_value()?;
+                            raw_body = bytes_vec.map(bytes::Bytes::from);
+                        }
+                        Field::Headers => {
+                            headers = Some(std::sync::Arc::new(map.next_value()?));
+                        }
+                        Field::Cookies => {
+                            cookies = Some(std::sync::Arc::new(map.next_value()?));
+                        }
+                        Field::Method => {
+                            method = Some(map.next_value()?);
+                        }
+                        Field::Path => {
+                            path = Some(map.next_value()?);
+                        }
+                        #[cfg(feature = "di")]
+                        Field::HasDependencies => {
+                            // We skip this field as dependencies can't be deserialized
+                            let _: bool = map.next_value()?;
+                        }
+                    }
+                }
+
+                Ok(RequestData {
+                    path_params: path_params.ok_or_else(|| serde::de::Error::missing_field("path_params"))?,
+                    query_params: query_params.ok_or_else(|| serde::de::Error::missing_field("query_params"))?,
+                    raw_query_params: raw_query_params
+                        .ok_or_else(|| serde::de::Error::missing_field("raw_query_params"))?,
+                    body: body.ok_or_else(|| serde::de::Error::missing_field("body"))?,
+                    raw_body,
+                    headers: headers.ok_or_else(|| serde::de::Error::missing_field("headers"))?,
+                    cookies: cookies.ok_or_else(|| serde::de::Error::missing_field("cookies"))?,
+                    method: method.ok_or_else(|| serde::de::Error::missing_field("method"))?,
+                    path: path.ok_or_else(|| serde::de::Error::missing_field("path"))?,
+                    #[cfg(feature = "di")]
+                    dependencies: None,
+                })
+            }
+        }
+
+        #[cfg(feature = "di")]
+        const FIELDS: &[&str] = &[
+            "path_params",
+            "query_params",
+            "raw_query_params",
+            "body",
+            "raw_body",
+            "headers",
+            "cookies",
+            "method",
+            "path",
+            "has_dependencies",
+        ];
+
+        #[cfg(not(feature = "di"))]
+        const FIELDS: &[&str] = &[
+            "path_params",
+            "query_params",
+            "raw_query_params",
+            "body",
+            "raw_body",
+            "headers",
+            "cookies",
+            "method",
+            "path",
+        ];
+
+        deserializer.deserialize_struct("RequestData", FIELDS, RequestDataVisitor)
+    }
+}
+
+/// Result type for handlers
+pub type HandlerResult = Result<Response<Body>, (StatusCode, String)>;
+
+/// Handler trait that all language bindings must implement
+///
+/// This trait is completely language-agnostic. Each binding (Python, Node, WASM)
+/// implements this trait to bridge their runtime to our HTTP server.
+pub trait Handler: Send + Sync {
+    /// Handle an HTTP request
+    ///
+    /// Takes the extracted request data and returns a future that resolves to either:
+    /// - Ok(Response): A successful HTTP response
+    /// - Err((StatusCode, String)): An error with status code and message
+    fn call(
+        &self,
+        request: Request<Body>,
+        request_data: RequestData,
+    ) -> Pin<Box<dyn Future<Output = HandlerResult> + Send + '_>>;
+}
+
+/// Validated parameters from request (path, query, headers, cookies)
+#[derive(Debug, Clone)]
+pub struct ValidatedParams {
+    pub params: HashMap<String, Value>,
+}

data/vendor/crates/spikard-http/src/handler_trait_tests.rs

@@ -0,0 +1,284 @@
+//! Unit tests for the Handler trait and related functionality
+//!
+//! These tests verify the Handler trait works correctly and can be implemented
+//! by different language bindings without requiring PyO3 or other FFI dependencies.
+
+#[cfg(test)]
+mod tests {
+    use crate::handler_trait::{Handler, HandlerResult, RequestData};
+    use axum::body::Body;
+    use axum::http::{Method, Request, Response, StatusCode};
+    use serde_json::{Value, json};
+    use std::collections::HashMap;
+    use std::future::Future;
+    use std::pin::Pin;
+    use std::sync::Arc;
+
+    /// Mock handler for testing - always returns 200 OK with echoed request data
+    struct EchoHandler;
+
+    impl Handler for EchoHandler {
+        fn call(
+            &self,
+            _request: Request<Body>,
+            request_data: RequestData,
+        ) -> Pin<Box<dyn Future<Output = HandlerResult> + Send + '_>> {
+            Box::pin(async move {
+                let response_body = json!({
+                    "path_params": &*request_data.path_params,
+                    "query_params": request_data.query_params,
+                    "body": request_data.body,
+                    "headers_count": request_data.headers.len(),
+                    "cookies_count": request_data.cookies.len(),
+                    "method": request_data.method,
+                    "path": request_data.path,
+                });
+
+                let response = Response::builder()
+                    .status(StatusCode::OK)
+                    .header("Content-Type", "application/json")
+                    .body(Body::from(serde_json::to_string(&response_body).unwrap()))
+                    .unwrap();
+
+                Ok(response)
+            })
+        }
+    }
+
+    /// Mock handler for testing - always returns errors
+    struct ErrorHandler;
+
+    impl Handler for ErrorHandler {
+        fn call(
+            &self,
+            _request: Request<Body>,
+            _request_data: RequestData,
+        ) -> Pin<Box<dyn Future<Output = HandlerResult> + Send + '_>> {
+            Box::pin(async move { Err((StatusCode::INTERNAL_SERVER_ERROR, "Handler error".to_string())) })
+        }
+    }
+
+    /// Mock handler that checks for specific query parameters
+    struct QueryParamHandler {
+        required_param: String,
+    }
+
+    impl Handler for QueryParamHandler {
+        fn call(
+            &self,
+            _request: Request<Body>,
+            request_data: RequestData,
+        ) -> Pin<Box<dyn Future<Output = HandlerResult> + Send + '_>> {
+            let required = self.required_param.clone();
+            Box::pin(async move {
+                if request_data.raw_query_params.contains_key(&required) {
+                    let response = Response::builder()
+                        .status(StatusCode::OK)
+                        .body(Body::from("OK"))
+                        .unwrap();
+                    Ok(response)
+                } else {
+                    Err((
+                        StatusCode::BAD_REQUEST,
+                        format!("Missing required parameter: {}", required),
+                    ))
+                }
+            })
+        }
+    }
+
+    #[tokio::test]
+    async fn test_handler_trait_echo() {
+        let handler = Arc::new(EchoHandler);
+
+        let mut path_params = HashMap::new();
+        path_params.insert("id".to_string(), "123".to_string());
+
+        let mut headers = HashMap::new();
+        headers.insert("content-type".to_string(), "application/json".to_string());
+
+        let request_data = RequestData {
+            path_params: Arc::new(path_params),
+            query_params: json!({"page": 1}),
+            raw_query_params: Arc::new(HashMap::new()),
+            body: json!({"test": "data"}),
+            raw_body: None,
+            headers: Arc::new(headers),
+            cookies: Arc::new(HashMap::new()),
+            method: "POST".to_string(),
+            path: "/items/123".to_string(),
+            #[cfg(feature = "di")]
+            dependencies: None,
+        };
+
+        let request = Request::builder()
+            .method(Method::POST)
+            .uri("/items/123")
+            .body(Body::empty())
+            .unwrap();
+
+        let result = handler.call(request, request_data).await;
+        assert!(result.is_ok());
+
+        let response = result.unwrap();
+        assert_eq!(response.status(), StatusCode::OK);
+    }
+
+    #[tokio::test]
+    async fn test_handler_trait_error() {
+        let handler = Arc::new(ErrorHandler);
+
+        let request_data = RequestData {
+            path_params: Arc::new(HashMap::new()),
+            query_params: Value::Null,
+            raw_query_params: Arc::new(HashMap::new()),
+            body: Value::Null,
+            raw_body: None,
+            headers: Arc::new(HashMap::new()),
+            cookies: Arc::new(HashMap::new()),
+            method: "GET".to_string(),
+            path: "/error".to_string(),
+
+            #[cfg(feature = "di")]
+            dependencies: None,
+        };
+
+        let request = Request::builder()
+            .method(Method::GET)
+            .uri("/error")
+            .body(Body::empty())
+            .unwrap();
+
+        let result = handler.call(request, request_data).await;
+        assert!(result.is_err());
+
+        let (status, message) = result.unwrap_err();
+        assert_eq!(status, StatusCode::INTERNAL_SERVER_ERROR);
+        assert_eq!(message, "Handler error");
+    }
+
+    #[tokio::test]
+    async fn test_handler_trait_query_params() {
+        let handler = Arc::new(QueryParamHandler {
+            required_param: "api_key".to_string(),
+        });
+
+        let mut raw_query_params = HashMap::new();
+        raw_query_params.insert("api_key".to_string(), vec!["secret123".to_string()]);
+
+        let request_data = RequestData {
+            path_params: Arc::new(HashMap::new()),
+            query_params: json!({"api_key": "secret123"}),
+            raw_query_params: Arc::new(raw_query_params.clone()),
+            body: Value::Null,
+            raw_body: None,
+            headers: Arc::new(HashMap::new()),
+            cookies: Arc::new(HashMap::new()),
+            method: "GET".to_string(),
+            path: "/api/data".to_string(),
+            #[cfg(feature = "di")]
+            dependencies: None,
+        };
+
+        let request = Request::builder()
+            .method(Method::GET)
+            .uri("/api/data?api_key=secret123")
+            .body(Body::empty())
+            .unwrap();
+
+        let result = handler.call(request, request_data).await;
+        assert!(result.is_ok());
+
+        let request_data_no_param = RequestData {
+            path_params: Arc::new(HashMap::new()),
+            query_params: Value::Null,
+            raw_query_params: Arc::new(HashMap::new()),
+            body: Value::Null,
+            raw_body: None,
+            headers: Arc::new(HashMap::new()),
+            cookies: Arc::new(HashMap::new()),
+            method: "GET".to_string(),
+            path: "/api/data".to_string(),
+
+            #[cfg(feature = "di")]
+            dependencies: None,
+        };
+
+        let request_no_param = Request::builder()
+            .method(Method::GET)
+            .uri("/api/data")
+            .body(Body::empty())
+            .unwrap();
+
+        let result_err = handler.call(request_no_param, request_data_no_param).await;
+        assert!(result_err.is_err());
+
+        let (status, message) = result_err.unwrap_err();
+        assert_eq!(status, StatusCode::BAD_REQUEST);
+        assert!(message.contains("api_key"));
+    }
+
+    #[tokio::test]
+    async fn test_request_data_serialization() {
+        let mut path_params = HashMap::new();
+        path_params.insert("user_id".to_string(), "42".to_string());
+
+        let mut raw_query_params = HashMap::new();
+        raw_query_params.insert("filter".to_string(), vec!["active".to_string()]);
+
+        let request_data = RequestData {
+            path_params: Arc::new(path_params),
+            query_params: json!({"filter": "active"}),
+            raw_query_params: Arc::new(raw_query_params),
+            body: json!({"name": "test"}),
+            raw_body: None,
+            headers: Arc::new(HashMap::new()),
+            cookies: Arc::new(HashMap::new()),
+            method: "PUT".to_string(),
+            path: "/users/42".to_string(),
+            #[cfg(feature = "di")]
+            dependencies: None,
+        };
+
+        let json_str = serde_json::to_string(&request_data).unwrap();
+        let deserialized: RequestData = serde_json::from_str(&json_str).unwrap();
+
+        assert_eq!(deserialized.method, "PUT");
+        assert_eq!(deserialized.path, "/users/42");
+        assert_eq!(deserialized.path_params.get("user_id").unwrap(), "42");
+        assert_eq!(deserialized.body, json!({"name": "test"}));
+    }
+
+    #[test]
+    fn test_request_data_default_values() {
+        let request_data = RequestData {
+            path_params: Arc::new(HashMap::new()),
+            query_params: Value::Null,
+            raw_query_params: Arc::new(HashMap::new()),
+            body: Value::Null,
+            raw_body: None,
+            headers: Arc::new(HashMap::new()),
+            cookies: Arc::new(HashMap::new()),
+            method: "GET".to_string(),
+            path: "/".to_string(),
+
+            #[cfg(feature = "di")]
+            dependencies: None,
+        };
+
+        assert_eq!(request_data.method, "GET");
+        assert_eq!(request_data.path, "/");
+        assert!(request_data.path_params.is_empty());
+        assert!(request_data.raw_query_params.is_empty());
+        assert!(request_data.headers.is_empty());
+        assert!(request_data.cookies.is_empty());
+        assert_eq!(request_data.body, Value::Null);
+        assert_eq!(request_data.query_params, Value::Null);
+    }
+
+    #[test]
+    fn test_handler_is_send_sync() {
+        fn assert_send_sync<T: Send + Sync>() {}
+        assert_send_sync::<Arc<dyn Handler>>();
+    }
+}