reinhardt_di/

lib.rs

//! # Reinhardt Dependency Injection
//!
//! FastAPI-inspired dependency injection system for Reinhardt.
//!
//! ## Features
//!
//! - **Type-safe**: Full compile-time type checking
//! - **Async-first**: Built for async/await
//! - **Scoped**: Request-scoped and singleton dependencies
//! - **Composable**: Dependencies can depend on other dependencies
//! - **Cache**: Automatic caching within request scope
//! - **Circular Dependency Detection**: Automatic runtime detection with optimized performance
//!
//! ## Cargo features
//!
//! - `testing` — exposes [`DependencyRegistry::register_override`] and
//!   [`testing::OverrideGuard`] for use by `reinhardt-testkit` and other
//!   test harnesses. When operating on a per-context registry (via
//!   `InjectionContextBuilder::with_registry`), `#[serial(di_registry)]`
//!   is not required. Direct mutations of the global registry still
//!   require `#[serial(di_registry)]`.
//!
//! ## Development Tools (dev-tools feature)
//!
//! When the `dev-tools` feature is enabled, additional debugging and profiling tools are available:
//!
//! - **Visualization**: Generate dependency graphs in DOT format for Graphviz
//! - **Profiling**: Track dependency resolution performance and identify bottlenecks
//! - **Advanced Caching**: LRU and TTL-based caching strategies
//!
//! ## Generator Support (generator feature) ✅
//!
//! Generator-based dependency resolution for lazy, streaming dependency injection.
//!
//! **Note**: Uses `genawaiter` crate as a workaround for unstable native async yield.
//! Will be migrated to native syntax when Rust stabilizes async generators.
//!
//! ```rust,no_run
//! # #[cfg(feature = "generator")]
//! # use reinhardt_di::generator::DependencyGenerator;
//! # #[cfg(feature = "generator")]
//! # async fn example() {
//! // let gen = DependencyGenerator::new(|co| async move {
//! //     let db = resolve_database().await;
//! //     co.yield_(db).await;
//! //
//! //     let cache = resolve_cache().await;
//! //     co.yield_(cache).await;
//! // });
//! # }
//! ```
//!
//! ## Example
//!
//! ```rust,no_run
//! # use reinhardt_di::{Depends, Injectable};
//! # #[tokio::main]
//! # async fn main() {
//! // Define a dependency
//! // struct Database {
//! //     pool: DbPool,
//! // }
//! //
//! // #[async_trait]
//! // impl Injectable for Database {
//! //     async fn inject(ctx: &InjectionContext) -> Result<Self> {
//! //         Ok(Database {
//! //             pool: get_pool().await?,
//! //         })
//! //     }
//! // }
//! //
//! // Use in endpoint
//! // #[endpoint(GET "/users")]
//! // async fn list_users(
//! //     db: Depends<Database>,
//! // ) -> Result<Vec<User>> {
//! //     db.query("SELECT * FROM users").await
//! // }
//! # }
//! ```
//!
//! ## InjectionContext Construction
//!
//! InjectionContext is constructed using the builder pattern with a required singleton scope:
//!
//! ```rust
//! use reinhardt_di::{InjectionContext, SingletonScope};
//! use std::sync::Arc;
//!
//! // Create singleton scope
//! let singleton = Arc::new(SingletonScope::new());
//!
//! // Build injection context with singleton scope
//! let ctx = InjectionContext::builder(singleton).build();
//! ```
//!
//! Optional request and param context can be added:
//!
//! ```no_run
//! use reinhardt_di::{InjectionContext, SingletonScope};
//! use reinhardt_http::Request;
//! use std::sync::Arc;
//!
//! let singleton = Arc::new(SingletonScope::new());
//!
//! // Create a dummy request for demonstration
//! let request = Request::builder()
//!     .method(hyper::Method::GET)
//!     .uri("/")
//!     .version(hyper::Version::HTTP_11)
//!     .headers(hyper::HeaderMap::new())
//!     .body(bytes::Bytes::new())
//!     .build()
//!     .unwrap();
//!
//! let ctx = InjectionContext::builder(singleton)
//!     .with_request(request)
//!     .build();
//! ```
//!
//! ## Resolve Context
//!
//! The [`get_di_context`] function provides access to the active
//! [`InjectionContext`] within `#[injectable_factory]` and `#[injectable]`
//! function bodies, without requiring `#[inject]`.
//!
//! This enables factories to access the DI context for purposes like
//! passing it to downstream consumers:
//!
//! ```rust,ignore
//! use reinhardt_di::{ContextLevel, Depends, get_di_context};
//!
//! #[injectable_factory(scope = "transient")]
//! async fn make_router(
//!     #[inject] config: Depends<AppConfig>,
//! ) -> Router {
//!     let di_ctx = get_di_context(ContextLevel::Current);
//!     Router::new().with_di_context(di_ctx)
//! }
//! ```
//!
//! [`ContextLevel::Root`] returns the application-level context, while
//! [`ContextLevel::Current`] returns the currently active context
//! (which may be a request-scoped fork).
//!
//! Use [`try_get_di_context`] for a non-panicking variant that returns
//! `None` when called outside of a DI resolution context.
//!
//! ## Circular Dependency Detection
//!
//! The DI system automatically detects circular dependencies at runtime using an optimized
//! thread-local mechanism:
//!
//! ```ignore
//! # use reinhardt_di::{Injectable, InjectionContext, SingletonScope, DiResult};
//! # use async_trait::async_trait;
//! # use std::sync::Arc;
//! #[derive(Clone)]
//! struct ServiceA {
//!     b: Arc<ServiceB>,
//! }
//!
//! #[derive(Clone)]
//! struct ServiceB {
//!     a: Arc<ServiceA>,  // Circular dependency!
//! }
//!
//! #[async_trait]
//! impl Injectable for ServiceA {
//!     async fn inject(ctx: &InjectionContext) -> DiResult<Self> {
//!         let b = ctx.resolve::<ServiceB>().await?;
//!         Ok(ServiceA { b })
//!     }
//! }
//!
//! #[async_trait]
//! impl Injectable for ServiceB {
//!     async fn inject(ctx: &InjectionContext) -> DiResult<Self> {
//!         let a = ctx.resolve::<ServiceA>().await?;
//!         Ok(ServiceB { a })
//!     }
//! }
//!
//! let singleton = Arc::new(SingletonScope::new());
//! let ctx = InjectionContext::builder(singleton).build();
//!
//! // This will return Err with DiError::CircularDependency
//! let result = ctx.resolve::<ServiceA>().await;
//! assert!(result.is_err());
//! ```
//!
//! ### Performance Characteristics
//!
//! - **Cache Hit**: < 5% overhead (cycle detection completely skipped)
//! - **Cache Miss**: 10-20% overhead (O(1) detection using HashSet)
//! - **Deep Chains**: Sampling reduces linear cost (checks every 10th at depth 50+)
//! - **Thread Safety**: Thread-local storage eliminates lock contention
//!
//! ## Development Tools Example
//!
//! ```no_run
//! # #[cfg(feature = "dev-tools")]
//! # use reinhardt_di::{visualization::DependencyGraph, profiling::DependencyProfiler};
//! # #[cfg(feature = "dev-tools")]
//! # fn main() {
//! // fn visualize_dependencies() {
//! //     let mut graph = DependencyGraph::new();
//! //     graph.add_node("Database", "singleton");
//! //     graph.add_node("UserService", "request");
//! //     graph.add_dependency("UserService", "Database");
//! //
//! //     println!("{}", graph.to_dot());
//! // }
//! //
//! // fn profile_resolution() {
//! //     let mut profiler = DependencyProfiler::new();
//! //     profiler.start_resolve("Database");
//! //     // ... perform resolution ...
//! //     profiler.end_resolve("Database");
//! //
//! //     let report = profiler.generate_report();
//! //     println!("{}", report.to_string());
//! // }
//! # }
//! ```
//!
//! ## Auth Extractor DI Context Requirements
//!
//! The `reinhardt-auth` crate provides injectable auth extractors that depend on
//! specific DI context configuration. Understanding these requirements is essential
//! for proper authentication integration.
//!
//! ### `CurrentUser<U>` (recommended)
//!
//! Loads the full user model from the database. Requires:
//!
//! - **`DatabaseConnection`** registered as a singleton in `InjectionContext`
//! - **`AuthState`** present in request extensions (set by authentication middleware)
//! - Feature `params` enabled on `reinhardt-auth`
//!
//! Returns an injection error if any requirement is missing (fail-fast behavior).
//!
//! ```ignore
//! use reinhardt_auth::CurrentUser;
//! use reinhardt_auth::DefaultUser;
//!
//! #[get("/profile/")]
//! pub async fn profile(
//!     #[inject] CurrentUser(user): CurrentUser<DefaultUser>,
//! ) -> ViewResult<Response> {
//!     let username = user.get_username();
//!     // ...
//! }
//! ```
//!
//! ### `AuthInfo` (lightweight alternative)
//!
//! Extracts authentication metadata without a database query. Requires:
//!
//! - **`AuthState`** present in request extensions (set by authentication middleware)
//! - No `DatabaseConnection` needed
//!
//! ### `AuthUser<U>` (deprecated)
//!
//! Deprecated in favor of `CurrentUser<U>` and scheduled for removal in 0.3.
//! It retains the same fail-fast behavior as `CurrentUser<U>` for 0.2
//! compatibility.
//!
//! ### Startup Validation
//!
//! Call `reinhardt_auth::validate_auth_extractors()` during application startup
//! to verify that required dependencies (e.g., `DatabaseConnection`) are registered
//! before the first request arrives.

