ansible-rs 1.1.0

//! Ansible playbook execution and management.
//!
//! This module provides the [`Playbook`] struct for executing Ansible playbooks
//! and the [`Play`] enum for representing different types of playbook content.

use crate::command_config::CommandConfig;
use crate::errors::{AnsibleError, Result};
use std::ffi::OsStr;
use std::fmt::{Display, Formatter};
use std::io::Write;
use std::process;

/// Ansible playbook executor with comprehensive configuration options.
///
/// The `Playbook` struct provides a fluent interface for configuring and executing
/// Ansible playbooks. It supports all major ansible-playbook command-line options
/// and provides type-safe configuration.
///
/// # Examples
///
/// ## Basic Playbook Execution
///
/// ```rust,no_run
/// use ansible::{Playbook, Play};
///
/// let mut playbook = Playbook::default();
/// playbook.set_inventory("hosts.yml");
///
/// // Run from file
/// let result = playbook.run(Play::from_file("site.yml"))?;
/// println!("Playbook result: {}", result);
/// # Ok::<(), ansible::AnsibleError>(())
/// ```
///
/// ## Advanced Configuration
///
/// ```rust,no_run
/// use ansible::{Playbook, Play};
///
/// let mut playbook = Playbook::default();
/// playbook
///     .set_inventory("production")
///     .set_verbosity(2)
///     .add_extra_var("env", "production")
///     .add_extra_var("version", "1.2.3")
///     .add_tag("deploy")
///     .add_tag("config")
///     .set_check_mode(true);
///
/// let result = playbook.run(Play::from_file("deploy.yml"))?;
/// # Ok::<(), ansible::AnsibleError>(())
/// ```
///
/// ## Environment Configuration
///
/// ```rust,no_run
/// use ansible::Playbook;
///
/// let mut playbook = Playbook::default();
/// playbook
///     .set_system_envs()
///     .filter_envs(["HOME", "PATH", "USER"])
///     .add_env("ANSIBLE_HOST_KEY_CHECKING", "False")
///     .add_env("ANSIBLE_STDOUT_CALLBACK", "json");
/// # Ok::<(), ansible::AnsibleError>(())
/// ```
#[derive(Debug, Clone)]
pub struct Playbook {
    pub(crate) command: String,
    pub(crate) cfg: CommandConfig,
    pub(crate) inventory: Option<String>,
}

impl Default for Playbook {
    fn default() -> Self {
        Self {
            command: "ansible-playbook".into(),
            cfg: CommandConfig::default(),
            inventory: None,
        }
    }
}

impl Display for Playbook {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.command)?;

        if let Some(ref inventory) = self.inventory {
            if !inventory.is_empty() {
                write!(f, " -i {}", inventory)?;
            }
        }

        if !self.cfg.args.is_empty() {
            write!(f, " {}", self.cfg.args.join(" "))?;
        }

        Ok(())
    }
}

impl Playbook {
    /// Set environment variables from the current system environment.
    ///
    /// This method copies all environment variables from the current process
    /// to be passed to the ansible-playbook command.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Playbook;
    ///
    /// let mut playbook = Playbook::default();
    /// playbook.set_system_envs();
    /// ```
    pub fn set_system_envs(&mut self) -> &mut Self {
        self.cfg.set_system_envs();
        self
    }

    /// Filter environment variables to only include specified keys.
    ///
    /// This method is useful for limiting which environment variables
    /// are passed to ansible-playbook commands.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Playbook;
    ///
    /// let mut playbook = Playbook::default();
    /// playbook
    ///     .set_system_envs()
    ///     .filter_envs(["HOME", "PATH", "USER"]);
    /// ```
    pub fn filter_envs<T, S>(&mut self, iter: T) -> &mut Self
    where
        T: IntoIterator<Item = S>,
        S: AsRef<OsStr> + Display,
    {
        self.cfg.filter_envs(iter);
        self
    }

    /// Add a single environment variable.
    ///
    /// This method adds or overwrites an environment variable that will
    /// be passed to the ansible-playbook command.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Playbook;
    ///
    /// let mut playbook = Playbook::default();
    /// playbook
    ///     .add_env("ANSIBLE_HOST_KEY_CHECKING", "False")
    ///     .add_env("ANSIBLE_STDOUT_CALLBACK", "json");
    /// ```
    pub fn add_env(&mut self, key: impl Into<String>, value: impl Into<String>) -> &mut Self {
        self.cfg.add_env(key, value);
        self
    }

