//! Kubernetes Cluster Management and Operations
//!
//! This module provides comprehensive Rust bindings for interacting with Kubernetes clusters.
//! It offers both high-level fluent builders for common tasks and low-level access to the
//! Kubernetes API client.
//!
//! # Architecture Overview
//!
//! The module is organized into several sub-modules, each handling different aspects of
//! Kubernetes operations:
//!
//! ## Core Components
//!
//! 1. **KubernetesManager** (`kubernetes_manager.rs`)
//!    - Main entry point for Kubernetes operations
//!    - Namespace-scoped resource management
//!    - Pod, Service, Deployment, ConfigMap, and Secret CRUD operations
//!    - Pattern-based resource deletion
//!    - Async/await based API
//!
//! 2. **Fluent API** (`fluent.rs`)
//!    - Builder pattern for easy resource construction
//!    - Supports: PodBuilder, ServiceBuilder, DeploymentBuilder, ConfigMapBuilder, SecretBuilder
//!    - Chainable method calls for readable code
//!    - KubernetesContext for batch operations
//!
//! 3. **Build Machine** (`kubebuilder.rs`)
//!    - Specialized module for container image building in Kubernetes
//!    - Runs Buildah in pods for building OCI images
//!    - Pushes images to registries
//!    - Handles pod lifecycle for build operations
//!
//! 4. **Development Machine** (`kubedevel.rs`)
//!    - SSH-based development environment in Kubernetes
//!    - Creates dev pods with SSH access
//!    - Port forwarding and interactive sessions
//!    - Useful for debugging and development tasks
//!
//! 5. **Registry Management** (`registry.rs`)
//!    - Docker/Container registry deployment
//!    - Configuration and secret management
//!    - Registry interaction helpers
//!    - Authentication setup
//!
//! 6. **Traefik Integration** (`traefik.rs`)
//!    - Ingress and reverse proxy configuration
//!    - HTTP/TCP/UDP route builders
//!    - TLS/SSL configuration
//!    - Middleware support
//!
//! 7. **SSH Access** (`kubessh.rs`)
//!    - SSH client for pod shell access
//!    - Interactive and non-interactive commands
//!    - Port forwarding setup
//!
//! ## Design Patterns
//!
//! ### Async/Await First
//!
//! All operations are async and require a tokio runtime:
//!
//! ```rust,ignore
//! use herolib_virt::kubernetes::KubernetesManager;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let km = KubernetesManager::new("default").await?;
//!     let pods = km.pods_list().await?;
//!     Ok(())
//! }
//! ```
//!
//! ### Namespace Scoping
//!
//! Each KubernetesManager instance is tied to a specific namespace. All operations
//! (except cluster-level operations) work within that namespace:
//!
//! ```rust,ignore
//! // Operations on "prod" namespace
//! let prod_manager = KubernetesManager::new("prod").await?;
//!
//! // Operations on "dev" namespace
//! let dev_manager = KubernetesManager::new("dev").await?;
//! ```
//!
//! ### Builder Pattern for Fluent API
//!
//! Complex resources are constructed using fluent builders:
//!
//! ```rust,ignore
//! use herolib_virt::kubernetes::DeploymentBuilder;
//!
//! let builder = DeploymentBuilder::new("my-app")
//!     .image("nginx:latest")
//!     .replicas(3)
//!     .port(80)
//!     .env_var("LOG_LEVEL", "info");
//! ```
//!
//! # Quick Start Examples
//!
//! ## Basic Pod Operations
//!
//! ```rust,ignore
//! use herolib_virt::kubernetes::KubernetesManager;
//! use std::collections::BTreeMap;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let km = KubernetesManager::new("default").await?;
//!
//!     // Create a pod
//!     let labels = [("app".to_string(), "test".to_string())]
//!         .iter().cloned().collect::<BTreeMap<_, _>>();
//!
//!     km.pod_create("test-pod", "nginx:latest", labels).await?;
//!
//!     // List pods
//!     let pods = km.pods_list().await?;
//!     for pod in pods {
//!         println!("Pod: {:?}", pod.metadata.name);
//!     }
//!
//!     // Delete pod
//!     km.pod_delete("test-pod").await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! ## Building Container Images
//!
//! ```rust,ignore
//! use herolib_virt::kubernetes::BuildMachine;
//!
//! let builder = BuildMachine::new("build-ns").await?;
//! let result = builder.build_image(
//!     "my-app:latest",
//!     Some("https://github.com/user/repo".to_string()),
//! ).await?;
//! println!("Built image: {}", result.image_id);
//! ```
//!
//! ## Setting Up a Dev Environment
//!
//! ```rust,ignore
//! use herolib_virt::kubernetes::DevelopmentMachine;
//!
//! let dev = DevelopmentMachine::new("dev-ns").await?;
//! let session = dev.create("dev-machine", 22, 8080).await?;
//! println!("SSH: ssh -p {} root@localhost", session.ssh_port);
//! ```
//!
//! # Error Handling
//!
//! All operations return `KubernetesResult<T>` which is `Result<T, KubernetesError>`.
//! Errors include:
//!
//! - **ClientCreationFailed**: Could not connect to cluster
//! - **ResourceNotFound**: Resource doesn't exist
//! - **OperationFailed**: API operation returned an error
//! - **InvalidInput**: Invalid parameters provided
//! - **Other**: Various Kubernetes/API errors
//!
//! # Performance Considerations
//!
//! 1. **Connection Pooling**: The client automatically pools connections
//! 2. **Timeouts**: Operations have reasonable defaults (30 seconds)
//! 3. **Pagination**: List operations handle large result sets automatically
//! 4. **Rate Limiting**: Use governor for API rate limiting if needed
//!
//! # Feature Flag
//!
//! This module requires the `kubernetes` feature to be enabled in Cargo.toml:
//!
//! ```toml
//! herolib-virt = { version = "...", features = ["kubernetes"] }
//! ```

pub mod config;
pub mod error;
pub mod fluent;
pub mod kubebuilder;
pub mod kubedevel;
pub mod kubernetes_manager;
pub mod kubessh;
pub mod registry;
pub mod rhai;
pub mod traefik;

// Re-export main types for convenience
pub use config::KubernetesConfig;
pub use error::{KubernetesError, KubernetesResult};
pub use fluent::{
    ConfigMapBuilder, DeploymentBuilder, HealthCheckBuilder, KubernetesContext, NamespaceBuilder,
    PodBuilder, SecretBuilder, ServiceBuilder,
};
pub use kubebuilder::{BuildMachine, BuildMachineHandle, KubeBuilderError, KubeBuilderResult};
pub use kubedevel::DevelopmentMachine;
pub use kubernetes_manager::{KubernetesManager, ServiceConnectionInfo};
pub use kubessh::KubeSsh;
pub use registry::{
    RegistryConfig, RegistryConfigBuilder, RegistryDeployer, RegistryDeployerBuilder,
    RegistryDeploymentResult,
};

pub use traefik::{
    HttpRoute, HttpRouteBuilder, Middleware, MiddlewareBuilder, MiddlewareSpec, ServiceTarget,
    TcpRoute, TcpRouteBuilder, TlsConfig, TlsOption, TlsOptionBuilder, UdpRoute, UdpRouteBuilder,
};

// Re-export commonly used Kubernetes types
pub use k8s_openapi::api::apps::v1::{Deployment, ReplicaSet};
pub use k8s_openapi::api::core::v1::{Namespace, Pod, Service};
