Merge #258: feat: add socket address uniqueness validation for tracker configuration

dc153f0 refactor: [#255] eliminate duplication in binding collection (Jose Celano)
170ce02 refactor: [#255] extract conflict checking logic into separate method (Jose Celano)
97368e5 refactor: [#255] extract binding collection logic into separate method (Jose Celano)
16ade4a feat: [#255] add socket address uniqueness validation with tiered help system (Jose Celano)
981547b refactor: [#255] move database module into config/core (Jose Celano)
eca6dff refactor: [#255] extract tracker config types into submodules (Jose Celano)
ab84bbe feat: add configurable Health Check API to tracker configuration (Jose Celano)

Pull request description:

  ## Summary

  Implements socket address uniqueness validation for tracker configuration as described in issue #255. This prevents configuration errors where multiple services attempt to bind to the same socket address with the same protocol, which would result in runtime failures.

  ## Changes

  ### Core Implementation
  - **BindingAddress value object** (`src/domain/tracker/binding_address.rs`)
    - Combines `SocketAddr` with `Protocol` for type-safe binding representation
    - Implements `Hash` and `Eq` for HashMap-based duplicate detection
    - 7 comprehensive unit tests

  - **TrackerConfig validation** (`src/domain/tracker/config/mod.rs`)
    - `validate()` - Main validation orchestrator
    - `collect_bindings()` - Gathers all socket bindings with service names
    - `check_for_conflicts()` - Detects duplicate bindings
    - `register_binding()` / `register_trackers()` - DRY helper methods
    - `HasBindAddress` trait for generic tracker handling
    - 8 validation tests covering all scenarios

  - **TrackerConfigError** with tiered help system
    - Brief Display with actionable tip
    - Detailed `.help()` method for troubleshooting
    - Follows error handling conventions from `docs/contributing/error-handling.md`

  ### Integration
  - Validation integrated at DTO boundary (`TrackerSection.to_tracker_config()`)
  - Error propagation through `CreateConfigError`
  - 2 integration tests for DTO validation

  ### Validation Rules
  ✅ **Rejects**: Same protocol + same socket address
  - Multiple HTTP services on same TCP port
  - Multiple UDP trackers on same port
  - HTTP tracker + HTTP API conflict
  - HTTP tracker + Health Check API conflict

  ✅ **Allows**: Different protocols sharing same port
  - UDP tracker + HTTP tracker on same port (different protocols)
  - Same port on different IP addresses

  ## Manual E2E Testing

  Tested with real environment configurations to verify production behavior:

  ### Test Case 1: TCP Conflict ❌ (Correctly Rejected)
  **Configuration**: HTTP Tracker and HTTP API both on `0.0.0.0:7070` (TCP)

  ```json
  {
    "http_trackers": [{"bind_address": "0.0.0.0:7070"}],
    "http_api": {"bind_address": "0.0.0.0:7070", "admin_token": "..."}
  }
  ```

  **Result**:
  ```
  ❌ Configuration validation failed: Socket address conflict: 'HTTP Tracker #1', 'HTTP API' cannot bind to 0.0.0.0:7070 (TCP)
  Tip: Assign different port numbers to each service
  ```

  ### Test Case 2: UDP Conflict ❌ (Correctly Rejected)
  **Configuration**: Two UDP trackers on same address

  ```json
  {
    "udp_trackers": [
      {"bind_address": "0.0.0.0:6969"},
      {"bind_address": "0.0.0.0:6969"}
    ]
  }
  ```

  **Result**:
  ```
  ❌ Socket address conflict: 'UDP Tracker #1', 'UDP Tracker #2' cannot bind to 0.0.0.0:6969 (UDP)
  Tip: Assign different port numbers to each service
  ```

  ### Test Case 3: Valid Configuration ✅ (Correctly Accepted)
  **Configuration**: All services on unique addresses

  ```json
  {
    "udp_trackers": [{"bind_address": "0.0.0.0:6969"}],
    "http_trackers": [{"bind_address": "0.0.0.0:7070"}],
    "http_api": {"bind_address": "0.0.0.0:1212"},
    "health_check_api": {"bind_address": "127.0.0.1:1313"}
  }
  ```

  **Result**: ✅ Environment created successfully

  ### Test Case 4: Cross-Protocol ✅ (Correctly Accepted)
  **Configuration**: UDP and TCP sharing same port (different protocols)

  ```json
  {
    "udp_trackers": [{"bind_address": "0.0.0.0:7070"}],
    "http_trackers": [{"bind_address": "0.0.0.0:7070"}]
  }
  ```

  **Result**: ✅ Environment created successfully (UDP and TCP use separate port spaces)

  ## Automated Testing
  - ✅ 1613 unit tests passing
  - ✅ All linters passing (markdown, YAML, TOML, cspell, clippy, rustfmt, shellcheck)
  - ✅ Documentation builds successfully
  - ✅ E2E infrastructure lifecycle tests passing
  - ✅ E2E deployment workflow tests passing
  - ✅ Total pre-commit time: 4m 45s

  ## Code Quality Improvements
  This PR includes several refactoring commits that improve code quality:

  1. **Extract binding collection** - Separate method for gathering bindings
  2. **Extract conflict checking** - Focused method for duplicate detection
  3. **Eliminate duplication** - DRY helpers for binding registration

  **Benefits**:
  - Single Responsibility Principle compliance
  - Better testability with focused methods
  - Reduced code duplication (~30 lines → ~15 lines)
  - Clear separation of concerns
  - Easier to maintain and extend

  ## Documentation
  - Comprehensive rustdoc comments on all public APIs
  - Error help text with platform-specific troubleshooting
  - References to `docs/external-issues/tracker/udp-tcp-port-sharing-allowed.md`

  ## Related
  - Closes #255
  - Related: Socket address validation specification

ACKs for top commit:
  josecelano:
    ACK dc153f0

Tree-SHA512: e77aae9c25da50fed3aebf6bf513462f5f7b31378920a0b3bd725d454870ab0d8e3f993377a855ae599e96ea63c649f91c8158298f7aca3c7b1f5fff17308372

Author: josecelano

project-words.txt

@@ -303,3 +303,5 @@ zeroize
 ключ
 конфиг
 файл
+Datagram
+connectionless

schemas/environment-config.json

@@ -155,6 +155,17 @@
         "admin_password"
       ]
     },
+    "HealthCheckApiSection": {
+      "type": "object",
+      "properties": {
+        "bind_address": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "bind_address"
+      ]
+    },
     "HetznerProviderSection": {
       "description": "Hetzner-specific configuration section\n\nUses raw `String` fields for JSON deserialization. Convert to domain\n`HetznerConfig` via `ProviderSection::to_provider_config()`.\n\n# Examples\n\n```rust\nuse torrust_tracker_deployer_lib::application::command_handlers::create::config::HetznerProviderSection;\n\nlet section = HetznerProviderSection {\n    api_token: \"your-api-token\".to_string(),\n    server_type: \"cx22\".to_string(),\n    location: \"nbg1\".to_string(),\n    image: \"ubuntu-24.04\".to_string(),\n};\n```",
       "type": "object",
@@ -320,13 +331,17 @@
       ]
     },
     "TrackerSection": {
-      "description": "Tracker configuration section (application DTO)\n\nAggregates all tracker configuration sections: core, UDP trackers,\nHTTP trackers, and HTTP API.\n\n# Examples\n\n```json\n{\n  \"core\": {\n    \"database\": {\n      \"driver\": \"sqlite3\",\n      \"database_name\": \"tracker.db\"\n    },\n    \"private\": false\n  },\n  \"udp_trackers\": [\n    { \"bind_address\": \"0.0.0.0:6969\" }\n  ],\n  \"http_trackers\": [\n    { \"bind_address\": \"0.0.0.0:7070\" }\n  ],\n  \"http_api\": {\n    \"bind_address\": \"0.0.0.0:1212\",\n    \"admin_token\": \"MyAccessToken\"\n  }\n}\n```",
+      "description": "Tracker configuration section (application DTO)\n\nAggregates all tracker configuration sections: core, UDP trackers,\nHTTP trackers, and HTTP API.\n\n# Examples\n\n```json\n{\n  \"core\": {\n    \"database\": {\n      \"driver\": \"sqlite3\",\n      \"database_name\": \"tracker.db\"\n    },\n    \"private\": false\n  },\n  \"udp_trackers\": [\n    { \"bind_address\": \"0.0.0.0:6969\" }\n  ],\n  \"http_trackers\": [\n    { \"bind_address\": \"0.0.0.0:7070\" }\n  ],\n  \"http_api\": {\n    \"bind_address\": \"0.0.0.0:1212\",\n    \"admin_token\": \"MyAccessToken\"\n  },\n  \"health_check_api\": {\n    \"bind_address\": \"127.0.0.1:1313\"\n  }\n}\n```",
       "type": "object",
       "properties": {
         "core": {
           "description": "Core tracker configuration (database, privacy mode)",
           "$ref": "#/$defs/TrackerCoreSection"
         },
+        "health_check_api": {
+          "description": "Health Check API configuration",
+          "$ref": "#/$defs/HealthCheckApiSection"
+        },
         "http_api": {
           "description": "HTTP API configuration",
           "$ref": "#/$defs/HttpApiSection"
@@ -350,7 +365,8 @@
         "core",
         "udp_trackers",
         "http_trackers",
-        "http_api"
+        "http_api",
+        "health_check_api"
       ]
     },
     "UdpTrackerSection": {
@@ -365,4 +381,4 @@
       ]
     }
   }
-}
+}

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

