mecha10-core 0.8.2

//! Service Manager for Lifecycle Management
//!
//! This module provides centralized management of Service lifecycles, including
//! registration, startup, shutdown, and health monitoring.
//!
//! # Architecture
//!
//! ```text
//! ┌────────────────────────────────────────────────────────────┐
//! │                    ServiceManager                           │
//! ├────────────────────────────────────────────────────────────┤
//! │                                                            │
//! │  1. Register services (init phase)                         │
//! │     ├─ HTTP API Service                                    │
//! │     ├─ Database Service                                    │
//! │     └─ Job Processor Service                               │
//! │                                                            │
//! │  2. Start all services (in registration order)             │
//! │     └─ Spawn background tasks                              │
//! │                                                            │
//! │  3. Monitor health                                         │
//! │     └─ Periodic health checks                              │
//! │                                                            │
//! │  4. Stop all services (reverse order)                      │
//! │     └─ Graceful shutdown                                   │
//! │                                                            │
//! └────────────────────────────────────────────────────────────┘
//! ```
//!
//! # Example
//!
//! ```rust
//! use mecha10_core::prelude::*;
//! use mecha10_core::service::Service;
//! use mecha10_core::service_manager::ServiceManager;
//!
//! # async fn example() -> Result<()> {
//! // Create service manager
//! let mut service_manager = ServiceManager::new();
//!
//! # let http_config = HttpConfig;
//! # let db_config = DbConfig;
//! // Register services
//! service_manager.register::<HttpApiService>(http_config).await?;
//! service_manager.register::<DatabaseService>(db_config).await?;
//!
//! // Start all services
//! service_manager.start_all().await?;
//!
//! // ... application runs ...
//!
//! // Wait for shutdown signal
//! tokio::signal::ctrl_c().await?;
//!
//! // Stop all services (in reverse order)
//! service_manager.stop_all().await?;
//! # Ok(())
//! # }
//! # #[derive(Debug)] struct HttpApiService;
//! # #[derive(Debug)] struct DatabaseService;
//! # #[derive(Debug, serde::Deserialize)] struct HttpConfig;
//! # #[derive(Debug, serde::Deserialize)] struct DbConfig;
//! # #[async_trait::async_trait]
//! # impl Service for HttpApiService {
//! #     type Config = HttpConfig;
//! #     async fn init(_: Self::Config) -> Result<Self> { Ok(Self) }
//! #     async fn start(&mut self) -> Result<()> { Ok(()) }
//! #     async fn stop(&mut self) -> Result<()> { Ok(()) }
//! #     fn name(&self) -> &str { "http" }
//! # }
//! # #[async_trait::async_trait]
//! # impl Service for DatabaseService {
//! #     type Config = DbConfig;
//! #     async fn init(_: Self::Config) -> Result<Self> { Ok(Self) }
//! #     async fn start(&mut self) -> Result<()> { Ok(()) }
//! #     async fn stop(&mut self) -> Result<()> { Ok(()) }
//! #     fn name(&self) -> &str { "db" }
//! # }
//! ```

use crate::service::Service;
use crate::{HealthStatus, Result};
use async_trait::async_trait;
use tokio::sync::broadcast;
use tracing::{debug, error, info};

#[async_trait]
trait ServiceWrapper: Send + Sync {
    async fn start(&mut self) -> Result<()>;
    async fn stop(&mut self) -> Result<()>;
    async fn health_check(&self) -> HealthStatus;
    fn name(&self) -> &str;
}

struct ServiceBox<S: Service> {
    service: S,
}

#[async_trait]
impl<S: Service> ServiceWrapper for ServiceBox<S> {
    async fn start(&mut self) -> Result<()> {
        self.service.start().await
    }

    async fn stop(&mut self) -> Result<()> {
        self.service.stop().await
    }

    async fn health_check(&self) -> HealthStatus {
        self.service.health_check().await
    }

    fn name(&self) -> &str {
        self.service.name()
    }
}

pub struct ServiceManager {
    services: Vec<Box<dyn ServiceWrapper>>,

    shutdown_tx: broadcast::Sender<()>,
}

impl ServiceManager {
    /// Create a new ServiceManager.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use mecha10_core::service_manager::ServiceManager;
    /// let manager = ServiceManager::new();
    /// ```
    pub fn new() -> Self {
        let (shutdown_tx, _) = broadcast::channel(1);
        Self {
            services: Vec::new(),
            shutdown_tx,
        }
    }

