Module Organization

This document outlines the conventions for organizing items within Rust modules in the Torrust Tracker Deployer project.

📚 Background

While Rust doesn't enforce strict ordering rules for items within modules, following consistent organization principles makes code more maintainable, readable, and easier to navigate. The approach described here aligns with common Rust community practices and emphasizes a top-down, public-first organization style.

Formal Conventions

The Rust community commonly refers to these practices as:

Top-down organization: High-level abstractions before low-level details
Visibility-first ordering: Public items before private items
Importance-based ordering: Main responsibilities before secondary concerns

While not formally standardized in official Rust guidelines, these patterns are widely adopted in well-maintained Rust projects and align with principles of progressive disclosure and cognitive load reduction.

🎯 Core Principles

1. Imports Always First

Keep all imports at the top of the file, organized in groups:

// Standard library imports
use std::path::{Path, PathBuf};
use std::sync::Arc;

// External crate imports
use anyhow::Result;
use serde::{Deserialize, Serialize};
use thiserror::Error;

// Internal crate imports - absolute paths
use crate::domain::Environment;
use crate::shared::Clock;

// Internal crate imports - relative paths (if needed)
use super::config::Config;

Why: This follows universal Rust conventions and makes dependencies immediately visible.

2. Prefer Imports Over Full Paths

Always import types and use their short names rather than fully-qualified paths, unless you need to disambiguate naming conflicts.

✅ Good: Import and use short names

use std::sync::Arc;
use crate::presentation::views::UserOutput;

pub struct CommandHandler {
    output: Arc<UserOutput>,
}

impl CommandHandler {
    pub fn new(output: Arc<UserOutput>) -> Self {
        Self { output }
    }

    pub fn execute(&self) -> Result<()> {
        self.output.display_success("Done!");
        Ok(())
    }
}

❌ Bad: Full namespace paths

// Don't do this - it's verbose and hard to read
pub struct CommandHandler {
    output: std::sync::Arc<crate::presentation::views::UserOutput>,
}

impl CommandHandler {
    pub fn new(output: std::sync::Arc<crate::presentation::views::UserOutput>) -> Self {
        Self { output }
    }
}

When Full Paths Are Acceptable

Use full paths only when you need to disambiguate between types with the same name:

// ✅ Good: Disambiguating same-named types
use crate::domain::Environment as DomainEnvironment;
use crate::config::Environment as ConfigEnvironment;

// Or when the conflict is rare:
use crate::domain::Environment;

pub fn compare(
    domain: &Environment,
    config: &crate::config::Environment  // Only this one needs full path
) -> bool {
    // ...
}

Exception: Quick One-Off Usage

In rare cases where a type is used exactly once and importing it would add clutter, a full path may be acceptable:

// Acceptable for single use
pub fn create_temp_dir() -> std::io::Result<std::path::PathBuf> {
    // Only used here, importing might not add value
}

However, if the type appears multiple times, always import it.

❌ Avoid: Inline Full Paths in Function Bodies

Never use fully-qualified paths inside function implementations. Always import at the module level:

// ❌ Bad: Full path inside function body
pub struct AnsibleVariablesContext {
    ssh_port: u16,
}

impl AnsibleVariablesContext {
    pub fn new(ssh_port: u16) -> Result<Self, AnsibleVariablesContextError> {
        // Don't do this - hard to read and breaks the import-at-top convention
        crate::infrastructure::external_tools::ansible::template::wrappers::inventory::context::AnsiblePort::new(ssh_port)?;

        Ok(Self { ssh_port })
    }
}

// ✅ Good: Import at module level, use short name
use crate::infrastructure::external_tools::ansible::template::wrappers::inventory::context::AnsiblePort;

pub struct AnsibleVariablesContext {
    ssh_port: u16,
}

impl AnsibleVariablesContext {
    pub fn new(ssh_port: u16) -> Result<Self, AnsibleVariablesContextError> {
        // Much cleaner and easier to read
        AnsiblePort::new(ssh_port)?;

        Ok(Self { ssh_port })
    }
}

