torrust_tracker_deployer_lib/application/command_handlers/run/mod.rs
1//! Run Command Module
2//!
3//! This module implements the delivery-agnostic `RunCommandHandler`
4//! for orchestrating the execution of the deployed software stack.
5//!
6//! ## Architecture
7//!
8//! The `RunCommandHandler` 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//! - **Synchronous**: Follows existing patterns (no async/await)
19//! - **Explicit State Transitions**: Type-safe state machine for environment lifecycle
20//! - **Explicit Errors**: All errors implement `.help()` with actionable guidance
21//!
22//! ## Run Workflow
23//!
24//! The command handler orchestrates a multi-step workflow:
25//!
26//! 1. **Load environment** - Retrieve environment from repository
27//! 2. **Validate state** - Ensure environment is in a valid state for running
28//! 3. **Start services** - Start the deployed software stack on the target instance
29//!
30//! ## State Management
31//!
32//! The command handler integrates with the type-state pattern for environment lifecycle:
33//!
34//! - Accepts environment in `Released` state
35//! - Transitions to `Environment<Running>` at start
36//! - Returns `Environment<Running>` on success
37//! - Transitions to `Environment<RunFailed>` on error
38//!
39//! State is persisted after each transition using the injected repository.
40
41pub mod errors;
42pub mod handler;
43
44#[cfg(test)]
45mod tests;
46
47// Re-export main types for convenience
48pub use errors::RunCommandHandlerError;
49pub use handler::RunCommandHandler;