@@ -67,6 +67,9 @@ use super::tracker::TrackerSection;
 ///         "http_api": {
 ///             "bind_address": "0.0.0.0:1212",
 ///             "admin_token": "MyAccessToken"
+///         },
+///         "health_check_api": {
+///             "bind_address": "127.0.0.1:1313"
 ///         }
 ///     },
 ///     "prometheus": {
@@ -417,6 +420,7 @@ impl EnvironmentCreationConfig {
                     bind_address: "0.0.0.0:1212".to_string(),
                     admin_token: "MyAccessToken".to_string(),
                 },
+                health_check_api: super::tracker::HealthCheckApiSection::default(),
             },
             prometheus: Some(PrometheusSection::default()),
             grafana: Some(GrafanaSection::default()),
@@ -572,6 +576,9 @@ mod tests {
                 "http_api": {
                     "bind_address": "0.0.0.0:1212",
                     "admin_token": "MyAccessToken"
+                },
+                "health_check_api": {
+                    "bind_address": "127.0.0.1:1313"
                 }
             }
         }"#;
@@ -633,6 +640,9 @@ mod tests {
                 "http_api": {
                     "bind_address": "0.0.0.0:1212",
                     "admin_token": "MyAccessToken"
+                },
+                "health_check_api": {
+                    "bind_address": "127.0.0.1:1313"
                 }
             }
         }"#;

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/health_check_api_section.rs

