crawlrs 0.2.0

crawlrs - Enterprise-grade web scraping and crawling platform built with Rust
Documentation
// Copyright (c) 2025-2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! # Dependency Injection Module (trait-kit)
//!
//! Provides standardized dependency injection for the crawlrs application using
//! the [trait-kit](https://crates.io/crates/trait-kit) library.
//!
//! ## Architecture
//!
//! ```text
//! AsyncKit<Unbuilt>
//!   │  kit.set_config(Arc<Settings>)
//!   │  kit.register::<M>() for each module
//!   â–¼
//! AsyncKit<Ready>  ──►  CrawlRsState::from_kit(&kit)
//!                          │
//!                          â–¼
//!                     Axum handlers (Extension<Arc<CrawlRsState>>)
//! ```
//!
//! ## Module Dependency Graph
//!
//! ```text
//! SettingsModule (config: Arc<Settings>)
//!   ├── DatabaseModule    → Arc<DatabasePool>
//!   ├── HttpModule        → Arc<reqwest::Client>
//!   └── CacheModule       → CacheComponents (SearchCache + ConcurrencyController)
//!          ├── RepositoryModule    → Repositories (depends: DatabaseModule)
//!          └── EngineModule        → EngineComponents (depends: HttpModule, SettingsModule)
//!                 └── ServiceModule         → ServicesComponents (depends: all above)
//!                     └── InfrastructureModule → InfrastructureComponents (aggregates all)
//! ```
//!
//! ## Quick Start
//!
//! ### 1. Bootstrap Application (main.rs)
//!
//! ```rust,no_run
//! use crawlrs::config::Settings;
//! use crawlrs::di::modules::*;
//! use crawlrs::di::CrawlRsState;
//! use trait_kit::AsyncKit;
//!
//! # async fn bootstrap() -> anyhow::Result<()> {
//! let settings = Arc::new(Settings::load()?);
//!
//! let mut kit = AsyncKit::new();
//! kit.set_config(settings.clone());
//! kit.register::<SettingsModule>()?;
//! kit.register::<DatabaseModule>()?;
//! kit.register::<HttpModule>()?;
//! kit.register::<CacheModule>()?;
//! kit.register::<RepositoryModule>()?;
//! kit.register::<EngineModule>()?;
//! kit.register::<InfrastructureModule>()?;
//! kit.register::<ServiceModule>()?;
//!
//! let kit = kit.build().await?;
//! let app_state = CrawlRsState::from_kit(&kit)?;
//! # Ok(())
//! # }
//! ```
//!
//! ### 2. Access Dependencies in Handlers
//!
//! ```rust,ignore
//! use std::sync::Arc;
//! use axum::extract::Extension;
//! use crawlrs::di::{CrawlRsState, CrawlRsStateExt};
//!
//! async fn my_handler(
//!     Extension(app_state): Extension<Arc<CrawlRsState>>,
//! ) -> impl IntoResponse {
//!     let task_repo = app_state.task_repo();      // Arc<dyn TaskRepository>
//!     let engine_client = app_state.engine_client(); // Arc<EngineClient>
//!     // ...
//! }
//! ```
//!
//! ## Module Catalog
//!
//! | Module | Capability | Dependencies |
//! |--------|------------|--------------|
//! | `SettingsModule` | `Arc<Settings>` | (none) |
//! | `DatabaseModule` | `Arc<DatabasePool>` | Settings |
//! | `HttpModule` | `Arc<reqwest::Client>` | Settings |
//! | `CacheModule` | `CacheComponents` | Settings |
//! | `RepositoryModule` | `Repositories` | Database |
//! | `EngineModule` | `EngineComponents` | Http, Settings |
//! | `InfrastructureModule` | `InfrastructureComponents` | Database, Http, Cache, Repository |
//! | `ServiceModule` | `ServicesComponents` | Infrastructure, Engine, Settings |
//!
//! ## Testing
//!
//! Tests use `tcf::DbHandle` (testcontainers) to provision PostgreSQL,
//! then build a real `AsyncKit` via the same module registration flow as production.
//! See `axum_state::tests::build_app_state()` for the canonical test helper.
//!
//! ## Error Handling
//!
//! Module construction failures return [`ModuleBuildError`]modules::ModuleBuildError,
//! which converts to `anyhow::Error` via `?` in application code.
//!
//! `TraitKitError` (from `trait_kit::TraitKitError`) does **not** implement `Sync`
//! because it wraps `Box<dyn std::error::Error + Send + 'static>`. Use the
//! `.map_err(|e| anyhow::anyhow!("...: {e}"))?` pattern when propagating
//! `register()`, `build()`, or `require()` errors through `anyhow::Result`.