Why:

Keeps all dependencies visible at the top of the file
Makes function bodies cleaner and more readable
Follows Rust's standard conventions
Easier to refactor and maintain

Summary: Short names improve readability and reduce visual noise. Rust's import system exists to make code cleaner - use it!

3. Public Before Private

Place public items before private items:

// ✅ Good: Public API first
pub struct Environment {
    name: String,
    data_dir: PathBuf,
}

impl Environment {
    pub fn new(name: String) -> Self {
        let data_dir = calculate_data_dir(&name);
        Self { name, data_dir }
    }

    pub fn name(&self) -> &str {
        &self.name
    }
}

// Private helpers come after
fn calculate_data_dir(name: &str) -> PathBuf {
    PathBuf::from("data").join(name)
}

Why: Users of the module see the public interface first without wading through implementation details.

4. High-Level Before Low-Level

Organize abstractions from high-level (business logic) to low-level (implementation details):

// ✅ Good: High-level abstraction first
pub trait CommandExecutor {
    fn execute(&self, command: Command) -> Result<State>;
}

// Mid-level implementation
pub struct DefaultCommandExecutor {
    step_runner: Arc<dyn StepRunner>,
}

impl CommandExecutor for DefaultCommandExecutor {
    fn execute(&self, command: Command) -> Result<State> {
        self.step_runner.run_steps(command.steps())
    }
}

// Low-level details
trait StepRunner {
    fn run_steps(&self, steps: Vec<Step>) -> Result<State>;
}

Why: Readers can understand what the module does before diving into how it works.

5. Important Before Secondary

Place primary responsibilities before secondary concerns (like error types, constants, helpers):

// ✅ Good: Main types and functions first
pub struct ConfigLoader {
    base_path: PathBuf,
}

impl ConfigLoader {
    pub fn new(base_path: PathBuf) -> Self {
        Self { base_path }
    }

    pub fn load(&self) -> Result<Config, ConfigError> {
        let path = self.config_path();
        let content = std::fs::read_to_string(&path)
            .map_err(|source| ConfigError::FileAccess { path: path.clone(), source })?;

        serde_json::from_str(&content)
            .map_err(|source| ConfigError::InvalidJson { path, source })
    }

    fn config_path(&self) -> PathBuf {
        self.base_path.join("config.json")
    }
}

// Secondary: Error types come after main implementation
#[derive(Debug, Error)]
pub enum ConfigError {
    #[error("Cannot access configuration file: {path}")]
    FileAccess {
        path: PathBuf,
        #[source]
        source: std::io::Error,
    },

    #[error("Invalid JSON in configuration file: {path}")]
    InvalidJson {
        path: PathBuf,
        #[source]
        source: serde_json::Error,
    },
}

Why: The main purpose and capabilities of the module are immediately visible.

📋 Complete Ordering Guide

For a typical module, use this order:

