footing 0.1.5

Feature-gated foundations for Rust backend services
Documentation
//! Async resource probes and ordered diagnostic registry.

use std::{collections::BTreeMap, fmt, future::Future, sync::Arc, time::Duration};

use async_trait::async_trait;

use crate::result::BoxError;

use super::{
    error::ResourceRegistryError,
    model::{
        DEFAULT_RESOURCE_PROBE_TIMEOUT, ResourceDescriptor, ResourceDiagnostic,
        ResourceDiagnosticsReport, normalize_diagnostics_service_name,
    },
};

/// A resource probe registered with a [`ResourceRegistry`].
#[async_trait]
pub trait ResourceProbe: Send + Sync + 'static {
    /// Static descriptor used for registry validation and failed probes.
    fn descriptor(&self) -> ResourceDescriptor;

    /// Runs the probe.
    async fn probe(&self) -> Result<ResourceDiagnostic, BoxError>;
}

/// Builds a static probe from a descriptor, constructor, and summary.
#[must_use]
pub fn static_resource_probe(
    descriptor: ResourceDescriptor,
    diagnostic: fn(ResourceDescriptor, String) -> ResourceDiagnostic,
    summary: impl Into<String>,
) -> Arc<dyn ResourceProbe> {
    let summary = summary.into();
    resource_probe(descriptor, move |descriptor| {
        let summary = summary.clone();
        async move { Ok(diagnostic(descriptor, summary)) }
    })
}

/// Builds a probe from a descriptor and an async closure.
///
/// This is the usual choice for application diagnostics because the closure can
/// capture config, clients, or preloaded state without requiring one-off probe
/// structs.
#[must_use]
pub fn resource_probe<F, Fut>(descriptor: ResourceDescriptor, probe: F) -> Arc<dyn ResourceProbe>
where
    F: Fn(ResourceDescriptor) -> Fut + Send + Sync + 'static,
    Fut: Future<Output = Result<ResourceDiagnostic, BoxError>> + Send + 'static,
{
    Arc::new(FnResourceProbe { descriptor, probe })
}

/// Ordered registry of resources probed for startup/readiness.
#[derive(Clone)]
pub struct ResourceRegistry {
    service_name: String,
    probes: Vec<Arc<dyn ResourceProbe>>,
    probe_timeout: Duration,
}

impl ResourceRegistry {
    /// Creates an empty registry.
    pub fn new(service_name: impl Into<String>) -> Result<Self, ResourceRegistryError> {
        Ok(Self {
            service_name: normalize_diagnostics_service_name(service_name)
                .map_err(|_| ResourceRegistryError::InvalidServiceName)?,
            probes: Vec::new(),
            probe_timeout: DEFAULT_RESOURCE_PROBE_TIMEOUT,
        })
    }

    /// Configures the maximum duration of each individual probe.
    #[must_use]
    pub const fn with_probe_timeout(mut self, probe_timeout: Duration) -> Self {
        self.probe_timeout = probe_timeout;
        self
    }

    /// Registers one probe.
    #[must_use]
    pub fn with_probe(mut self, probe: Arc<dyn ResourceProbe>) -> Self {
        self.probes.push(probe);
        self
    }

    /// Registers one probe by mutable reference.
    pub fn push_probe(&mut self, probe: Arc<dyn ResourceProbe>) {
        self.probes.push(probe);
    }

    /// Returns registered probes in execution order.
    #[must_use]
    pub fn probes(&self) -> &[Arc<dyn ResourceProbe>] {
        &self.probes
    }

    /// Returns the maximum duration of each individual probe.
    #[must_use]
    pub const fn probe_timeout(&self) -> Duration {
        self.probe_timeout
    }

    /// Validates static registry metadata.
    pub fn validate(&self) -> Result<(), ResourceRegistryError> {
        normalize_diagnostics_service_name(&self.service_name)
            .map_err(|_| ResourceRegistryError::InvalidServiceName)?;
        if self.probe_timeout.is_zero() {
            return Err(ResourceRegistryError::InvalidProbeTimeout);
        }

        let mut seen = BTreeMap::<String, usize>::new();
        for (index, probe) in self.probes.iter().enumerate() {
            let descriptor = probe.descriptor();
            descriptor
                .validate()
                .map_err(|source| ResourceRegistryError::InvalidDescriptor { index, source })?;
            if let Some(first_index) = seen.insert(descriptor.id.clone(), index) {
                return Err(ResourceRegistryError::DuplicateResourceId {
                    id: descriptor.id,
                    first_index,
                    second_index: index,
                });
            }
        }
        Ok(())
    }

    /// Runs every probe and returns a report.
    pub async fn run(&self) -> Result<ResourceDiagnosticsReport, BoxError> {
        self.validate()?;
        let mut diagnostics = Vec::with_capacity(self.probes.len());
        for probe in &self.probes {
            let descriptor = probe.descriptor();
            match tokio::time::timeout(self.probe_timeout, probe.probe()).await {
                Ok(Ok(mut diagnostic)) => {
                    diagnostic.resource = descriptor;
                    diagnostics.push(diagnostic);
                }
                Ok(Err(_)) => diagnostics.push(ResourceDiagnostic::unhealthy(
                    descriptor,
                    "resource probe failed",
                )),
                Err(_) => diagnostics.push(ResourceDiagnostic::unhealthy(
                    descriptor,
                    "resource probe timed out",
                )),
            }
        }

        Ok(ResourceDiagnosticsReport::new(
            self.service_name.clone(),
            diagnostics,
        )?)
    }
}

impl fmt::Debug for ResourceRegistry {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("ResourceRegistry")
            .field("service_name", &self.service_name)
            .field("probes", &self.probes.len())
            .field("probe_timeout", &self.probe_timeout)
            .finish()
    }
}

impl Default for ResourceRegistry {
    fn default() -> Self {
        Self {
            service_name: String::new(),
            probes: Vec::new(),
            probe_timeout: DEFAULT_RESOURCE_PROBE_TIMEOUT,
        }
    }
}

struct FnResourceProbe<F> {
    descriptor: ResourceDescriptor,
    probe: F,
}

#[async_trait]
impl<F, Fut> ResourceProbe for FnResourceProbe<F>
where
    F: Fn(ResourceDescriptor) -> Fut + Send + Sync + 'static,
    Fut: Future<Output = Result<ResourceDiagnostic, BoxError>> + Send + 'static,
{
    fn descriptor(&self) -> ResourceDescriptor {
        self.descriptor.clone()
    }

    async fn probe(&self) -> Result<ResourceDiagnostic, BoxError> {
        (self.probe)(self.descriptor.clone()).await
    }
}