refactor: refactor SSH wait functionality to use centralized SSH service checker

- Create new SshServiceChecker in src/shared/ssh/service_checker.rs for pure SSH service availability testing without authentication
- Update SshWaitAction to use SshServiceChecker instead of direct SSH commands
- Add service_checker module export to src/shared/ssh/mod.rs
- Separate concerns between authenticated SSH operations (SshClient) and service availability checking (SshServiceChecker)
- Maintain same external API and behavior while centralizing SSH connectivity logic
- Add comprehensive unit tests and documentation for the new service checker

Author: josecelano

src/e2e/containers/actions/ssh_wait.rs

@@ -6,6 +6,8 @@
 use std::time::{Duration, Instant};
 use tracing::{info, warn};
 
+use crate::shared::ssh::SshServiceChecker;
+
 /// Specific error types for SSH wait operations
 #[derive(Debug, thiserror::Error)]
 pub enum SshWaitError {
@@ -152,77 +154,25 @@ impl SshWaitAction {
         })
     }
 
-    /// Test SSH connection by attempting a simple SSH command
+    /// Test SSH connection by checking if SSH service is available
     fn test_ssh_connection(host: &str, port: u16) -> Result<()> {
-        use std::process::Command;
+        let checker = SshServiceChecker::new();
 
-        let output = Command::new("ssh")
-            .args([
-                "-o",
-                "StrictHostKeyChecking=no",
-                "-o",
-                "UserKnownHostsFile=/dev/null",
-                "-o",
-                "ConnectTimeout=5",
-                "-o",
-                "BatchMode=yes", // Non-interactive mode
-                "-p",
-                &port.to_string(),
-                &format!("test@{host}"),
-                "echo",
-                "test",
-            ])
-            .output()
-            .map_err(|source| SshWaitError::SshConnectionTestFailed {
+        match checker.is_service_available(host, port) {
+            Ok(true) => Ok(()),
+            Ok(false) => Err(SshWaitError::SshConnectionTestFailed {
                 host: host.to_string(),
                 port,
-                source,
-            })?;
-
-        // For SSH connectivity testing, we just need to know if the SSH server
-        // is responding, even if authentication fails
-        match output.status.code() {
-            Some(0) => {
-                // SSH command succeeded (unlikely in this test scenario, but good)
-                Ok(())
-            }
-            Some(255) => {
-                // Exit code 255 can mean either:
-                // 1. Authentication failed (server reachable) - this is OK for connectivity test
-                // 2. Connection refused (server not reachable) - this is what we want to catch
-
-                let stderr = String::from_utf8_lossy(&output.stderr);
-
-                if stderr.contains("Connection refused") || stderr.contains("No route to host") {
-                    // Server is not reachable
-                    Err(SshWaitError::SshConnectionTestFailed {
-                        host: host.to_string(),
-                        port,
-                        source: std::io::Error::new(
-                            std::io::ErrorKind::ConnectionRefused,
-                            "SSH server not reachable",
-                        ),
-                    })
-                } else {
-                    // Server is reachable (auth failed, but that's OK for connectivity test)
-                    Ok(())
-                }
-            }
-            Some(_) => {
-                // Other exit codes indicate server is reachable (auth issues, command issues, etc.)
-                Ok(())
-            }
-            None => {
-                // Process terminated by signal
-                Err(SshWaitError::SshConnectionTestFailed {
-                    host: host.to_string(),
-                    port,
-                    source: std::io::Error::new(
-                        std::io::ErrorKind::Interrupted,
-                        "SSH process terminated by signal",
-                    ),
-                })
-            }
+                source: std::io::Error::new(
+                    std::io::ErrorKind::ConnectionRefused,
+                    "SSH server not reachable",
+                ),
+            }),
+            Err(e) => Err(SshWaitError::SshConnectionTestFailed {
+                host: host.to_string(),
+                port,
+                source: std::io::Error::other(format!("SSH service check failed: {e}")),
+            }),
         }
     }
 }

src/shared/ssh/mod.rs

@@ -9,12 +9,14 @@
 //! - `client` - SSH client implementation for remote command execution
 //! - `connection` - SSH connection configuration and management
 //! - `credentials` - SSH authentication credentials and key management
