spikard 0.3.0 → 0.3.2

data/vendor/crates/spikard-core/src/di/dependency.rs

@@ -0,0 +1,273 @@
+//! Core dependency trait
+//!
+//! This module defines the `Dependency` trait which all dependency implementations
+//! must implement to integrate with the DI container.
+
+use super::error::DependencyError;
+use super::resolved::ResolvedDependencies;
+use crate::request_data::RequestData;
+use http::Request;
+use std::any::Any;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+
+type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
+
+/// Trait for all dependency implementations
+///
+/// This trait defines how dependencies are resolved within the DI container.
+/// Implementations can be simple values, factories, or complex async providers.
+///
+/// # Type Erasure
+///
+/// Dependencies return `Arc<dyn Any + Send + Sync>` to support storing heterogeneous
+/// types in the same container. Use `ResolvedDependencies::get<T>()` for type-safe access.
+///
+/// # Async Resolution
+///
+/// All dependencies resolve asynchronously, allowing for I/O operations like
+/// database connections or HTTP requests during resolution.
+///
+/// # Caching Strategies
+///
+/// - **Singleton**: Resolved once globally, cached forever
+/// - **Cacheable**: Resolved once per request, cached for that request
+/// - **Factory**: Resolved every time it's requested
+///
+/// # Examples
+///
+/// ```ignore
+/// use spikard_core::di::{Dependency, DependencyError, ResolvedDependencies};
+/// use http::Request;
+/// use crate::request_data::RequestData;
+/// use std::any::Any;
+/// use std::sync::Arc;
+///
+/// struct SimpleDependency {
+///     key: String,
+///     value: Arc<i32>,
+/// }
+///
+/// impl Dependency for SimpleDependency {
+///     fn resolve(
+///         &self,
+///         _request: &Request<()>,
+///         _request_data: &RequestData,
+///         _resolved: &ResolvedDependencies,
+///     ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Arc<dyn Any + Send + Sync>, DependencyError>> + Send>> {
+///         let value = self.value.clone();
+///         Box::pin(async move {
+///             Ok(value as Arc<dyn Any + Send + Sync>)
+///         })
+///     }
+///
+///     fn key(&self) -> &str {
+///         &self.key
+///     }
+///
+///     fn depends_on(&self) -> Vec<String> {
+///         vec![]
+///     }
+/// }
+/// ```
+pub trait Dependency: Send + Sync {
+    /// Resolve this dependency to a concrete value
+    ///
+    /// This method is called by the DI container to obtain the actual dependency value.
+    /// It can perform async operations, access request data, and retrieve other
+    /// already-resolved dependencies.
+    ///
+    /// # Arguments
+    ///
+    /// * `request` - The HTTP request being handled
+    /// * `request_data` - Extracted request data (params, headers, body, etc.)
+    /// * `resolved` - Already-resolved dependencies that this dependency may need
+    ///
+    /// # Returns
+    ///
+    /// A future that resolves to either:
+    /// - `Ok(Arc<dyn Any + Send + Sync>)` - The resolved dependency value
+    /// - `Err(DependencyError)` - An error during resolution
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// use spikard_core::di::{Dependency, DependencyError, ResolvedDependencies};
+    /// use http::Request;
+    /// use crate::request_data::RequestData;
+    /// use std::any::Any;
+    /// use std::sync::Arc;
+    ///
+    /// struct ConfigDependency;
+    ///
+    /// impl Dependency for ConfigDependency {
+    ///     fn resolve(
+    ///         &self,
+    ///         _request: &Request<()>,
+    ///         request_data: &RequestData,
+    ///         _resolved: &ResolvedDependencies,
+    ///     ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Arc<dyn Any + Send + Sync>, DependencyError>> + Send>> {
+    ///         // Access request data to determine config
+    ///         let env = request_data.headers
+    ///             .get("X-Environment")
+    ///             .map(|s| s.as_str())
+    ///             .unwrap_or("production");
+    ///
+    ///         let config = format!("Config for {}", env);
+    ///         Box::pin(async move {
+    ///             Ok(Arc::new(config) as Arc<dyn Any + Send + Sync>)
+    ///         })
+    ///     }
+    ///
+    ///     fn key(&self) -> &str {
+    ///         "config"
+    ///     }
+    ///
+    ///     fn depends_on(&self) -> Vec<String> {
+    ///         vec![]
+    ///     }
+    /// }
+    /// ```
+    fn resolve(
+        &self,
+        request: &Request<()>,
+        request_data: &RequestData,
+        resolved: &ResolvedDependencies,
+    ) -> BoxFuture<'_, Result<Arc<dyn Any + Send + Sync>, DependencyError>>;
+
+    /// Get the unique key for this dependency
+    ///
+    /// This key is used to identify the dependency in the container and
+    /// when other dependencies reference it.
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// use spikard_core::di::Dependency;
+    /// # use spikard_core::di::{DependencyError, ResolvedDependencies};
+    /// # use http::Request;
+    /// # use crate::request_data::RequestData;
+    /// # use std::any::Any;
+    /// # use std::sync::Arc;
+    ///
+    /// # struct MyDependency { key: String }
+    /// # impl Dependency for MyDependency {
+    /// #     fn resolve(&self, _: &Request<()>, _: &RequestData, _: &ResolvedDependencies)
+    /// #         -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Arc<dyn Any + Send + Sync>, DependencyError>> + Send>>
+    /// #     { Box::pin(async { Ok(Arc::new(()) as Arc<dyn Any + Send + Sync>) }) }
+    /// fn key(&self) -> &str {
+    ///     &self.key
+    /// }
+    /// #     fn depends_on(&self) -> Vec<String> { vec![] }
+    /// # }
+    /// ```
+    fn key(&self) -> &str;
+
+    /// Get the list of dependency keys that this dependency requires
+    ///
+    /// These dependencies will be resolved before this one, and will be
+    /// available in the `resolved` parameter passed to `resolve()`.
+    ///
+    /// # Returns
+    ///
+    /// A vector of dependency keys that must be resolved first
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// use spikard_core::di::Dependency;
+    /// # use spikard_core::di::{DependencyError, ResolvedDependencies};
+    /// # use http::Request;
+    /// # use crate::request_data::RequestData;
+    /// # use std::any::Any;
+    /// # use std::sync::Arc;
+    ///
+    /// # struct MyDependency;
+    /// # impl Dependency for MyDependency {
+    /// #     fn resolve(&self, _: &Request<()>, _: &RequestData, _: &ResolvedDependencies)
+    /// #         -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Arc<dyn Any + Send + Sync>, DependencyError>> + Send>>
+    /// #     { Box::pin(async { Ok(Arc::new(()) as Arc<dyn Any + Send + Sync>) }) }
+    /// #     fn key(&self) -> &str { "service" }
+    /// fn depends_on(&self) -> Vec<String> {
+    ///     vec!["database".to_string(), "cache".to_string()]
+    /// }
+    /// # }
+    /// ```
+    fn depends_on(&self) -> Vec<String>;
+
+    /// Whether this dependency's value can be cached within a single request
+    ///
+    /// If `true`, the dependency will be resolved once per request and the
+    /// same value will be reused for all handlers in that request.
+    ///
+    /// If `false`, the dependency will be resolved every time it's requested.
+    ///
+    /// # Default
+    ///
+    /// Returns `false` by default (no caching).
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// use spikard_core::di::Dependency;
+    /// # use spikard_core::di::{DependencyError, ResolvedDependencies};
+    /// # use http::Request;
+    /// # use crate::request_data::RequestData;
+    /// # use std::any::Any;
+    /// # use std::sync::Arc;
+    ///
+    /// # struct MyDependency;
+    /// # impl Dependency for MyDependency {
+    /// #     fn resolve(&self, _: &Request<()>, _: &RequestData, _: &ResolvedDependencies)
+    /// #         -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Arc<dyn Any + Send + Sync>, DependencyError>> + Send>>
+    /// #     { Box::pin(async { Ok(Arc::new(()) as Arc<dyn Any + Send + Sync>) }) }
+    /// #     fn key(&self) -> &str { "request_id" }
+    /// #     fn depends_on(&self) -> Vec<String> { vec![] }
+    /// fn cacheable(&self) -> bool {
+    ///     true  // Cache within the request
+    /// }
+    /// # }
+    /// ```
+    fn cacheable(&self) -> bool {
+        false
+    }
+
+    /// Whether this dependency is a singleton (cached globally across all requests)
+    ///
+    /// If `true`, the dependency will be resolved once globally and the same
+    /// value will be reused for all requests.
+    ///
+    /// If `false`, the dependency will be resolved per-request (if cacheable)
+    /// or per-use (if not cacheable).
+    ///
+    /// # Default
+    ///
+    /// Returns `false` by default (not a singleton).
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// use spikard_core::di::Dependency;
+    /// # use spikard_core::di::{DependencyError, ResolvedDependencies};
+    /// # use http::Request;
+    /// # use crate::request_data::RequestData;
+    /// # use std::any::Any;
+    /// # use std::sync::Arc;
+    ///
+    /// # struct MyDependency;
+    /// # impl Dependency for MyDependency {
+    /// #     fn resolve(&self, _: &Request<()>, _: &RequestData, _: &ResolvedDependencies)
+    /// #         -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Arc<dyn Any + Send + Sync>, DependencyError>> + Send>>
+    /// #     { Box::pin(async { Ok(Arc::new(()) as Arc<dyn Any + Send + Sync>) }) }
+    /// #     fn key(&self) -> &str { "database_pool" }
+    /// #     fn depends_on(&self) -> Vec<String> { vec![] }
+    /// fn singleton(&self) -> bool {
+    ///     true  // Resolve once globally
+    /// }
+    /// # }
+    /// ```
+    fn singleton(&self) -> bool {
+        false
+    }
+}

