ansible/

lib.rs

//! # Ansible-rs
//!
//! A modern, type-safe Rust wrapper library for Ansible command-line tools.
//!
//! This library provides a safe, ergonomic interface for executing Ansible commands,
//! playbooks, and managing Ansible configurations from Rust applications. It supports
//! all major Ansible tools including `ansible`, `ansible-playbook`, `ansible-vault`,
//! `ansible-config`, and `ansible-inventory`.
//!
//! ## Features
//!
//! - **🔒 Type-safe** - Leverages Rust's type system to prevent common configuration errors
//! - **🚀 Modern API** - Uses builder patterns and fluent interfaces for ergonomic usage
//! - **🛡️ Comprehensive error handling** - Detailed error types for different failure modes
//! - **⚡ Memory efficient** - Optimized for minimal allocations and clones
//! - **🔧 Smart build system** - Automatic Ansible detection and installation during build
//! - **🌍 Cross-platform** - Supports Linux, macOS, and BSD systems
//! - **📚 Rust 2024 edition** - Uses the latest Rust features and idioms
//! - **🧪 100% test coverage** - Comprehensive test suite with property-based testing
//!
//! ## System Requirements
//!
//! - **Supported platforms**: Linux, macOS, FreeBSD, OpenBSD, NetBSD
//! - **Ansible**: Version 2.9 or higher (automatically detected and installed)
//! - **Python**: Version 3.6 or higher (required by Ansible)
//!
//! The build script will automatically detect and attempt to install Ansible if not present.
//! See the [installation guide](https://docs.ansible.com/ansible/latest/installation_guide/) for manual installation.
//!
//! ## Quick Start
//!
//! ### Basic Ansible Commands
//!
//! ```rust,no_run
//! use ansible::{Ansible, Module};
//!
//! let mut ansible = Ansible::default();
//! ansible
//!     .set_system_envs()
//!     .filter_envs(["HOME", "PATH"])
//!     .add_host("all")
//!     .set_inventory("./hosts");
//!
//! // Execute a ping
//! let result = ansible.ping()?;
//! println!("Ping result: {}", result);
//!
//! // Execute a shell command
//! let result = ansible.shell("uptime")?;
//! println!("Uptime: {}", result);
//! # Ok::<(), ansible::AnsibleError>(())
//! ```
//!
//! ### Playbook Execution
//!
//! ```rust,no_run
//! use ansible::{Playbook, Play};
//!
//! let mut playbook = Playbook::default();
//! playbook.set_inventory("./hosts");
//!
//! // Run from file
//! let result = playbook.run(Play::from_file("site.yml"))?;
//! println!("Playbook result: {}", result);
//!
//! // Run from string content
//! let yaml_content = r#"
//! ---
//! - hosts: all
//!   tasks:
//!     - name: Ensure nginx is installed
//!       package:
//!         name: nginx
//!         state: present
//! "#;
//! let result = playbook.run(Play::from_content(yaml_content))?;
//! # Ok::<(), ansible::AnsibleError>(())
//! ```
//!
//! ### Ansible Vault Operations
//!
//! Manage encrypted files and strings with Ansible Vault:
//!
//! ```rust,no_run
//! use ansible::AnsibleVault;
//!
//! let mut vault = AnsibleVault::new();
//! vault.set_vault_password_file("vault_pass.txt");
//!
//! // Encrypt a file
//! vault.encrypt("secrets.yml")?;
//!
//! // Decrypt a file
//! vault.decrypt("secrets.yml")?;
//!
//! // Encrypt a string
//! let encrypted = vault.encrypt_string("my_secret_password")?;
//! println!("Encrypted: {}", encrypted);
//! # Ok::<(), ansible::AnsibleError>(())
//! ```
//!
//! ### Configuration Management
//!
//! Query and manage Ansible configuration:
//!
//! ```rust,no_run
//! use ansible::{AnsibleConfig, ConfigFormat, PluginType};
//!
//! let mut config = AnsibleConfig::new();
//!
//! // List all configuration options
//! let config_list = config.list()?;
//! println!("Configuration: {}", config_list);
//!
//! // Dump configuration in JSON format
//! config.set_format(ConfigFormat::Json);
//! let config_dump = config.dump()?;
//! println!("Config dump: {}", config_dump);
//!
//! // List specific plugin types
//! config.set_plugin_type(PluginType::Callback);
//! let callbacks = config.list()?;
//! # Ok::<(), ansible::AnsibleError>(())
//! ```
//!
//! ### Inventory Management
//!
//! Parse and query Ansible inventories:
//!
//! ```rust,no_run
//! use ansible::{AnsibleInventory, InventoryFormat};
//!
//! let mut inventory = AnsibleInventory::new();
//! inventory
//!     .set_inventory("hosts.yml")
//!     .set_format(InventoryFormat::Json);
//!
//! // List all hosts
//! let hosts = inventory.list()?;
//! println!("Hosts: {}", hosts);
//!
//! // Get specific host information
//! let host_info = inventory.host("web01")?;
//! println!("Host info: {}", host_info);
//!
//! // Parse inventory data
//! let inventory_data = inventory.parse_inventory_data()?;
//! for (group_name, group) in &inventory_data.groups {
//!     println!("Group {}: {} hosts", group_name, group.hosts.len());
//! }
//! # Ok::<(), ansible::AnsibleError>(())
//! ```
//!
//! ### System Requirements Validation
//!
//! Check system compatibility and Ansible installation:
//!
//! ```rust,no_run
//! use ansible::{validate_system, get_system_info, PlatformValidator};
//!
//! // Quick validation
//! validate_system()?;
//!
//! // Detailed system information
//! let system_info = get_system_info()?;
//! println!("{}", system_info);
//!
//! if system_info.is_fully_supported() {
//!     println!("All Ansible features are available!");
//! } else {
//!     println!("Missing features: {:?}", system_info.missing_features());
//! }
//!
//! // Check individual components
//! if PlatformValidator::is_platform_supported() {
//!     println!("Platform is supported");
//! }
//! # Ok::<(), ansible::AnsibleError>(())
//! ```
//!
//! ## Error Handling
//!
//! The library provides comprehensive error handling with detailed error types:
//!
//! ```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: {}", stderr);
//!         }
//!     }
//!     Err(AnsibleError::UnsupportedPlatform(msg)) => {
//!         eprintln!("Platform not supported: {}", msg);
//!     }
//!     Err(e) => eprintln!("Other error: {}", e),
//! }
//! ```
//!
//! ## Environment Variables
//!
//! Control build-time behavior with environment variables:
//!
//! - `SKIP_ANSIBLE_CHECK=1` - Skip Ansible installation check during build
//! - `ANSIBLE_AUTO_INSTALL=true` - Enable automatic Ansible installation
//! - `CI=1` - Disable interactive installation prompts in CI environments
//! - `DOCS_RS=1` - Skip all checks when building documentation
//!
//! ## Module Organization
//!
//! The library is organized into several modules:
//!
//! - Core Ansible command execution and module management
//! - Ansible playbook execution and management
//! - [`vault`] - Ansible Vault encryption and decryption operations
//! - [`config`] - Ansible configuration querying and management
//! - [`inventory`] - Inventory parsing and host management
//! - [`platform`] - System requirements validation and platform detection
//! - [`errors`] - Comprehensive error types and handling
//! - [`command_config`] - Low-level command configuration utilities
//!
//! ## Examples
//!
//! See the `examples/` directory for complete working examples:
//!
//! - `examples/basic.rs` - Basic Ansible commands
//! - `examples/playbook.rs` - Playbook execution
//! - `examples/new_features_demo.rs` - Vault, config, and inventory features
//! - `examples/system_check.rs` - System requirements validation
//! - `examples/test_build.rs` - Build script functionality testing

mod ansible;
pub mod command_config;
pub mod config;
pub mod errors;
pub mod inventory;
pub mod platform;
mod playbook;
pub mod vault;

// 异步支持模块（可选）
#[cfg(feature = "async")]
pub mod async_support;

// Re-export main types for convenience
pub use ansible::{
    Ansible, Module,
    PackageState, ServiceState, FileState, UserState, GroupState
};
pub use playbook::{Playbook, Play};
pub use errors::{AnsibleError, Result};
pub use vault::{AnsibleVault, VaultError};
pub use config::{AnsibleConfig, ConfigFormat, PluginType};
pub use inventory::{AnsibleInventory, InventoryFormat, InventoryData, InventoryGroup, InventoryMeta};
pub use platform::{PlatformValidator, SystemInfo, validate_system, get_system_info};

// 异步类型重新导出（可选）
#[cfg(feature = "async")]
pub use async_support::{
    AsyncAnsible, AsyncPlaybook, AsyncPlay, AsyncAnsibleVault,
    AsyncAnsibleConfig, AsyncAnsibleInventory,
    AsyncResult, AsyncExecute, IntoAsync, FromAsync
};