refactor: [#300] Phase 3 Port Topology Template Integration (P3.4)

[josecelano]

Summary

Integrates the PortBinding domain types (created in #298) into the Docker Compose template rendering, completing Phase 3 of the topology refactoring.

Changes

Port Derivation (port_derivation.rs)

• Implements PORT-01 through PORT-11 rules from the refactoring plan
• derive_tracker_ports() - UDP always exposed, HTTP/API only when no TLS
• derive_caddy_ports() - Always exposes 80, 443, 443/udp
• derive_prometheus_ports() - 9090 on localhost only
• derive_grafana_ports() - 3000 only when no TLS
• derive_mysql_ports() - No exposed ports

Port Definition DTO (port_definition.rs)

• PortDefinition struct with binding and description fields
• From<&PortBinding> trait for idiomatic conversion
• Serializable for Tera template context

Service Context Updates

• Added ports: Vec<PortDefinition> to all service configs
• Tracker, Caddy, Prometheus, Grafana, MySQL all derive their ports

Template Simplification (docker-compose.yml.tera)

• Replaced conditional port logic with simple loops
• Added description comments using # {{ port.description }}
• Removed needs_ports_section checks (replaced by ports | length > 0)

Validation

• try_build() method on DockerComposeContextBuilder validates port uniqueness
• PortConflictError with help() method for actionable error messages
• DDD "always valid" pattern: DockerComposeTopology::new() returns Result

Documentation

• Created Issue [Refactor] Phase 4: Service Topology DDD Layer Alignment #301 spec for Phase 4 (DDD Layer Alignment - future work)
• Updated Epic [Epic] Docker Compose Topology Domain Model Refactoring #287 with Phase 4 tasks

Testing

• 15 unit tests for port derivation functions
• Unit tests for PortDefinition conversion
• Tests for try_build() validation
• All E2E tests pass

Rendered Output Example

services:
  tracker:
    ports:
      # BitTorrent UDP announce
      - "6969:6969/udp"
      # HTTP tracker announce
      - "7070:7070"
      # HTTP API (stats/whitelist)
      - "1212:1212"

Checklist

• Pre-commit checks pass: ./scripts/pre-commit.sh
• All PORT-* rules implemented in port derivation functions
• Port descriptions render as YAML comments in generated output
• Template uses loops over service.ports
• Cross-service port conflicts detected before rendering via try_build()
• All existing E2E tests pass

Related

• Issue: [Refactor] Phase 3: Port Topology Template Integration (P3.4) #300
• Epic: [Epic] Docker Compose Topology Domain Model Refactoring #287 - Docker Compose Topology Domain Model Refactoring
• Foundation PR: refactor: [#298] Phase 3 Port Topology Domain Model - Foundation (P3.1-P3.3) #299 (merged)
• Spec: docs/issues/300-phase-3-port-topology-template-integration.md

[josecelano]

ACK 8dcbbc9