    /// Register a service with configuration.
    ///
    /// Calls `Service::init()` to initialize the service, then stores it
    /// for later startup. Services are started in the order they are registered.
    ///
    /// # Arguments
    ///
    /// * `config` - Service-specific configuration
    ///
    /// # Returns
    ///
    /// * `Ok(())` - Service registered successfully
    /// * `Err(_)` - Service initialization failed
    ///
    /// # Example
    ///
    /// ```rust
    /// # use mecha10_core::prelude::*;
    /// # use mecha10_core::service::Service;
    /// # use mecha10_core::service_manager::ServiceManager;
    /// # async fn example() -> Result<()> {
    /// let mut manager = ServiceManager::new();
    ///
    /// // Register HTTP API
    /// manager.register::<HttpApiService>(HttpApiConfig {
    ///     host: "0.0.0.0".to_string(),
    ///     port: 8080,
    /// }).await?;
    ///
    /// // Register database
    /// manager.register::<DatabaseService>(DatabaseConfig {
    ///     url: "postgresql://localhost/mecha10".to_string(),
    ///     max_connections: 20,
    /// }).await?;
    /// # Ok(())
    /// # }
    /// # #[derive(Debug)] struct HttpApiService;
    /// # #[derive(Debug)] struct DatabaseService;
    /// # #[derive(Debug, serde::Deserialize)] struct HttpApiConfig { host: String, port: u16 }
    /// # #[derive(Debug, serde::Deserialize)] struct DatabaseConfig { url: String, max_connections: u32 }
    /// # #[async_trait::async_trait]
    /// # impl Service for HttpApiService {
    /// #     type Config = HttpApiConfig;
    /// #     async fn init(_: Self::Config) -> Result<Self> { Ok(Self) }
    /// #     async fn start(&mut self) -> Result<()> { Ok(()) }
    /// #     async fn stop(&mut self) -> Result<()> { Ok(()) }
    /// #     fn name(&self) -> &str { "http_api" }
    /// # }
    /// # #[async_trait::async_trait]
    /// # impl Service for DatabaseService {
    /// #     type Config = DatabaseConfig;
    /// #     async fn init(_: Self::Config) -> Result<Self> { Ok(Self) }
    /// #     async fn start(&mut self) -> Result<()> { Ok(()) }
    /// #     async fn stop(&mut self) -> Result<()> { Ok(()) }
    /// #     fn name(&self) -> &str { "database" }
    /// # }
    /// ```
    pub async fn register<S>(&mut self, config: S::Config) -> Result<()>
    where
        S: Service + 'static,
    {
        debug!("Registering service: {}", std::any::type_name::<S>());

        let service = S::init(config).await?;
        let name = service.name().to_string();

        let boxed = Box::new(ServiceBox { service });

        self.services.push(boxed);

        info!("Registered service: {}", name);
        Ok(())
    }

    /// Start all registered services.
    ///
    /// Services are started in the order they were registered. If any service
    /// fails to start, the error is returned and remaining services are not started.
    ///
    /// # Returns
    ///
    /// * `Ok(())` - All services started successfully
    /// * `Err(_)` - A service failed to start
    ///
    /// # Example
    ///
    /// ```rust
    /// # use mecha10_core::prelude::*;
    /// # use mecha10_core::service_manager::ServiceManager;
    /// # async fn example() -> Result<()> {
    /// let mut manager = ServiceManager::new();
    /// // ... register services ...
    ///
    /// // Start all services
    /// manager.start_all().await?;
    ///
    /// info!("All services started successfully");
    /// # Ok(())
    /// # }
    /// ```
    pub async fn start_all(&mut self) -> Result<()> {
        info!("Starting {} services", self.services.len());

        for service in &mut self.services {
            let name = service.name().to_string();
            debug!("Starting service: {}", name);

            if let Err(e) = service.start().await {
                error!("Failed to start service '{}': {}", name, e);
                return Err(e);
            }

            info!("Started service: {}", name);
        }

        info!("All services started successfully");
        Ok(())
    }

    /// Stop all services gracefully.
    ///
    /// Services are stopped in **reverse order** of registration. This ensures
    /// that dependent services are stopped first (e.g., stop API server before database).
    ///
    /// Each service's `stop()` method is called, even if previous services failed
    /// to stop. All errors are logged, and the first error encountered is returned.
    ///
    /// # Returns
    ///
    /// * `Ok(())` - All services stopped successfully
    /// * `Err(_)` - At least one service failed to stop
    ///
    /// # Example
    ///
    /// ```rust
    /// # use mecha10_core::prelude::*;
    /// # use mecha10_core::service_manager::ServiceManager;
    /// # async fn example() -> Result<()> {
    /// # let mut manager = ServiceManager::new();
    /// // ... services running ...
    ///
    /// // Graceful shutdown
    /// tokio::signal::ctrl_c().await?;
    /// manager.stop_all().await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn stop_all(&mut self) -> Result<()> {
        info!("Stopping {} services (in reverse order)", self.services.len());

