Struct CreateCommandHandler 

pub struct CreateCommandHandler { /* private fields */ }

Command to create a new deployment environment

This command is delivery-agnostic and can be used from CLI, REST API, GraphQL, or any other delivery mechanism. It orchestrates the business logic for environment creation without knowledge of how the configuration was obtained.

Architecture

The command follows these design principles:

• Synchronous: No async/await, following existing patterns
• Dependency Injection: Uses Arc<dyn Trait> for testability
• Repository Pattern: Delegates persistence to repository
• Explicit Errors: All failures return structured errors with .help()

Business Logic Flow

1. Convert configuration to domain objects
2. Check if environment already exists (prevent duplicates)
3. Create environment entity using Environment::new()
4. Persist via repository (repository handles directory creation)

Examples

use std::sync::Arc;
use torrust_tracker_deployer_lib::application::command_handlers::create::CreateCommandHandler;
use torrust_tracker_deployer_lib::application::command_handlers::create::config::{
    EnvironmentCreationConfig, EnvironmentSection, LxdProviderSection, ProviderSection,
    SshCredentialsConfig,
};
use torrust_tracker_deployer_lib::application::command_handlers::create::config::tracker::TrackerSection;
use torrust_tracker_deployer_lib::infrastructure::persistence::file_repository_factory::FileRepositoryFactory;
use torrust_tracker_deployer_lib::shared::{SystemClock, Clock};

// Setup dependencies
let file_repository_factory = FileRepositoryFactory::new(std::time::Duration::from_secs(30));
let repository = file_repository_factory.create(std::path::PathBuf::from("."));
let clock: Arc<dyn Clock> = Arc::new(SystemClock);

// Create command
let command = CreateCommandHandler::new(repository, clock);

// Prepare configuration
let config = EnvironmentCreationConfig::new(
    EnvironmentSection {
        name: "dev".to_string(),
        description: None,
        instance_name: None, // Auto-generate from environment name
    },
    SshCredentialsConfig::new(
        "fixtures/testing_rsa".to_string(),
        "fixtures/testing_rsa.pub".to_string(),
        "torrust".to_string(),
        22,
    ),
    ProviderSection::Lxd(LxdProviderSection {
        profile_name: "lxd-dev".to_string(),
    }),
    TrackerSection::default(),
    None, // prometheus
    None, // grafana
    None, // https
    None, // backup
);

// Execute command with working directory
let working_dir = std::path::Path::new(".");
let environment = command.execute(config, working_dir)?;
println!("Created environment: {}", environment.name());

Implementations

impl CreateCommandHandler

pub fn new( environment_repository: Arc<dyn EnvironmentRepository>, clock: Arc<dyn Clock>, ) -> Self

Create a new CreateCommandHandler with required dependencies

Arguments

• environment_repository - Repository for persisting environment state
• clock - Clock for timestamp generation (for future use)

Examples

use std::sync::Arc;
use torrust_tracker_deployer_lib::application::command_handlers::create::CreateCommandHandler;
use torrust_tracker_deployer_lib::infrastructure::persistence::file_repository_factory::FileRepositoryFactory;
use torrust_tracker_deployer_lib::shared::{SystemClock, Clock};

let file_repository_factory = FileRepositoryFactory::new(std::time::Duration::from_secs(30));
let repository = file_repository_factory.create(std::path::PathBuf::from("."));
let clock: Arc<dyn Clock> = Arc::new(SystemClock);

let command = CreateCommandHandler::new(repository, clock);

pub fn execute( &self, config: EnvironmentCreationConfig, working_dir: &Path, ) -> Result<Environment<Created>, CreateCommandHandlerError>

Execute the create command with validated configuration

This method orchestrates the complete environment creation workflow:

1. Converts configuration to domain objects
2. Validates environment uniqueness
3. Creates the environment entity
4. Persists the environment state

Arguments

• config - Validated environment configuration from domain layer

Returns

• Ok(Environment<Created>) - Successfully created environment
• Err(CreateCommandHandlerError) - Business logic or persistence failure

Business Rules

1. Configuration must convert to valid domain objects
2. Environment name must be unique (no duplicates)
3. Repository handles directory creation atomically during save
4. Environment state must be persisted successfully

Errors

Returns an error if:

• Configuration validation fails
• Environment with the same name already exists
• Repository persistence fails

All errors implement .help() with detailed troubleshooting guidance.

Panics

This function does not panic in practice. The internal .expect() call when generating the profile name is theoretically unreachable because valid environment names always produce valid profile names.

Examples

use torrust_tracker_deployer_lib::application::command_handlers::create::CreateCommandHandler;
use torrust_tracker_deployer_lib::application::command_handlers::create::config::{
    EnvironmentCreationConfig, EnvironmentSection, LxdProviderSection, ProviderSection,
    SshCredentialsConfig,
};
use torrust_tracker_deployer_lib::application::command_handlers::create::config::tracker::TrackerSection;

let config = EnvironmentCreationConfig::new(
    EnvironmentSection {
        name: "staging".to_string(),
        description: None,
        instance_name: None, // Auto-generate from environment name
    },
    SshCredentialsConfig::new(
        "keys/stage_key".to_string(),
        "keys/stage_key.pub".to_string(),
        "torrust".to_string(),
        22,
    ),
    ProviderSection::Lxd(LxdProviderSection {
        profile_name: "lxd-staging".to_string(),
    }),
    TrackerSection::default(),
    None, // prometheus
    None, // grafana
    None, // https
    None, // backup
);

let working_dir = std::path::Path::new(".");
let environment = command.execute(config, working_dir)?;
println!("Created: {}", environment.name());