Module-level documentation (//! comments)
Imports (grouped: std → external → internal)
Public constants and type aliases
Public traits (high-level abstractions)
Public structs and enums (main types)
Public implementations (for the main types)
Public free functions (module-level utilities)
Private constants and type aliases
Private traits
Private structs and enums (implementation details)
Private implementations
Private helper functions
Error types (even if public, these are secondary concerns)
Test modules (#[cfg(test)])

Complete Example

//! Configuration management for deployment environments.
//!
//! This module provides functionality to load, validate, and manage
//! configuration for different deployment environments.

// Standard library
use std::fs;
use std::path::{Path, PathBuf};

// External crates
use serde::{Deserialize, Serialize};
use thiserror::Error;

// Internal crate
use crate::domain::Environment;

// ============================================================================
// PUBLIC API - Constants
// ============================================================================

/// Default configuration file name
pub const DEFAULT_CONFIG_FILE: &str = "config.json";

// ============================================================================
// PUBLIC API - Traits
// ============================================================================

/// Trait for loading configuration from various sources
pub trait ConfigLoader {
    fn load(&self) -> Result<Config, ConfigError>;
}

// ============================================================================
// PUBLIC API - Main Types
// ============================================================================

/// Configuration for a deployment environment
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Config {
    pub name: String,
    pub provider: String,
    pub instance_count: usize,
}

impl Config {
    pub fn new(name: String, provider: String, instance_count: usize) -> Self {
        Self {
            name,
            provider,
            instance_count,
        }
    }

    pub fn validate(&self) -> Result<(), ConfigError> {
        if self.instance_count == 0 {
            return Err(ConfigError::InvalidInstanceCount {
                value: self.instance_count,
            });
        }
        Ok(())
    }
}

// ============================================================================
// PUBLIC API - Implementations
// ============================================================================

/// Loads configuration from the filesystem
pub struct FileSystemConfigLoader {
    base_path: PathBuf,
}

impl FileSystemConfigLoader {
    pub fn new(base_path: PathBuf) -> Self {
        Self { base_path }
    }

    fn config_path(&self) -> PathBuf {
        self.base_path.join(DEFAULT_CONFIG_FILE)
    }
}

impl ConfigLoader for FileSystemConfigLoader {
    fn load(&self) -> Result<Config, ConfigError> {
        let path = self.config_path();
        let content = fs::read_to_string(&path)
            .map_err(|source| ConfigError::FileAccess {
                path: path.clone(),
                source,
            })?;

        let config: Config = serde_json::from_str(&content)
            .map_err(|source| ConfigError::InvalidJson { path, source })?;

        config.validate()?;

        Ok(config)
    }
}

// ============================================================================
// PRIVATE - Helper Functions
// ============================================================================

fn default_base_path() -> PathBuf {
    PathBuf::from("./config")
}

// ============================================================================
// ERROR TYPES - Secondary Concerns
// ============================================================================

#[derive(Debug, Error)]
pub enum ConfigError {
    #[error("Cannot access configuration file: {path}")]
    FileAccess {
        path: PathBuf,
        #[source]
        source: std::io::Error,
    },

    #[error("Invalid JSON in configuration file: {path}")]
    InvalidJson {
        path: PathBuf,
        #[source]
        source: serde_json::Error,
    },

    #[error("Invalid instance count: {value}, must be greater than 0")]
    InvalidInstanceCount { value: usize },
}

// ============================================================================
// TESTS
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::TempDir;

    #[test]
    fn it_should_load_valid_configuration() {
        let temp_dir = TempDir::new().unwrap();
        let config_path = temp_dir.path().join(DEFAULT_CONFIG_FILE);

        let config_json = r#"{
            "name": "test",
            "provider": "lxd",
            "instance_count": 1
        }"#;

        fs::write(&config_path, config_json).unwrap();

        let loader = FileSystemConfigLoader::new(temp_dir.path().to_path_buf());
        let config = loader.load().unwrap();

        assert_eq!(config.name, "test");
        assert_eq!(config.provider, "lxd");
        assert_eq!(config.instance_count, 1);
    }

    #[test]
    fn it_should_reject_zero_instance_count() {
        let config = Config::new("test".to_string(), "lxd".to_string(), 0);
        let result = config.validate();

        assert!(result.is_err());
    }
}

🚫 Anti-Patterns to Avoid

❌ Random Ordering

// Bad: No clear organization
fn private_helper() -> String {
    "helper".to_string()
}

pub struct MainType {
    field: String,
}

const PRIVATE_CONSTANT: &str = "value";

pub fn public_function() -> String {
    private_helper()
}

#[derive(Error)]
pub enum MyError {
    // ...
}

❌ Private Before Public

// Bad: Private implementation details first
fn internal_calculate(x: i32) -> i32 {
    x * 2
}

struct InternalState {
    value: i32,
}

// Public API buried below
pub struct Calculator {
    state: InternalState,
}

pub fn calculate(x: i32) -> i32 {
    internal_calculate(x)
}

