From a05d6011be8b952b6d08ae5535ecfe8568c735b1 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Mon, 29 Jun 2026 19:36:30 +0100 Subject: [PATCH 1/2] chore(docs): close SI-1 through SI-5 issue specs and update EPIC #1938 - Move closed issue specs from docs/issues/open/ to docs/issues/closed/ - Update frontmatter: status, spec-path, closure dates - Fix stale 'docs/issues/drafts/' references in all affected specs - Update EPIC.md: status, tables, sub-issue links, dependency tracking, progress log, success criteria to reflect completed migrations - Fix 'drafts' reference in SI-6 spec - Add SI-7 spec (#1959) for post-migration code cleanup tasks (test relocation + v1 namespace alignment) --- ...-1938-si-1-migrate-health-check-context.md | 10 +- ...940-1938-si-2-migrate-whitelist-context.md | 10 +- ...1941-1938-si-3-migrate-auth-key-context.md | 14 +- .../1942-1938-si-4-migrate-stats-context.md | 15 +- ...1943-1938-si-5-deprecate-rest-api-core.md} | 5 +- .../EPIC.md | 164 ++++++++---------- .../1944-1938-si-6-align-rest-api-client.md | 2 +- ...38-si-7-review-tests-align-v1-namespace.md | 116 +++++++++++++ 8 files changed, 214 insertions(+), 122 deletions(-) rename docs/issues/{open => closed}/1939-1938-si-1-migrate-health-check-context.md (95%) rename docs/issues/{open => closed}/1940-1938-si-2-migrate-whitelist-context.md (96%) rename docs/issues/{open => closed}/1941-1938-si-3-migrate-auth-key-context.md (96%) rename docs/issues/{open => closed}/1942-1938-si-4-migrate-stats-context.md (96%) rename docs/issues/{open/1943-1938-si-5-deprecate-rest-api-core/ISSUE.md => closed/1943-1938-si-5-deprecate-rest-api-core.md} (97%) create mode 100644 docs/issues/open/1959-1938-si-7-review-tests-align-v1-namespace.md diff --git a/docs/issues/open/1939-1938-si-1-migrate-health-check-context.md b/docs/issues/closed/1939-1938-si-1-migrate-health-check-context.md similarity index 95% rename from docs/issues/open/1939-1938-si-1-migrate-health-check-context.md rename to docs/issues/closed/1939-1938-si-1-migrate-health-check-context.md index a046348d1..cf7477b35 100644 --- a/docs/issues/open/1939-1938-si-1-migrate-health-check-context.md +++ b/docs/issues/closed/1939-1938-si-1-migrate-health-check-context.md @@ -1,18 +1,18 @@ --- doc-type: spec issue-type: task -status: planned +status: completed priority: p1 epic: 1938 github-issue: 1939 -spec-path: docs/issues/open/1939-1938-si-1-migrate-health-check-context.md -last-updated-utc: 2026-06-24 - updated-reason: Updated to reference context/ module structure instead of resources/ +spec-path: docs/issues/closed/1939-1938-si-1-migrate-health-check-context.md +last-updated-utc: 2026-06-25 + updated-reason: Closed — issue implemented semantic-links: skill-links: - create-issue related-artifacts: - - docs/issues/drafts/rest-api-contract-first-migration/EPIC.md + - docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md - packages/axum-rest-api-server/src/v1/context/health_check/ - packages/axum-rest-api-server/src/routes.rs - packages/rest-api-protocol/src/v1/ diff --git a/docs/issues/open/1940-1938-si-2-migrate-whitelist-context.md b/docs/issues/closed/1940-1938-si-2-migrate-whitelist-context.md similarity index 96% rename from docs/issues/open/1940-1938-si-2-migrate-whitelist-context.md rename to docs/issues/closed/1940-1938-si-2-migrate-whitelist-context.md index bcc4db4d9..a09c75382 100644 --- a/docs/issues/open/1940-1938-si-2-migrate-whitelist-context.md +++ b/docs/issues/closed/1940-1938-si-2-migrate-whitelist-context.md @@ -1,18 +1,18 @@ --- doc-type: spec issue-type: task -status: planned +status: completed priority: p1 epic: 1938 github-issue: 1940 -spec-path: docs/issues/open/1940-1938-si-2-migrate-whitelist-context.md -last-updated-utc: 2026-06-24 - updated-reason: Added normalized module structure convention note +spec-path: docs/issues/closed/1940-1938-si-2-migrate-whitelist-context.md +last-updated-utc: 2026-06-26 + updated-reason: Closed — issue implemented semantic-links: skill-links: - create-issue related-artifacts: - - docs/issues/drafts/rest-api-contract-first-migration/EPIC.md + - docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md - packages/axum-rest-api-server/src/v1/context/whitelist/ - packages/rest-api-protocol/src/v1/ - packages/rest-api-application/src/ diff --git a/docs/issues/open/1941-1938-si-3-migrate-auth-key-context.md b/docs/issues/closed/1941-1938-si-3-migrate-auth-key-context.md similarity index 96% rename from docs/issues/open/1941-1938-si-3-migrate-auth-key-context.md rename to docs/issues/closed/1941-1938-si-3-migrate-auth-key-context.md index 5b530eb7c..6b72f90cd 100644 --- a/docs/issues/open/1941-1938-si-3-migrate-auth-key-context.md +++ b/docs/issues/closed/1941-1938-si-3-migrate-auth-key-context.md @@ -1,18 +1,18 @@ --- doc-type: spec issue-type: task -status: planned +status: completed priority: p1 epic: 1938 github-issue: 1941 -spec-path: docs/issues/open/1941-1938-si-3-migrate-auth-key-context.md -last-updated-utc: 2026-06-24 - updated-reason: Updated paths to context/ and added module structure convention note +spec-path: docs/issues/closed/1941-1938-si-3-migrate-auth-key-context.md +last-updated-utc: 2026-06-26 + updated-reason: Closed — issue implemented semantic-links: skill-links: - create-issue related-artifacts: - - docs/issues/drafts/rest-api-contract-first-migration/EPIC.md + - docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md - packages/axum-rest-api-server/src/v1/context/auth_key/ - packages/rest-api-protocol/src/v1/ - packages/rest-api-application/src/ @@ -122,8 +122,8 @@ See the `torrent` and `health_check` contexts for the reference pattern. - [x] `AuthKeyApiService` use-case implemented - [x] `TrackerAuthKeyAdapter` implemented in `rest-api-runtime-adapter` - [x] Axum handlers dispatch through use-case -- [ ] Pre-commit checks pass -- [ ] Pre-push checks pass +- [x] Pre-commit checks pass +- [x] Pre-push checks pass ### Progress Log diff --git a/docs/issues/open/1942-1938-si-4-migrate-stats-context.md b/docs/issues/closed/1942-1938-si-4-migrate-stats-context.md similarity index 96% rename from docs/issues/open/1942-1938-si-4-migrate-stats-context.md rename to docs/issues/closed/1942-1938-si-4-migrate-stats-context.md index d28a57e25..ec052d000 100644 --- a/docs/issues/open/1942-1938-si-4-migrate-stats-context.md +++ b/docs/issues/closed/1942-1938-si-4-migrate-stats-context.md @@ -1,18 +1,18 @@ --- doc-type: spec issue-type: task -status: planned +status: completed priority: p1 epic: 1938 github-issue: 1942 -spec-path: docs/issues/open/1942-1938-si-4-migrate-stats-context.md -last-updated-utc: 2026-06-24 - updated-reason: Updated paths to context/ and added module structure convention note +spec-path: docs/issues/closed/1942-1938-si-4-migrate-stats-context.md +last-updated-utc: 2026-06-27 + updated-reason: Closed — issue implemented semantic-links: skill-links: - create-issue related-artifacts: - - docs/issues/drafts/rest-api-contract-first-migration/EPIC.md + - docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md - packages/axum-rest-api-server/src/v1/context/stats/ - packages/rest-api-protocol/src/v1/ - packages/rest-api-application/src/ @@ -174,7 +174,7 @@ The use-case maps domain errors to protocol error codes and returns protocol DTO | T7 | DONE | Rewire Axum handlers to use `StatsApiService` | No more tuple-state or rest-api-core calls | | T8 | DONE | Update Axum state to inject `TrackerStatsAdapter` (replacing 6+ tuples) | Single `Arc` in `v1/routes.rs` | | T9 | DONE | Remove direct internal deps from `axum-rest-api-server` stats wiring | 7+ tuple-state removed, handler uses only service | -| T10 | TODO | Verify pre-commit and pre-push checks pass | | +| T10 | DONE | Verify pre-commit and pre-push checks pass | | ## Verification / Progress @@ -186,7 +186,7 @@ The use-case maps domain errors to protocol error codes and returns protocol DTO - [x] Axum handlers dispatch through use-case - [x] Direct internal crate deps removed from Axum server stats wiring - [x] Pre-commit checks pass -- [ ] Pre-push checks pass +- [x] Pre-push checks pass ### Progress Log @@ -194,3 +194,4 @@ The use-case maps domain errors to protocol error codes and returns protocol DTO | ---------- | ---------------------------------------------------------------------------------------- | | 2026-06-24 | Draft spec created | | 2026-06-26 | Stats context migrated to contract-first architecture (Option 3: aggregation in adapter) | +| 2026-06-27 | Issue closed on GitHub — all checks passing | diff --git a/docs/issues/open/1943-1938-si-5-deprecate-rest-api-core/ISSUE.md b/docs/issues/closed/1943-1938-si-5-deprecate-rest-api-core.md similarity index 97% rename from docs/issues/open/1943-1938-si-5-deprecate-rest-api-core/ISSUE.md rename to docs/issues/closed/1943-1938-si-5-deprecate-rest-api-core.md index dc09d63d6..77b431c50 100644 --- a/docs/issues/open/1943-1938-si-5-deprecate-rest-api-core/ISSUE.md +++ b/docs/issues/closed/1943-1938-si-5-deprecate-rest-api-core.md @@ -5,13 +5,14 @@ status: completed priority: p2 epic: 1938 github-issue: 1943 -spec-path: docs/issues/open/1943-1938-si-5-deprecate-rest-api-core/ISSUE.md +spec-path: docs/issues/closed/1943-1938-si-5-deprecate-rest-api-core.md last-updated-utc: 2026-06-29 + updated-reason: Closed — issue implemented semantic-links: skill-links: - create-issue related-artifacts: - - docs/issues/drafts/rest-api-contract-first-migration/EPIC.md + - docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md - packages/rest-api-core/ - packages/rest-api-runtime-adapter/ - packages/rest-api-application/ diff --git a/docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md b/docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md index 4acc0fba2..f52f1ee9c 100644 --- a/docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md +++ b/docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md @@ -1,13 +1,13 @@ --- doc-type: epic issue-type: task -status: planned +status: in_progress priority: p1 epic: 1938 github-issue: 1938 spec-path: docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md epic-owner: josecelano -last-updated-utc: 2026-06-24 +last-updated-utc: 2026-06-29 semantic-links: skill-links: - create-issue @@ -28,23 +28,22 @@ semantic-links: ## Goal -Progressively migrate all remaining REST API contexts (`health_check`, `whitelist`, `auth_key`, `stats`) from direct tracker-internal wiring to the contract-first layered architecture (protocol → application → runtime-adapter → axum transport), following the pattern validated by [SI-33 (#1930)](../../open/1930-1669-si-33-rest-api-contract-first-architecture.md) PoC. +Migrate all remaining REST API contexts (`health_check`, `whitelist`, `auth_key`, `stats`) from direct tracker-internal wiring to the contract-first layered architecture (protocol → application → runtime-adapter → axum transport), following the pattern validated by [SI-33 (#1930)](../../open/1930-1669-si-33-rest-api-contract-first-architecture.md) PoC. -## Why This Is Needed +All context migrations are **complete** (SI-1 through SI-5 closed). The only remaining open item is SI-6 (`ApiClient` high-level typed client). -[SI-33](../../open/1930-1669-si-33-rest-api-contract-first-architecture.md) validated the contract-first architecture with a single endpoint (torrent detail). The remaining contexts still have the old coupling: +## Why This Is Needed -- Axum handlers call tracker internals directly (`tracker-core`, `udp-core`, `http-core`, `udp-server`). -- DTO/response types are defined locally in the Axum server, not in `rest-api-protocol`. -- No port traits or use-case services exist for these contexts. -- The forbidden dependency edges (`axum-rest-api-server → tracker-core` etc.) still exist for non-torrent contexts. +Before this EPIC, the REST API had a mixture of architectures: -Migrating all contexts to the new architecture will: +- **`torrent` context** (SI-33 PoC) already used the contract-first architecture. +- **All other contexts** (`health_check`, `whitelist`, `auth_key`, `stats`) still had the old coupling: + - Axum handlers calling tracker internals directly (`tracker-core`, `udp-core`, `http-core`, `udp-server`). + - DTO/response types defined locally in the Axum server, not in `rest-api-protocol`. + - No port traits or use-case services existed for these contexts. + - Forbidden dependency edges (`axum-rest-api-server → tracker-core` etc.) still existed for non-torrent contexts. -- Allow removing direct internal crate dependencies from `axum-rest-api-server` (currently 7+ internal crate deps for non-torrent contexts). -- Make each context testable at the application layer without Axum. -- Provide a clear path toward a tracker-agnostic REST API standard. -- Complete the architectural vision started by SI-33. +This EPIC eliminated that coupling. The remaining open item (SI-6) is about improving the client API, not the server architecture. ## Relationship to SI-33 @@ -54,14 +53,15 @@ This EPIC is the follow-up work identified in [SI-33](../../open/1930-1669-si-33 The contexts are ordered by complexity and dependency depth. Follow-up tasks (SI-5, SI-6) come after all contexts are migrated: -| Order | Context / Task | Effort | Handlers | Tracker Deps | Rationale | -| ----- | ------------------------------- | ------ | -------- | ------------------------ | ------------------------------------------------ | -| 1 | SI-1: `health_check` | Small | 1 | None | Trivial starter — no tracker deps | -| 2 | SI-2: `whitelist` | Medium | 3 | `tracker-core` only | Clean pattern, no DTOs needed | -| 3 | SI-3: `auth_key` | Medium | 4 | `tracker-core` + `clock` | Form DTOs + validation, 4 endpoints | -| 4 | SI-4: `stats` | Large | 2 | 5+ crates | 28-field DTO, Prometheus, multi-repo aggregation | -| 5 | SI-5: deprecate `rest-api-core` | Small | — | — | Cleanup after all contexts migrated | -| 6 | SI-6: introduce `ApiClient` | Medium | — | — | Typed high-level wrapper over `ApiHttpClient` | +| Order | Context / Task | Effort | Handlers | Tracker Deps | Status | +| ----- | -------------------------------- | ------ | -------- | ------------------------ | ------ | +| 1 | SI-1: `health_check` | Small | 1 | None | ✅ | +| 2 | SI-2: `whitelist` | Medium | 3 | `tracker-core` only | ✅ | +| 3 | SI-3: `auth_key` | Medium | 4 | `tracker-core` + `clock` | ✅ | +| 4 | SI-4: `stats` | Large | 2 | 5+ crates | ✅ | +| 5 | SI-5: deprecate `rest-api-core` | Small | — | — | ✅ | +| 6 | SI-6: introduce `ApiClient` | Medium | — | — | ❌ | +| 7 | SI-7: review tests + align v1 ns | Small | — | — | 🏗️ | ## Context Status Summary @@ -69,63 +69,28 @@ The contexts are ordered by complexity and dependency depth. Follow-up tasks (SI | ------------------------------- | :-----------: | :------------: | :---------: | :-------: | :--------------: | --------------------------------------------------------------------------------- | | `torrent` | 2 ✅ done | ✅ | ✅ | ✅ | ✅ | Reference pattern — lives under `v1::context::torrent::resources::torrent` | | SI-1: `health_check` | 1 ✅ done | ✅ | ❌ N/A | ❌ N/A | ❌ N/A | No tracker deps — DTOs under `v1::context::health_check::resources::health_check` | -| SI-2: `whitelist` | 3 | ❌ | ❌ | ❌ | ❌ | Reuses `ActionStatus` | -| SI-3: `auth_key` | 4 | ❌ | ❌ | ❌ | ❌ | Form DTOs + `clock` | -| SI-4: `stats` | 2 | ❌ | ❌ | ❌ | ❌ | 28-field DTO, SI-30 traits | -| SI-5: deprecate `rest-api-core` | — | — | — | — | — | Post-migration cleanup | -| SI-6: introduce `ApiClient` | — | — | — | — | — | Typed wrapper over `ApiHttpClient` | +| SI-2: `whitelist` | 3 ✅ done | ✅ | ✅ | ✅ | ✅ | Reuses `ActionStatus` | +| SI-3: `auth_key` | 4 ✅ done | ✅ | ✅ | ✅ | ✅ | Form DTOs + `clock` | +| SI-4: `stats` | 2 ✅ done | ✅ | ✅ | ✅ | ✅ | 28-field DTO, SI-30 traits | +| SI-5: deprecate `rest-api-core` | — | — | — | — | — | ✅ done — crate removed from workspace | +| SI-6: introduce `ApiClient` | — | — | — | — | — | ❌ pending — typed wrapper over `ApiHttpClient` | ## Scope -### In Scope - -- Create protocol DTOs (request/response/error types) in `rest-api-protocol` for each remaining context. - Each context follows a normalized module structure under `packages/rest-api-protocol/src/v1/context/`: - - ```text - context/ - └── / - ├── mod.rs # context docs + pub mod resources; - └── resources/ - ├── mod.rs # pub mod ; - └── .rs # DTO definitions - ``` - - See the `torrent` context for the reference pattern. - -- Define port traits in `rest-api-application` for each context's query/command operations. - These are flat files named after the context in `packages/rest-api-application/src/ports/`: - - ```text - ports/ - ├── mod.rs # pub mod torrent; pub mod whitelist; ... - └── .rs # port trait definition - ``` - -- Implement use-case services in `rest-api-application`. - Similarly flat files in `packages/rest-api-application/src/use_cases/`: - - ```text - use_cases/ - ├── mod.rs # pub mod torrent; pub mod whitelist; ... - └── .rs # use-case service implementation - ``` - -- Implement runtime adapters in `rest-api-runtime-adapter` wrapping tracker internals. - Flat files in `packages/rest-api-runtime-adapter/src/adapters/`: +### In Scope (completed for SI-1 through SI-5) - ```text - adapters/ - ├── mod.rs # pub mod torrent; pub mod whitelist; ... - └── .rs # adapter implementation - ``` +The following scope items have been completed across sub-issues SI-1 through SI-5: -- Rewire Axum handlers to dispatch through use cases instead of direct internals. -- Update tests to use adapter conversion functions. -- Remove internal crate dependencies from `axum-rest-api-server` as contexts are migrated. -- Update `deny.toml` layer bans as dependencies are removed. -- Deprecate and clean up `rest-api-core` after all contexts are migrated (SI-5). -- Introduce `ApiClient` — a high-level typed client wrapping `ApiHttpClient` with protocol DTOs (SI-6). +- ✅ Create protocol DTOs (request/response/error types) in `rest-api-protocol` for each context. +- ✅ Define port traits in `rest-api-application` for each context's operations. +- ✅ Implement use-case services in `rest-api-application`. +- ✅ Implement runtime adapters in `rest-api-runtime-adapter` wrapping tracker internals. +- ✅ Rewire Axum handlers to dispatch through use cases instead of direct internals. +- ✅ Remove internal crate dependencies from `axum-rest-api-server` as contexts were migrated. +- ✅ Update `deny.toml` layer bans as dependencies were removed. +- ✅ Deprecate and clean up `rest-api-core` (SI-5). +- ❌ **SI-6 (pending)**: Introduce `ApiClient` — a high-level typed client wrapping `ApiHttpClient` with protocol DTOs. +- 🏗️ **SI-7 (in progress)**: Review tests and align v1 namespace across REST API packages. ### Out of Scope @@ -137,12 +102,13 @@ The contexts are ordered by complexity and dependency depth. Follow-up tasks (SI ## Sub-issues -- [#1939](https://github.com/torrust/torrust-tracker/issues/1939) — [SI-1](../1939-1938-si-1-migrate-health-check-context.md): Migrate `health_check` context -- [#1940](https://github.com/torrust/torrust-tracker/issues/1940) — [SI-2](../1940-1938-si-2-migrate-whitelist-context.md): Migrate `whitelist` context -- [#1941](https://github.com/torrust/torrust-tracker/issues/1941) — [SI-3](../1941-1938-si-3-migrate-auth-key-context.md): Migrate `auth_key` context -- [#1942](https://github.com/torrust/torrust-tracker/issues/1942) — [SI-4](../1942-1938-si-4-migrate-stats-context.md): Migrate `stats` context -- [#1943](https://github.com/torrust/torrust-tracker/issues/1943) — [SI-5](../1943-1938-si-5-deprecate-rest-api-core/ISSUE.md): Deprecate `rest-api-core` and remove from workspace +- [#1939](https://github.com/torrust/torrust-tracker/issues/1939) — [SI-1](../../closed/1939-1938-si-1-migrate-health-check-context.md): Migrate `health_check` context ✅ closed +- [#1940](https://github.com/torrust/torrust-tracker/issues/1940) — [SI-2](../../closed/1940-1938-si-2-migrate-whitelist-context.md): Migrate `whitelist` context ✅ closed +- [#1941](https://github.com/torrust/torrust-tracker/issues/1941) — [SI-3](../../closed/1941-1938-si-3-migrate-auth-key-context.md): Migrate `auth_key` context ✅ closed +- [#1942](https://github.com/torrust/torrust-tracker/issues/1942) — [SI-4](../../closed/1942-1938-si-4-migrate-stats-context.md): Migrate `stats` context ✅ closed +- [#1943](https://github.com/torrust/torrust-tracker/issues/1943) — [SI-5](../../closed/1943-1938-si-5-deprecate-rest-api-core.md): Deprecate `rest-api-core` and remove from workspace ✅ closed - [#1944](https://github.com/torrust/torrust-tracker/issues/1944) — [SI-6](../1944-1938-si-6-align-rest-api-client.md): Introduce `ApiClient` — a high-level typed client over protocol DTOs +- [#1959](https://github.com/torrust/torrust-tracker/issues/1959) — [SI-7](../1959-1938-si-7-review-tests-align-v1-namespace.md): Review tests and align v1 namespace across REST API packages ## Contract Evolution Governance @@ -166,26 +132,28 @@ Types that are not exposed over the wire (e.g., internal Rust enums used only fo ## Dependency Removal Tracking -The following table maps each internal crate dependency to the sub-issue that removes it from `axum-rest-api-server/Cargo.toml`: +The following table maps each internal crate dependency to the sub-issue that removed it from `axum-rest-api-server/Cargo.toml`: -| Dependency | Removed by | Notes | -| ----------------------------- | ---------------------------------- | -------------------------------------------------- | -| `tracker-core` | SI-2 (whitelist) + SI-3 (auth_key) | Both contexts must finish | -| `http-core` | SI-4 (stats) | Via stats repository port | -| `udp-core` | SI-4 (stats) | Via SI-30 `BanningStats`, `UdpCoreStatsRepository` | -| `udp-server` | SI-4 (stats) | Via SI-30 `UdpServerStatsRepository` | -| `rest-api-core` | SI-5 (deprecate) | After all contexts migrated | -| `swarm-coordination-registry` | SI-4 (stats) | Via stats repository port | -| `clock` | SI-3 (auth_key) | Moved to runtime adapter | +| Dependency | Removed by | Status | +| ----------------------------- | ---------------------------------- | ------ | +| `tracker-core` | SI-2 (whitelist) + SI-3 (auth_key) | ✅ | +| `http-core` | SI-4 (stats) | ✅ | +| `udp-core` | SI-4 (stats) | ✅ | +| `udp-server` | SI-4 (stats) | ✅ | +| `rest-api-core` | SI-5 (deprecate) | ✅ | +| `swarm-coordination-registry` | SI-4 (stats) | ✅ | +| `clock` | SI-3 (auth_key) | ✅ | ## Success Criteria -- All 10 non-torrent Axum handler functions dispatch through application use-case services. -- All response DTOs live in `rest-api-protocol`; none are defined locally in Axum server. -- All direct `tracker-core`, `udp-core`, `http-core`, `udp-server`, `rest-api-core`, and `swarm-coordination-registry` imports are removed from `axum-rest-api-server`. -- `deny.toml` layer bans enforce the new dependency rules. -- All pre-commit and pre-push checks pass. -- Integration tests continue to pass without behavioural changes. +- ✅ All 10 non-torrent Axum handler functions dispatch through application use-case services. +- ✅ All response DTOs live in `rest-api-protocol`; none are defined locally in Axum server. +- ✅ All direct `tracker-core`, `udp-core`, `http-core`, `udp-server`, `rest-api-core`, and `swarm-coordination-registry` imports are removed from `axum-rest-api-server`. +- ✅ `deny.toml` layer bans enforce the new dependency rules. +- ✅ All pre-commit and pre-push checks pass. +- ✅ Integration tests continue to pass without behavioural changes. +- ❌ **SI-6 pending**: Introduce `ApiClient` high-level typed client. +- 🏗️ **SI-7 in progress**: Review tests and align v1 namespace. ## Progress Tracking @@ -196,3 +164,9 @@ The following table maps each internal crate dependency to the sub-issue that re | 2026-06-24 | Draft EPIC created after SI-33 PoC validation | | 2026-06-24 | SI-1 (health_check) implemented — protocol DTOs migrated | | 2026-06-24 | Specs updated to document normalized `context/` module structure for all protocol DTOs | +| 2026-06-25 | SI-1 closed on GitHub | +| 2026-06-26 | SI-2 (whitelist) and SI-3 (auth_key) closed on GitHub | +| 2026-06-27 | SI-4 (stats) closed on GitHub | +| 2026-06-29 | SI-5 (rest-api-core deprecation) closed on GitHub | +| 2026-06-29 | Closed issue specs moved to `docs/issues/closed/` with updated frontmatter | +| 2026-06-29 | SI-7 (review tests + align v1 ns) added — remaining task: SI-6 (ApiClient) | diff --git a/docs/issues/open/1944-1938-si-6-align-rest-api-client.md b/docs/issues/open/1944-1938-si-6-align-rest-api-client.md index 7c22b7329..3d4de21ce 100644 --- a/docs/issues/open/1944-1938-si-6-align-rest-api-client.md +++ b/docs/issues/open/1944-1938-si-6-align-rest-api-client.md @@ -11,7 +11,7 @@ semantic-links: skill-links: - create-issue related-artifacts: - - docs/issues/drafts/rest-api-contract-first-migration/EPIC.md + - docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md - packages/rest-api-client/ - packages/rest-api-protocol/ - packages/rest-api-client/src/v1/client.rs diff --git a/docs/issues/open/1959-1938-si-7-review-tests-align-v1-namespace.md b/docs/issues/open/1959-1938-si-7-review-tests-align-v1-namespace.md new file mode 100644 index 000000000..3b1af141d --- /dev/null +++ b/docs/issues/open/1959-1938-si-7-review-tests-align-v1-namespace.md @@ -0,0 +1,116 @@ +--- +doc-type: spec +issue-type: task +status: planned +priority: p3 +epic: 1938 +github-issue: 1959 +spec-path: docs/issues/open/1959-1938-si-7-review-tests-align-v1-namespace.md +last-updated-utc: 2026-06-29 +semantic-links: + skill-links: + - create-issue + related-artifacts: + - docs/issues/open/1938-rest-api-contract-first-migration/EPIC.md + - packages/axum-rest-api-server/src/v1/context/torrent/resources/torrent.rs + - packages/axum-rest-api-server/src/v1/context/torrent/resources/peer.rs + - packages/rest-api-runtime-adapter/src/conversion.rs + - packages/rest-api-application/src/ + - packages/rest-api-runtime-adapter/src/ + - packages/rest-api-protocol/src/ + - packages/axum-rest-api-server/src/ + - packages/rest-api-client/src/ +--- + + + +# SI-7: Review tests and align v1 namespace across REST API packages + +## Subissue of REST API Contract-First Migration EPIC + +## Problem + +During the contract-first migration (SI-1 through SI-5), production code was moved from `axum-rest-api-server` to the new layered packages (`rest-api-protocol`, `rest-api-application`, `rest-api-runtime-adapter`). However, some unit tests were left behind in the wrong package, and the `v1` namespace is not consistently applied across all packages. + +### Issue 1: Tests in wrong packages + +The file `packages/axum-rest-api-server/src/v1/context/torrent/resources/torrent.rs` contains two unit tests that test functions defined in `rest-api-runtime-adapter::conversion`: + +- `torrent_resource_should_be_converted_from_torrent_info()` — tests `conversion::from_domain_info()` +- `torrent_resource_list_item_should_be_converted_from_the_basic_torrent_info()` — tests `conversion::list_item_from_domain()` + +These tests should live alongside the production code they test, in `rest-api-runtime-adapter`. + +Additionally, `packages/axum-rest-api-server/src/v1/context/torrent/resources/peer.rs` is a stub file containing only a doc comment saying _"Protocol DTOs are defined in `rest-api-protocol`."_ — it has no production code and should be removed. + +A review of the whole `axum-rest-api-server` package is needed to identify all such cases. + +### Issue 2: Inconsistent v1 namespace + +The API packages use the `v1` module inconsistently: + +| Package | Has `v1` module? | Notes | +| -------------------------- | ------------------ | -------------------------------------------- | +| `rest-api-protocol` | ✅ `src/v1/mod.rs` | Canonical home for v1 DTOs | +| `axum-rest-api-server` | ✅ `src/v1/` | Axum handlers, routes, responses | +| `rest-api-client` | ✅ `src/v1/` | Client for v1 endpoints | +| `rest-api-application` | ❌ No `v1` | Ports and use-cases at top level | +| `rest-api-runtime-adapter` | ❌ No `v1` | Adapters, container, conversion at top level | + +For `rest-api-application` and `rest-api-runtime-adapter`, the content is specific to the v1 API contract. Adding a `v1` module would align them with the other packages and make the version boundary explicit. + +## Scope + +### In Scope + +#### Part A: Move misplaced tests + +- Move the two conversion tests from `axum-rest-api-server/src/v1/context/torrent/resources/torrent.rs` to `rest-api-runtime-adapter/src/conversion.rs` (or a new `tests/` module in that package). +- Remove the empty stub file `axum-rest-api-server/src/v1/context/torrent/resources/peer.rs` and its module declaration. +- Review the entire `axum-rest-api-server` package for any other tests that test code from other packages. + +#### Part B: Align v1 namespace + +- Add `src/v1/` module to `rest-api-application` and move `ports/` and `use_cases/` under it. +- Add `src/v1/` module to `rest-api-runtime-adapter` and move `adapters/`, `container.rs`, `conversion.rs` under it. +- Update all internal imports across the workspace to use the new paths. +- Update `lib.rs` in both packages to re-export from `v1`. + +### Out of Scope + +- Changing test logic or adding new tests — only moving existing tests. +- Changing the Axum server test infrastructure or integration tests. +- Creating the SI-6 `ApiClient` implementation. + +## Implementation Plan + +### Part A: Move misplaced tests + +| ID | Status | Task | Notes | +| --- | ------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| A1 | TODO | Move conversion tests from `axum-rest-api-server` to `rest-api-runtime-adapter::conversion` | Tests for `from_domain_info()` and `list_item_from_domain()` | +| A2 | TODO | Remove empty `axum-rest-api-server/src/v1/context/torrent/resources/peer.rs` stub | Only doc comment, no code | +| A3 | TODO | Clean up module declarations after removing peer.rs | Remove `pub mod peer;` from `resources/mod.rs` | +| A4 | TODO | Review the whole `axum-rest-api-server/` package for similar misplaced tests | Check all context handlers, responses, routes | + +### Part B: Align v1 namespace + +| ID | Status | Task | Notes | +| --- | ------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | +| B1 | TODO | Add `v1/` module to `rest-api-application`, move `ports/` and `use_cases/` under it | Update `lib.rs` | +| B2 | TODO | Add `v1/` module to `rest-api-runtime-adapter`, move `adapters/`, `container.rs`, `conversion.rs` under it | Update `lib.rs` | +| B3 | TODO | Update internal imports across workspace | For `rest-api-application` and `rest-api-runtime-adapter` consumers | +| B4 | TODO | Verify workspace builds cleanly | `cargo build` | +| B5 | TODO | Pre-commit and pre-push checks pass | | + +## Verification / Progress + +- [ ] A1: Conversion tests moved to `rest-api-runtime-adapter` +- [ ] A2: Empty `peer.rs` stub removed +- [ ] A3: Module declarations cleaned up +- [ ] A4: No other misplaced tests found in `axum-rest-api-server` +- [ ] B1: `rest-api-application` has `v1/` module with ports + use-cases +- [ ] B2: `rest-api-runtime-adapter` has `v1/` module with adapters + container + conversion +- [ ] B3: All internal imports updated +- [ ] B4: Workspace builds cleanly +- [ ] B5: Pre-commit and pre-push checks pass From 7808d7ee3bc423acc94e910356504f10d90ab918 Mon Sep 17 00:00:00 2001 From: Jose Celano Date: Mon, 29 Jun 2026 19:46:39 +0100 Subject: [PATCH 2/2] fix(docs): correct YAML frontmatter in closed SI specs - Change status from 'completed' to 'done' per project convention - Unindent 'updated-reason' to make it a top-level YAML key --- .../closed/1939-1938-si-1-migrate-health-check-context.md | 4 ++-- .../issues/closed/1940-1938-si-2-migrate-whitelist-context.md | 4 ++-- docs/issues/closed/1941-1938-si-3-migrate-auth-key-context.md | 4 ++-- docs/issues/closed/1942-1938-si-4-migrate-stats-context.md | 4 ++-- docs/issues/closed/1943-1938-si-5-deprecate-rest-api-core.md | 4 ++-- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/issues/closed/1939-1938-si-1-migrate-health-check-context.md b/docs/issues/closed/1939-1938-si-1-migrate-health-check-context.md index cf7477b35..1c50b1061 100644 --- a/docs/issues/closed/1939-1938-si-1-migrate-health-check-context.md +++ b/docs/issues/closed/1939-1938-si-1-migrate-health-check-context.md @@ -1,13 +1,13 @@ --- doc-type: spec issue-type: task -status: completed +status: done priority: p1 epic: 1938 github-issue: 1939 spec-path: docs/issues/closed/1939-1938-si-1-migrate-health-check-context.md last-updated-utc: 2026-06-25 - updated-reason: Closed — issue implemented +updated-reason: Closed — issue implemented semantic-links: skill-links: - create-issue diff --git a/docs/issues/closed/1940-1938-si-2-migrate-whitelist-context.md b/docs/issues/closed/1940-1938-si-2-migrate-whitelist-context.md index a09c75382..d266c458e 100644 --- a/docs/issues/closed/1940-1938-si-2-migrate-whitelist-context.md +++ b/docs/issues/closed/1940-1938-si-2-migrate-whitelist-context.md @@ -1,13 +1,13 @@ --- doc-type: spec issue-type: task -status: completed +status: done priority: p1 epic: 1938 github-issue: 1940 spec-path: docs/issues/closed/1940-1938-si-2-migrate-whitelist-context.md last-updated-utc: 2026-06-26 - updated-reason: Closed — issue implemented +updated-reason: Closed — issue implemented semantic-links: skill-links: - create-issue diff --git a/docs/issues/closed/1941-1938-si-3-migrate-auth-key-context.md b/docs/issues/closed/1941-1938-si-3-migrate-auth-key-context.md index 6b72f90cd..ab08fed47 100644 --- a/docs/issues/closed/1941-1938-si-3-migrate-auth-key-context.md +++ b/docs/issues/closed/1941-1938-si-3-migrate-auth-key-context.md @@ -1,13 +1,13 @@ --- doc-type: spec issue-type: task -status: completed +status: done priority: p1 epic: 1938 github-issue: 1941 spec-path: docs/issues/closed/1941-1938-si-3-migrate-auth-key-context.md last-updated-utc: 2026-06-26 - updated-reason: Closed — issue implemented +updated-reason: Closed — issue implemented semantic-links: skill-links: - create-issue diff --git a/docs/issues/closed/1942-1938-si-4-migrate-stats-context.md b/docs/issues/closed/1942-1938-si-4-migrate-stats-context.md index ec052d000..68090d208 100644 --- a/docs/issues/closed/1942-1938-si-4-migrate-stats-context.md +++ b/docs/issues/closed/1942-1938-si-4-migrate-stats-context.md @@ -1,13 +1,13 @@ --- doc-type: spec issue-type: task -status: completed +status: done priority: p1 epic: 1938 github-issue: 1942 spec-path: docs/issues/closed/1942-1938-si-4-migrate-stats-context.md last-updated-utc: 2026-06-27 - updated-reason: Closed — issue implemented +updated-reason: Closed — issue implemented semantic-links: skill-links: - create-issue diff --git a/docs/issues/closed/1943-1938-si-5-deprecate-rest-api-core.md b/docs/issues/closed/1943-1938-si-5-deprecate-rest-api-core.md index 77b431c50..57f80e84a 100644 --- a/docs/issues/closed/1943-1938-si-5-deprecate-rest-api-core.md +++ b/docs/issues/closed/1943-1938-si-5-deprecate-rest-api-core.md @@ -1,13 +1,13 @@ --- doc-type: spec issue-type: task -status: completed +status: done priority: p2 epic: 1938 github-issue: 1943 spec-path: docs/issues/closed/1943-1938-si-5-deprecate-rest-api-core.md last-updated-utc: 2026-06-29 - updated-reason: Closed — issue implemented +updated-reason: Closed — issue implemented semantic-links: skill-links: - create-issue