errors.rs

//! Error types for the Destroy command handler

use std::path::PathBuf;

use crate::adapters::tofu::client::OpenTofuError;
use crate::domain::environment::state::StateTypeError;
use crate::shared::command::CommandError;

/// Comprehensive error type for the `DestroyCommandHandler`
#[derive(Debug, thiserror::Error)]
pub enum DestroyCommandHandlerError {
    /// Environment was not found in the repository
    #[error("Environment not found: {name}")]
    EnvironmentNotFound {
        /// The name of the environment that was not found
        name: String,
    },

    #[error("OpenTofu command failed: {0}")]
    OpenTofu(#[from] OpenTofuError),

    #[error("Command execution failed: {0}")]
    Command(#[from] CommandError),

    #[error("Failed to persist environment state: {0}")]
    StatePersistence(#[from] crate::domain::environment::repository::RepositoryError),

    #[error("Invalid state transition: {0}")]
    StateTransition(#[from] StateTypeError),

    #[error("Failed to clean up state files at '{path}': {source}")]
    StateCleanupFailed {
        path: PathBuf,
        #[source]
        source: std::io::Error,
    },
}

impl crate::shared::Traceable for DestroyCommandHandlerError {
    fn trace_format(&self) -> String {
        match self {
            Self::EnvironmentNotFound { name } => {
                format!("DestroyCommandHandlerError: Environment not found - {name}")
            }
            Self::OpenTofu(e) => {
                format!("DestroyCommandHandlerError: OpenTofu command failed - {e}")
            }
            Self::Command(e) => {
                format!("DestroyCommandHandlerError: Command execution failed - {e}")
            }
            Self::StatePersistence(e) => {
                format!("DestroyCommandHandlerError: Failed to persist environment state - {e}")
            }
            Self::StateTransition(e) => {
                format!("DestroyCommandHandlerError: Invalid state transition - {e}")
            }
            Self::StateCleanupFailed { path, source } => {
                format!(
                    "DestroyCommandHandlerError: Failed to clean up state files at '{}' - {source}",
                    path.display()
                )
            }
        }
    }

    fn trace_source(&self) -> Option<&dyn crate::shared::Traceable> {
        match self {
            Self::OpenTofu(e) => Some(e),
            Self::Command(e) => Some(e),
            Self::EnvironmentNotFound { .. }
            | Self::StatePersistence(_)
            | Self::StateTransition(_)
            | Self::StateCleanupFailed { .. } => None,
        }
    }

    fn error_kind(&self) -> crate::shared::ErrorKind {
        match self {
            Self::EnvironmentNotFound { .. } | Self::StateTransition(_) => {
                crate::shared::ErrorKind::Configuration
            }
            Self::OpenTofu(_) => crate::shared::ErrorKind::InfrastructureOperation,
            Self::Command(_) => crate::shared::ErrorKind::CommandExecution,
            Self::StatePersistence(_) | Self::StateCleanupFailed { .. } => {
                crate::shared::ErrorKind::StatePersistence
            }
        }
    }
}

impl DestroyCommandHandlerError {
    /// Provides detailed troubleshooting guidance for this error
    ///
    /// Returns context-specific help text that guides users toward resolving
    /// the issue. This implements the project's tiered help system pattern
    /// for actionable error messages.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use torrust_tracker_deployer_lib::application::command_handlers::destroy::DestroyCommandHandlerError;
    /// use torrust_tracker_deployer_lib::adapters::tofu::client::OpenTofuError;
    /// use torrust_tracker_deployer_lib::shared::command::CommandError;
    ///
    /// let error = DestroyCommandHandlerError::OpenTofu(
    ///     OpenTofuError::CommandError(CommandError::ExecutionFailed {
    ///         command: "tofu".to_string(),
    ///         exit_code: "1".to_string(),
    ///         stdout: String::new(),
    ///         stderr: "error".to_string(),
    ///     })
    /// );
    ///
    /// let help = error.help();
    /// assert!(help.contains("OpenTofu"));
    /// assert!(help.contains("Troubleshooting"));
    /// ```
    #[must_use]
    pub fn help(&self) -> &'static str {
        match self {
            Self::EnvironmentNotFound { .. } => {
                "Environment Not Found - Troubleshooting:

1. Verify the environment name is correct
2. Check if the environment was created:
   ls data/

3. If the environment doesn't exist, there's nothing to destroy

4. If the environment was previously destroyed, it has already been removed

Common causes:
- Typo in environment name
- Environment was already destroyed
- Working in the wrong directory

For more information, see docs/user-guide/commands.md"
            }
            Self::OpenTofu(_) => {
                "OpenTofu Destroy Failed - Troubleshooting:

1. Check OpenTofu is installed: tofu version
2. Verify your infrastructure provider is accessible
3. Check if instance/server still exists using provider tools
4. Review OpenTofu error output above for specific issues
5. Try manually running:
   cd build/<env-name>/tofu/<provider> && tofu destroy

6. Common issues:
   - Instance already deleted: Normal, destroy succeeds
   - Provider not running: Start the provider service
   - Permission denied: Check provider permissions
   - State file locked: Wait or remove .terraform.lock.hcl

7. Force removal if needed:
   Use provider-specific commands to delete the instance

For provider troubleshooting, see docs/vm-providers.md"
            }
            Self::Command(_) => {
                "Command Execution Failed - Troubleshooting:

1. Check that required tools are installed (tofu)
2. Verify PATH environment variable includes tool locations
3. Check command permissions and executability
4. Review stderr output above for specific error details
5. Try running the command manually to diagnose issues

Common issues:
- Tool not in PATH: which tofu
- Permission denied: Check execute permissions
- Command not found: Install OpenTofu

For tool installation, see the setup documentation."
            }
            Self::StatePersistence(_) => {
                "State Persistence Failed - Troubleshooting:

1. Check file system permissions for the data directory
2. Verify available disk space: df -h
3. Ensure no other process is accessing the environment files
4. Check for file system errors: dmesg | tail
5. Verify the data directory is writable

State files are stored in: data/<env-name>/

The repository handles directory creation atomically during save.
If partially created files exist, remove them and retry.

If the problem persists, report it with full system details."
            }
            Self::StateTransition(_) => {
                "Invalid State Transition - Troubleshooting:

1. This error indicates an internal state machine issue
2. Check the current environment state: cat data/<env-name>/environment.json
3. The environment may be in an unexpected state

Possible causes:
- Manual modification of state files
- Interrupted previous command
- Bug in state transition logic

To recover:
1. Check environment status to understand current state
2. If necessary, manually edit state file (not recommended)
3. Or destroy and recreate the environment

If this persists, please report it with full details."
            }
            Self::StateCleanupFailed { .. } => {
                "State Cleanup Failed - Troubleshooting:

1. Check file permissions for the directory:
   ls -la <parent-directory>

2. Verify the path exists and is accessible

3. Check for read-only filesystems:
   mount | grep <filesystem>

4. Look for process locks:
   lsof | grep <path>

5. Manual cleanup if needed:
   rm -rf data/<env-name>
   rm -rf build/<env-name>

Common causes:
- Permission denied: Check ownership and permissions
- Directory in use: Close applications using the directory
- Read-only filesystem: Remount as read-write
- File system errors: Check dmesg for errors

If the problem persists, report it with full system details."
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::adapters::tofu::client::OpenTofuError;
    use crate::domain::environment::repository::RepositoryError;
    use crate::domain::environment::state::StateTypeError;
    use crate::shared::command::CommandError;
    use std::path::PathBuf;

    #[test]
    fn it_should_provide_help_for_opentofu_error() {
        use crate::shared::command::CommandError;

        let error = DestroyCommandHandlerError::OpenTofu(OpenTofuError::CommandError(
            CommandError::ExecutionFailed {
                command: "tofu".to_string(),
                exit_code: "1".to_string(),
                stdout: String::new(),
                stderr: "destroy failed".to_string(),
            },
        ));

        let help = error.help();
        assert!(help.contains("OpenTofu Destroy"));
        assert!(help.contains("Troubleshooting"));
        assert!(help.contains("tofu version"));
        assert!(help.contains("provider"));
    }

    #[test]
    fn it_should_provide_help_for_command_execution() {
        let error = DestroyCommandHandlerError::Command(CommandError::ExecutionFailed {
            command: "test".to_string(),
            exit_code: "1".to_string(),
            stdout: String::new(),
            stderr: "error".to_string(),
        });

        let help = error.help();
        assert!(help.contains("Command Execution"));
        assert!(help.contains("Troubleshooting"));
        assert!(help.contains("PATH"));
    }

    #[test]
    fn it_should_provide_help_for_state_persistence() {
        let error = DestroyCommandHandlerError::StatePersistence(RepositoryError::NotFound);

        let help = error.help();
        assert!(help.contains("State Persistence"));
        assert!(help.contains("Troubleshooting"));
        assert!(help.contains("data/<env-name>/"));
    }

    #[test]
    fn it_should_provide_help_for_state_transition() {
        let error = DestroyCommandHandlerError::StateTransition(StateTypeError::UnexpectedState {
            expected: "Provisioned",
            actual: "Created".to_string(),
        });

        let help = error.help();
        assert!(help.contains("State Transition"));
        assert!(help.contains("Troubleshooting"));
        assert!(help.contains("state machine"));
    }

    #[test]
    fn it_should_provide_help_for_state_cleanup_failed() {
        let error = DestroyCommandHandlerError::StateCleanupFailed {
            path: PathBuf::from("/test/path"),
            source: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "test"),
        };

        let help = error.help();
        assert!(help.contains("State Cleanup"));
        assert!(help.contains("Troubleshooting"));
        assert!(help.contains("permissions"));
    }

    #[test]
    fn it_should_provide_help_for_environment_not_found() {
        let error = DestroyCommandHandlerError::EnvironmentNotFound {
            name: "test-env".to_string(),
        };

        let help = error.help();
        assert!(help.contains("Environment Not Found"));
        assert!(help.contains("Troubleshooting"));
        assert!(help.contains("environment name"));
    }

    #[test]
    fn it_should_have_help_for_all_error_variants() {
        let errors = vec![
            DestroyCommandHandlerError::EnvironmentNotFound {
                name: "test-env".to_string(),
            },
            DestroyCommandHandlerError::OpenTofu(OpenTofuError::CommandError(
                CommandError::ExecutionFailed {
                    command: "tofu".to_string(),
                    exit_code: "1".to_string(),
                    stdout: String::new(),
                    stderr: "error".to_string(),
                },
            )),
            DestroyCommandHandlerError::Command(CommandError::ExecutionFailed {
                command: "test".to_string(),
                exit_code: "1".to_string(),
                stdout: String::new(),
                stderr: "error".to_string(),
            }),
            DestroyCommandHandlerError::StatePersistence(RepositoryError::NotFound),
            DestroyCommandHandlerError::StateTransition(StateTypeError::UnexpectedState {
                expected: "Provisioned",
                actual: "Created".to_string(),
            }),
            DestroyCommandHandlerError::StateCleanupFailed {
                path: PathBuf::from("/test"),
                source: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "test"),
            },
        ];

        for error in errors {
            let help = error.help();
            assert!(!help.is_empty(), "Help text should not be empty");
            assert!(
                help.contains("Troubleshooting"),
                "Help should contain troubleshooting guidance"
            );
            assert!(help.len() > 50, "Help should be detailed");
        }
    }
}