ansible-rs 1.1.0

//! Comprehensive error handling for Ansible operations.
//!
//! This module provides detailed error types for different failure modes
//! that can occur when working with Ansible commands and operations.

use thiserror::Error;

/// Comprehensive error types for Ansible operations.
///
/// The `AnsibleError` enum provides detailed error information for different
/// types of failures that can occur when executing Ansible commands, managing
/// configurations, or working with inventories.
///
/// # Examples
///
/// ## Error Handling
///
/// ```rust,no_run
/// use ansible::{Ansible, AnsibleError};
///
/// let result = Ansible::default().ping();
/// match result {
///     Ok(output) => println!("Success: {}", output),
///     Err(AnsibleError::CommandFailed { message, exit_code, stdout, stderr }) => {
///         eprintln!("Command failed: {}", message);
///         if let Some(code) = exit_code {
///             eprintln!("Exit code: {}", code);
///         }
///         if let Some(stderr) = stderr {
///             eprintln!("Error output: {}", stderr);
///         }
///     }
///     Err(AnsibleError::UnsupportedPlatform(msg)) => {
///         eprintln!("Platform not supported: {}", msg);
///     }
///     Err(e) => eprintln!("Other error: {}", e),
/// }
/// ```
///
/// ## Error Construction
///
/// ```rust
/// use ansible::AnsibleError;
///
/// // Create specific error types
/// let cmd_error = AnsibleError::command_failed(
///     "ansible ping failed",
///     Some(1),
///     Some("output".to_string()),
///     Some("error".to_string())
/// );
///
/// let platform_error = AnsibleError::unsupported_platform("Windows not supported");
/// ```
#[derive(Error, Debug)]
pub enum AnsibleError {
    /// I/O operation failed
    #[error("I/O operation failed: {0}")]
    Io(#[from] std::io::Error),

    /// Ansible command execution failed
    #[error("Ansible command execution failed: {message}")]
    CommandFailed {
        message: String,
        exit_code: Option<i32>,
        stdout: Option<String>,
        stderr: Option<String>,
    },

    /// Invalid module configuration
    #[error("Invalid module configuration: {0}")]
    InvalidModule(String),

    /// Invalid inventory configuration
    #[error("Invalid inventory configuration: {0}")]
    InvalidInventory(String),

    /// Playbook parsing or execution error
    #[error("Playbook error: {0}")]
    PlaybookError(String),

    /// Environment variable error
    #[error("Environment variable error: {0}")]
    EnvironmentError(String),

    /// Configuration error
    #[error("Configuration error: {0}")]
    ConfigError(String),

    /// Unsupported platform error
    #[error("Unsupported platform: {0}")]
    UnsupportedPlatform(String),

    /// Command not found error
    #[error("Command not found: {0}")]
    CommandNotFound(String),

    /// System requirement not met
    #[error("System requirement not met: {0}")]
    SystemRequirement(String),

    /// Unknown error
    #[error("Unknown error occurred")]
    Unknown,
}

impl AnsibleError {
    /// Create a command failed error with detailed information
    pub fn command_failed(
        message: impl Into<String>,
        exit_code: Option<i32>,
        stdout: Option<String>,
        stderr: Option<String>,
    ) -> Self {
        Self::CommandFailed {
            message: message.into(),
            exit_code,
            stdout,
            stderr,
        }
    }

    /// Create an invalid module error
    pub fn invalid_module(message: impl Into<String>) -> Self {
        Self::InvalidModule(message.into())
    }

    /// Create an invalid inventory error
    pub fn invalid_inventory(message: impl Into<String>) -> Self {
        Self::InvalidInventory(message.into())
    }

    /// Create a playbook error
    pub fn playbook_error(message: impl Into<String>) -> Self {
        Self::PlaybookError(message.into())
    }

    /// Create an environment error
    pub fn environment_error(message: impl Into<String>) -> Self {
        Self::EnvironmentError(message.into())
    }

    /// Create a configuration error
    pub fn config_error(message: impl Into<String>) -> Self {
        Self::ConfigError(message.into())
    }

    /// Create an unsupported platform error
    pub fn unsupported_platform(message: impl Into<String>) -> Self {
        Self::UnsupportedPlatform(message.into())
    }

    /// Create a command not found error
    pub fn command_not_found(message: impl Into<String>) -> Self {
        Self::CommandNotFound(message.into())
    }

    /// Create a system requirement error
    pub fn system_requirement(message: impl Into<String>) -> Self {
        Self::SystemRequirement(message.into())
    }

    /// Create a parsing failed error
    pub fn parsing_failed(message: impl Into<String>) -> Self {
        Self::ConfigError(message.into())
    }

    /// Create an IO error
    pub fn io_error(message: impl Into<String>) -> Self {
        Self::ConfigError(message.into())
    }
}

/// Type alias for Results with AnsibleError
pub type Result<T> = std::result::Result<T, AnsibleError>;