Merge #299: refactor: [#298] Phase 3 Port Topology Domain Model - Foundation (P3.1-P3.3)

dd3ab12 docs: [#298] update epic and spec to reflect PR split strategy (Jose Celano)
943a274 refactor: [#298] add PortBinding domain type and cross-service port validation (Jose Celano)

Pull request description:

  ## Summary

  This PR implements the domain layer foundation for Phase 3 of the Docker Compose Topology refactoring (Epic #287). It creates type-safe port binding types and cross-service port conflict validation, following the same pattern established for networks in Phase 1-2.

  ## Changes

  ### P3.1: Create Port Domain Types ✅

  - **Reused `Protocol` enum** from `domain/tracker/protocol.rs` (no duplication)
  - **Created `PortBinding` struct** with:
    - Private fields: `host_port`, `container_port`, `protocol`, `host_ip`, `description`
    - Convenience constructors: `tcp()`, `udp()`, `localhost_tcp()`
    - `docker_compose_binding()` method for YAML rendering (e.g., `"6969:6969/udp"`)
    - Description support for inline YAML comments
  - **10 unit tests** covering all constructors and binding formats

  ### P3.2: Extend ServiceTopology with Ports ✅

  - Added `ports: Vec<PortBinding>` field to `ServiceTopology`
  - Added `new()` constructor with ports parameter
  - Added `with_networks()` for backward compatibility
  - Made all fields private with getters (DDD compliance)
  - **4 new tests** for port functionality

  ### P3.3: Add Cross-Service Port Validation ✅

  - Created `PortConflict` error type with full context (both services, both bindings)
  - Created `TopologyError` enum with `help()` method (DDD error conventions)
  - Implemented `validate_port_uniqueness()` on `DockerComposeTopology`
  - **6 tests** covering conflict scenarios

  ## DDD Compliance

  All code follows the project's DDD practices ([docs/contributing/ddd-practices.md](docs/contributing/ddd-practices.md)):

  | Requirement | Status |
  |-------------|--------|
  | Private fields with getters | ✅ All domain types |
  | `#[must_use]` on getters | ✅ Applied |
  | Expressive errors with `help()` | ✅ `TopologyError::help()` |
  | Single point of validation | ✅ Aggregate method |

  ## What's NOT in this PR

  **P3.4 (Template Integration)** will be a follow-up PR:
  - Update `DockerComposeContext` to use derived ports
  - Simplify `docker-compose.yml.tera` port sections
  - Remove conditional port logic from template

  This split allows the domain foundation to be reviewed and merged independently.

  ## Testing

  - ✅ 20 new unit tests for port topology
  - ✅ All 2021 existing tests pass
  - ✅ All 393 doc tests pass
  - ✅ E2E infrastructure lifecycle tests pass
  - ✅ E2E deployment workflow tests pass
  - ✅ All linters pass (clippy, rustfmt, markdown, yaml, toml, cspell, shellcheck)

  ## Files Changed

  | File | Change |
  |------|--------|
  | `src/domain/topology/port.rs` | NEW - `PortBinding` struct |
  | `src/domain/topology/error.rs` | NEW - `PortConflict`, `TopologyError` |
  | `src/domain/topology/aggregate.rs` | Extended `ServiceTopology` with ports |
  | `src/domain/topology/mod.rs` | Added module exports |
  | `docs/issues/287-*.md` | Updated epic with PR split |
  | `docs/issues/298-*.md` | Updated spec with completed tasks |

  ## Related

  - Epic: #287
  - Issue: #298
  - Spec: [docs/issues/298-phase-3-port-topology-domain-model.md](docs/issues/298-phase-3-port-topology-domain-model.md)

ACKs for top commit:
  josecelano:
    ACK dd3ab12

Tree-SHA512: 408a7610a75fcf7ab82128c693f57b6cadc79ad6dbfc7de4073aca790c7719c6c62c4459a8093a0a9cab8a46e3b96e46be0caacd25169ea7079705961dd60cff

Author: josecelano

docs/issues/287-docker-compose-topology-refactoring-epic.md

@@ -38,11 +38,14 @@ Implementation follows a 5-PR strategy (original scope), with Phase 3 added as a
 ### Phase 3: Port Topology (Added Extension)
 
 > **Note**: Phase 3 was part of the original refactoring plan analysis (see PORT-01 through PORT-11 rules in [docker-compose-topology-domain-model.md](../refactors/plans/docker-compose-topology-domain-model.md#port-exposure-rules)) but was not included in the initial 5-PR strategy. It follows the same pattern as networks and completes the topology domain model.
-
-- [ ] [#298](https://github.com/torrust/torrust-tracker-deployer/issues/298) - [Refactor] Phase 3: Create Port Topology Domain Model (P3.1, P3.2, P3.3, P3.4) → [Spec](298-phase-3-port-topology-domain-model.md)
-  - P3.1: Create Port domain types (`PortBinding`, `Protocol`)
-  - P3.2: Extend `ServiceTopology` with port derivation
-  - P3.3: Add cross-service port conflict validation
+>
+> **Implementation Note**: Phase 3 is split into two PRs for better reviewability. PR #298 delivers the domain layer foundation (P3.1-P3.3), while a follow-up PR will integrate ports into the template (P3.4).
+
+- [ ] [#298](https://github.com/torrust/torrust-tracker-deployer/issues/298) - [Refactor] Phase 3: Port Topology Domain Model - Foundation (P3.1, P3.2, P3.3) → [Spec](298-phase-3-port-topology-domain-model.md)
+  - P3.1: Create Port domain types (`PortBinding`, reuse `Protocol`)
+  - P3.2: Extend `ServiceTopology` with ports field
+  - P3.3: Add cross-service port conflict validation with `help()` method
+- [ ] TBD - [Refactor] Phase 3: Port Topology Template Integration (P3.4)
   - P3.4: Update template to use derived ports with descriptions
 
 ## PR Dependencies
@@ -60,7 +63,10 @@ PR 4 (Phase 1)
 PR 5 (Phase 2)
     │
     ▼
-PR 6 (Phase 3) ◄─── Extension: Port topology (added post-completion)
+PR 6 (Phase 3 Foundation) ◄─── Domain types: PortBinding, validation, help()
+    │
+    ▼
+PR 7 (Phase 3 Template) ◄─── Template integration (P3.4) - follow-up
 ```
 
 ## Key Decisions
@@ -71,6 +77,8 @@ PR 6 (Phase 3) ◄─── Extension: Port topology (added post-completion)
 - ~47 domain rules identified with test specifications
 - Network descriptions rendered as YAML comments for sysadmin documentation
 - Port topology follows same pattern as networks (Phase 3)
+- Phase 3 split into foundation (domain) and integration (template) PRs for reviewability
+- `PortConflict` error includes `help()` method per DDD error handling conventions
 
 ## Related
 

docs/issues/298-phase-3-port-topology-domain-model.md

@@ -2,7 +2,16 @@
 
 **Epic**: [#287](https://github.com/torrust/torrust-tracker-deployer/issues/287) - Docker Compose Topology Domain Model Refactoring
 **Related Plan**: [docs/refactors/plans/docker-compose-topology-domain-model.md](../../refactors/plans/docker-compose-topology-domain-model.md)
-**Status**: Draft
+**Status**: In Progress (P3.1-P3.3 Complete)
+
+## Implementation Notes
+
+> **PR Strategy**: This phase is split into two PRs for better reviewability:
+>
+> - **PR #298 (this PR)**: Domain layer foundation - P3.1, P3.2, P3.3
+> - **Follow-up PR**: Template integration - P3.4
+>
+> The domain types are stable and well-tested. Template integration is a larger change that benefits from being a separate, focused PR.
 
 ## Overview
 
@@ -177,46 +186,60 @@ services:
 
 ## Tasks
 
-### P3.1: Create Port Domain Types
+### P3.1: Create Port Domain Types ✅
 
-- [ ] Create `Protocol` enum (or reuse from `domain/tracker`)
-- [ ] Create `PortBinding` struct with description support
-- [ ] Add `PortDefinition` context type for template rendering
-- [ ] Add unit tests for port binding creation
+- [x] Reuse `Protocol` enum from `domain/tracker/protocol.rs`
+- [x] Create `PortBinding` struct with description support
+- [x] Add convenience constructors: `tcp()`, `udp()`, `localhost_tcp()`
+- [x] Add `docker_compose_binding()` method for YAML rendering
+- [x] Add unit tests for port binding creation (10 tests)
 
-### P3.2: Extend ServiceTopology with Ports
+### P3.2: Extend ServiceTopology with Ports ✅
 
-- [ ] Add `ports: Vec<PortBinding>` to `ServiceTopology`
-- [ ] Implement port derivation for each service type:
-  - Tracker: UDP ports, HTTP ports (TLS-dependent), API (TLS-dependent)
-  - Caddy: 80, 443, 443/udp (fixed)
-  - Prometheus: 9090 (localhost)
-  - Grafana: 3000 (TLS-dependent)
-  - MySQL: none
-- [ ] Add unit tests for each service's port derivation
+- [x] Add `ports: Vec<PortBinding>` to `ServiceTopology`
+- [x] Add `new()` constructor with ports parameter
+- [x] Add `with_networks()` for backward compatibility
+- [x] Add `ports()` and `has_ports()` getters with `#[must_use]`
+- [x] Make all fields private with getters (DDD compliance)
+- [x] Add unit tests for port field (4 tests)
 
-### P3.3: Add Cross-Service Port Validation
+### P3.3: Add Cross-Service Port Validation ✅
 
-- [ ] Implement `DockerComposeTopology::validate_port_uniqueness()`
-- [ ] Create `TopologyError::PortConflict` variant
-- [ ] Add tests for conflict detection scenarios
+- [x] Implement `DockerComposeTopology::validate_port_uniqueness()`
+- [x] Create `PortConflict` error type with full context
+- [x] Create `TopologyError` enum with `help()` method (DDD error conventions)
+- [x] Add tests for conflict detection scenarios (6 tests)
 
-### P3.4: Update Template and Context
+### P3.4: Update Template and Context (Follow-up PR)
 
 - [ ] Create `PortDefinition` with `binding()` and `description()` for template
 - [ ] Update `DockerComposeContext` to use derived ports
 - [ ] Simplify `docker-compose.yml.tera` port sections
 - [ ] Remove conditional port logic from template
+- [ ] Implement port derivation for each service type:
+  - Tracker: UDP ports, HTTP ports (TLS-dependent), API (TLS-dependent)
+  - Caddy: 80, 443, 443/udp (fixed)
+  - Prometheus: 9090 (localhost)
+  - Grafana: 3000 (TLS-dependent)
+  - MySQL: none
 
 ## Acceptance Criteria
 
+### PR #298 (Domain Foundation) ✅
+
+- [x] `PortBinding` type with description support created
+- [x] `ServiceTopology` extended with ports field
+- [x] Cross-service port conflicts detected with actionable `help()` message
+- [x] All fields private with getters (DDD compliance)
+- [x] No duplication with `TrackerConfig` validation (different scopes)
+- [x] All existing E2E tests pass
+- [x] Pre-commit checks pass
+
+### Follow-up PR (Template Integration)
+
 - [ ] All PORT-\* rules from refactoring plan are implemented in domain
 - [ ] Port descriptions render as YAML comments in output
-- [ ] Cross-service port conflicts are detected and reported with actionable error
 - [ ] Template has no conditional port logic (just loops)
-- [ ] No duplication with `TrackerConfig` validation (different scopes)
-- [ ] All existing E2E tests pass
-- [ ] Pre-commit checks pass
 
 ## Testing Strategy