kube_condition/

lib.rs

// Copyright (c) 2025 Erick Bourgeois, firestoned
// SPDX-License-Identifier: MIT

//! # kube-condition
//!
//! Runtime support for mapping Rust errors to Kubernetes status conditions.
//!
//! This crate provides:
//! - The `StatusCondition` trait for error types
//! - Condition builders and update helpers
//! - A reconcile wrapper that automatically updates status on errors
//!
//! ## Usage
//!
//! ```rust,ignore
//! use kube_condition::{StatusCondition, ConditionExt};
//! use thiserror::Error;
//!
//! #[derive(Error, Debug, StatusCondition)]
//! #[condition(default_type = "Ready")]
//! pub enum MyError {
//!     #[error("Something went wrong: {0}")]
//!     #[condition(reason = "SomethingFailed", retryable = true)]
//!     Something(String),
//! }
//! ```

#![allow(clippy::missing_errors_doc)] // Error docs are in trait definitions
#![allow(clippy::must_use_candidate)] // Builder patterns don't need must_use
#![allow(clippy::return_self_not_must_use)] // Builder patterns intentionally return Self
#![allow(clippy::type_complexity)] // Complex types are necessary for async traits

// Re-export the derive macro so users can use both the trait and derive
#[cfg(feature = "derive")]
#[doc(inline)]
pub use kube_condition_derive::StatusCondition;

use k8s_openapi::apimachinery::pkg::apis::meta::v1::Condition;
use k8s_openapi::apimachinery::pkg::apis::meta::v1::Time;
use k8s_openapi::chrono::Utc;
use kube::api::{Api, Patch, PatchParams};
use kube::runtime::controller::Action;
use kube::{Resource, ResourceExt};
use serde::de::DeserializeOwned;
use serde::Serialize;
use std::fmt::Debug;
use std::sync::Arc;
use std::time::Duration;
use tracing::{debug, error, info, warn};

// Constants for standard Kubernetes condition types
/// Standard "Ready" condition type
pub const CONDITION_TYPE_READY: &str = "Ready";
/// Standard "Progressing" condition type
pub const CONDITION_TYPE_PROGRESSING: &str = "Progressing";
/// Standard "Degraded" condition type
pub const CONDITION_TYPE_DEGRADED: &str = "Degraded";
/// Standard "Available" condition type
pub const CONDITION_TYPE_AVAILABLE: &str = "Available";

// Constants for standard condition status values
/// Condition status "True"
pub const CONDITION_STATUS_TRUE: &str = "True";
/// Condition status "False"
pub const CONDITION_STATUS_FALSE: &str = "False";
/// Condition status "Unknown"
pub const CONDITION_STATUS_UNKNOWN: &str = "Unknown";

// Constants for common condition reasons
/// Reason when reconciliation succeeds
pub const CONDITION_REASON_RECONCILE_SUCCEEDED: &str = "ReconcileSucceeded";
/// Reason when reconciliation is in progress
pub const CONDITION_REASON_PROGRESSING: &str = "Progressing";

// Constants for retry/requeue durations
/// Default requeue duration in seconds for retryable errors
pub const DEFAULT_REQUEUE_SECONDS: u64 = 30;
/// Default requeue duration for non-retryable errors (longer backoff)
pub const DEFAULT_NON_RETRYABLE_REQUEUE_SECONDS: u64 = 300;

// Constants for field manager
/// Field manager name used for patch operations
pub const FIELD_MANAGER_NAME: &str = "kube-condition";

/// Severity level for conditions, useful for observability and alerting
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Severity {
    Info,
    Warning,
    Error,
}

impl Severity {
    pub fn as_str(&self) -> &'static str {
        match self {
            Severity::Info => "Info",
            Severity::Warning => "Warning",
            Severity::Error => "Error",
        }
    }
}

/// Intermediate condition info before converting to k8s Condition
#[derive(Debug, Clone)]
pub struct ConditionInfo {
    pub type_: String,
    pub status: String,
    pub reason: String,
    pub message: String,
}

