spikard 0.7.4 → 0.8.0

data/vendor/crates/spikard-http/src/grpc/service.rs

@@ -0,0 +1,392 @@
+//! Tonic service bridge
+//!
+//! This module bridges Tonic's service traits with our GrpcHandler trait.
+//! It handles the conversion between Tonic's types and our internal representation,
+//! enabling language-agnostic gRPC handling.
+
+use crate::grpc::handler::{GrpcHandler, GrpcHandlerResult, GrpcRequestData, GrpcResponseData};
+use bytes::Bytes;
+use std::sync::Arc;
+use tonic::{Request, Response, Status};
+
+/// Generic gRPC service that routes requests to a GrpcHandler
+///
+/// This service implements Tonic's server traits and routes all requests
+/// to the provided GrpcHandler implementation. It handles serialization
+/// at the boundary between Tonic and our handler trait.
+///
+/// # Example
+///
+/// ```ignore
+/// use spikard_http::grpc::service::GenericGrpcService;
+/// use std::sync::Arc;
+///
+/// let handler = Arc::new(MyGrpcHandler);
+/// let service = GenericGrpcService::new(handler);
+/// ```
+pub struct GenericGrpcService {
+    handler: Arc<dyn GrpcHandler>,
+}
+
+impl GenericGrpcService {
+    /// Create a new generic gRPC service with the given handler
+    pub fn new(handler: Arc<dyn GrpcHandler>) -> Self {
+        Self { handler }
+    }
+
+    /// Handle a unary RPC call
+    ///
+    /// Converts the Tonic Request into our GrpcRequestData format,
+    /// calls the handler, and converts the result back to a Tonic Response.
+    ///
+    /// # Arguments
+    ///
+    /// * `service_name` - Fully qualified service name
+    /// * `method_name` - Method name
+    /// * `request` - Tonic request containing the serialized protobuf message
+    pub async fn handle_unary(
+        &self,
+        service_name: String,
+        method_name: String,
+        request: Request<Bytes>,
+    ) -> Result<Response<Bytes>, Status> {
+        // Extract metadata and payload from Tonic request
+        let (metadata, _extensions, payload) = request.into_parts();
+
+        // Create our internal request representation
+        let grpc_request = GrpcRequestData {
+            service_name,
+            method_name,
+            payload,
+            metadata,
+        };
+
+        // Call the handler
+        let result: GrpcHandlerResult = self.handler.call(grpc_request).await;
+
+        // Convert result to Tonic response
+        match result {
+            Ok(grpc_response) => {
+                let mut response = Response::new(grpc_response.payload);
+                copy_metadata(&grpc_response.metadata, response.metadata_mut());
+                Ok(response)
+            }
+            Err(status) => Err(status),
+        }
+    }
+
+    /// Get the service name from the handler
+    pub fn service_name(&self) -> &str {
+        self.handler.service_name()
+    }
+}
+
+/// Helper function to parse gRPC path into service and method names
+///
+/// gRPC paths follow the format: `/<package>.<service>/<method>`
+///
+/// # Example
+///
+/// ```ignore
+/// use spikard_http::grpc::service::parse_grpc_path;
+///
+/// let (service, method) = parse_grpc_path("/mypackage.UserService/GetUser").unwrap();
+/// assert_eq!(service, "mypackage.UserService");
+/// assert_eq!(method, "GetUser");
+/// ```
+pub fn parse_grpc_path(path: &str) -> Result<(String, String), Status> {
+    // gRPC paths are in the format: /<package>.<service>/<method>
+    let path = path.trim_start_matches('/');
+    let parts: Vec<&str> = path.split('/').collect();
+
+    if parts.len() != 2 {
+        return Err(Status::invalid_argument(format!("Invalid gRPC path: {}", path)));
+    }
+
+    let service_name = parts[0].to_string();
+    let method_name = parts[1].to_string();
+
+    if service_name.is_empty() || method_name.is_empty() {
+        return Err(Status::invalid_argument("Service or method name is empty"));
+    }
+
+    Ok((service_name, method_name))
+}
+
+/// Check if a request is a gRPC request
+///
+/// Checks the content-type header for "application/grpc" prefix.
+///
+/// # Example
+///
+/// ```ignore
+/// use spikard_http::grpc::service::is_grpc_request;
+/// use axum::http::HeaderMap;
+///
+/// let mut headers = HeaderMap::new();
+/// headers.insert("content-type", "application/grpc".parse().unwrap());
+///
+/// assert!(is_grpc_request(&headers));
+/// ```
+pub fn is_grpc_request(headers: &axum::http::HeaderMap) -> bool {
+    headers
+        .get(axum::http::header::CONTENT_TYPE)
+        .and_then(|v| v.to_str().ok())
+        .map(|v| v.starts_with("application/grpc"))
+        .unwrap_or(false)
+}
+
+/// Copy metadata from source to destination MetadataMap
+///
+/// Efficiently copies all metadata entries (both ASCII and binary)
+/// from one MetadataMap to another without unnecessary allocations.
+///
+/// # Arguments
+///
+/// * `source` - Source metadata to copy from
+/// * `dest` - Destination metadata to copy into
+pub fn copy_metadata(source: &tonic::metadata::MetadataMap, dest: &mut tonic::metadata::MetadataMap) {
+    for key_value in source.iter() {
+        match key_value {
+            tonic::metadata::KeyAndValueRef::Ascii(key, value) => {
+                dest.insert(key, value.clone());
+            }
+            tonic::metadata::KeyAndValueRef::Binary(key, value) => {
+                dest.insert_bin(key, value.clone());
+            }
+        }
+    }
+}
+
+/// Convert GrpcResponseData to Tonic Response
+///
+/// Helper function to convert our internal response representation
+/// to a Tonic Response.
+pub fn grpc_response_to_tonic(response: GrpcResponseData) -> Response<Bytes> {
+    let mut tonic_response = Response::new(response.payload);
+    copy_metadata(&response.metadata, tonic_response.metadata_mut());
+    tonic_response
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::grpc::handler::GrpcHandler;
+    use std::future::Future;
+    use std::pin::Pin;
+    use tonic::metadata::MetadataMap;
+
+    struct TestHandler;
+
+    impl GrpcHandler for TestHandler {
+        fn call(&self, request: GrpcRequestData) -> Pin<Box<dyn Future<Output = GrpcHandlerResult> + Send>> {
+            Box::pin(async move {
+                // Echo back the request payload
+                Ok(GrpcResponseData {
+                    payload: request.payload,
+                    metadata: MetadataMap::new(),
+                })
+            })
+        }
+
+        fn service_name(&self) -> &'static str {
+            "test.TestService"
+        }
+    }
+
+    #[tokio::test]
+    async fn test_generic_grpc_service_handle_unary() {
+        let handler = Arc::new(TestHandler);
+        let service = GenericGrpcService::new(handler);
+
+        let request = Request::new(Bytes::from("test payload"));
+        let result = service.handle_unary("test.TestService".to_string(), "TestMethod".to_string(), request).await;
+
+        assert!(result.is_ok());
+        let response = result.unwrap();
+        assert_eq!(response.into_inner(), Bytes::from("test payload"));
+    }
+
+    #[tokio::test]
+    async fn test_generic_grpc_service_with_metadata() {
+        let handler = Arc::new(TestHandler);
+        let service = GenericGrpcService::new(handler);
+
+        let mut request = Request::new(Bytes::from("payload"));
+        request
+            .metadata_mut()
+            .insert("custom-header", "custom-value".parse().unwrap());
+
+        let result = service.handle_unary("test.TestService".to_string(), "TestMethod".to_string(), request).await;
+
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_parse_grpc_path_valid() {
+        let (service, method) = parse_grpc_path("/mypackage.UserService/GetUser").unwrap();
+        assert_eq!(service, "mypackage.UserService");
+        assert_eq!(method, "GetUser");
+    }
+
+    #[test]
+    fn test_parse_grpc_path_with_nested_package() {
+        let (service, method) = parse_grpc_path("/com.example.api.v1.UserService/GetUser").unwrap();
+        assert_eq!(service, "com.example.api.v1.UserService");
+        assert_eq!(method, "GetUser");
+    }
+
+    #[test]
+    fn test_parse_grpc_path_invalid_format() {
+        let result = parse_grpc_path("/invalid");
+        assert!(result.is_err());
+        let status = result.unwrap_err();
+        assert_eq!(status.code(), tonic::Code::InvalidArgument);
+    }
+
+    #[test]
+    fn test_parse_grpc_path_empty_service() {
+        let result = parse_grpc_path("//Method");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_parse_grpc_path_empty_method() {
+        let result = parse_grpc_path("/Service/");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_parse_grpc_path_no_leading_slash() {
+        let (service, method) = parse_grpc_path("package.Service/Method").unwrap();
+        assert_eq!(service, "package.Service");
+        assert_eq!(method, "Method");
+    }
+
+    #[test]
+    fn test_is_grpc_request_valid() {
+        let mut headers = axum::http::HeaderMap::new();
+        headers.insert(
+            axum::http::header::CONTENT_TYPE,
+            "application/grpc".parse().unwrap(),
+        );
+        assert!(is_grpc_request(&headers));
+    }
+
+    #[test]
+    fn test_is_grpc_request_with_subtype() {
+        let mut headers = axum::http::HeaderMap::new();
+        headers.insert(
+            axum::http::header::CONTENT_TYPE,
+            "application/grpc+proto".parse().unwrap(),
+        );
+        assert!(is_grpc_request(&headers));
+    }
+
+    #[test]
+    fn test_is_grpc_request_not_grpc() {
+        let mut headers = axum::http::HeaderMap::new();
+        headers.insert(
+            axum::http::header::CONTENT_TYPE,
+            "application/json".parse().unwrap(),
+        );
+        assert!(!is_grpc_request(&headers));
+    }
+
+    #[test]
+    fn test_is_grpc_request_no_content_type() {
+        let headers = axum::http::HeaderMap::new();
+        assert!(!is_grpc_request(&headers));
+    }
+
+    #[test]
+    fn test_grpc_response_to_tonic_basic() {
+        let response = GrpcResponseData {
+            payload: Bytes::from("response"),
+            metadata: MetadataMap::new(),
+        };
+
+        let tonic_response = grpc_response_to_tonic(response);
+        assert_eq!(tonic_response.into_inner(), Bytes::from("response"));
+    }
+
+    #[test]
+    fn test_grpc_response_to_tonic_with_metadata() {
+        let mut metadata = MetadataMap::new();
+        metadata.insert("custom-header", "value".parse().unwrap());
+
+        let response = GrpcResponseData {
+            payload: Bytes::from("data"),
+            metadata,
+        };
+
+        let tonic_response = grpc_response_to_tonic(response);
+        assert_eq!(tonic_response.get_ref(), &Bytes::from("data"));
+        assert!(tonic_response.metadata().get("custom-header").is_some());
+    }
+
+    #[test]
+    fn test_generic_grpc_service_service_name() {
+        let handler = Arc::new(TestHandler);
+        let service = GenericGrpcService::new(handler);
+        assert_eq!(service.service_name(), "test.TestService");
+    }
+
+    #[test]
+    fn test_copy_metadata() {
+        let mut source = MetadataMap::new();
+        source.insert("key1", "value1".parse().unwrap());
+        source.insert("key2", "value2".parse().unwrap());
+
+        let mut dest = MetadataMap::new();
+        copy_metadata(&source, &mut dest);
+
+        assert_eq!(dest.get("key1").unwrap(), "value1");
+        assert_eq!(dest.get("key2").unwrap(), "value2");
+    }
+
+    #[test]
+    fn test_copy_metadata_empty() {
+        let source = MetadataMap::new();
+        let mut dest = MetadataMap::new();
+        copy_metadata(&source, &mut dest);
+        assert!(dest.is_empty());
+    }
+
+    #[test]
+    fn test_copy_metadata_binary() {
+        let mut source = MetadataMap::new();
+        source.insert_bin("binary-key-bin", tonic::metadata::MetadataValue::from_bytes(b"binary"));
+
+        let mut dest = MetadataMap::new();
+        copy_metadata(&source, &mut dest);
+
+        assert!(dest.get_bin("binary-key-bin").is_some());
+    }
+
+    #[tokio::test]
+    async fn test_generic_grpc_service_error_handling() {
+        struct ErrorHandler;
+
+        impl GrpcHandler for ErrorHandler {
+            fn call(&self, _request: GrpcRequestData) -> Pin<Box<dyn Future<Output = GrpcHandlerResult> + Send>> {
+                Box::pin(async { Err(Status::not_found("Resource not found")) })
+            }
+
+            fn service_name(&self) -> &'static str {
+                "test.ErrorService"
+            }
+        }
+
+        let handler = Arc::new(ErrorHandler);
+        let service = GenericGrpcService::new(handler);
+
+        let request = Request::new(Bytes::new());
+        let result = service.handle_unary("test.ErrorService".to_string(), "ErrorMethod".to_string(), request).await;
+
+        assert!(result.is_err());
+        let status = result.unwrap_err();
+        assert_eq!(status.code(), tonic::Code::NotFound);
+        assert_eq!(status.message(), "Resource not found");
+    }
+}

data/vendor/crates/spikard-http/src/grpc/streaming.rs

@@ -0,0 +1,237 @@
+//! Streaming support utilities for gRPC
+//!
+//! This module provides utilities for handling streaming RPCs:
+//! - Client streaming (receiving stream of messages)
+//! - Server streaming (sending stream of messages)
+//! - Bidirectional streaming (both directions)
+
+use bytes::Bytes;
+use futures_util::Stream;
+use std::pin::Pin;
+use tonic::Status;
+
+/// Type alias for a stream of protobuf message bytes
+///
+/// Used for both client streaming (incoming) and server streaming (outgoing).
+/// Each item in the stream is either:
+/// - Ok(Bytes): A serialized protobuf message
+/// - Err(Status): A gRPC error
+pub type MessageStream = Pin<Box<dyn Stream<Item = Result<Bytes, Status>> + Send>>;
+
+/// Request for client streaming RPC
+///
+/// Contains metadata and a stream of incoming messages from the client.
+pub struct StreamingRequest {
+    /// Service name
+    pub service_name: String,
+    /// Method name
+    pub method_name: String,
+    /// Stream of incoming protobuf messages
+    pub message_stream: MessageStream,
+    /// Request metadata
+    pub metadata: tonic::metadata::MetadataMap,
+}
+
+/// Response for server streaming RPC
+///
+/// Contains metadata and a stream of outgoing messages to the client.
+pub struct StreamingResponse {
+    /// Stream of outgoing protobuf messages
+    pub message_stream: MessageStream,
+    /// Response metadata
+    pub metadata: tonic::metadata::MetadataMap,
+}
+
+/// Helper to create a message stream from a vector of bytes
+///
+/// Useful for testing and for handlers that want to create a stream
+/// from a fixed set of messages.
+///
+/// # Example
+///
+/// ```ignore
+/// use spikard_http::grpc::streaming::message_stream_from_vec;
+/// use bytes::Bytes;
+///
+/// let messages = vec![
+///     Bytes::from("message1"),
+///     Bytes::from("message2"),
+/// ];
+///
+/// let stream = message_stream_from_vec(messages);
+/// ```
+pub fn message_stream_from_vec(messages: Vec<Bytes>) -> MessageStream {
+    Box::pin(futures_util::stream::iter(messages.into_iter().map(Ok)))
+}
+
+/// Helper to create an empty message stream
+///
+/// Useful for testing or for handlers that need to return an empty stream.
+pub fn empty_message_stream() -> MessageStream {
+    Box::pin(futures_util::stream::empty())
+}
+
+/// Helper to create a single-message stream
+///
+/// Useful for converting unary responses to streaming responses.
+///
+/// # Example
+///
+/// ```ignore
+/// use spikard_http::grpc::streaming::single_message_stream;
+/// use bytes::Bytes;
+///
+/// let stream = single_message_stream(Bytes::from("response"));
+/// ```
+pub fn single_message_stream(message: Bytes) -> MessageStream {
+    Box::pin(futures_util::stream::once(async move { Ok(message) }))
+}
+
+/// Helper to create an error stream
+///
+/// Returns a stream that immediately yields a gRPC error.
+///
+/// # Example
+///
+/// ```ignore
+/// use spikard_http::grpc::streaming::error_stream;
+/// use tonic::Status;
+///
+/// let stream = error_stream(Status::internal("Something went wrong"));
+/// ```
+pub fn error_stream(status: Status) -> MessageStream {
+    Box::pin(futures_util::stream::once(async move { Err(status) }))
+}
+
+/// Helper to convert a Tonic ReceiverStream to our MessageStream
+///
+/// This is used in the service bridge to convert Tonic's streaming types
+/// to our internal representation.
+pub fn from_tonic_stream<S>(stream: S) -> MessageStream
+where
+    S: Stream<Item = Result<Bytes, Status>> + Send + 'static,
+{
+    Box::pin(stream)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use futures_util::StreamExt;
+
+    #[tokio::test]
+    async fn test_message_stream_from_vec() {
+        let messages = vec![Bytes::from("msg1"), Bytes::from("msg2"), Bytes::from("msg3")];
+
+        let mut stream = message_stream_from_vec(messages.clone());
+
+        let msg1 = stream.next().await.unwrap().unwrap();
+        assert_eq!(msg1, Bytes::from("msg1"));
+
+        let msg2 = stream.next().await.unwrap().unwrap();
+        assert_eq!(msg2, Bytes::from("msg2"));
+
+        let msg3 = stream.next().await.unwrap().unwrap();
+        assert_eq!(msg3, Bytes::from("msg3"));
+
+        assert!(stream.next().await.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_empty_message_stream() {
+        let mut stream = empty_message_stream();
+        assert!(stream.next().await.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_single_message_stream() {
+        let mut stream = single_message_stream(Bytes::from("single"));
+
+        let msg = stream.next().await.unwrap().unwrap();
+        assert_eq!(msg, Bytes::from("single"));
+
+        assert!(stream.next().await.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_error_stream() {
+        let mut stream = error_stream(Status::internal("test error"));
+
+        let result = stream.next().await.unwrap();
+        assert!(result.is_err());
+
+        let error = result.unwrap_err();
+        assert_eq!(error.code(), tonic::Code::Internal);
+        assert_eq!(error.message(), "test error");
+
+        assert!(stream.next().await.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_message_stream_from_vec_empty() {
+        let messages: Vec<Bytes> = vec![];
+        let mut stream = message_stream_from_vec(messages);
+        assert!(stream.next().await.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_message_stream_from_vec_large() {
+        let mut messages = vec![];
+        for i in 0..100 {
+            messages.push(Bytes::from(format!("message{}", i)));
+        }
+
+        let mut stream = message_stream_from_vec(messages);
+
+        for i in 0..100 {
+            let msg = stream.next().await.unwrap().unwrap();
+            assert_eq!(msg, Bytes::from(format!("message{}", i)));
+        }
+
+        assert!(stream.next().await.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_from_tonic_stream() {
+        let messages = vec![Ok(Bytes::from("a")), Ok(Bytes::from("b")), Err(Status::cancelled("done"))];
+
+        let tonic_stream = futures_util::stream::iter(messages);
+        let mut stream = from_tonic_stream(tonic_stream);
+
+        let msg1 = stream.next().await.unwrap().unwrap();
+        assert_eq!(msg1, Bytes::from("a"));
+
+        let msg2 = stream.next().await.unwrap().unwrap();
+        assert_eq!(msg2, Bytes::from("b"));
+
+        let result = stream.next().await.unwrap();
+        assert!(result.is_err());
+
+        assert!(stream.next().await.is_none());
+    }
+
+    #[test]
+    fn test_streaming_request_creation() {
+        let stream = empty_message_stream();
+        let request = StreamingRequest {
+            service_name: "test.Service".to_string(),
+            method_name: "StreamMethod".to_string(),
+            message_stream: stream,
+            metadata: tonic::metadata::MetadataMap::new(),
+        };
+
+        assert_eq!(request.service_name, "test.Service");
+        assert_eq!(request.method_name, "StreamMethod");
+    }
+
+    #[test]
+    fn test_streaming_response_creation() {
+        let stream = empty_message_stream();
+        let response = StreamingResponse {
+            message_stream: stream,
+            metadata: tonic::metadata::MetadataMap::new(),
+        };
+
+        assert!(response.metadata.is_empty());
+    }
+}

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

@@ -13,6 +13,7 @@ pub mod cors;
 pub mod debug;
 #[cfg(feature = "di")]
 pub mod di_handler;
+pub mod grpc;
 pub mod handler_response;
 pub mod handler_trait;
 pub mod jsonrpc;
@@ -39,6 +40,10 @@ pub use background::{
 pub use body_metadata::ResponseBodySize;
 #[cfg(feature = "di")]
 pub use di_handler::DependencyInjectingHandler;
+pub use grpc::{
+    GrpcConfig, GrpcHandler, GrpcHandlerResult, GrpcRegistry, GrpcRequestData, GrpcResponseData, MessageStream,
+    StreamingRequest, StreamingResponse,
+};
 pub use handler_response::HandlerResponse;
 pub use handler_trait::{Handler, HandlerResult, RequestData, ValidatedParams};
 pub use jsonrpc::JsonRpcConfig;
@@ -140,6 +145,8 @@ pub struct ServerConfig {
     pub openapi: Option<crate::openapi::OpenApiConfig>,
     /// JSON-RPC configuration
     pub jsonrpc: Option<crate::jsonrpc::JsonRpcConfig>,
+    /// gRPC configuration
+    pub grpc: Option<crate::grpc::GrpcConfig>,
     /// Lifecycle hooks for request/response processing
     pub lifecycle_hooks: Option<std::sync::Arc<LifecycleHooks>>,
     /// Background task executor configuration
@@ -169,6 +176,7 @@ impl Default for ServerConfig {
             shutdown_timeout: 30,
             openapi: None,
             jsonrpc: None,
+            grpc: None,
             lifecycle_hooks: None,
             background_tasks: BackgroundTaskConfig::default(),
             enable_http_trace: false,
@@ -339,6 +347,12 @@ impl ServerConfigBuilder {
         self
     }
 
+    /// Set gRPC configuration
+    pub fn grpc(mut self, grpc: Option<crate::grpc::GrpcConfig>) -> Self {
+        self.config.grpc = grpc;
+        self
+    }
+
     /// Set lifecycle hooks for request/response processing
     pub fn lifecycle_hooks(mut self, hooks: Option<std::sync::Arc<LifecycleHooks>>) -> Self {
         self.config.lifecycle_hooks = hooks;