refactor(infrastructure): [#301] extract ServiceTopology shared type

Extract common ports/networks fields into ServiceTopology type.
All Docker Compose ServiceContext types now use this shared topology
via #[serde(flatten)] to maintain template compatibility.

Makes the architectural pattern explicit:
- Topology (ports/networks) → docker-compose.yml template
- Configuration (credentials) → .env template

Changes:
- Add service_topology.rs with shared ServiceTopology struct
- Update TrackerServiceContext to embed ServiceTopology
- Update GrafanaServiceContext to embed ServiceTopology
- Update PrometheusServiceContext to embed ServiceTopology
- Update CaddyServiceContext to embed ServiceTopology
- Update MysqlServiceContext to embed ServiceTopology
- Add ports() and networks() accessor methods
- Update builder.rs to use accessor methods
- Update all tests to use accessor methods

Author: josecelano

src/infrastructure/templating/docker_compose/template/wrappers/docker_compose/context/builder.rs

@@ -218,20 +218,20 @@ impl DockerComposeContextBuilder {
         let mut networks: HashSet<Network> = HashSet::new();
 
         // Collect from tracker (always present)
-        networks.extend(tracker.networks.iter().copied());
+        networks.extend(tracker.networks().iter().copied());
 
         // Collect from optional services
         if let Some(prom) = prometheus {
-            networks.extend(prom.networks.iter().copied());
+            networks.extend(prom.networks().iter().copied());
         }
         if let Some(graf) = grafana {
-            networks.extend(graf.networks.iter().copied());
+            networks.extend(graf.networks().iter().copied());
         }
         if let Some(cad) = caddy {
-            networks.extend(cad.networks.iter().copied());
+            networks.extend(cad.networks().iter().copied());
         }
         if let Some(my) = mysql {
-            networks.extend(my.networks.iter().copied());
+            networks.extend(my.networks().iter().copied());
         }
 
         // Sort for deterministic output (alphabetically by name)
@@ -263,22 +263,22 @@ impl DockerComposeContextBuilder {
 
         // Collect ports with service names
         let service_ports: Vec<(&'static str, &[PortDefinition])> = vec![
-            ("tracker", &context.tracker.ports),
+            ("tracker", context.tracker.ports()),
             (
                 "prometheus",
-                context.prometheus.as_ref().map_or(&[][..], |p| &p.ports),
+                context.prometheus.as_ref().map_or(&[][..], |p| p.ports()),
             ),
             (
                 "grafana",
-                context.grafana.as_ref().map_or(&[][..], |g| &g.ports),
+                context.grafana.as_ref().map_or(&[][..], |g| g.ports()),
             ),
             (
                 "caddy",
-                context.caddy.as_ref().map_or(&[][..], |c| &c.ports),
+                context.caddy.as_ref().map_or(&[][..], |c| c.ports()),
             ),
             (
                 "mysql",
-                context.mysql.as_ref().map_or(&[][..], |m| &m.ports),
+                context.mysql.as_ref().map_or(&[][..], |m| m.ports()),
             ),
         ];
 

src/infrastructure/templating/docker_compose/template/wrappers/docker_compose/context/caddy.rs

@@ -20,13 +20,16 @@ use crate::domain::caddy::CaddyConfig;
 use crate::domain::topology::{EnabledServices, Network, NetworkDerivation, PortDerivation};
 
 use super::port_definition::PortDefinition;
+use super::service_topology::ServiceTopology;
 
 /// Caddy reverse proxy service configuration for Docker Compose
 ///
 /// Contains configuration for the Caddy service definition in docker-compose.yml.
 /// This is intentionally minimal - the actual Caddy configuration (domains, ports)
 /// is in the Caddyfile, rendered separately.
 ///
+/// Uses `ServiceTopology` to share the common topology structure with other services.
+///
 /// # Example
 ///
 /// ```rust
@@ -35,20 +38,16 @@ use super::port_definition::PortDefinition;
 /// use torrust_tracker_deployer_lib::domain::topology::{EnabledServices, Network};
 ///
 /// let caddy = CaddyServiceContext::from_domain_config(&CaddyConfig::new(), &EnabledServices::default());
-/// assert_eq!(caddy.networks, vec![Network::Proxy]);
-/// assert_eq!(caddy.ports.len(), 3); // 80, 443, 443/udp
+/// assert_eq!(caddy.networks(), &[Network::Proxy]);
+/// assert_eq!(caddy.ports().len(), 3); // 80, 443, 443/udp
 /// ```
 #[derive(Debug, Clone, Serialize, PartialEq)]
 pub struct CaddyServiceContext {
-    /// Port bindings for Docker Compose
-    ///
-    /// Caddy exposes ports 80 (HTTP for ACME), 443 (HTTPS), and 443/udp (QUIC).
-    pub ports: Vec<PortDefinition>,
-    /// Networks this service connects to
+    /// Service topology (ports and networks)
     ///
-    /// Caddy always connects to `proxy_network` for reverse proxying
-    /// to backend services (tracker API, HTTP trackers, Grafana).
-    pub networks: Vec<Network>,
+    /// Flattened for template compatibility - serializes ports/networks at top level.
+    #[serde(flatten)]
+    pub topology: ServiceTopology,
 }
 
 impl CaddyServiceContext {
@@ -67,7 +66,9 @@ impl CaddyServiceContext {
         let ports = port_bindings.iter().map(PortDefinition::from).collect();
         let networks = config.derive_networks(enabled_services);
 
-        Self { ports, networks }
+        Self {
+            topology: ServiceTopology::new(ports, networks),
+        }
     }
 
     /// Creates a new `CaddyServiceContext` with default configuration
@@ -77,6 +78,18 @@ impl CaddyServiceContext {
     pub fn new() -> Self {
         Self::from_domain_config(&CaddyConfig::new(), &EnabledServices::default())
     }
+
+    /// Returns a reference to the port bindings
+    #[must_use]
+    pub fn ports(&self) -> &[PortDefinition] {
+        &self.topology.ports
+    }
+
+    /// Returns a reference to the networks
+    #[must_use]
+    pub fn networks(&self) -> &[Network] {
+        &self.topology.networks
+    }
 }
 
 impl Default for CaddyServiceContext {
@@ -93,14 +106,14 @@ mod tests {
     fn it_should_connect_caddy_to_proxy_network() {
         let caddy = CaddyServiceContext::new();
 
-        assert_eq!(caddy.networks, vec![Network::Proxy]);
+        assert_eq!(caddy.networks(), &[Network::Proxy]);
     }
 
     #[test]
     fn it_should_implement_default() {
         let caddy = CaddyServiceContext::default();
 
-        assert_eq!(caddy.networks, vec![Network::Proxy]);
+        assert_eq!(caddy.networks(), &[Network::Proxy]);
     }
 
     #[test]
@@ -117,7 +130,7 @@ mod tests {
     fn it_should_expose_three_ports() {
         let caddy = CaddyServiceContext::new();
 
-        assert_eq!(caddy.ports.len(), 3);
+        assert_eq!(caddy.ports().len(), 3);
     }
 
     #[test]
@@ -138,7 +151,7 @@ mod tests {
         let caddy = CaddyServiceContext::from_domain_config(&config, &enabled_services);
 
         // Verify ports come from domain trait
-        assert_eq!(caddy.ports.len(), 3);
+        assert_eq!(caddy.ports().len(), 3);
     }
 
     #[test]
@@ -148,6 +161,6 @@ mod tests {
         let caddy = CaddyServiceContext::from_domain_config(&config, &enabled_services);
 
         // Verify networks come from domain trait
-        assert_eq!(caddy.networks, vec![Network::Proxy]);
+        assert_eq!(caddy.networks(), &[Network::Proxy]);
     }
 }

src/infrastructure/templating/docker_compose/template/wrappers/docker_compose/context/grafana.rs

@@ -7,25 +7,22 @@ use crate::domain::grafana::GrafanaConfig;
 use crate::domain::topology::{EnabledServices, Network, NetworkDerivation, PortDerivation};
 
 use super::port_definition::PortDefinition;
+use super::service_topology::ServiceTopology;
 
 /// Grafana service configuration for Docker Compose
 ///
 /// Contains configuration needed for the Grafana service definition in docker-compose.yml.
 /// Only includes fields actually used by the template (ports and networks).
 /// Credentials are handled separately by the env context for .env template.
+///
+/// Uses `ServiceTopology` to share the common topology structure with other services.
 #[derive(Serialize, Debug, Clone)]
 pub struct GrafanaServiceContext {
-    /// Port bindings for Docker Compose
-    ///
-    /// When TLS is disabled, Grafana exposes port 3000 directly.
-    /// When TLS is enabled, Caddy handles the port and this is empty.
-    pub ports: Vec<PortDefinition>,
-    /// Networks the Grafana service should connect to
+    /// Service topology (ports and networks)
     ///
-    /// Pre-computed list based on enabled features:
-    /// - Always includes `visualization_network` (queries Prometheus)
-    /// - Includes `proxy_network` if Caddy TLS proxy is enabled
-    pub networks: Vec<Network>,
+    /// Flattened for template compatibility - serializes ports/networks at top level.
+    #[serde(flatten)]
+    pub topology: ServiceTopology,
 }
 
 impl GrafanaServiceContext {
@@ -46,7 +43,21 @@ impl GrafanaServiceContext {
             .iter()
             .map(PortDefinition::from)
             .collect();
-        Self { ports, networks }
+        Self {
+            topology: ServiceTopology::new(ports, networks),
+        }
+    }
+
+    /// Returns a reference to the port bindings
+    #[must_use]
+    pub fn ports(&self) -> &[PortDefinition] {
+        &self.topology.ports
+    }
+
+    /// Returns a reference to the networks
+    #[must_use]
+    pub fn networks(&self) -> &[Network] {
+        &self.topology.networks
     }
 }
 
@@ -81,27 +92,24 @@ mod tests {
         let context = make_context(false);
         let config = GrafanaServiceContext::from_domain_config(&make_config(false), &context);
 
-        assert!(config.networks.contains(&Network::Visualization));
+        assert!(config.networks().contains(&Network::Visualization));
     }
 
     #[test]
     fn it_should_not_connect_grafana_to_proxy_network_when_caddy_disabled() {
         let context = make_context(false);
         let config = GrafanaServiceContext::from_domain_config(&make_config(false), &context);
 
-        assert_eq!(config.networks, vec![Network::Visualization]);
-        assert!(!config.networks.contains(&Network::Proxy));
+        assert_eq!(config.networks(), &[Network::Visualization]);
+        assert!(!config.networks().contains(&Network::Proxy));
     }
 
     #[test]
     fn it_should_connect_grafana_to_proxy_network_when_caddy_enabled() {
         let context = make_context(true);
         let config = GrafanaServiceContext::from_domain_config(&make_config(true), &context);
 
-        assert_eq!(
-            config.networks,
-            vec![Network::Visualization, Network::Proxy]
-        );
+        assert_eq!(config.networks(), &[Network::Visualization, Network::Proxy]);
     }
 
     #[test]
@@ -121,15 +129,15 @@ mod tests {
         let context = make_context(false);
         let config = GrafanaServiceContext::from_domain_config(&make_config(false), &context);
 
-        assert_eq!(config.ports.len(), 1);
-        assert_eq!(config.ports[0].binding(), "3000:3000");
+        assert_eq!(config.ports().len(), 1);
+        assert_eq!(config.ports()[0].binding(), "3000:3000");
     }
 
     #[test]
     fn it_should_not_expose_ports_when_tls_enabled() {
         let context = make_context(true);
         let config = GrafanaServiceContext::from_domain_config(&make_config(true), &context);
 
-        assert!(config.ports.is_empty());
+        assert!(config.ports().is_empty());
     }
 }

src/infrastructure/templating/docker_compose/template/wrappers/docker_compose/context/mod.rs

@@ -15,6 +15,7 @@ mod mysql;
 mod network_definition;
 mod port_definition;
 mod prometheus;
+mod service_topology;
 mod tracker;
 
 // Re-exports - service contexts
@@ -29,6 +30,7 @@ pub use builder::{DockerComposeContextBuilder, PortConflictError};
 pub use database::{DatabaseConfig, MysqlSetupConfig};
 pub use network_definition::NetworkDefinition;
 pub use port_definition::PortDefinition;
+pub use service_topology::ServiceTopology;
 
 /// Context for rendering the docker-compose.yml template
 ///
@@ -288,11 +290,11 @@ mod tests {
         assert_eq!(context.database().driver(), "sqlite3");
         assert!(context.database().mysql().is_none());
         // Verify ports are derived correctly (2 UDP + 1 HTTP + 1 API = 4 ports)
-        assert_eq!(context.tracker().ports.len(), 4);
-        assert_eq!(context.tracker().ports[0].binding(), "6868:6868/udp");
-        assert_eq!(context.tracker().ports[1].binding(), "6969:6969/udp");
-        assert_eq!(context.tracker().ports[2].binding(), "7070:7070");
-        assert_eq!(context.tracker().ports[3].binding(), "1212:1212");
+        assert_eq!(context.tracker().ports().len(), 4);
+        assert_eq!(context.tracker().ports()[0].binding(), "6868:6868/udp");
+        assert_eq!(context.tracker().ports()[1].binding(), "6969:6969/udp");
+        assert_eq!(context.tracker().ports()[2].binding(), "7070:7070");
+        assert_eq!(context.tracker().ports()[3].binding(), "1212:1212");
     }
 
     #[test]
@@ -320,9 +322,9 @@ mod tests {
         assert_eq!(mysql.port, 3306);
 
         // Verify ports are derived correctly (2 UDP + 1 HTTP + 1 API = 4 ports)
-        assert_eq!(context.tracker().ports.len(), 4);
-        assert_eq!(context.tracker().ports[0].binding(), "6868:6868/udp");
-        assert_eq!(context.tracker().ports[1].binding(), "6969:6969/udp");
+        assert_eq!(context.tracker().ports().len(), 4);
+        assert_eq!(context.tracker().ports()[0].binding(), "6868:6868/udp");
+        assert_eq!(context.tracker().ports()[1].binding(), "6969:6969/udp");
     }
 
     #[test]
@@ -394,7 +396,7 @@ mod tests {
             .build();
 
         assert!(context.prometheus().is_some());
-        assert!(!context.prometheus().unwrap().ports.is_empty());
+        assert!(!context.prometheus().unwrap().ports().is_empty());
     }
 
     #[test]
@@ -432,7 +434,7 @@ mod tests {
             .build();
 
         let prometheus = context.prometheus().unwrap();
-        assert_eq!(prometheus.networks, vec![Network::Metrics]);
+        assert_eq!(prometheus.networks(), &[Network::Metrics]);
     }
 
     #[test]
@@ -452,8 +454,8 @@ mod tests {
 
         let prometheus = context.prometheus().unwrap();
         assert_eq!(
-            prometheus.networks,
-            vec![Network::Metrics, Network::Visualization]
+            prometheus.networks(),
+            &[Network::Metrics, Network::Visualization]
         );
     }
 
@@ -470,7 +472,7 @@ mod tests {
             .build();
 
         let grafana = context.grafana().unwrap();
-        assert_eq!(grafana.networks, vec![Network::Visualization]);
+        assert_eq!(grafana.networks(), &[Network::Visualization]);
     }
 
     #[test]
@@ -482,14 +484,14 @@ mod tests {
         let grafana_config =
             GrafanaConfig::new("admin".to_string(), "password".to_string(), None, false);
         let context = DockerComposeContext::builder(tracker)
-            .with_grafana(grafana_config)
             .with_caddy()
+            .with_grafana(grafana_config)
             .build();
 
         let grafana = context.grafana().unwrap();
         assert_eq!(
-            grafana.networks,
-            vec![Network::Visualization, Network::Proxy]
+            grafana.networks(),
+            &[Network::Visualization, Network::Proxy]
         );
     }