feat: [#255] add socket address uniqueness validation with tiered help system

- Add BindingAddress value object combining SocketAddr with Protocol
- Add TrackerConfig::validate() method to detect socket address conflicts
- Add TrackerConfigError enum with DuplicateSocketAddress variant
- Implement tiered help system (brief Display + detailed .help() method)
- Integrate validation at DTO boundary (TrackerSection.to_tracker_config)
- Add comprehensive unit tests for validation logic
- Add integration tests for DTO validation

Follows error handling conventions from docs/contributing/error-handling.md

Author: josecelano

src/application/command_handlers/create/config/errors.rs

@@ -7,6 +7,7 @@
 use std::path::PathBuf;
 use thiserror::Error;
 
+use crate::domain::tracker::TrackerConfigError;
 use crate::domain::EnvironmentNameError;
 use crate::domain::ProfileNameError;
 use crate::shared::UsernameError;
@@ -105,6 +106,10 @@ pub enum CreateConfigError {
     /// Invalid Prometheus configuration
     #[error("Invalid Prometheus configuration: {0}")]
     InvalidPrometheusConfig(String),
+
+    /// Tracker configuration validation failed
+    #[error("Tracker configuration validation failed: {0}")]
+    TrackerConfigValidation(#[from] TrackerConfigError),
 }
 
 impl CreateConfigError {
@@ -424,6 +429,27 @@ impl CreateConfigError {
                  Note: The template automatically adds the 's' suffix (e.g., 15 becomes '15s'),\n\
                  so you only need to specify the numeric value."
             }
+            Self::TrackerConfigValidation(_) => {
+                "Tracker configuration validation failed.\n\
+                 \n\
+                 This error indicates a problem with the tracker service configuration,\n\
+                 typically related to socket address (IP:Port:Protocol) conflicts.\n\
+                 \n\
+                 The error message above provides specific details about:\n\
+                 - Which services are in conflict\n\
+                 - The conflicting socket addresses\n\
+                 - Why the configuration is invalid\n\
+                 \n\
+                 Common issues:\n\
+                 1. Multiple services on same TCP port (HTTP tracker + API)\n\
+                 2. Duplicate UDP tracker ports\n\
+                 3. Duplicate HTTP tracker ports\n\
+                 \n\
+                 Note: UDP and TCP can share the same port (different protocols),\n\
+                 but this is not recommended for clarity.\n\
+                 \n\
+                 Related: docs/external-issues/tracker/udp-tcp-port-sharing-allowed.md"
+            }
         }
     }
 }

src/application/command_handlers/create/config/tracker/tracker_section.rs

@@ -68,6 +68,7 @@ impl TrackerSection {
     /// Returns error if any of the nested sections fail validation:
     /// - Invalid bind address formats
     /// - Invalid database configuration
+    /// - Socket address conflicts (multiple services on same IP:Port:Protocol)
     pub fn to_tracker_config(&self) -> Result<TrackerConfig, CreateConfigError> {
         let core = self.core.to_tracker_core_config()?;
 
@@ -88,13 +89,18 @@ impl TrackerSection {
         let health_check_api: HealthCheckApiConfig =
             self.health_check_api.to_health_check_api_config()?;
 
-        Ok(TrackerConfig {
+        let config = TrackerConfig {
             core,
             udp_trackers: udp_trackers?,
             http_trackers: http_trackers?,
             http_api,
             health_check_api,
-        })
+        };
+
+        // Validate socket address uniqueness
+        config.validate().map_err(CreateConfigError::from)?;
+
+        Ok(config)
     }
 }
 
@@ -306,4 +312,60 @@ mod tests {
         assert_eq!(section.udp_trackers.len(), 1);
         assert_eq!(section.http_trackers.len(), 1);
     }
+
+    #[test]
+    fn it_should_reject_configuration_with_duplicate_socket_addresses() {
+        // HTTP tracker and API on same port (TCP protocol conflict)
+        let section = TrackerSection {
+            core: TrackerCoreSection {
+                database: DatabaseSection::Sqlite {
+                    database_name: "tracker.db".to_string(),
+                },
+                private: false,
+            },
+            udp_trackers: vec![],
+            http_trackers: vec![HttpTrackerSection {
+                bind_address: "0.0.0.0:7070".to_string(),
+            }],
+            http_api: HttpApiSection {
+                bind_address: "0.0.0.0:7070".to_string(),
+                admin_token: "token".to_string(),
+            },
+            health_check_api: HealthCheckApiSection::default(),
+        };
+
+        let result = section.to_tracker_config();
+        assert!(result.is_err());
+        assert!(matches!(
+            result.unwrap_err(),
+            CreateConfigError::TrackerConfigValidation(_)
+        ));
+    }
+
+    #[test]
+    fn it_should_accept_udp_and_tcp_on_same_port() {
+        // UDP and TCP can share the same port (different protocol spaces)
+        let section = TrackerSection {
+            core: TrackerCoreSection {
+                database: DatabaseSection::Sqlite {
+                    database_name: "tracker.db".to_string(),
+                },
+                private: false,
+            },
+            udp_trackers: vec![UdpTrackerSection {
+                bind_address: "0.0.0.0:7070".to_string(),
+            }],
+            http_trackers: vec![HttpTrackerSection {
+                bind_address: "0.0.0.0:7070".to_string(),
+            }],
+            http_api: HttpApiSection {
+                bind_address: "0.0.0.0:1212".to_string(),
+                admin_token: "token".to_string(),
+            },
+            health_check_api: HealthCheckApiSection::default(),
+        };
+
+        let result = section.to_tracker_config();
+        assert!(result.is_ok());
+    }
 }

