[Refactor] Phase 3: Port Topology Template Integration (P3.4)

[josecelano]

Overview

Integrate the PortBinding domain types (created in #298) into the Docker Compose template rendering. This completes Phase 3 of the topology refactoring by moving port exposure logic from Tera template conditionals to the domain layer.

Parent Epic

• Epic: [Epic] Docker Compose Topology Domain Model Refactoring #287 - Docker Compose Topology Domain Model Refactoring
• Foundation: [Refactor] Phase 3: Create Port Topology Domain Model #298 - Phase 3 Foundation (P3.1-P3.3) ✅ Merged

Specification

See detailed specification: docs/issues/300-phase-3-port-topology-template-integration.md

Problem Statement

The current template has complex conditional logic for port exposure:

{%- if tracker.needs_ports_section %}
    ports:
      {%- for udp_tracker in tracker.udp_trackers %}
      - "{{ udp_tracker.port }}:{{ udp_tracker.port }}/udp"
      {%- endfor %}
      {%- for http_tracker_port in tracker.http_tracker_ports_without_tls %}
      - "{{ http_tracker_port }}:{{ http_tracker_port }}"
      {%- endfor %}
      {%- if not tracker.http_api_has_tls %}
      - "{{ tracker.http_api_port }}:{{ tracker.http_api_port }}"
      {%- endif %}
{%- endif %}

This should become simple loops using the PortBinding types from domain:

{%- if service.ports | length > 0 %}
    ports:
{%- for port in service.ports %}
      # {{ port.description }}
      - "{{ port.binding }}"
{%- endfor %}
{%- endif %}

Implementation Plan

P3.4.1: Create Port Derivation Functions

• Create functions to derive ports from configuration for each service
• Implement TLS-dependent port inclusion/exclusion

P3.4.2: Create Template Context Types

• Create PortDefinition struct for template rendering
• Implement conversion from PortBinding

P3.4.3: Update Context Builder

• Build DockerComposeTopology with derived ports
• Call validate_port_uniqueness() before rendering
• Remove legacy port computation

P3.4.4: Simplify Template

• Replace conditional port logic with simple loops
• Add description comments

P3.4.5: Validation Integration

• Surface port conflict errors with actionable messages

Acceptance Criteria

• All PORT-* rules from refactoring plan implemented in domain derivation
• Port descriptions render as YAML comments in output
• Template has no conditional port logic (just loops)
• Cross-service port conflicts detected before rendering
• All existing E2E tests pass
• Pre-commit checks pass: ./scripts/pre-commit.sh

Related

• Epic: [Epic] Docker Compose Topology Domain Model Refactoring #287
• Foundation: [Refactor] Phase 3: Create Port Topology Domain Model #298 → PR refactor: [#298] Phase 3 Port Topology Domain Model - Foundation (P3.1-P3.3) #299 (merged)
• Refactoring Plan: docs/refactors/plans/docker-compose-topology-domain-model.md

[josecelano]

Implemented via #302