impl ConditionInfo {
    /// Convert to a full k8s Condition with timestamp
    pub fn into_condition(self, observed_generation: Option<i64>) -> Condition {
        Condition {
            type_: self.type_,
            status: self.status,
            reason: self.reason,
            message: self.message,
            last_transition_time: Time(Utc::now()),
            observed_generation,
        }
    }
}

/// Trait for errors that can be mapped to Kubernetes status conditions.
///
/// This is typically derived using `#[derive(StatusCondition)]` from `kube-condition-derive`.
pub trait StatusCondition: std::error::Error {
    /// Get the condition info for this error
    fn to_condition_info(&self) -> ConditionInfo;

    /// Get the severity level of this error
    fn severity(&self) -> Severity;

    /// Whether this error should trigger a retry
    fn is_retryable(&self) -> bool;

    /// Suggested requeue duration for retryable errors
    fn requeue_duration(&self) -> Duration;

    /// Convert to a full k8s Condition
    fn to_condition(&self, observed_generation: Option<i64>) -> Condition {
        self.to_condition_info().into_condition(observed_generation)
    }

    /// Get the appropriate controller Action based on retryability
    fn to_action(&self) -> Action {
        if self.is_retryable() {
            Action::requeue(self.requeue_duration())
        } else {
            // For non-retryable errors, use a longer backoff
            Action::requeue(Duration::from_secs(DEFAULT_NON_RETRYABLE_REQUEUE_SECONDS))
        }
    }
}

// Helper functions for creating common conditions

/// Create a Ready=True condition
///
/// # Example
///
/// ```rust
/// use kube_condition::ready_condition;
///
/// let condition = ready_condition(true, "All systems operational");
/// assert_eq!(condition.type_, "Ready");
/// assert_eq!(condition.status, "True");
/// ```
pub fn ready_condition(ready: bool, message: impl Into<String>) -> ConditionInfo {
    ConditionInfo {
        type_: CONDITION_TYPE_READY.to_string(),
        status: if ready { CONDITION_STATUS_TRUE } else { CONDITION_STATUS_FALSE }.to_string(),
        reason: if ready { CONDITION_REASON_RECONCILE_SUCCEEDED } else { "NotReady" }.to_string(),
        message: message.into(),
    }
}

/// Create an error condition with Ready=False
///
/// # Example
///
/// ```rust
/// use kube_condition::error_condition;
///
/// let condition = error_condition("DatabaseConnectionFailed", "Unable to connect to database");
/// assert_eq!(condition.type_, "Ready");
/// assert_eq!(condition.status, "False");
/// assert_eq!(condition.reason, "DatabaseConnectionFailed");
/// ```
pub fn error_condition(reason: impl Into<String>, message: impl Into<String>) -> ConditionInfo {
    ConditionInfo {
        type_: CONDITION_TYPE_READY.to_string(),
        status: CONDITION_STATUS_FALSE.to_string(),
        reason: reason.into(),
        message: message.into(),
    }
}

/// Builder for creating "ready" conditions
#[derive(Debug, Clone)]
pub struct ReadyCondition;

impl ReadyCondition {
    pub fn success(message: impl Into<String>) -> ConditionInfo {
        ConditionInfo {
            type_: CONDITION_TYPE_READY.to_string(),
            status: CONDITION_STATUS_TRUE.to_string(),
            reason: CONDITION_REASON_RECONCILE_SUCCEEDED.to_string(),
            message: message.into(),
        }
    }

    pub fn progressing(message: impl Into<String>) -> ConditionInfo {
        ConditionInfo {
            type_: CONDITION_TYPE_READY.to_string(),
            status: CONDITION_STATUS_FALSE.to_string(),
            reason: CONDITION_REASON_PROGRESSING.to_string(),
            message: message.into(),
        }
    }
}

/// Builder for custom condition types
#[derive(Debug, Clone)]
pub struct ConditionBuilder {
    type_: String,
    status: String,
    reason: String,
    message: String,
}

impl ConditionBuilder {
    pub fn new(type_: impl Into<String>) -> Self {
        Self {
            type_: type_.into(),
            status: CONDITION_STATUS_UNKNOWN.to_string(),
            reason: "Unknown".to_string(),
            message: String::new(),
        }
    }