src/domain/tracker/binding_address.rs

@@ -0,0 +1,143 @@
+//! Binding address value object for tracker services
+//!
+//! This module provides a type-safe representation of socket addresses
+//! with protocol information, used for validating tracker configurations.
+
+use std::fmt;
+use std::net::SocketAddr;
+
+use super::Protocol;
+
+/// A binding address combining socket address and protocol
+///
+/// Represents a complete socket binding specification including both the
+/// network address (IP + port) and the protocol (UDP or TCP). This ensures
+/// that socket address uniqueness validation accounts for protocol differences.
+///
+/// # Examples
+///
+/// ```rust
+/// use torrust_tracker_deployer_lib::domain::tracker::{BindingAddress, Protocol};
+///
+/// let udp_addr = BindingAddress::new(
+///     "0.0.0.0:6969".parse().unwrap(),
+///     Protocol::Udp
+/// );
+///
+/// let tcp_addr = BindingAddress::new(
+///     "0.0.0.0:7070".parse().unwrap(),
+///     Protocol::Tcp
+/// );
+///
+/// assert_eq!(udp_addr.socket().port(), 6969);
+/// assert_eq!(tcp_addr.protocol(), Protocol::Tcp);
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct BindingAddress {
+    socket: SocketAddr,
+    protocol: Protocol,
+}
+
+impl BindingAddress {
+    /// Creates a new binding address
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use torrust_tracker_deployer_lib::domain::tracker::{BindingAddress, Protocol};
+    ///
+    /// let addr = BindingAddress::new(
+    ///     "0.0.0.0:6969".parse().unwrap(),
+    ///     Protocol::Udp
+    /// );
+    /// ```
+    #[must_use]
+    pub fn new(socket: SocketAddr, protocol: Protocol) -> Self {
+        Self { socket, protocol }
+    }
+
+    /// Returns the socket address
+    #[must_use]
+    pub fn socket(&self) -> &SocketAddr {
+        &self.socket
+    }
+
+    /// Returns the protocol
+    #[must_use]
+    pub fn protocol(&self) -> Protocol {
+        self.protocol
+    }
+}
+
+impl fmt::Display for BindingAddress {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{} ({})", self.socket, self.protocol)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn it_should_create_binding_address_with_udp_protocol() {
+        let socket: SocketAddr = "0.0.0.0:6969".parse().unwrap();
+        let addr = BindingAddress::new(socket, Protocol::Udp);
+
+        assert_eq!(addr.socket(), &socket);
+        assert_eq!(addr.protocol(), Protocol::Udp);
+    }
+
+    #[test]
+    fn it_should_create_binding_address_with_tcp_protocol() {
+        let socket: SocketAddr = "127.0.0.1:7070".parse().unwrap();
+        let addr = BindingAddress::new(socket, Protocol::Tcp);
+
+        assert_eq!(addr.socket(), &socket);
+        assert_eq!(addr.protocol(), Protocol::Tcp);
+    }
+
+    #[test]
+    fn it_should_display_binding_address_with_protocol() {
+        let addr = BindingAddress::new("0.0.0.0:6969".parse().unwrap(), Protocol::Udp);
+        assert_eq!(addr.to_string(), "0.0.0.0:6969 (UDP)");
+
+        let addr = BindingAddress::new("127.0.0.1:7070".parse().unwrap(), Protocol::Tcp);
+        assert_eq!(addr.to_string(), "127.0.0.1:7070 (TCP)");
+    }
+
+    #[test]
+    fn it_should_consider_same_socket_different_protocol_as_different() {
+        let udp_addr = BindingAddress::new("0.0.0.0:7070".parse().unwrap(), Protocol::Udp);
+        let tcp_addr = BindingAddress::new("0.0.0.0:7070".parse().unwrap(), Protocol::Tcp);
+
+        assert_ne!(udp_addr, tcp_addr);
+    }
+
+    #[test]
+    fn it_should_consider_same_socket_same_protocol_as_equal() {
+        let addr1 = BindingAddress::new("0.0.0.0:7070".parse().unwrap(), Protocol::Tcp);
+        let addr2 = BindingAddress::new("0.0.0.0:7070".parse().unwrap(), Protocol::Tcp);
+
+        assert_eq!(addr1, addr2);
+    }
+
+    #[test]
+    fn it_should_consider_different_ips_same_port_as_different() {
+        let addr1 = BindingAddress::new("192.168.1.10:7070".parse().unwrap(), Protocol::Tcp);
+        let addr2 = BindingAddress::new("192.168.1.20:7070".parse().unwrap(), Protocol::Tcp);
+
+        assert_ne!(addr1, addr2);
+    }
+
+    #[test]
+    fn it_should_be_usable_as_hash_map_key() {
+        use std::collections::HashMap;
+
+        let mut map = HashMap::new();
+        let addr = BindingAddress::new("0.0.0.0:6969".parse().unwrap(), Protocol::Udp);
+        map.insert(addr, "UDP Tracker");
+
+        assert_eq!(map.get(&addr), Some(&"UDP Tracker"));
+    }
+}