Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
josecelano merged 2 commits into from
Jan 25, 2026
Merged

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

josecelano merged 2 commits into from
Jan 25, 2026
+879 −81

Conversation

@josecelano
Copy link
Member

@josecelano josecelano commented Jan 25, 2026

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):

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

@josecelano
refactor: [#298] add PortBinding domain type and cross-service port v…
943a274 
…alidation

This commit implements Phase 3 (P3.1-P3.3) of Epic #287:

P3.1 - Create Port domain types:
- Add PortBinding struct with protocol, host/container ports, host IP, description
- Reuse existing Protocol enum from domain/tracker
- Add convenience constructors: tcp(), udp(), localhost_tcp()
- Add docker_compose_binding() for YAML rendering

P3.2 - Extend ServiceTopology with ports:
- Add ports: Vec<PortBinding> to ServiceTopology
- Add new() constructor with networks and ports
- Add with_networks() backward-compatible convenience constructor
- Add ports() and has_ports() methods

P3.3 - Add cross-service port validation:
- Add validate_port_uniqueness() to DockerComposeTopology
- Create PortConflict error with actionable details
- Create TopologyError enum for topology validation errors

All PORT-* rules from the original refactoring plan are now representable
as domain types. P3.4 (template integration) is tracked separately.
@josecelano
docs: [#298] update epic and spec to reflect PR split strategy
dd3ab12 
- Split Phase 3 into two PRs for better reviewability
- PR #298: Domain foundation (P3.1-P3.3) - this PR
- Follow-up PR: Template integration (P3.4)
- Mark P3.1-P3.3 tasks as complete in spec
- Update acceptance criteria to show partial completion
- Add key decision about PR split and DDD error conventions
@josecelano josecelano self-assigned this Jan 25, 2026
@josecelano
Copy link
Member Author

josecelano commented Jan 25, 2026

ACK dd3ab12

@josecelano josecelano merged commit 24b3185 into main Jan 25, 2026
38 checks passed
@josecelano josecelano mentioned this pull request Jan 25, 2026
Open
16 tasks
@josecelano josecelano linked an issue Jan 25, 2026 that may be closed by this pull request
[Refactor] Phase 3: Create Port Topology Domain Model #298
Closed
21 tasks
@josecelano josecelano mentioned this pull request Jan 25, 2026
Closed
21 tasks
josecelano added a commit that referenced this pull request Jan 25, 2026
@josecelano
docs: [#300] add Phase 3 Port Topology Template Integration spec
0a8484c 
- Create spec for P3.4 template integration
- Update epic to mark #298 as complete with PR #299
- Add #300 as new task for template integration
- Link spec to GitHub issue #300
@josecelano josecelano mentioned this pull request Jan 25, 2026
Open
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@josecelano josecelano

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Refactor] Phase 3: Create Port Topology Domain Model

2 participants

@josecelano