@@ -0,0 +1,125 @@
+use std::net::SocketAddr;
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use crate::application::command_handlers::create::config::errors::CreateConfigError;
+use crate::domain::tracker::HealthCheckApiConfig;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, JsonSchema)]
+pub struct HealthCheckApiSection {
+    pub bind_address: String,
+}
+
+impl HealthCheckApiSection {
+    /// Converts this DTO to a domain `HealthCheckApiConfig`
+    ///
+    /// # Errors
+    ///
+    /// Returns `CreateConfigError::InvalidBindAddress` if the bind address cannot be parsed as a valid IP:PORT combination.
+    /// Returns `CreateConfigError::DynamicPortNotSupported` if port 0 (dynamic port assignment) is specified.
+    pub fn to_health_check_api_config(&self) -> Result<HealthCheckApiConfig, CreateConfigError> {
+        // Validate that the bind address can be parsed as SocketAddr
+        let bind_address = self.bind_address.parse::<SocketAddr>().map_err(|e| {
+            CreateConfigError::InvalidBindAddress {
+                address: self.bind_address.clone(),
+                source: e,
+            }
+        })?;
+
+        // Reject port 0 (dynamic port assignment)
+        if bind_address.port() == 0 {
+            return Err(CreateConfigError::DynamicPortNotSupported {
+                bind_address: self.bind_address.clone(),
+            });
+        }
+
+        Ok(HealthCheckApiConfig { bind_address })
+    }
+}
+
+impl Default for HealthCheckApiSection {
+    fn default() -> Self {
+        Self {
+            bind_address: "127.0.0.1:1313".to_string(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn it_should_convert_to_domain_config_when_bind_address_is_valid() {
+        let section = HealthCheckApiSection {
+            bind_address: "127.0.0.1:1313".to_string(),
+        };
+
+        let config = section.to_health_check_api_config().unwrap();
+
+        assert_eq!(
+            config.bind_address,
+            "127.0.0.1:1313".parse::<SocketAddr>().unwrap()
+        );
+    }
+
+    #[test]
+    fn it_should_fail_when_bind_address_is_invalid() {
+        let section = HealthCheckApiSection {
+            bind_address: "invalid".to_string(),
+        };
+
+        let result = section.to_health_check_api_config();
+
+        assert!(result.is_err());
+        assert!(matches!(
+            result.unwrap_err(),
+            CreateConfigError::InvalidBindAddress { .. }
+        ));
+    }
+
+    #[test]
+    fn it_should_reject_dynamic_port_assignment() {
+        let section = HealthCheckApiSection {
+            bind_address: "0.0.0.0:0".to_string(),
+        };
+
+        let result = section.to_health_check_api_config();
+
+        assert!(result.is_err());
+        assert!(matches!(
+            result.unwrap_err(),
+            CreateConfigError::DynamicPortNotSupported { .. }
+        ));
+    }
+
+    #[test]
+    fn it_should_allow_ipv6_addresses() {
+        let section = HealthCheckApiSection {
+            bind_address: "[::1]:1313".to_string(),
+        };
+
+        let result = section.to_health_check_api_config();
+
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn it_should_allow_any_port_except_zero() {
+        let section = HealthCheckApiSection {
+            bind_address: "127.0.0.1:8080".to_string(),
+        };
+
+        let result = section.to_health_check_api_config();
+
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn it_should_provide_default_localhost_1313() {
+        let section = HealthCheckApiSection::default();
+
+        assert_eq!(section.bind_address, "127.0.0.1:1313");
+    }
+}

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

@@ -4,12 +4,14 @@
 //! environment creation. These types use raw primitives (String) for
 //! JSON deserialization and convert to rich domain types (`SocketAddr`).
 
+mod health_check_api_section;
 mod http_api_section;
 mod http_tracker_section;
 mod tracker_core_section;
 mod tracker_section;
 mod udp_tracker_section;
 
+pub use health_check_api_section::HealthCheckApiSection;
 pub use http_api_section::HttpApiSection;
 pub use http_tracker_section::HttpTrackerSection;
 pub use tracker_core_section::{DatabaseSection, TrackerCoreSection};