data/vendor/crates/spikard-core/src/di/error.rs

@@ -0,0 +1,118 @@
+//! Dependency injection error types
+//!
+//! This module defines all error types that can occur during dependency registration
+//! and resolution in the DI container.
+
+/// Errors that can occur during dependency injection operations
+///
+/// # Examples
+///
+/// ```ignore
+/// use spikard_core::di::DependencyError;
+///
+/// let error = DependencyError::NotFound {
+///     key: "database".to_string(),
+/// };
+/// assert_eq!(error.to_string(), "Dependency not found: database");
+/// ```
+#[derive(thiserror::Error, Debug)]
+pub enum DependencyError {
+    /// A circular dependency was detected during registration or resolution
+    ///
+    /// Contains the cycle as a vector of dependency keys in the order they were encountered.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// use spikard_core::di::DependencyError;
+    ///
+    /// let error = DependencyError::CircularDependency {
+    ///     cycle: vec!["A".to_string(), "B".to_string(), "A".to_string()],
+    /// };
+    /// println!("{}", error); // "Circular dependency detected: ["A", "B", "A"]"
+    /// ```
+    #[error("Circular dependency detected: {cycle:?}")]
+    CircularDependency {
+        /// The cycle of dependencies (e.g., ["A", "B", "C", "A"])
+        cycle: Vec<String>,
+    },
+
+    /// A requested dependency was not found in the container
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// use spikard_core::di::DependencyError;
+    ///
+    /// let error = DependencyError::NotFound {
+    ///     key: "cache".to_string(),
+    /// };
+    /// assert!(error.to_string().contains("cache"));
+    /// ```
+    #[error("Dependency not found: {key}")]
+    NotFound {
+        /// The key of the missing dependency
+        key: String,
+    },
+
+    /// Type mismatch when attempting to downcast a dependency to a concrete type
+    ///
+    /// This occurs when calling `ResolvedDependencies::get<T>()` with the wrong type.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// use spikard_core::di::DependencyError;
+    ///
+    /// let error = DependencyError::TypeMismatch {
+    ///     key: "config".to_string(),
+    /// };
+    /// println!("{}", error); // "Type mismatch for dependency: config"
+    /// ```
+    #[error("Type mismatch for dependency: {key}")]
+    TypeMismatch {
+        /// The key of the dependency with the type mismatch
+        key: String,
+    },
+
+    /// A dependency failed to resolve
+    ///
+    /// This is a catch-all for any errors that occur during the resolution process,
+    /// such as factory function failures or async resolution errors.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// use spikard_core::di::DependencyError;
+    ///
+    /// let error = DependencyError::ResolutionFailed {
+    ///     message: "Database connection failed".to_string(),
+    /// };
+    /// assert!(error.to_string().contains("Database connection"));
+    /// ```
+    #[error("Resolution failed: {message}")]
+    ResolutionFailed {
+        /// Description of the resolution failure
+        message: String,
+    },
+
+    /// A duplicate dependency key was registered
+    ///
+    /// The DI container does not allow multiple dependencies with the same key.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// use spikard_core::di::DependencyError;
+    ///
+    /// let error = DependencyError::DuplicateKey {
+    ///     key: "logger".to_string(),
+    /// };
+    /// println!("{}", error); // "Duplicate dependency key: logger"
+    /// ```
+    #[error("Duplicate dependency key: {key}")]
+    DuplicateKey {
+        /// The duplicate key
+        key: String,
+    },
+}