#![warn(missing_docs)]

#[cfg(feature = "params")]
pub mod params;

pub mod context;
pub mod cycle_detection;
pub mod depends;
pub mod function_handle;
pub mod graph;
pub mod injectable;
pub mod injected;
pub mod override_registry;
pub mod provider;
pub mod registration;
pub mod registry;
pub mod resolve_context;
pub mod scope;
#[cfg(feature = "testing")]
pub mod testing;
pub mod validation;

use thiserror::Error;

pub use context::{InjectionContext, InjectionContextBuilder, RequestContext};
pub use cycle_detection::{
	CycleError, ResolutionGuard, begin_resolution, begin_scoped_resolution,
	current_dependent_scope, register_type_name, with_cycle_detection_scope,
};
pub use function_handle::FunctionHandle;
pub use override_registry::OverrideRegistry;

#[cfg(feature = "params")]
pub use context::{ParamContext, Request};
pub use depends::{Depends, DependsBuilder, DependsOption, DependsResult};
pub use injectable::Injectable;
pub use injected::{DependencyScope as InjectedScope, InjectionMetadata};
pub use provider::{Provider, ProviderFn};
pub use registration::DiRegistrationList;
pub use registry::{
	DependencyRegistration, DependencyRegistry, DependencyScope, FactoryTrait, InjectableFactory,
	InjectableRegistration, global_registry,
};
pub use resolve_context::{ContextLevel, get_di_context, try_get_di_context};
pub use scope::{RequestScope, Scope, SingletonScope};
#[cfg(feature = "testing")]
pub use testing::OverrideGuard;
pub use validation::{RegistryValidator, ValidationError, ValidationErrorKind};

