refactor: [#272] Replace tls with domain+use_tls_proxy for HTTP API

Step 7.5.2: Apply the same TLS configuration pattern to the Tracker REST API
(HttpApiSection/HttpApiConfig) as was done for HTTP trackers in Step 7.5.1.

Changes:
- Replace `tls: Option<TlsSection>` with `domain: Option<String>` and
  `use_tls_proxy: Option<bool>` in HttpApiSection DTO
- Update HttpApiConfig domain type with `domain: Option<DomainName>` and
  `use_tls_proxy: bool` fields
- Add `uses_tls_proxy()` and `tls_domain()` helper methods to HttpApiConfig
- Update TrackerConfig::check_localhost_with_tls() validation
- Update show command to use new fields for API endpoint display
- Update all test code and doc comments to use new structure
- Update envs/manual-https-test.json with new HTTP API configuration

This is part of the incremental migration to remove the TlsSection type
and use explicit domain + use_tls_proxy fields for clearer semantics.

Author: josecelano

docs/issues/272-add-https-support-with-caddy.md

@@ -1443,15 +1443,15 @@ The implementation is split into incremental steps, one service type at a time,
 
 ##### Step 7.5.2: Tracker REST API
 
-- [ ] Add `domain: Option<String>` and `use_tls_proxy: Option<bool>` to `HttpApiSection` DTO
-- [ ] Update `HttpApiConfig` domain type
-- [ ] Add validation rules (same as HTTP trackers)
-- [ ] Update Caddy template for API
-- [ ] Update show command `ServiceInfo` for API
-- [ ] Update `envs/manual-https-test.json` for API
-- [ ] Remove `TlsSection` from API
-- [ ] Add unit tests for API validation
-- [ ] Run E2E tests
+- [x] Add `domain: Option<String>` and `use_tls_proxy: Option<bool>` to `HttpApiSection` DTO
+- [x] Update `HttpApiConfig` domain type
+- [x] Add validation rules (same as HTTP trackers)
+- [x] Update Caddy template for API
+- [x] Update show command `ServiceInfo` for API
+- [x] Update `envs/manual-https-test.json` for API
+- [x] Remove `TlsSection` from API
+- [x] Add unit tests for API validation
+- [x] Run E2E tests
 
 ##### Step 7.5.3: Tracker Health Check API
 

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

@@ -397,7 +397,7 @@ impl EnvironmentCreationConfig {
     #[must_use]
     pub fn has_any_tls_configured(&self) -> bool {
         // Check HTTP API
-        if self.tracker.http_api.tls.is_some() {
+        if self.tracker.http_api.use_tls_proxy == Some(true) {
             return true;
         }
 
@@ -513,7 +513,8 @@ impl EnvironmentCreationConfig {
                 http_api: super::tracker::HttpApiSection {
                     bind_address: "0.0.0.0:1212".to_string(),
                     admin_token: "MyAccessToken".to_string(),
-                    tls: None,
+                    domain: None,
+                    use_tls_proxy: None,
                 },
                 health_check_api: super::tracker::HealthCheckApiSection::default(),
             },
@@ -1392,7 +1393,6 @@ mod tests {
 
     #[test]
     fn it_should_return_true_for_has_any_tls_configured_when_http_api_has_tls() {
-        use crate::application::command_handlers::create::config::https::TlsSection;
         use crate::application::command_handlers::create::config::tracker::{
             DatabaseSection, HealthCheckApiSection, HttpApiSection, HttpTrackerSection,
             TrackerCoreSection, TrackerSection, UdpTrackerSection,
@@ -1416,9 +1416,8 @@ mod tests {
             http_api: HttpApiSection {
                 bind_address: "0.0.0.0:1212".to_string(),
                 admin_token: "MyAccessToken".to_string(),
-                tls: Some(TlsSection {
-                    domain: "api.tracker.example.com".to_string(),
-                }),
+                domain: Some("api.tracker.example.com".to_string()),
+                use_tls_proxy: Some(true),
             },
             health_check_api: HealthCheckApiSection::default(),
         };
@@ -1492,7 +1491,8 @@ mod tests {
             http_api: HttpApiSection {
                 bind_address: "0.0.0.0:1212".to_string(),
                 admin_token: "MyAccessToken".to_string(),
-                tls: None,
+                domain: None,
+                use_tls_proxy: None,
             },
             health_check_api: HealthCheckApiSection::default(),
         };
@@ -1582,7 +1582,8 @@ mod tests {
             http_api: HttpApiSection {
                 bind_address: "0.0.0.0:1212".to_string(),
                 admin_token: "MyAccessToken".to_string(),
-                tls: None,
+                domain: None,
+                use_tls_proxy: None,
             },
             health_check_api: HealthCheckApiSection::default(),
         };

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

@@ -4,8 +4,6 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
 use crate::application::command_handlers::create::config::errors::CreateConfigError;
-use crate::application::command_handlers::create::config::https::TlsSection;
-use crate::domain::tls::TlsConfig;
 use crate::domain::tracker::HttpApiConfig;
 use crate::shared::secrets::PlainApiToken;
 use crate::shared::DomainName;
@@ -15,12 +13,26 @@ pub struct HttpApiSection {
     pub bind_address: String,
     pub admin_token: PlainApiToken,
 
-    /// Optional TLS configuration for HTTPS
+    /// Domain name for HTTPS certificate acquisition
     ///
-    /// When present, this service will be proxied through Caddy with HTTPS enabled.
-    /// The domain specified will be used for Let's Encrypt certificate acquisition.
+    /// When present along with `use_tls_proxy: true`, this service will be
+    /// accessible via HTTPS through the Caddy reverse proxy using this domain.
+    /// The domain is used for Let's Encrypt certificate acquisition.
     #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub tls: Option<TlsSection>,
+    pub domain: Option<String>,
+
+    /// Whether to proxy this service through Caddy with TLS termination
+    ///
+    /// When `true`:
+    /// - The service is proxied through Caddy with HTTPS enabled
+    /// - `domain` field is required
+    /// - Cannot be used with localhost bind addresses (`127.0.0.1`, `::1`)
+    ///
+    /// When `false` or omitted:
+    /// - The service is accessed directly without TLS termination
+    /// - `domain` field is optional (ignored if present)
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub use_tls_proxy: Option<bool>,
 }
 
 impl HttpApiSection {
@@ -30,7 +42,8 @@ impl HttpApiSection {
     ///
     /// 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.
-    /// Returns `CreateConfigError::InvalidDomain` if the TLS domain is invalid.
+    /// Returns `CreateConfigError::InvalidDomain` if the domain is invalid.
+    /// Returns `CreateConfigError::TlsProxyWithoutDomain` if `use_tls_proxy` is true but domain is missing.
     ///
     /// Note: Localhost + TLS validation is performed at the domain layer
     /// (see `TrackerConfig::validate()`) to avoid duplicating business rules.
@@ -50,25 +63,34 @@ impl HttpApiSection {
             });
         }
 
-        // Convert TLS section to domain type with validation
-        let tls = match &self.tls {
-            Some(tls_section) => {
-                tls_section.validate()?;
-                let domain = DomainName::new(&tls_section.domain).map_err(|e| {
-                    CreateConfigError::InvalidDomain {
-                        domain: tls_section.domain.clone(),
+        let use_tls_proxy = self.use_tls_proxy.unwrap_or(false);
+
+        // Validate: use_tls_proxy: true requires domain
+        if use_tls_proxy && self.domain.is_none() {
+            return Err(CreateConfigError::TlsProxyWithoutDomain {
+                service_type: "HTTP API".to_string(),
+                bind_address: self.bind_address.clone(),
+            });
+        }
+
+        // Convert domain to domain type with validation (if present)
+        let domain = match &self.domain {
+            Some(domain_str) => {
+                let domain =
+                    DomainName::new(domain_str).map_err(|e| CreateConfigError::InvalidDomain {
+                        domain: domain_str.clone(),
                         reason: e.to_string(),
-                    }
-                })?;
-                Some(TlsConfig::new(domain))
+                    })?;
+                Some(domain)
             }
             None => None,
         };
 
         Ok(HttpApiConfig {
             bind_address,
             admin_token: self.admin_token.clone().into(),
-            tls,
+            domain,
+            use_tls_proxy,
         })
     }
 }
@@ -82,7 +104,8 @@ mod tests {
         let section = HttpApiSection {
             bind_address: "0.0.0.0:1212".to_string(),
             admin_token: "MyAccessToken".to_string(),
-            tls: None,
+            domain: None,
+            use_tls_proxy: None,
         };
 
         let result = section.to_http_api_config();
@@ -94,14 +117,16 @@ mod tests {
             "0.0.0.0:1212".parse::<SocketAddr>().unwrap()
         );
         assert_eq!(config.admin_token.expose_secret(), "MyAccessToken");
+        assert!(!config.use_tls_proxy);
     }
 
     #[test]
     fn it_should_fail_for_invalid_bind_address() {
         let section = HttpApiSection {
             bind_address: "invalid-address".to_string(),
             admin_token: "token".to_string(),
-            tls: None,
+            domain: None,
+            use_tls_proxy: None,
         };
 
         let result = section.to_http_api_config();
@@ -119,7 +144,8 @@ mod tests {
         let section = HttpApiSection {
             bind_address: "0.0.0.0:0".to_string(),
             admin_token: "token".to_string(),
-            tls: None,
+            domain: None,
+            use_tls_proxy: None,
         };
 
         let result = section.to_http_api_config();
@@ -137,7 +163,8 @@ mod tests {
         let section = HttpApiSection {
             bind_address: "0.0.0.0:1212".to_string(),
             admin_token: "MyAccessToken".to_string(),
-            tls: None,
+            domain: None,
+            use_tls_proxy: None,
         };
 
         let json = serde_json::to_string(&section).unwrap();
@@ -153,22 +180,76 @@ mod tests {
         let section: HttpApiSection = serde_json::from_str(json).unwrap();
         assert_eq!(section.bind_address, "0.0.0.0:1212");
         assert_eq!(section.admin_token, "MyAccessToken");
+        assert!(section.domain.is_none());
+        assert!(section.use_tls_proxy.is_none());
+    }
+
+    #[test]
+    fn it_should_allow_non_localhost_with_tls_proxy() {
+        let section = HttpApiSection {
+            bind_address: "0.0.0.0:1212".to_string(),
+            admin_token: "token".to_string(),
+            domain: Some("api.tracker.local".to_string()),
+            use_tls_proxy: Some(true),
+        };
+
+        let result = section.to_http_api_config();
+
+        assert!(result.is_ok());
+        let config = result.unwrap();
+        assert!(config.use_tls_proxy);
+        assert!(config.domain.is_some());
     }
 
     #[test]
-    fn it_should_allow_non_localhost_with_tls() {
+    fn it_should_reject_tls_proxy_without_domain() {
         let section = HttpApiSection {
             bind_address: "0.0.0.0:1212".to_string(),
             admin_token: "token".to_string(),
-            tls: Some(TlsSection {
-                domain: "api.tracker.local".to_string(),
-            }),
+            domain: None,
+            use_tls_proxy: Some(true),
         };
 
         let result = section.to_http_api_config();
+        assert!(result.is_err());
+
+        if let Err(CreateConfigError::TlsProxyWithoutDomain {
+            service_type,
+            bind_address,
+        }) = result
+        {
+            assert_eq!(service_type, "HTTP API");
+            assert_eq!(bind_address, "0.0.0.0:1212");
+        } else {
+            panic!("Expected TlsProxyWithoutDomain error");
+        }
+    }
+
+    #[test]
+    fn it_should_accept_domain_without_tls_proxy() {
+        // Domain provided but use_tls_proxy is false - domain is ignored
+        let section = HttpApiSection {
+            bind_address: "0.0.0.0:1212".to_string(),
+            admin_token: "token".to_string(),
+            domain: Some("api.tracker.local".to_string()),
+            use_tls_proxy: Some(false),
+        };
 
+        let result = section.to_http_api_config();
         assert!(result.is_ok());
+
         let config = result.unwrap();
-        assert!(config.tls.is_some());
+        assert!(!config.use_tls_proxy);
+        // Domain is still stored but won't be used for TLS
+        assert!(config.domain.is_some());
+    }
+
+    #[test]
+    fn it_should_deserialize_with_new_fields() {
+        let json = r#"{"bind_address":"0.0.0.0:1212","admin_token":"token","domain":"api.example.com","use_tls_proxy":true}"#;
+        let section: HttpApiSection = serde_json::from_str(json).unwrap();
+        assert_eq!(section.bind_address, "0.0.0.0:1212");
+        assert_eq!(section.domain, Some("api.example.com".to_string()));
+        assert_eq!(section.use_tls_proxy, Some(true));
     }
 }

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

@@ -134,7 +134,8 @@ impl Default for TrackerSection {
             http_api: HttpApiSection {
                 bind_address: "0.0.0.0:1212".to_string(),
                 admin_token: "MyAccessToken".to_string(),
-                tls: None,
+                domain: None,
+                use_tls_proxy: None,
             },
             health_check_api: HealthCheckApiSection::default(),
         }
@@ -169,7 +170,8 @@ mod tests {
             http_api: HttpApiSection {
                 bind_address: "0.0.0.0:1212".to_string(),
                 admin_token: "MyAccessToken".to_string(),
-                tls: None,
+                domain: None,
+                use_tls_proxy: None,
             },
             health_check_api: HealthCheckApiSection::default(),
         };
@@ -223,7 +225,8 @@ mod tests {
             http_api: HttpApiSection {
                 bind_address: "0.0.0.0:1212".to_string(),
                 admin_token: "MyAccessToken".to_string(),
-                tls: None,
+                domain: None,
+                use_tls_proxy: None,
             },
             health_check_api: HealthCheckApiSection::default(),
         };
@@ -250,7 +253,8 @@ mod tests {
             http_api: HttpApiSection {
                 bind_address: "0.0.0.0:1212".to_string(),
                 admin_token: "MyAccessToken".to_string(),
-                tls: None,
+                domain: None,
+                use_tls_proxy: None,
             },
             health_check_api: HealthCheckApiSection::default(),
         };
@@ -284,7 +288,8 @@ mod tests {
             http_api: HttpApiSection {
                 bind_address: "0.0.0.0:1212".to_string(),
                 admin_token: "MyAccessToken".to_string(),
-                tls: None,
+                domain: None,
+                use_tls_proxy: None,
             },
             health_check_api: HealthCheckApiSection::default(),
         };
@@ -347,7 +352,8 @@ mod tests {
             http_api: HttpApiSection {
                 bind_address: "0.0.0.0:7070".to_string(),
                 admin_token: "token".to_string(),
-                tls: None,
+                domain: None,
+                use_tls_proxy: None,
             },
             health_check_api: HealthCheckApiSection::default(),
         };
@@ -381,7 +387,8 @@ mod tests {
             http_api: HttpApiSection {
                 bind_address: "0.0.0.0:1212".to_string(),
                 admin_token: "token".to_string(),
-                tls: None,
+                domain: None,
+                use_tls_proxy: None,
             },
             health_check_api: HealthCheckApiSection::default(),
         };