+//! - `service_checker` - SSH service availability testing without authentication
 //!
 //! ## Key Features
 //!
 //! - Private key authentication with configurable credentials
 //! - Connection timeout and retry mechanisms
 //! - Secure remote command execution with error handling
+//! - SSH service availability checking for connectivity testing
 //! - Integration with deployment automation workflows
 //!
 //! The SSH wrapper is designed for automated deployment scenarios where
@@ -23,10 +25,12 @@
 pub mod client;
 pub mod connection;
 pub mod credentials;
+pub mod service_checker;
 
 pub use client::SshClient;
 pub use connection::SshConnection;
 pub use credentials::SshCredentials;
+pub use service_checker::SshServiceChecker;
 
 use thiserror::Error;
 

src/shared/ssh/service_checker.rs

@@ -0,0 +1,235 @@
+//! SSH Service Checker
+//!
+//! This module provides functionality to check if SSH service is available on a remote host
+//! without requiring authentication. It's designed for connectivity testing only - like a "ping"
+//! for SSH services to verify that the SSH daemon is running and accepting connections.
+//!
+//! ## Key Features
+//!
+//! - Pure connectivity testing without authentication
+//! - Minimal SSH command execution to test service availability
+//! - Distinguishes between "service not available" and "service available but auth failed"
+//! - Lightweight and focused on service discovery
+//!
+//! ## Usage
+//!
+//! ```rust,no_run
+//! use torrust_tracker_deploy::shared::ssh::SshServiceChecker;
+//!
+//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! let checker = SshServiceChecker::new();
+//! let is_available = checker.is_service_available("192.168.1.1", 22)?;
+//! if is_available {
+//!     println!("SSH service is available");
+//! } else {
+//!     println!("SSH service is not available");
+//! }
+//! # Ok(())
+//! # }
+//! ```
+
+use std::process::Command;
+use tracing::debug;
+
+/// SSH Service availability checker errors
+#[derive(Debug, thiserror::Error)]
+pub enum SshServiceError {
+    /// Command execution failed (e.g., ssh binary not found, process interrupted)
+    #[error("Failed to execute SSH service check command: {source}")]
+    CommandExecutionFailed {
+        #[source]
+        source: std::io::Error,
+    },
+}
+
+/// Result type for SSH service operations
+pub type Result<T> = std::result::Result<T, SshServiceError>;
+
+/// SSH Service Checker for testing service availability
+///
+/// This checker performs lightweight connectivity tests to determine if an SSH daemon
+/// is running and accepting connections on a given host and port. It does not attempt
+/// to authenticate or establish a working SSH session.
+///
+/// The checker uses minimal SSH commands with short timeouts and batch mode to quickly
+/// determine service availability without user interaction.
+#[derive(Debug)]
+pub struct SshServiceChecker {
+    /// Connection timeout in seconds for SSH attempts
+    connect_timeout: u16,
+}
+
+impl Default for SshServiceChecker {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl SshServiceChecker {
+    /// Create a new SSH service checker with default settings
+    ///
+    /// Default connection timeout is 5 seconds.
+    #[must_use]
+    pub fn new() -> Self {
+        Self { connect_timeout: 5 }
+    }
+
+    /// Create a new SSH service checker with custom connection timeout
+    ///
+    /// # Arguments
+    /// * `connect_timeout` - Timeout in seconds for connection attempts
+    #[must_use]
+    pub fn with_timeout(connect_timeout: u16) -> Self {
+        Self { connect_timeout }
+    }
+
+    /// Check if SSH service is available on the specified host and port
+    ///
+    /// This method attempts a minimal SSH connection to test service availability.
+    /// It distinguishes between:
+    /// - Service not available (connection refused, no route to host)
+    /// - Service available (authentication failures are considered as service available)
+    ///
+    /// # Arguments
+    /// * `host` - The hostname or IP address to test
+    /// * `port` - The SSH port to test
+    ///
+    /// # Returns
+    /// * `Ok(true)` - SSH service is available and accepting connections
+    /// * `Ok(false)` - SSH service is not available or not reachable
+    /// * `Err(SshServiceError)` - Command execution error (e.g., ssh binary not found)
+    ///
+    /// # Errors
+    /// Returns an error if the SSH command cannot be executed (e.g., ssh binary not found
+    /// or process was terminated by signal).
+    pub fn is_service_available(&self, host: &str, port: u16) -> Result<bool> {
+        debug!(
+            host = host,
+            port = port,
+            timeout = self.connect_timeout,
+            "Testing SSH service availability"
+        );
+
+        let output = Command::new("ssh")
+            .args([
+                "-o",
+                "StrictHostKeyChecking=no",
+                "-o",
+                "UserKnownHostsFile=/dev/null",
+                "-o",
+                &format!("ConnectTimeout={}", self.connect_timeout),
+                "-o",
+                "BatchMode=yes", // Non-interactive mode
+                "-p",
+                &port.to_string(),
+                &format!("test@{host}"),
+                "echo",
+                "connectivity_test",
+            ])
+            .output()
+            .map_err(|source| SshServiceError::CommandExecutionFailed { source })?;
+
+        // Analyze the command result to determine service availability
+        match output.status.code() {
+            Some(0) => {
+                // SSH command succeeded - service is definitely available
+                debug!(
+                    host = host,
+                    port = port,
+                    "SSH service available (command succeeded)"
+                );
+                Ok(true)
+            }
+            Some(255) => {
+                // Exit code 255 can indicate different scenarios
+                let stderr = String::from_utf8_lossy(&output.stderr);
+
+                if stderr.contains("Connection refused") || stderr.contains("No route to host") {
+                    // Service is not available or host is not reachable
+                    debug!(
+                        host = host,
+                        port = port,
+                        error = %stderr.trim(),
+                        "SSH service not available"
+                    );
+                    Ok(false)
+                } else {
+                    // Authentication failed, permission denied, etc. - service is available
+                    debug!(
+                        host = host,
+                        port = port,
+                        error = %stderr.trim(),
+                        "SSH service available (authentication failed)"
+                    );
+                    Ok(true)
+                }
+            }
+            Some(exit_code) => {
+                // Other non-zero exit codes typically indicate service is available
+                // but there are other issues (auth, command execution, etc.)
+                debug!(
+                    host = host,
+                    port = port,
+                    exit_code = exit_code,
+                    "SSH service available (non-zero exit code)"
+                );
+                Ok(true)
+            }
+            None => {
+                // Process was terminated by signal - treat as command execution error
+                Err(SshServiceError::CommandExecutionFailed {
+                    source: std::io::Error::new(
+                        std::io::ErrorKind::Interrupted,
+                        "SSH process terminated by signal",
+                    ),
+                })
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn it_should_create_ssh_service_checker_with_defaults() {
+        let checker = SshServiceChecker::new();
+        assert_eq!(checker.connect_timeout, 5);
+    }
+
+    #[test]
+    fn it_should_create_ssh_service_checker_with_custom_timeout() {
+        let checker = SshServiceChecker::with_timeout(10);
+        assert_eq!(checker.connect_timeout, 10);
+    }
+
+    #[test]
+    fn it_should_implement_default_trait() {
+        let checker = SshServiceChecker::default();
+        assert_eq!(checker.connect_timeout, 5);
+    }
+
+    #[test]
+    fn it_should_have_proper_error_display() {
+        let io_error = std::io::Error::new(std::io::ErrorKind::NotFound, "ssh command not found");
+        let error = SshServiceError::CommandExecutionFailed { source: io_error };
+
+        assert!(error
+            .to_string()
+            .contains("Failed to execute SSH service check command"));
+        assert!(std::error::Error::source(&error).is_some());
+    }
+
+    #[test]
+    fn it_should_support_debug_formatting() {
+        let checker = SshServiceChecker::new();
+        let debug_str = format!("{checker:?}");
+        assert!(debug_str.contains("SshServiceChecker"));
+        assert!(debug_str.contains("connect_timeout"));
+    }
+
+    // Note: We don't include integration tests that actually connect to SSH services
+    // as they would be flaky and depend on external services. The actual connectivity
+    // testing logic is documented through these unit tests and the implementation.
+}