torrust_tracker_deployer_lib/application/command_handlers/release/mod.rs
1//! Release Command Module
2//!
3//! This module implements the delivery-agnostic `ReleaseCommandHandler`
4//! for orchestrating software release operations on target instances.
5//!
6//! ## Architecture
7//!
8//! The `ReleaseCommandHandler` 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//! ## Module Organization
23//!
24//! - `handler.rs` - Core handler with `execute()`, state transitions, workflow orchestration
25//! - `workflow.rs` - Release workflow orchestration (step coordination)
26//! - `errors.rs` - Error types for release operations
27//! - `steps/` - Service-specific step implementations (tracker, prometheus, etc.)
28//!
29//! ## Release Workflow
30//!
31//! The command handler orchestrates a multi-step workflow:
32//!
33//! 1. **Load environment** - Retrieve environment from repository
34//! 2. **Validate state** - Ensure environment is in a valid state for release
35//! 3. **Release software** - Deploy software to the target instance
36//!
37//! ## State Management
38//!
39//! The command handler integrates with the type-state pattern for environment lifecycle:
40//!
41//! - Accepts environment in `Configured` state
42//! - Transitions to `Environment<Releasing>` at start
43//! - Returns `Environment<Released>` on success
44//! - Transitions to `Environment<ReleaseFailed>` on error
45//!
46//! State is persisted after each transition using the injected repository.
47
48pub mod errors;
49pub mod handler;
50mod steps;
51mod workflow;
52
53#[cfg(test)]
54mod tests;
55
56// Re-export main types for convenience
57pub use errors::ReleaseCommandHandlerError;
58pub use handler::ReleaseCommandHandler;