solti-runner 0.0.2

//! # Metrics backend trait and label types.
//!
//! [`MetricsBackend`] is the abstraction for collecting task execution metrics.
//! Concrete backends (e.g. `solti-prometheus`) implement this trait.
//!
//! See the [metrics module](super) for the convenience [`noop_metrics`](super::noop_metrics) constructor.

use std::sync::Arc;

/// Runner implementation type for metrics labeling.
///
/// Passed to [`MetricsBackend`] methods so dashboards can slice metrics by runner backend.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum RunnerType {
    /// OS subprocess runner.
    Subprocess,
    /// Container (OCI) runner.
    Container,
    /// WebAssembly runner.
    Wasm,
}

impl RunnerType {
    /// Return label value for metrics.
    #[inline]
    pub fn as_label(self) -> &'static str {
        match self {
            Self::Subprocess => "subprocess",
            Self::Container => "container",
            Self::Wasm => "wasm",
        }
    }
}

/// Runner setup/teardown error kind for metrics labeling.
///
/// Passed to [`MetricsBackend::record_runner_error`] so dashboards can slice errors by a bounded, low-cardinality label rather than free-form strings.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum RunnerErrorKind {
    /// cgroup v2 preparation (creation / attribute write) failed.
    CgroupPrepareFailed,
    /// Applying runner-specific configuration to the task command failed (rlimits, capabilities, namespaces, …).
    BackendConfigFailed,
    /// Spawning the child process or actor failed.
    SpawnFailed,
    /// Loading the runner module (WASM / container image) failed.
    ModuleLoadFailed,
}

impl RunnerErrorKind {
    /// Return label value for metrics.
    #[inline]
    pub fn as_label(self) -> &'static str {
        match self {
            Self::CgroupPrepareFailed => "cgroup_prepare_failed",
            Self::BackendConfigFailed => "backend_config_failed",
            Self::SpawnFailed => "spawn_failed",
            Self::ModuleLoadFailed => "module_load_failed",
        }
    }
}

/// Task execution outcome for metrics classification.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TaskOutcome {
    /// Task completed successfully.
    Success,
    /// Task failed.
    Failure,
    /// Task canceled.
    Canceled,
    /// Task timeout.
    Timeout,
}

impl TaskOutcome {
    /// Return label value for metrics.
    #[inline]
    pub fn as_label(&self) -> &'static str {
        match self {
            TaskOutcome::Success => "success",
            TaskOutcome::Failure => "failure",
            TaskOutcome::Canceled => "canceled",
            TaskOutcome::Timeout => "timeout",
        }
    }
}

/// Backend metrics collection interface.
///
/// This trait abstracts metrics collection across different backends.
/// Implementations are injected via [`crate::BuildContext`] and used by all runners.
///
/// ## Also
///
/// - [`NoOpMetrics`](super::NoOpMetrics): zero-size default backend.
/// - [`crate::BuildContext::metrics`]: access the handle from within a runner.
/// - `solti-prometheus::PrometheusMetrics` is a production Prometheus implementation.
pub trait MetricsBackend: Send + Sync + 'static {
    /// Record task spawn event.
    ///
    /// Called when a task is submitted and starts executing.
    fn record_task_started(&self, runner_type: RunnerType);

    /// Record task completion with outcome and duration.
    ///
    /// Called when task exits (success, failure, timeout, cancel).
    fn record_task_completed(
        &self,
        runner_type: RunnerType,
        outcome: TaskOutcome,
        duration_ms: u64,
    );

    /// Record runner-specific error during task setup/teardown.
    ///
    /// Called when runner fails to spawn/cleanup a task.
    /// This is separate from task failures (which are `record_task_completed` with `Failure`).
    fn record_runner_error(&self, runner_type: RunnerType, error_kind: RunnerErrorKind);
}

/// Shared handle to metrics backend.
///
/// Stored in [`crate::BuildContext`] and cloned into each task.
pub type MetricsHandle = Arc<dyn MetricsBackend>;

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

    #[test]
    fn runner_error_kind_as_label_maps_all_variants() {
        assert_eq!(
            RunnerErrorKind::CgroupPrepareFailed.as_label(),
            "cgroup_prepare_failed"
        );
        assert_eq!(
            RunnerErrorKind::BackendConfigFailed.as_label(),
            "backend_config_failed"
        );
        assert_eq!(RunnerErrorKind::SpawnFailed.as_label(), "spawn_failed");
        assert_eq!(
            RunnerErrorKind::ModuleLoadFailed.as_label(),
            "module_load_failed"
        );
    }
}