        let mut first_error = None;

        for service in self.services.iter_mut().rev() {
            let name = service.name().to_string();
            debug!("Stopping service: {}", name);

            match service.stop().await {
                Ok(()) => {
                    info!("Stopped service: {}", name);
                }
                Err(e) => {
                    error!("Failed to stop service '{}': {}", name, e);
                    if first_error.is_none() {
                        first_error = Some(e);
                    }
                }
            }
        }

        if let Some(err) = first_error {
            error!("Service manager stopped with errors");
            Err(err)
        } else {
            info!("All services stopped successfully");
            Ok(())
        }
    }

    /// Check health of all services.
    ///
    /// Calls `health_check()` on each registered service and returns a vector
    /// of (name, status) tuples.
    ///
    /// # Returns
    ///
    /// * `Vec<(String, HealthStatus)>` - Health status for each service
    ///
    /// # Example
    ///
    /// ```rust
    /// # use mecha10_core::prelude::*;
    /// # use mecha10_core::service_manager::ServiceManager;
    /// # async fn example() -> Result<()> {
    /// # let manager = ServiceManager::new();
    /// let health = manager.health_check_all().await;
    ///
    /// for (name, status) in health {
    ///     if !status.healthy {
    ///         warn!("Service '{}' is unhealthy: {:?}", name, status.message);
    ///     } else {
    ///         info!("Service '{}' is healthy", name);
    ///     }
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub async fn health_check_all(&self) -> Vec<(String, HealthStatus)> {
        let mut results = Vec::new();

        for service in &self.services {
            let name = service.name().to_string();
            let status = service.health_check().await;

            debug!("Health check for '{}': healthy={}", name, status.healthy);
            results.push((name, status));
        }

        results
    }

    /// Get a broadcast receiver for shutdown signals.
    ///
    /// Services can use this to listen for shutdown signals and stop gracefully.
    ///
    /// # Returns
    ///
    /// * `broadcast::Receiver<()>` - Shutdown signal receiver
    ///
    /// # Example
    ///
    /// ```rust
    /// # use mecha10_core::service_manager::ServiceManager;
    /// # async fn example() {
    /// let manager = ServiceManager::new();
    /// let mut shutdown_rx = manager.shutdown_signal();
    ///
    /// tokio::spawn(async move {
    ///     shutdown_rx.recv().await.ok();
    ///     // Service cleanup...
    /// });
    /// # }
    /// ```
    pub fn shutdown_signal(&self) -> broadcast::Receiver<()> {
        self.shutdown_tx.subscribe()
    }

    /// Trigger shutdown by broadcasting to all listeners.
    ///
    /// This sends a signal to all `shutdown_signal()` receivers. Services
    /// should listen to this signal to stop gracefully.
    ///
    /// Note: This does NOT call `stop_all()`. You must call `stop_all()`
    /// separately to actually stop services.
    ///
    /// # Example
    ///
    /// ```rust
    /// # use mecha10_core::service_manager::ServiceManager;
    /// # async fn example() {
    /// let mut manager = ServiceManager::new();
    ///
    /// // Trigger shutdown signal
    /// manager.shutdown();
    ///
    /// // Then stop all services
    /// manager.stop_all().await.ok();
    /// # }
    /// ```
    pub fn shutdown(&self) {
        info!("Broadcasting shutdown signal");
        let _ = self.shutdown_tx.send(());
    }

    /// Get the number of registered services.
    ///
    /// # Returns
    ///
    /// * `usize` - Number of services
    ///
    /// # Example
    ///
    /// ```rust
    /// # use mecha10_core::service_manager::ServiceManager;
    /// # let manager = ServiceManager::new();
    /// println!("Services registered: {}", manager.service_count());
    /// ```
    pub fn service_count(&self) -> usize {
        self.services.len()
    }

    /// Get names of all registered services.
    ///
    /// # Returns
    ///
    /// * `Vec<String>` - Service names
    ///
    /// # Example
    ///
    /// ```rust
    /// # use mecha10_core::service_manager::ServiceManager;
    /// # let manager = ServiceManager::new();
    /// let names = manager.service_names();
    /// println!("Services: {}", names.join(", "));
    /// ```
    pub fn service_names(&self) -> Vec<String> {
        self.services.iter().map(|s| s.name().to_string()).collect()
    }
}

impl Default for ServiceManager {
    fn default() -> Self {
        Self::new()
    }
}