    /// Add a single command-line argument.
    ///
    /// This method adds a raw command-line argument to the ansible-playbook command.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Playbook;
    ///
    /// let mut playbook = Playbook::default();
    /// playbook
    ///     .arg("--verbose")
    ///     .arg("--check");
    /// ```
    pub fn arg<S: AsRef<OsStr> + Display>(&mut self, arg: S) -> &mut Self {
        self.cfg.args.push(arg.to_string());
        self
    }

    /// Add multiple command-line arguments.
    ///
    /// This method adds multiple raw command-line arguments to the ansible-playbook command.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Playbook;
    ///
    /// let mut playbook = Playbook::default();
    /// playbook.args(["--verbose", "--check", "--diff"]);
    /// ```
    pub fn args<T, S>(&mut self, args: T) -> &mut Self
    where
        T: IntoIterator<Item = S>,
        S: AsRef<OsStr> + Display,
    {
        for arg in args {
            self.arg(arg);
        }
        self
    }

    /// Set the inventory file or directory.
    ///
    /// This method specifies the inventory file or directory to use
    /// for host and group information.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Playbook;
    ///
    /// let mut playbook = Playbook::default();
    /// playbook.set_inventory("hosts.yml");
    /// playbook.set_inventory("/etc/ansible/hosts");
    /// playbook.set_inventory("production");
    /// ```
    pub fn set_inventory(&mut self, s: &str) -> &mut Self {
        self.inventory = Some(s.to_string());
        self
    }

    /// Configure output to use JSON format.
    ///
    /// This method sets environment variables to configure ansible-playbook
    /// to output results in JSON format.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Playbook;
    ///
    /// let mut playbook = Playbook::default();
    /// playbook.set_output_json();
    /// ```
    pub fn set_output_json(&mut self) -> &mut Self {
        self.cfg
            .add_env("ANSIBLE_STDOUT_CALLBACK", "json")
            .add_env("ANSIBLE_LOAD_CALLBACK_PLUGINS", "True");
        self
    }

    /// Set the verbosity level for playbook execution.
    ///
    /// This method sets the verbosity level for ansible-playbook output.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Playbook;
    ///
    /// let mut playbook = Playbook::default();
    /// playbook.set_verbosity(2); // -vv
    /// ```
    pub fn set_verbosity(&mut self, level: u8) -> &mut Self {
        let verbose_arg = format!("-{}", "v".repeat(level as usize));
        self.arg(verbose_arg);
        self
    }

    /// Add an extra variable for playbook execution.
    ///
    /// This method adds extra variables that will be passed to the playbook.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Playbook;
    ///
    /// let mut playbook = Playbook::default();
    /// playbook
    ///     .add_extra_var("env", "production")
    ///     .add_extra_var("version", "1.2.3");
    /// ```
    pub fn add_extra_var(&mut self, key: impl Into<String>, value: impl Into<String>) -> &mut Self {
        let var_string = format!("{}={}", key.into(), value.into());
        self.arg("--extra-vars").arg(var_string);
        self
    }

    /// Add a tag to limit playbook execution.
    ///
    /// This method adds tags to limit which tasks are executed.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Playbook;
    ///
    /// let mut playbook = Playbook::default();
    /// playbook
    ///     .add_tag("deploy")
    ///     .add_tag("config");
    /// ```
    pub fn add_tag(&mut self, tag: impl Into<String>) -> &mut Self {
        self.arg("--tags").arg(tag.into());
        self
    }

    /// Enable check mode (dry run).
    ///
    /// This method enables check mode for the playbook execution.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Playbook;
    ///
    /// let mut playbook = Playbook::default();
    /// playbook.set_check_mode(true);
    /// ```
    pub fn set_check_mode(&mut self, enabled: bool) -> &mut Self {
        if enabled {
            self.arg("--check");
        }
        self
    }

