torrust_tracker_deployer_lib/application/command_handlers/provision/mod.rs
1//! Provision Command Module
2//!
3//! This module implements the delivery-agnostic `ProvisionCommandHandler`
4//! for orchestrating infrastructure provisioning business logic.
5//!
6//! ## Architecture
7//!
8//! The `ProvisionCommandHandler` implements the Command Pattern and uses Dependency Injection
9//! to interact with infrastructure services through interfaces:
10//!
11//! - **Repository Pattern**: Persists environment state via `EnvironmentRepository`
12//! - **Clock Abstraction**: Provides deterministic time for testing via `Clock` trait
13//! - **Domain-Driven Design**: Uses domain objects from `domain::environment`
14//!
15//! ## Design Principles
16//!
17//! - **Delivery-Agnostic**: Works with CLI, REST API, or any delivery mechanism
18//! - **Asynchronous**: Uses async/await for network operations
19//! - **Explicit State Transitions**: Type-safe state machine for environment lifecycle
20//! - **Explicit Errors**: All errors implement `.help()` with actionable guidance
21//!
22//! ## Provisioning Workflow
23//!
24//! The command handler orchestrates a multi-step workflow:
25//!
26//! 1. **Render `OpenTofu` templates** - Generate infrastructure configuration
27//! 2. **Initialize `OpenTofu`** - Set up Terraform/`OpenTofu` backend
28//! 3. **Validate configuration** - Check syntax and consistency
29//! 4. **Plan infrastructure** - Preview changes
30//! 5. **Apply infrastructure** - Provision virtual machines
31//! 6. **Get instance information** - Retrieve IP address and metadata
32//! 7. **Render `Ansible` templates** - Generate configuration with runtime IP
33//! 8. **Wait for SSH connectivity** - Ensure VM is reachable
34//! 9. **Wait for cloud-init** - Ensure system is ready for configuration
35//!
36//! ## State Management
37//!
38//! The command handler integrates with the type-state pattern for environment lifecycle:
39//!
40//! - Accepts `Environment<Created>` as input
41//! - Transitions to `Environment<Provisioning>` at start
42//! - Returns `Environment<Provisioned>` on success
43//! - Transitions to `Environment<ProvisionFailed>` on error
44//!
45//! State is persisted after each transition using the injected repository.
46
47pub mod errors;
48pub mod handler;
49
50#[cfg(test)]
51mod tests;
52
53// Re-export main types for convenience
54pub use errors::ProvisionCommandHandlerError;
55pub use handler::ProvisionCommandHandler;