❌ Error Types Mixed with Main Logic

// Bad: Error types interrupting the flow
pub struct Config {
    name: String,
}

#[derive(Error)]
pub enum ConfigError {
    // ...
}

impl Config {
    pub fn load() -> Result<Self, ConfigError> {
        // ...
    }
}

#[derive(Error)]
pub enum LoadError {
    // ...
}

📏 Guidelines Summary

Do's ✅

Keep imports at the top - Always, in organized groups
Public before private - Makes the API clear
High-level before low-level - Improves comprehension
Important before secondary - Highlights main responsibilities
Group related items - Use section comments for clarity
Error types at the end - Unless they're the module's main purpose
Tests last - Always in #[cfg(test)] modules

Don'ts ❌

Don't scatter public items - Group them together
Don't bury the API - Public items should be easily found
Don't mix concerns - Keep related items together
Don't ignore visibility - Respect public/private boundaries
Don't forget documentation - Especially for public items

🎯 When to Deviate

These guidelines are general principles, not absolute rules. Consider deviating when:

Error types are the main purpose: If a module primarily defines error types (e.g., domain::errors), they should be prominent
Builder patterns: When using the builder pattern, keeping the builder next to the main type may improve clarity
Strongly related types: When types are tightly coupled, grouping them together may be more important than strict ordering
Small modules: Very small modules (< 100 lines) may not need strict section separation

Use your judgment, but always prioritize readability and maintainability.

📂 Command Module Structure Patterns

For presentation layer commands in src/presentation/commands/, we follow standardized folder structures that make it clear whether a command has subcommands or is a simple single-purpose command.

Pattern 1: Simple Commands (No Subcommands)

For commands that perform a single operation (like destroy):

src/presentation/commands/destroy/
  ├── mod.rs                         // Module documentation and re-exports
  ├── handler.rs                     // Main command implementation
  ├── errors.rs                      // Error types
  └── tests/                         // Test modules
      ├── mod.rs
      └── integration.rs

Key characteristics:

Uses handler.rs for the main command logic
Direct implementation without routing
Clean and focused on single responsibility

Example:

// In handler.rs
pub fn handle_destroy_command(
    environment_name: &str,
    working_dir: &Path,
) -> Result<(), DestroySubcommandError> {
    // Direct implementation
}

Pattern 2: Commands with Subcommands

For commands that route to multiple subcommands (like create):

src/presentation/commands/create/
  ├── mod.rs                         // Module documentation and re-exports
  ├── handler.rs                     // Router that delegates to subcommands
  ├── errors.rs                      // Shared error types
  ├── config_loader.rs              // Shared utilities (if needed)
  ├── subcommands/                   // 🆕 Dedicated subcommands folder
  │   ├── mod.rs                     // Subcommands module and re-exports
  │   ├── environment.rs             // Environment creation subcommand
  │   └── template.rs                // Template generation subcommand
  └── tests/                         // Test modules
      ├── mod.rs
      ├── integration.rs
      └── fixtures.rs

Key characteristics:

handler.rs acts as a simple router/dispatcher
Each subcommand has its own focused module in subcommands/
Subcommands are isolated and single-responsibility
Easy to add new subcommands without cluttering main files

Example:

// In handler.rs (router)
pub fn handle_create_command(
    action: CreateAction,
    working_dir: &Path,
) -> Result<(), CreateSubcommandError> {
    match action {
        CreateAction::Environment { env_file } => {
            subcommands::handle_environment_creation(&env_file, working_dir)
        }
        CreateAction::Template { output_path } => {
            let template_path = output_path.unwrap_or_else(CreateAction::default_template_path);
            subcommands::handle_template_generation(&template_path)
        }
    }
}

// In subcommands/environment.rs
pub fn handle_environment_creation(
    env_file: &Path,
    working_dir: &Path,
) -> Result<(), CreateSubcommandError> {
    // Focused implementation for environment creation
}