// Re-export inventory and async_trait for macro use
pub use async_trait;
pub use inventory;

// Re-export macros
#[cfg(feature = "macros")]
pub use reinhardt_di_macros::{injectable, injectable_factory};

/// Errors that can occur during dependency injection resolution.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum DiError {
	/// The requested dependency was not found in the container.
	#[error("Dependency not found: {0}")]
	NotFound(String),

	/// A circular dependency chain was detected during resolution.
	#[error("Circular dependency detected: {0}")]
	CircularDependency(String),

	/// An error occurred in a dependency provider function.
	#[error("Provider error: {0}")]
	ProviderError(String),

	/// The resolved type did not match the expected type.
	#[error("Type mismatch: expected {expected}, got {actual}")]
	TypeMismatch {
		/// The type that was expected.
		expected: String,
		/// The type that was actually resolved.
		actual: String,
	},

	/// An error related to dependency scoping (request vs singleton).
	#[error("Scope error: {0}")]
	ScopeError(String),

	/// The requested type was not registered in the dependency registry.
	#[error("Type '{type_name}' not registered. {hint}")]
	NotRegistered {
		/// The name of the unregistered type.
		type_name: String,
		/// A hint message suggesting how to register the type.
		hint: String,
	},

	/// A required dependency was not registered.
	#[error("Dependency not registered: {type_name}")]
	DependencyNotRegistered {
		/// The name of the unregistered dependency type.
		type_name: String,
	},

	/// An internal error in the DI system.
	#[error("Internal error: {message}")]
	Internal {
		/// A description of the internal error.
		message: String,
	},

	/// An authorization error (insufficient permissions).
	#[error("Authorization error: {0}")]
	Authorization(String),

	/// An authentication error (user not authenticated).
	#[error("Authentication error: {0}")]
	Authentication(String),

	/// An extractor requires HTTP request data, but the `InjectionContext`
	/// has no [`ParamContext`] attached.
	///
	/// Occurs when a factory or handler takes a request-scoped extractor
	/// (`Path<T>`, `Query<T>`, `Json<T>`, …) but the DI container was built
	/// without `with_request(...).with_param_context(...)`. Typically a
	/// configuration bug — outside of tests, the request boundary should
	/// always populate both.
	#[cfg(feature = "params")]
	#[error(
		"Extractor `{extractor}` requires HTTP request data, but no ParamContext is attached to the InjectionContext"
	)]
	MissingParamContext {
		/// Name of the extractor that triggered the failure (`"Path"`,
		/// `"Query"`, `"Json"`, …) for diagnostic output.
		extractor: &'static str,
	},

	/// A request-scoped extractor failed during HTTP parameter extraction.
	///
	/// Wraps the underlying [`params::ParamError`]
	/// so that callers can `match` on the inner variant (`MissingParameter`,
	/// `ParseError`, `DeserializationError`, `Authentication`, …) without
	/// duplicating the parameter-error taxonomy on `DiError`.
	#[cfg(feature = "params")]
	#[error("Parameter extraction failed: {0}")]
	ParamExtraction(Box<crate::params::ParamError>),
}