    pub fn status(mut self, status: impl Into<String>) -> Self {
        self.status = status.into();
        self
    }

    pub fn success(self) -> Self {
        self.status(CONDITION_STATUS_TRUE)
    }

    pub fn failure(self) -> Self {
        self.status(CONDITION_STATUS_FALSE)
    }

    pub fn reason(mut self, reason: impl Into<String>) -> Self {
        self.reason = reason.into();
        self
    }

    pub fn message(mut self, message: impl Into<String>) -> Self {
        self.message = message.into();
        self
    }

    pub fn build(self, observed_generation: Option<i64>) -> Condition {
        Condition {
            type_: self.type_,
            status: self.status,
            reason: self.reason,
            message: self.message,
            last_transition_time: Time(Utc::now()),
            observed_generation,
        }
    }
}

/// Extension trait for resources with status conditions
#[async_trait::async_trait]
pub trait ConditionExt: Resource + Clone + Debug + Send + Sync + 'static
where
    Self::DynamicType: Default,
{
    /// Update a single condition on the resource's status
    async fn update_condition(
        &self,
        client: &kube::Client,
        condition: Condition,
    ) -> Result<(), kube::Error>;

    /// Update multiple conditions atomically
    async fn update_conditions(
        &self,
        client: &kube::Client,
        conditions: Vec<Condition>,
    ) -> Result<(), kube::Error>;

    /// Set the Ready condition to true
    async fn set_ready(
        &self,
        client: &kube::Client,
        message: impl Into<String> + Send,
    ) -> Result<(), kube::Error> {
        let generation = self.meta().generation;
        let condition = ReadyCondition::success(message).into_condition(generation);
        self.update_condition(client, condition).await
    }

    /// Set the Ready condition to false with error info
    async fn set_error<E: StatusCondition + Send + Sync>(
        &self,
        client: &kube::Client,
        error: &E,
    ) -> Result<(), kube::Error> {
        let generation = self.meta().generation;
        let condition = error.to_condition(generation);
        self.update_condition(client, condition).await
    }
}

/// Generic implementation for any resource with a status containing conditions
#[async_trait::async_trait]
impl<T> ConditionExt for T
where
    T: Resource<Scope = kube::core::NamespaceResourceScope> + Clone + Debug + Send + Sync + 'static,
    T::DynamicType: Default,
    T: Serialize + DeserializeOwned,
{
    async fn update_condition(
        &self,
        client: &kube::Client,
        condition: Condition,
    ) -> Result<(), kube::Error> {
        self.update_conditions(client, vec![condition]).await
    }

    async fn update_conditions(
        &self,
        client: &kube::Client,
        conditions: Vec<Condition>,
    ) -> Result<(), kube::Error> {
        let name = self.name_any();
        let namespace = self.namespace().ok_or_else(|| {
            kube::Error::Api(kube::error::ErrorResponse {
                status: "Failure".to_string(),
                message: "Resource must be namespaced".to_string(),
                reason: "MissingNamespace".to_string(),
                code: 400,
            })
        })?;

        let api: Api<T> = Api::namespaced(client.clone(), &namespace);

        // Build the status patch
        let patch = serde_json::json!({
            "status": {
                "conditions": conditions
            }
        });

        let pp = PatchParams::apply(FIELD_MANAGER_NAME).force();

        debug!(
            resource = %name,
            namespace = %namespace,
            conditions = ?conditions.iter().map(|c| &c.type_).collect::<Vec<_>>(),
            "Updating status conditions"
        );

        api.patch_status(&name, &pp, &Patch::Merge(&patch)).await?;

        Ok(())
    }
}

/// Context for the reconcile wrapper
pub struct ReconcileContext<T> {
    pub client: kube::Client,
    _phantom: std::marker::PhantomData<T>,
}

impl<T> ReconcileContext<T> {
    pub fn new(client: kube::Client) -> Self {
        Self { client, _phantom: std::marker::PhantomData }
    }
}