// In subcommands/template.rs
pub fn handle_template_generation(
    output_path: &Path,
) -> Result<(), CreateSubcommandError> {
    // Focused implementation for template generation
}

When to Use Each Pattern

Use Pattern 1 (Simple Commands) when:

The command performs a single, focused operation
No routing or branching logic is needed
The implementation fits naturally in one module

Use Pattern 2 (Commands with Subcommands) when:

The command has multiple distinct subcommands
Each subcommand has significant implementation
You want to isolate different behaviors for clarity
You anticipate adding more subcommands in the future

Benefits of These Patterns

✅ Clear Visual Distinction: Folder structure immediately shows command complexity ✅ Consistent Naming: All commands use handler.rs for their main entry point ✅ Single Responsibility: Each subcommand module has one clear purpose ✅ Easy Extension: Adding new subcommands is straightforward ✅ Better Testing: Each subcommand can be tested independently ✅ Improved Navigation: Developers can quickly find the right code

Migration Guide

When refactoring existing commands to follow these patterns:

For simple commands: Rename command.rs → handler.rs
For commands with subcommands:
- Create subcommands/ directory
- Move subcommand implementations to individual files in subcommands/
- Rename main file to handler.rs and simplify to a router
- Update mod.rs to include the subcommands module
- Update re-exports to use the new structure

Example migration:

# Before
create/
  └── subcommand.rs    (contains all logic)

# After
create/
  ├── handler.rs       (router only)
  └── subcommands/
      ├── mod.rs
      ├── environment.rs
      └── template.rs

🔗 Related Documentation

Testing Conventions - How to organize test code
Error Handling Guide - Error type design principles
Development Principles - Overall code quality standards

📚 Further Reading

Rust API Guidelines - Official Rust API design guidelines
Effective Rust - Best practices for Rust code organization
Clean Code principles applied to Rust development

By following these conventions, we ensure that modules in the Torrust Tracker Deployer project are consistent, readable, and maintainable for all contributors.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Module Organization

📚 Background

Formal Conventions

🎯 Core Principles

1. Imports Always First

2. Prefer Imports Over Full Paths

✅ Good: Import and use short names

❌ Bad: Full namespace paths

When Full Paths Are Acceptable

Exception: Quick One-Off Usage

❌ Avoid: Inline Full Paths in Function Bodies

3. Public Before Private

4. High-Level Before Low-Level

5. Important Before Secondary

📋 Complete Ordering Guide

Complete Example

🚫 Anti-Patterns to Avoid

❌ Random Ordering

❌ Private Before Public

❌ Error Types Mixed with Main Logic

📏 Guidelines Summary

Do's ✅

Don'ts ❌

🎯 When to Deviate

📂 Command Module Structure Patterns

Pattern 1: Simple Commands (No Subcommands)

Pattern 2: Commands with Subcommands

When to Use Each Pattern

Benefits of These Patterns

Migration Guide

🔗 Related Documentation

📚 Further Reading

FilesExpand file tree

module-organization.md

Latest commit

History

module-organization.md

File metadata and controls

Module Organization

📚 Background

Formal Conventions

🎯 Core Principles

1. Imports Always First

2. Prefer Imports Over Full Paths

✅ Good: Import and use short names

❌ Bad: Full namespace paths

When Full Paths Are Acceptable

Exception: Quick One-Off Usage

❌ Avoid: Inline Full Paths in Function Bodies

3. Public Before Private

4. High-Level Before Low-Level

5. Important Before Secondary

📋 Complete Ordering Guide

Complete Example

🚫 Anti-Patterns to Avoid

❌ Random Ordering

❌ Private Before Public

❌ Error Types Mixed with Main Logic

📏 Guidelines Summary

Do's ✅

Don'ts ❌

🎯 When to Deviate

📂 Command Module Structure Patterns

Pattern 1: Simple Commands (No Subcommands)

Pattern 2: Commands with Subcommands

When to Use Each Pattern

Benefits of These Patterns

Migration Guide

🔗 Related Documentation

📚 Further Reading