torrust-tracker-deployer 0.1.0

Torrust Tracker Deployer - Deployment Infrastructure with Ansible and OpenTofu
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

//! Remote actions module (Level 3 of Three-Level Architecture)
//!
//! This module provides the lowest-level operations in the three-level architecture,
//! containing leaf-level actions that directly interact with remote systems via SSH.
//! These actions are the building blocks used by steps (Level 2) and commands (Level 1).
//!
//! ## Execution Context: Inside VM via SSH
//!
//! All remote actions in this module execute commands **INSIDE the VM via SSH**.
//! For external validation (E2E testing from outside the VM), see `external_validators/`.
//!
//! **Distinction**:
//! - **`remote_actions`** (this module): Execute commands inside VM via SSH
//! - **`external_validators`**: Validate services from outside VM via HTTP
//!
//! ## Available Remote Actions
//!
//! - `validators::cloud_init` - Cloud-init status checking and validation
//! - `validators::docker` - Docker installation and service management
//! - `validators::docker_compose` - Docker Compose installation and validation
//!
//! ## Architecture Pattern
//!
//! Remote actions follow a consistent pattern:
//! - Take SSH connection and required parameters
//! - Execute specific remote operations via SSH
//! - Provide structured error handling with action context
//! - Return typed results for use by higher-level components
//!
//! These actions are designed to be atomic, testable, and reusable across
//! different deployment scenarios.

use std::net::IpAddr;
use thiserror::Error;

use crate::shared::command::CommandError;

pub mod validators;

pub use validators::cloud_init::CloudInitValidator;
pub use validators::docker::DockerValidator;
pub use validators::docker_compose::DockerComposeValidator;

/// Errors that can occur during remote action execution
#[derive(Error, Debug)]
pub enum RemoteActionError {
    /// SSH command execution failed
    #[error("SSH command execution failed during '{action_name}': {source}")]
    SshCommandFailed {
        action_name: String,
        #[source]
        source: CommandError,
    },

    /// Action validation failed
    #[error("Action '{action_name}' validation failed: {message}")]
    ValidationFailed {
        action_name: String,
        message: String,
    },

    /// Action execution failed with custom error
    #[error("Action '{action_name}' execution failed: {message}")]
    ExecutionFailed {
        action_name: String,
        message: String,
    },
}

/// Trait for remote actions that can be executed on a server via SSH
///
/// Remote actions are lightweight scripts that connect to a provisioned
/// server via SSH to perform various operations such as:
///
/// - Validating server state and configuration
/// - Retrieving server information (hostname, installed packages, etc.)
/// - Executing maintenance tasks (updates, cleanup, etc.)
/// - Installing or configuring software components
#[allow(async_fn_in_trait)]
pub trait RemoteAction {
    /// Get the name of this action for logging purposes
    fn name(&self) -> &'static str;

    /// Execute the action against the specified server
    ///
    /// # Arguments
    /// * `server_ip` - The IP address of the server to execute the action on
    ///
    /// # Returns
    /// * `Ok(())` if the action executes successfully
    /// * `Err(RemoteActionError)` if the action fails or encounters an error
    async fn execute(&self, server_ip: &IpAddr) -> Result<(), RemoteActionError>;
}