#[cfg(feature = "params")]
impl DiError {
	/// Convert a [`ParamError`](crate::params::ParamError) into a `DiError`,
	/// preserving authentication semantics.
	///
	/// `From<ParamError> for DiError` is deliberately **not** provided to
	/// avoid breaking type inference of the `?` operator in
	/// [`Depends::resolve`](crate::Depends::resolve) call sites generated by
	/// `#[injectable_factory]` — adding the impl introduces a second
	/// candidate `From<E> for DiError` and Rust's inference engine fails to
	/// disambiguate (E0282). Call sites must therefore convert explicitly
	/// via `.map_err(DiError::from_param_error)`.
	pub fn from_param_error(err: crate::params::ParamError) -> Self {
		match err {
			// Authentication failures MUST surface as DiError::Authentication
			// so the handler returns HTTP 401, not 500.
			crate::params::ParamError::Authentication(msg) => DiError::Authentication(msg),
			other => DiError::ParamExtraction(Box::new(other)),
		}
	}
}

impl From<DiError> for reinhardt_core::exception::Error {
	fn from(err: DiError) -> Self {
		match err {
			DiError::NotFound(_)
			| DiError::NotRegistered { .. }
			| DiError::DependencyNotRegistered { .. } => reinhardt_core::exception::Error::NotFound(
				format!("Dependency injection error: {}", err),
			),
			DiError::Authorization(msg) => reinhardt_core::exception::Error::Authorization(msg),
			DiError::Authentication(msg) => reinhardt_core::exception::Error::Authentication(msg),
			// Delegate ParamExtraction to the existing `From<ParamError> for
			// CoreError` chain so that structured `ParamErrorContext` (field,
			// expected type, raw value) is preserved and the HTTP status is
			// driven by the inner ParamError variant rather than collapsed
			// to a generic 500.
			#[cfg(feature = "params")]
			DiError::ParamExtraction(inner) => (*inner).into(),
			// `MissingParamContext` is an infrastructure-level misconfiguration
			// (the request boundary did not attach a ParamContext), so it maps
			// to HTTP 500 rather than 400.
			#[cfg(feature = "params")]
			err @ DiError::MissingParamContext { .. } => reinhardt_core::exception::Error::Internal(
				format!("Dependency injection error: {}", err),
			),
			other => reinhardt_core::exception::Error::Internal(format!(
				"Dependency injection error: {}",
				other
			)),
		}
	}
}

/// A specialized `Result` type for dependency injection operations.
pub type DiResult<T> = std::result::Result<T, DiError>;

// Generator support
#[cfg(feature = "generator")]
pub mod generator;

#[cfg(test)]
mod tests {
	use rstest::rstest;

	use super::*;

	#[rstest]
	#[case::not_found(DiError::NotFound("missing".to_string()), 404)]
	#[case::not_registered(DiError::NotRegistered { type_name: "Foo".to_string(), hint: "".to_string() }, 404)]
	#[case::dependency_not_registered(DiError::DependencyNotRegistered { type_name: "Bar".to_string() }, 404)]
	#[case::authorization(DiError::Authorization("forbidden".to_string()), 403)]
	#[case::authentication(DiError::Authentication("not authenticated".to_string()), 401)]
	#[case::circular_dependency(DiError::CircularDependency("A -> B -> A".to_string()), 500)]
	#[case::provider_error(DiError::ProviderError("boom".to_string()), 500)]
	#[case::type_mismatch(DiError::TypeMismatch { expected: "A".to_string(), actual: "B".to_string() }, 500)]
	#[case::scope_error(DiError::ScopeError("wrong scope".to_string()), 500)]
	#[case::internal(DiError::Internal { message: "oops".to_string() }, 500)]
	fn test_di_error_to_http_error_status_mapping(
		#[case] di_err: DiError,
		#[case] expected_status: u16,
	) {
		// Arrange (provided by #[case])

		// Act
		let err: reinhardt_core::exception::Error = di_err.into();

		// Assert
		assert_eq!(err.status_code(), expected_status);
	}
}

// Development tools
#[cfg(feature = "dev-tools")]
pub mod visualization;

#[cfg(feature = "dev-tools")]
pub mod profiling;

#[cfg(feature = "dev-tools")]
pub mod advanced_cache;