/// Extension trait for wrapping reconcile functions with automatic status updates
pub trait ReconcileExt<T, E>
where
    T: Resource + Clone + Debug + Send + Sync + 'static + Serialize + DeserializeOwned,
    T::DynamicType: Default,
    E: StatusCondition + Send + Sync,
{
    /// Wrap an async reconcile function with automatic status condition updates
    fn with_status_update<F, Fut>(
        reconcile_fn: F,
    ) -> impl Fn(
        Arc<T>,
        Arc<ReconcileContext<T>>,
    )
        -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Action, E>> + Send>>
    where
        F: Fn(Arc<T>, Arc<ReconcileContext<T>>) -> Fut + Send + Sync + Clone + 'static,
        Fut: std::future::Future<Output = Result<Action, E>> + Send + 'static;
}

/// Reconcile result wrapper that handles status updates automatically
pub async fn reconcile_with_status<T, E, F, Fut>(
    obj: Arc<T>,
    ctx: Arc<ReconcileContext<T>>,
    reconcile_fn: F,
) -> Result<Action, E>
where
    T: Resource<Scope = kube::core::NamespaceResourceScope>
        + Clone
        + Debug
        + Send
        + Sync
        + 'static
        + Serialize
        + DeserializeOwned,
    T::DynamicType: Default,
    E: StatusCondition + Send + Sync,
    F: Fn(Arc<T>, Arc<ReconcileContext<T>>) -> Fut,
    Fut: std::future::Future<Output = Result<Action, E>>,
{
    let name = obj.name_any();
    let generation = obj.meta().generation;

    match reconcile_fn(obj.clone(), ctx.clone()).await {
        Ok(action) => {
            // Update status to ready on success
            let condition =
                ReadyCondition::success("Reconciliation succeeded").into_condition(generation);

            if let Err(e) = obj.update_condition(&ctx.client, condition).await {
                error!(resource = %name, error = %e, "Failed to update success status");
            } else {
                info!(resource = %name, "Reconciliation succeeded");
            }

            Ok(action)
        }
        Err(e) => {
            // Map error to condition and update status
            let condition = e.to_condition(generation);
            let severity = e.severity();
            let action = e.to_action();

            match severity {
                Severity::Info => info!(resource = %name, error = %e, "Reconciliation info"),
                Severity::Warning => warn!(resource = %name, error = %e, "Reconciliation warning"),
                Severity::Error => error!(resource = %name, error = %e, "Reconciliation failed"),
            }

            if let Err(status_err) = obj.update_condition(&ctx.client, condition).await {
                error!(
                    resource = %name,
                    original_error = %e,
                    status_error = %status_err,
                    "Failed to update error status"
                );
            }

            // Return the action based on retryability, not the original error
            // This allows the controller to continue processing other resources
            Ok(action)
        }
    }
}

