spikard 0.13.0 → 0.15.2

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

@@ -1,566 +0,0 @@
-#![allow(clippy::pedantic, clippy::nursery)]
-#![cfg_attr(test, allow(clippy::all))]
-//! Spikard HTTP Server
-//!
-//! Pure Rust HTTP server with language-agnostic handler trait.
-//! Language bindings (Python, Node, WASM) implement the Handler trait.
-
-pub mod auth;
-pub mod background;
-pub mod bindings;
-pub mod body_metadata;
-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;
-pub mod lifecycle;
-pub mod middleware;
-pub mod openapi;
-pub mod query_parser;
-pub mod response;
-pub mod server;
-pub mod sse;
-pub mod testing;
-pub mod websocket;
-
-use serde::{Deserialize, Serialize};
-use tokio::runtime::Runtime;
-
-#[cfg(test)]
-mod handler_trait_tests;
-
-pub use auth::{Claims, api_key_auth_middleware, jwt_auth_middleware};
-pub use background::{
-    BackgroundHandle, BackgroundJobError, BackgroundJobMetadata, BackgroundRuntime, BackgroundSpawnError,
-    BackgroundTaskConfig,
-};
-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, StaticResponse, StaticResponseHandler, ValidatedParams};
-pub use jsonrpc::JsonRpcConfig;
-pub use lifecycle::{HookResult, LifecycleHook, LifecycleHooks, LifecycleHooksBuilder, request_hook, response_hook};
-pub use openapi::{ContactInfo, LicenseInfo, OpenApiConfig, SecuritySchemeInfo, ServerInfo};
-pub use response::Response;
-pub use server::Server;
-pub use spikard_core::{
-    CompressionConfig, CorsConfig, Method, ParameterValidator, ProblemDetails, RateLimitConfig, Route, RouteHandler,
-    RouteMetadata, Router, SchemaRegistry, SchemaValidator,
-};
-pub use sse::{SseEvent, SseEventProducer, SseState, sse_handler};
-pub use testing::{ResponseSnapshot, SnapshotError, snapshot_response};
-pub use websocket::{WebSocketHandler, WebSocketState, websocket_handler};
-
-/// Reexport from spikard_core for convenience
-pub use spikard_core::problem::CONTENT_TYPE_PROBLEM_JSON;
-
-/// JWT authentication configuration
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct JwtConfig {
-    /// Secret key for JWT verification
-    pub secret: String,
-    /// Required algorithm (HS256, HS384, HS512, RS256, etc.)
-    #[serde(default = "default_jwt_algorithm")]
-    pub algorithm: String,
-    /// Required audience claim
-    pub audience: Option<Vec<String>>,
-    /// Required issuer claim
-    pub issuer: Option<String>,
-    /// Leeway for expiration checks (seconds)
-    #[serde(default)]
-    pub leeway: u64,
-}
-
-fn default_jwt_algorithm() -> String {
-    "HS256".to_string()
-}
-
-/// API Key authentication configuration
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct ApiKeyConfig {
-    /// Valid API keys
-    pub keys: Vec<String>,
-    /// Header name to check (e.g., "X-API-Key")
-    #[serde(default = "default_api_key_header")]
-    pub header_name: String,
-}
-
-fn default_api_key_header() -> String {
-    "X-API-Key".to_string()
-}
-
-/// Static file serving configuration
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct StaticFilesConfig {
-    /// Directory path to serve
-    pub directory: String,
-    /// URL path prefix (e.g., "/static")
-    pub route_prefix: String,
-    /// Fallback to index.html for directories
-    #[serde(default = "default_true")]
-    pub index_file: bool,
-    /// Cache-Control header value
-    pub cache_control: Option<String>,
-}
-
-/// Server configuration
-#[derive(Debug, Clone)]
-pub struct ServerConfig {
-    /// Host to bind to
-    pub host: String,
-    /// Port to bind to
-    pub port: u16,
-    /// Number of Tokio runtime worker threads used by binding-managed server runtimes
-    pub workers: usize,
-
-    /// Enable request ID generation and propagation
-    pub enable_request_id: bool,
-    /// Maximum request body size in bytes (None = unlimited, not recommended)
-    pub max_body_size: Option<usize>,
-    /// Request timeout in seconds (None = no timeout)
-    pub request_timeout: Option<u64>,
-    /// Enable compression middleware
-    pub compression: Option<CompressionConfig>,
-    /// Enable rate limiting
-    pub rate_limit: Option<RateLimitConfig>,
-    /// JWT authentication configuration
-    pub jwt_auth: Option<JwtConfig>,
-    /// API Key authentication configuration
-    pub api_key_auth: Option<ApiKeyConfig>,
-    /// Static file serving configuration
-    pub static_files: Vec<StaticFilesConfig>,
-    /// Enable graceful shutdown on SIGTERM/SIGINT
-    pub graceful_shutdown: bool,
-    /// Graceful shutdown timeout (seconds)
-    pub shutdown_timeout: u64,
-    /// OpenAPI documentation configuration
-    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
-    pub background_tasks: BackgroundTaskConfig,
-    /// Enable per-request HTTP tracing (tower-http `TraceLayer`)
-    pub enable_http_trace: bool,
-    /// Dependency injection container (requires 'di' feature)
-    #[cfg(feature = "di")]
-    pub di_container: Option<std::sync::Arc<spikard_core::di::DependencyContainer>>,
-}
-
-impl Default for ServerConfig {
-    fn default() -> Self {
-        Self {
-            host: "127.0.0.1".to_string(),
-            port: 8000,
-            workers: 1,
-            enable_request_id: false,
-            max_body_size: Some(10 * 1024 * 1024),
-            request_timeout: None,
-            compression: None,
-            rate_limit: None,
-            jwt_auth: None,
-            api_key_auth: None,
-            static_files: Vec::new(),
-            graceful_shutdown: true,
-            shutdown_timeout: 30,
-            openapi: None,
-            jsonrpc: None,
-            grpc: None,
-            lifecycle_hooks: None,
-            background_tasks: BackgroundTaskConfig::default(),
-            enable_http_trace: false,
-            #[cfg(feature = "di")]
-            di_container: None,
-        }
-    }
-}
-
-impl ServerConfig {
-    /// Create a new builder for ServerConfig
-    ///
-    /// # Example
-    ///
-    /// ```ignorerust
-    /// use spikard_http::ServerConfig;
-    ///
-    /// let config = ServerConfig::builder()
-    ///     .port(3000)
-    ///     .host("0.0.0.0")
-    ///     .build();
-    /// ```
-    pub fn builder() -> ServerConfigBuilder {
-        ServerConfigBuilder::default()
-    }
-}
-
-/// Builder for ServerConfig
-///
-/// Provides a fluent API for configuring a Spikard server with dependency injection support.
-///
-/// # Dependency Injection
-///
-/// The builder provides methods to register dependencies that will be injected into handlers:
-///
-/// ```ignorerust
-/// # #[cfg(feature = "di")]
-/// # {
-/// use spikard_http::ServerConfig;
-/// use std::sync::Arc;
-///
-/// let config = ServerConfig::builder()
-///     .port(3000)
-///     .provide_value("app_name", "MyApp".to_string())
-///     .provide_value("max_connections", 100)
-///     .build();
-/// # }
-/// ```
-///
-/// For factory dependencies that create values on-demand:
-///
-/// ```ignorerust
-/// # #[cfg(feature = "di")]
-/// # {
-/// use spikard_http::ServerConfig;
-///
-/// let config = ServerConfig::builder()
-///     .port(3000)
-///     .provide_value("db_url", "postgresql://localhost/mydb".to_string())
-///     .build();
-/// # }
-/// ```
-#[derive(Debug, Clone, Default)]
-pub struct ServerConfigBuilder {
-    config: ServerConfig,
-}
-
-impl ServerConfigBuilder {
-    /// Set the host address to bind to
-    pub fn host(mut self, host: impl Into<String>) -> Self {
-        self.config.host = host.into();
-        self
-    }
-
-    /// Set the port to bind to
-    pub fn port(mut self, port: u16) -> Self {
-        self.config.port = port;
-        self
-    }
-
-    /// Set the number of Tokio runtime worker threads
-    pub fn workers(mut self, workers: usize) -> Self {
-        self.config.workers = workers;
-        self
-    }
-
-    /// Enable or disable request ID generation and propagation
-    pub fn enable_request_id(mut self, enable: bool) -> Self {
-        self.config.enable_request_id = enable;
-        self
-    }
-
-    /// Enable or disable per-request HTTP tracing (tower-http `TraceLayer`)
-    pub fn enable_http_trace(mut self, enable: bool) -> Self {
-        self.config.enable_http_trace = enable;
-        self
-    }
-
-    /// Set maximum request body size in bytes (None = unlimited, not recommended)
-    pub fn max_body_size(mut self, size: Option<usize>) -> Self {
-        self.config.max_body_size = size;
-        self
-    }
-
-    /// Set request timeout in seconds (None = no timeout)
-    pub fn request_timeout(mut self, timeout: Option<u64>) -> Self {
-        self.config.request_timeout = timeout;
-        self
-    }
-
-    /// Set compression configuration
-    pub fn compression(mut self, compression: Option<CompressionConfig>) -> Self {
-        self.config.compression = compression;
-        self
-    }
-
-    /// Set rate limiting configuration
-    pub fn rate_limit(mut self, rate_limit: Option<RateLimitConfig>) -> Self {
-        self.config.rate_limit = rate_limit;
-        self
-    }
-
-    /// Set JWT authentication configuration
-    pub fn jwt_auth(mut self, jwt_auth: Option<JwtConfig>) -> Self {
-        self.config.jwt_auth = jwt_auth;
-        self
-    }
-
-    /// Set API key authentication configuration
-    pub fn api_key_auth(mut self, api_key_auth: Option<ApiKeyConfig>) -> Self {
-        self.config.api_key_auth = api_key_auth;
-        self
-    }
-
-    /// Add static file serving configuration
-    pub fn static_files(mut self, static_files: Vec<StaticFilesConfig>) -> Self {
-        self.config.static_files = static_files;
-        self
-    }
-
-    /// Add a single static file serving configuration
-    pub fn add_static_files(mut self, static_file: StaticFilesConfig) -> Self {
-        self.config.static_files.push(static_file);
-        self
-    }
-
-    /// Enable or disable graceful shutdown on SIGTERM/SIGINT
-    pub fn graceful_shutdown(mut self, enable: bool) -> Self {
-        self.config.graceful_shutdown = enable;
-        self
-    }
-
-    /// Set graceful shutdown timeout in seconds
-    pub fn shutdown_timeout(mut self, timeout: u64) -> Self {
-        self.config.shutdown_timeout = timeout;
-        self
-    }
-
-    /// Set OpenAPI documentation configuration
-    pub fn openapi(mut self, openapi: Option<crate::openapi::OpenApiConfig>) -> Self {
-        self.config.openapi = openapi;
-        self
-    }
-
-    /// Set JSON-RPC configuration
-    pub fn jsonrpc(mut self, jsonrpc: Option<crate::jsonrpc::JsonRpcConfig>) -> Self {
-        self.config.jsonrpc = jsonrpc;
-        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;
-        self
-    }
-
-    /// Set background task executor configuration
-    pub fn background_tasks(mut self, config: BackgroundTaskConfig) -> Self {
-        self.config.background_tasks = config;
-        self
-    }
-
-    /// Register a value dependency (like Fastify decorate)
-    ///
-    /// Value dependencies are static values that are cloned when injected into handlers.
-    /// Use this for configuration objects, constants, or small shared state.
-    ///
-    /// # Example
-    ///
-    /// ```ignorerust
-    /// # #[cfg(feature = "di")]
-    /// # {
-    /// use spikard_http::ServerConfig;
-    ///
-    /// let config = ServerConfig::builder()
-    ///     .provide_value("app_name", "MyApp".to_string())
-    ///     .provide_value("version", "1.0.0".to_string())
-    ///     .provide_value("max_connections", 100)
-    ///     .build();
-    /// # }
-    /// ```
-    #[cfg(feature = "di")]
-    pub fn provide_value<T: Clone + Send + Sync + 'static>(mut self, key: impl Into<String>, value: T) -> Self {
-        use spikard_core::di::{DependencyContainer, ValueDependency};
-        use std::sync::Arc;
-
-        let key_str = key.into();
-
-        let container = if let Some(container) = self.config.di_container.take() {
-            Arc::try_unwrap(container).unwrap_or_else(|_arc| DependencyContainer::new())
-        } else {
-            DependencyContainer::new()
-        };
-
-        let mut container = container;
-
-        let dep = ValueDependency::new(key_str.clone(), value);
-
-        container
-            .register(key_str, Arc::new(dep))
-            .expect("Failed to register dependency");
-
-        self.config.di_container = Some(Arc::new(container));
-        self
-    }
-
-    /// Register a factory dependency (like Litestar Provide)
-    ///
-    /// Factory dependencies create values on-demand, optionally depending on other
-    /// registered dependencies. Factories are async and have access to resolved dependencies.
-    ///
-    /// # Type Parameters
-    ///
-    /// * `F` - Factory function type
-    /// * `Fut` - Future returned by the factory
-    /// * `T` - Type of value produced by the factory
-    ///
-    /// # Arguments
-    ///
-    /// * `key` - Unique identifier for this dependency
-    /// * `factory` - Async function that creates the dependency value
-    ///
-    /// # Example
-    ///
-    /// ```ignorerust
-    /// # #[cfg(feature = "di")]
-    /// # {
-    /// use spikard_http::ServerConfig;
-    /// use std::sync::Arc;
-    ///
-    /// let config = ServerConfig::builder()
-    ///     .provide_value("db_url", "postgresql://localhost/mydb".to_string())
-    ///     .provide_factory("db_pool", |resolved| async move {
-    ///         let url: Arc<String> = resolved.get("db_url").ok_or("Missing db_url")?;
-    ///         // Create database pool...
-    ///         Ok(format!("Pool: {}", url))
-    ///     })
-    ///     .build();
-    /// # }
-    /// ```
-    #[cfg(feature = "di")]
-    pub fn provide_factory<F, Fut, T>(mut self, key: impl Into<String>, factory: F) -> Self
-    where
-        F: Fn(&spikard_core::di::ResolvedDependencies) -> Fut + Send + Sync + Clone + 'static,
-        Fut: std::future::Future<Output = Result<T, String>> + Send + 'static,
-        T: Send + Sync + 'static,
-    {
-        use futures::future::BoxFuture;
-        use spikard_core::di::{DependencyContainer, DependencyError, FactoryDependency};
-        use std::sync::Arc;
-
-        let key_str = key.into();
-
-        let container = if let Some(container) = self.config.di_container.take() {
-            Arc::try_unwrap(container).unwrap_or_else(|_| DependencyContainer::new())
-        } else {
-            DependencyContainer::new()
-        };
-
-        let mut container = container;
-
-        let factory_clone = factory.clone();
-
-        let dep = FactoryDependency::builder(key_str.clone())
-            .factory(
-                move |_req: &axum::http::Request<()>,
-                      _data: &spikard_core::RequestData,
-                      resolved: &spikard_core::di::ResolvedDependencies| {
-                    let factory = factory_clone.clone();
-                    let factory_result = factory(resolved);
-                    Box::pin(async move {
-                        let result = factory_result
-                            .await
-                            .map_err(|e| DependencyError::ResolutionFailed { message: e })?;
-                        Ok(Arc::new(result) as Arc<dyn std::any::Any + Send + Sync>)
-                    })
-                        as BoxFuture<'static, Result<Arc<dyn std::any::Any + Send + Sync>, DependencyError>>
-                },
-            )
-            .build()
-            .expect("Factory dependency must have a configured factory function");
-
-        container
-            .register(key_str, Arc::new(dep))
-            .expect("Failed to register dependency");
-
-        self.config.di_container = Some(Arc::new(container));
-        self
-    }
-
-    /// Register a dependency with full control (advanced API)
-    ///
-    /// This method allows you to register custom dependency implementations
-    /// that implement the `Dependency` trait. Use this for advanced use cases
-    /// where you need fine-grained control over dependency resolution.
-    ///
-    /// # Example
-    ///
-    /// ```ignorerust
-    /// # #[cfg(feature = "di")]
-    /// # {
-    /// use spikard_http::ServerConfig;
-    /// use spikard_core::di::ValueDependency;
-    /// use std::sync::Arc;
-    ///
-    /// let dep = ValueDependency::new("custom", "value".to_string());
-    ///
-    /// let config = ServerConfig::builder()
-    ///     .provide(Arc::new(dep))
-    ///     .build();
-    /// # }
-    /// ```
-    #[cfg(feature = "di")]
-    pub fn provide(mut self, dependency: std::sync::Arc<dyn spikard_core::di::Dependency>) -> Self {
-        use spikard_core::di::DependencyContainer;
-        use std::sync::Arc;
-
-        let key = dependency.key().to_string();
-
-        let container = if let Some(container) = self.config.di_container.take() {
-            Arc::try_unwrap(container).unwrap_or_else(|_| DependencyContainer::new())
-        } else {
-            DependencyContainer::new()
-        };
-
-        let mut container = container;
-
-        container
-            .register(key, dependency)
-            .expect("Failed to register dependency");
-
-        self.config.di_container = Some(Arc::new(container));
-        self
-    }
-
-    /// Build the ServerConfig
-    pub fn build(self) -> ServerConfig {
-        self.config
-    }
-}
-
-/// Build a Tokio runtime for serving HTTP requests with the configured worker count.
-///
-/// `workers == 1` uses a current-thread runtime to minimize scheduling overhead.
-/// `workers > 1` uses a multi-thread runtime with an explicit worker thread count.
-pub fn build_server_runtime(config: &ServerConfig) -> std::io::Result<Runtime> {
-    let mut builder = if config.workers <= 1 {
-        tokio::runtime::Builder::new_current_thread()
-    } else {
-        let mut builder = tokio::runtime::Builder::new_multi_thread();
-        builder.worker_threads(config.workers);
-        builder
-    };
-
-    builder.enable_all().build()
-}
-
-const fn default_true() -> bool {
-    true
-}