    /// Execute an Ansible playbook.
    ///
    /// This method executes an Ansible playbook from either a file or string content.
    /// It handles temporary file creation for string content and cleanup afterwards.
    ///
    /// # Arguments
    ///
    /// * `play` - The playbook source (file path or content)
    ///
    /// # Returns
    ///
    /// Returns the combined stdout and stderr output from the ansible-playbook command.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The playbook file cannot be read or created
    /// - The ansible-playbook command fails to execute
    /// - The command returns a non-zero exit code
    ///
    /// # Examples
    ///
    /// ## Running from File
    ///
    /// ```rust,no_run
    /// use ansible::{Playbook, Play};
    ///
    /// let mut playbook = Playbook::default();
    /// playbook.set_inventory("hosts.yml");
    ///
    /// let result = playbook.run(Play::from_file("site.yml"))?;
    /// println!("Playbook result: {}", result);
    /// # Ok::<(), ansible::AnsibleError>(())
    /// ```
    ///
    /// ## Running from Content
    ///
    /// ```rust,no_run
    /// use ansible::{Playbook, Play};
    ///
    /// let yaml_content = r#"
    /// - hosts: all
    ///   tasks:
    ///     - name: Ensure nginx is installed
    ///       package:
    ///         name: nginx
    ///         state: present
    /// "#;
    ///
    /// let mut playbook = Playbook::default();
    /// let result = playbook.run(Play::from_content(yaml_content))?;
    /// # Ok::<(), ansible::AnsibleError>(())
    /// ```
    pub fn run(&self, play: Play) -> Result<String> {
        let (playbook_path, is_temp) = match play {
            Play::File(path) => (path, false),
            Play::Content(content) => {
                let temp_dir = std::env::temp_dir();
                let temp_file = temp_dir.join("ansible_playbook.yaml");
                let mut f = std::fs::File::create(&temp_file)?;
                write!(f, "{}", content)?;
                (temp_file.to_string_lossy().to_string(), true)
            }
        };
        let full_cmd = self.to_string();
        let cmd_vec: Vec<&str> = full_cmd.split_whitespace().collect();
        let mut cmd = process::Command::new(&self.command);
        cmd.envs(&self.cfg.envs);
        cmd.args(&cmd_vec.as_slice()[1..]);
        cmd.args(&self.cfg.args);
        cmd.arg(&playbook_path);
        let output = cmd.output()?;

        if !output.status.success() {
            let stdout = String::from_utf8_lossy(&output.stdout).to_string();
            let stderr = String::from_utf8_lossy(&output.stderr).to_string();
            return Err(AnsibleError::command_failed(
                "Ansible playbook execution failed",
                output.status.code(),
                Some(stdout),
                Some(stderr),
            ));
        }

        let result = [output.stdout, "\n".as_bytes().to_vec(), output.stderr].concat();
        let output_str = String::from_utf8_lossy(&result).to_string();

        // Clean up temporary file if it was created
        if is_temp {
            std::fs::remove_file(&playbook_path)?;
        }

        Ok(output_str)
    }
}

/// Represents different sources of playbook content.
///
/// The `Play` enum allows you to specify playbook content either from
/// a file on disk or from a string containing YAML content.
///
/// # Examples
///
/// ## From File
///
/// ```rust
/// use ansible::Play;
///
/// let play = Play::from_file("site.yml");
/// let play = Play::from_file("/path/to/playbook.yml");
/// ```
///
/// ## From Content
///
/// ```rust
/// use ansible::Play;
///
/// let yaml_content = r#"
/// - hosts: all
///   tasks:
///     - name: Ensure nginx is installed
///       package:
///         name: nginx
///         state: present
/// "#;
///
/// let play = Play::from_content(yaml_content);
/// ```
#[derive(Debug, Clone)]
pub enum Play {
    /// Playbook content loaded from a file path
    ///
    /// The file should contain valid YAML playbook content.
    File(String),

    /// Playbook content provided as a string
    ///
    /// The string should contain valid YAML playbook content.
    Content(String),
}

impl Play {
    /// Create a Play from a file path.
    ///
    /// This method creates a Play that will read playbook content from
    /// the specified file when executed.
    ///
    /// # Arguments
    ///
    /// * `path` - Path to the playbook file (relative or absolute)
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Play;
    ///
    /// let play = Play::from_file("site.yml");
    /// let play = Play::from_file("/path/to/playbook.yml");
    /// let play = Play::from_file("playbooks/deploy.yml");
    /// ```
    pub fn from_file(path: impl Into<String>) -> Self {
        Play::File(path.into())
    }

    /// Create a Play from string content.
    ///
    /// This method creates a Play from YAML content provided as a string.
    /// The content will be written to a temporary file when executed.
    ///
    /// # Arguments
    ///
    /// * `content` - YAML playbook content as a string
    ///
    /// # Examples
    ///
    /// ```rust
    /// use ansible::Play;
    ///
    /// let yaml_content = r#"
    /// - hosts: all
    ///   become: yes
    ///   tasks:
    ///     - name: Update package cache
    ///       apt:
    ///         update_cache: yes
    ///       when: ansible_os_family == "Debian"
    ///
    ///     - name: Install essential packages
    ///       package:
    ///         name:
    ///           - curl
    ///           - wget
    ///           - git
    ///         state: present
    /// "#;
    ///
    /// let play = Play::from_content(yaml_content);
    /// ```
    pub fn from_content(content: impl Into<String>) -> Self {
        Play::Content(content.into())
    }
}