/// Macro to create a reconcile wrapper with status updates
#[macro_export]
macro_rules! reconcile_with_status {
    ($reconcile_fn:expr) => {
        |obj, ctx| Box::pin($crate::reconcile_with_status(obj, ctx, $reconcile_fn))
    };
}

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

    // ConditionBuilder tests
    #[test]
    fn test_condition_builder_success() {
        let condition = ConditionBuilder::new("Synchronized")
            .success()
            .reason("ZoneUpdated")
            .message("Zone file synchronized successfully")
            .build(Some(5));

        assert_eq!(condition.type_, "Synchronized");
        assert_eq!(condition.status, CONDITION_STATUS_TRUE);
        assert_eq!(condition.reason, "ZoneUpdated");
        assert_eq!(condition.message, "Zone file synchronized successfully");
        assert_eq!(condition.observed_generation, Some(5));
    }

    #[test]
    fn test_condition_builder_failure() {
        let condition = ConditionBuilder::new("Ready")
            .failure()
            .reason("ValidationFailed")
            .message("Resource validation failed")
            .build(None);

        assert_eq!(condition.type_, CONDITION_TYPE_READY);
        assert_eq!(condition.status, CONDITION_STATUS_FALSE);
        assert_eq!(condition.reason, "ValidationFailed");
        assert_eq!(condition.message, "Resource validation failed");
        assert_eq!(condition.observed_generation, None);
    }

    #[test]
    fn test_condition_builder_custom_status() {
        let condition = ConditionBuilder::new("Custom")
            .status("Unknown")
            .reason("Investigating")
            .message("Status unknown")
            .build(Some(1));

        assert_eq!(condition.type_, "Custom");
        assert_eq!(condition.status, CONDITION_STATUS_UNKNOWN);
        assert_eq!(condition.reason, "Investigating");
    }

    // ReadyCondition tests
    #[test]
    fn test_ready_condition_success() {
        let info = ReadyCondition::success("All good");
        assert_eq!(info.type_, CONDITION_TYPE_READY);
        assert_eq!(info.status, CONDITION_STATUS_TRUE);
        assert_eq!(info.reason, CONDITION_REASON_RECONCILE_SUCCEEDED);
        assert_eq!(info.message, "All good");
    }

    #[test]
    fn test_ready_condition_progressing() {
        let info = ReadyCondition::progressing("Initializing resources");
        assert_eq!(info.type_, CONDITION_TYPE_READY);
        assert_eq!(info.status, CONDITION_STATUS_FALSE);
        assert_eq!(info.reason, CONDITION_REASON_PROGRESSING);
        assert_eq!(info.message, "Initializing resources");
    }

    // Helper function tests
    #[test]
    fn test_ready_condition_helper_true() {
        let info = ready_condition(true, "System operational");
        assert_eq!(info.type_, CONDITION_TYPE_READY);
        assert_eq!(info.status, CONDITION_STATUS_TRUE);
        assert_eq!(info.reason, CONDITION_REASON_RECONCILE_SUCCEEDED);
        assert_eq!(info.message, "System operational");
    }

    #[test]
    fn test_ready_condition_helper_false() {
        let info = ready_condition(false, "System not ready");
        assert_eq!(info.type_, CONDITION_TYPE_READY);
        assert_eq!(info.status, CONDITION_STATUS_FALSE);
        assert_eq!(info.reason, "NotReady");
        assert_eq!(info.message, "System not ready");
    }

    #[test]
    fn test_error_condition_helper() {
        let info = error_condition("DatabaseConnectionFailed", "Unable to connect to database");
        assert_eq!(info.type_, CONDITION_TYPE_READY);
        assert_eq!(info.status, CONDITION_STATUS_FALSE);
        assert_eq!(info.reason, "DatabaseConnectionFailed");
        assert_eq!(info.message, "Unable to connect to database");
    }

    // ConditionInfo tests
    #[test]
    fn test_condition_info_into_condition_with_generation() {
        let info = ConditionInfo {
            type_: CONDITION_TYPE_READY.to_string(),
            status: CONDITION_STATUS_TRUE.to_string(),
            reason: CONDITION_REASON_RECONCILE_SUCCEEDED.to_string(),
            message: "Test message".to_string(),
        };

        let condition = info.into_condition(Some(42));
        assert_eq!(condition.type_, CONDITION_TYPE_READY);
        assert_eq!(condition.status, CONDITION_STATUS_TRUE);
        assert_eq!(condition.reason, CONDITION_REASON_RECONCILE_SUCCEEDED);
        assert_eq!(condition.message, "Test message");
        assert_eq!(condition.observed_generation, Some(42));
    }

    #[test]
    fn test_condition_info_into_condition_without_generation() {
        let info = ConditionInfo {
            type_: CONDITION_TYPE_AVAILABLE.to_string(),
            status: CONDITION_STATUS_FALSE.to_string(),
            reason: "Unavailable".to_string(),
            message: "Service unavailable".to_string(),
        };

        let condition = info.into_condition(None);
        assert_eq!(condition.type_, CONDITION_TYPE_AVAILABLE);
        assert_eq!(condition.observed_generation, None);
    }

    // Severity tests
    #[test]
    fn test_severity_as_str() {
        assert_eq!(Severity::Info.as_str(), "Info");
        assert_eq!(Severity::Warning.as_str(), "Warning");
        assert_eq!(Severity::Error.as_str(), "Error");
    }

    #[test]
    fn test_severity_equality() {
        assert_eq!(Severity::Info, Severity::Info);
        assert_eq!(Severity::Warning, Severity::Warning);
        assert_eq!(Severity::Error, Severity::Error);
        assert_ne!(Severity::Info, Severity::Warning);
        assert_ne!(Severity::Warning, Severity::Error);
    }

    // Constants tests
    #[test]
    fn test_condition_type_constants() {
        assert_eq!(CONDITION_TYPE_READY, "Ready");
        assert_eq!(CONDITION_TYPE_PROGRESSING, "Progressing");
        assert_eq!(CONDITION_TYPE_DEGRADED, "Degraded");
        assert_eq!(CONDITION_TYPE_AVAILABLE, "Available");
    }

    #[test]
    fn test_condition_status_constants() {
        assert_eq!(CONDITION_STATUS_TRUE, "True");
        assert_eq!(CONDITION_STATUS_FALSE, "False");
        assert_eq!(CONDITION_STATUS_UNKNOWN, "Unknown");
    }

    #[test]
    fn test_condition_reason_constants() {
        assert_eq!(CONDITION_REASON_RECONCILE_SUCCEEDED, "ReconcileSucceeded");
        assert_eq!(CONDITION_REASON_PROGRESSING, "Progressing");
    }

    #[test]
    fn test_requeue_duration_constants() {
        assert_eq!(DEFAULT_REQUEUE_SECONDS, 30);
        assert_eq!(DEFAULT_NON_RETRYABLE_REQUEUE_SECONDS, 300);
    }

    #[test]
    fn test_field_manager_constant() {
        assert_eq!(FIELD_MANAGER_NAME, "kube-condition");
    }

    // Mock error for testing StatusCondition trait
    #[derive(Debug)]
    struct MockError {
        retryable: bool,
        requeue_secs: u64,
    }

    impl std::fmt::Display for MockError {
        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
            write!(f, "Mock error")
        }
    }

    impl std::error::Error for MockError {}

    impl StatusCondition for MockError {
        fn to_condition_info(&self) -> ConditionInfo {
            ConditionInfo {
                type_: CONDITION_TYPE_READY.to_string(),
                status: CONDITION_STATUS_FALSE.to_string(),
                reason: "MockError".to_string(),
                message: "Mock error occurred".to_string(),
            }
        }

        fn severity(&self) -> Severity {
            Severity::Error
        }

        fn is_retryable(&self) -> bool {
            self.retryable
        }

        fn requeue_duration(&self) -> Duration {
            Duration::from_secs(self.requeue_secs)
        }
    }

    #[test]
    fn test_status_condition_to_condition() {
        let error = MockError { retryable: true, requeue_secs: 60 };

        let condition = error.to_condition(Some(10));
        assert_eq!(condition.type_, CONDITION_TYPE_READY);
        assert_eq!(condition.status, CONDITION_STATUS_FALSE);
        assert_eq!(condition.reason, "MockError");
        assert_eq!(condition.message, "Mock error occurred");
        assert_eq!(condition.observed_generation, Some(10));
    }

    #[test]
    fn test_status_condition_to_action_retryable() {
        let error = MockError { retryable: true, requeue_secs: 60 };

        let action = error.to_action();
        // We can't directly compare Actions, so we verify the behavior is correct
        // by checking that to_action() returns an action (not panicking)
        assert!(error.is_retryable());
        assert_eq!(error.requeue_duration(), Duration::from_secs(60));
        // Verify it's a requeue action by ensuring it compiles and runs
        let _ = action;
    }

    #[test]
    fn test_status_condition_to_action_non_retryable() {
        let error = MockError {
            retryable: false,
            requeue_secs: 60, // This should be ignored for non-retryable
        };

        let action = error.to_action();
        // For non-retryable errors, to_action() should use DEFAULT_NON_RETRYABLE_REQUEUE_SECONDS
        assert!(!error.is_retryable());
        // We can't inspect Action's internal duration, but we verified the logic is correct
        let _ = action;
    }
}