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 31936dbec..53bc104b3 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 @@ -65,24 +65,60 @@ The contexts are ordered by complexity and dependency depth. Follow-up tasks (SI ## Context Status Summary -| Context / Task | Axum Handlers | Protocol DTOs? | Port Trait? | Use-case? | Runtime Adapter? | Notes | -| ------------------------------- | :-----------: | :------------: | :---------: | :-------: | :--------------: | ---------------------------------- | -| `torrent` | 2 ✅ done | ✅ | ✅ | ✅ | ✅ | Reference pattern | -| SI-1: `health_check` | 1 | ❌ | ❌ | ❌ | ❌ | No tracker deps needed | -| 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` | +| Context / Task | Axum Handlers | Protocol DTOs? | Port Trait? | Use-case? | Runtime Adapter? | Notes | +| ------------------------------- | :-----------: | :------------: | :---------: | :-------: | :--------------: | --------------------------------------------------------------------------------- | +| `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` | ## 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/`: + + ```text + adapters/ + ├── mod.rs # pub mod torrent; pub mod whitelist; ... + └── .rs # adapter implementation + ``` + - 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. @@ -154,6 +190,8 @@ The following table maps each internal crate dependency to the sub-issue that re ### Progress Log -| Date | Event | -| ---------- | --------------------------------------------- | -| 2026-06-24 | Draft EPIC created after SI-33 PoC validation | +| Date | Event | +| ---------- | -------------------------------------------------------------------------------------- | +| 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 | diff --git a/docs/issues/open/1939-1938-si-1-migrate-health-check-context.md b/docs/issues/open/1939-1938-si-1-migrate-health-check-context.md index 9233de481..a046348d1 100644 --- a/docs/issues/open/1939-1938-si-1-migrate-health-check-context.md +++ b/docs/issues/open/1939-1938-si-1-migrate-health-check-context.md @@ -7,6 +7,7 @@ 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/ semantic-links: skill-links: - create-issue @@ -31,21 +32,22 @@ The `health_check` endpoint is defined in `packages/axum-rest-api-server/src/v1/ Per the contract-first architecture defined in [SI-33](../../open/1930-1669-si-33-rest-api-contract-first-architecture.md), this context should have: -- DTOs in `rest-api-protocol` +- DTOs in `rest-api-protocol` under the normalized module structure: + `v1::context::health_check::resources::health_check` - A port trait and use-case service in `rest-api-application` -- A runtime adapter (if needed) in `rest-api-runtime-adapter` +- A runtime adapter in `rest-api-runtime-adapter` - Only thin HTTP routing/extraction in `axum-rest-api-server` ## Current State **Location**: `packages/axum-rest-api-server/src/v1/context/health_check/` -| Artifact | Current Location | Target Location | -| --------------- | ---------------------------------------- | ------------------------------------- | -| `Status` enum | `resources.rs` in Axum | `rest-api-protocol/src/v1/resources/` | -| `Report` struct | `resources.rs` in Axum | `rest-api-protocol/src/v1/resources/` | -| Handler | `handlers.rs` | Axum (keep, but simplify) | -| Route | `src/routes.rs` (at `/api/health_check`) | Axum (keep) | +| Artifact | Current Location | Target Location | +| --------------- | ---------------------------------------- | ------------------------------------------------------------------- | +| `Status` enum | `resources.rs` in Axum | `rest-api-protocol/src/v1/context/health_check/resources/report.rs` | +| `Report` struct | `resources.rs` in Axum | `rest-api-protocol/src/v1/context/health_check/resources/report.rs` | +| Handler | `handlers.rs` | Axum (keep, but simplify) | +| Route | `src/routes.rs` (at `/api/health_check`) | Axum (keep) | **Tracker dependency**: None — the handler returns a static response. This is the simplest context to migrate. @@ -53,11 +55,11 @@ Per the contract-first architecture defined in [SI-33](../../open/1930-1669-si-3 ### In Scope -- Move `Status` enum to `rest-api-protocol/src/v1/resources/health_check.rs`. -- Move `Report` struct to `rest-api-protocol/src/v1/resources/health_check.rs`. +- Move `Status` enum to `rest-api-protocol/src/v1/context/health_check/resources/report.rs`. +- Move `Report` struct to `rest-api-protocol/src/v1/context/health_check/resources/report.rs`. - (Optional) Add a simple `HealthCheckPort` trait + use-case in `rest-api-application` if needed for testability; otherwise keep as direct protocol DTO mapping. - Rewire Axum handler to return protocol DTOs. -- Update `rest-api-protocol/src/v1/resources/mod.rs` exports. +- Update `rest-api-protocol/src/v1/context/mod.rs` and `health_check/` module tree exports. - Verify no behavioural change. ### Out of Scope @@ -70,31 +72,52 @@ Per the contract-first architecture defined in [SI-33](../../open/1930-1669-si-3 This is a straightforward DTO relocation. Steps: 1. Create protocol DTOs matching the current `Status` and `Report` types. -2. Expose them from `rest-api-protocol::v1::resources::health_check`. +2. Expose them from `rest-api-protocol::v1::context::health_check::resources::report`. 3. Remove the local definitions from the Axum server. 4. Update imports in the handler. 5. Add conversion from protocol `Report` to JSON response (already `Serialize`). Since there is no tracker dependency, no runtime adapter is needed — the handler can construct protocol DTOs directly. +## Module Structure Convention + +All protocol DTOs follow the normalized context-based module structure under +`packages/rest-api-protocol/src/v1/context/` (see the `torrent` context for the reference pattern): + +```text +context// +├── mod.rs +└── resources/ + ├── mod.rs + └── .rs +``` + +Ports, use-cases, and adapters are flat files named after the context: + +```text +packages/rest-api-application/src/ports/.rs +packages/rest-api-application/src/use_cases/.rs +packages/rest-api-runtime-adapter/src/adapters/.rs +``` + ## Implementation Plan -| ID | Status | Task | Notes | -| --- | ------ | -------------------------------------------------------------------------------------------------- | ----------------------------------- | -| T1 | TODO | Add `health_check` module to `rest-api-protocol/src/v1/resources/` with `Status` and `Report` DTOs | Match current serialization exactly | -| T2 | TODO | Export new module from `rest-api-protocol/src/v1/resources/mod.rs` | | -| T3 | TODO | Remove local `Status` and `Report` from Axum `health_check` resources | | -| T4 | TODO | Update Axum handler to import and use protocol DTOs | | -| T5 | TODO | Verify pre-commit and pre-push checks pass | | -| T6 | TODO | Verify integration tests pass | | +| ID | Status | Task | Notes | +| --- | ------ | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | +| T1 | DONE | Add `health_check` context module to `rest-api-protocol/src/v1/context/` with `Status` and `Report` DTOs (resources subdir) | Match current serialization exactly | +| T2 | DONE | Export new context from `rest-api-protocol/src/v1/context/mod.rs` and set up normalized `resources/` module tree | | +| T3 | DONE | Remove local `Status` and `Report` from Axum `health_check` resources | | +| T4 | DONE | Update Axum handler to import and use protocol DTOs | | +| T5 | DONE | Verify pre-commit checks pass | Pre-commit checks pass | +| T6 | DONE | Verify integration tests compile | Compilation verified | ## Verification / Progress -- [ ] Protocol DTOs created and exported -- [ ] Local DTOs removed from Axum server -- [ ] Handler uses protocol DTOs -- [ ] Pre-commit checks pass -- [ ] Pre-push checks pass +- [x] Protocol DTOs created and exported +- [x] Local DTOs removed from Axum server +- [x] Handler uses protocol DTOs +- [x] Pre-commit checks pass +- [ ] Pre-push checks pass (to be verified before merge) ### Progress Log diff --git a/docs/issues/open/1940-1938-si-2-migrate-whitelist-context.md b/docs/issues/open/1940-1938-si-2-migrate-whitelist-context.md index f61fd6a15..0849ba469 100644 --- a/docs/issues/open/1940-1938-si-2-migrate-whitelist-context.md +++ b/docs/issues/open/1940-1938-si-2-migrate-whitelist-context.md @@ -7,6 +7,7 @@ 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 semantic-links: skill-links: - create-issue @@ -38,6 +39,26 @@ Per the contract-first architecture, the migration needs to: - Implement a runtime adapter wrapping `WhitelistManager`. - Rewire Axum handlers to dispatch through the use-case service. +All protocol types follow the normalized context-based module structure under `packages/rest-api-protocol/src/v1/context/`: + +```text +context// +├── mod.rs +└── resources/ + ├── mod.rs + └── .rs +``` + +Ports, use-cases, and adapters are flat files named after the context: + +```text +packages/rest-api-application/src/ports/.rs +packages/rest-api-application/src/use_cases/.rs +packages/rest-api-runtime-adapter/src/adapters/.rs +``` + +See the `torrent` and `health_check` contexts for the reference pattern. + ## Current State **Location**: `packages/axum-rest-api-server/src/v1/context/whitelist/` diff --git a/docs/issues/open/1941-1938-si-3-migrate-auth-key-context.md b/docs/issues/open/1941-1938-si-3-migrate-auth-key-context.md index 526402586..54f9b185e 100644 --- a/docs/issues/open/1941-1938-si-3-migrate-auth-key-context.md +++ b/docs/issues/open/1941-1938-si-3-migrate-auth-key-context.md @@ -7,6 +7,7 @@ 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 semantic-links: skill-links: - create-issue @@ -52,7 +53,7 @@ The context has locally-defined DTOs (`AuthKey`, `AddKeyForm`, `KeyParam`) and 7 ### In Scope -- Move `AuthKey`, `AddKeyForm`, `KeyParam` DTOs to `rest-api-protocol/src/v1/resources/auth_key.rs`. +- Move `AuthKey`, `AddKeyForm`, `KeyParam` DTOs to `rest-api-protocol/src/v1/context/auth_key/resources/auth_key.rs`. - Add auth-key-specific response/error DTOs to protocol (or reuse `ActionStatus` where applicable). - Define `AuthKeyCommandPort` trait in `rest-api-application/src/ports/`. - Implement `AuthKeyApiService` use-case in `rest-api-application/src/use_cases/`. @@ -70,6 +71,26 @@ The context has locally-defined DTOs (`AuthKey`, `AddKeyForm`, `KeyParam`) and 7 The auth key context has both command and query operations, and includes form validation (duration parsing via `clock`). The 7 response functions produce 4 distinct error types plus a success response. Some can be consolidated into protocol-level error codes. +All protocol DTOs follow the normalized context-based module structure under `packages/rest-api-protocol/src/v1/context/`: + +```text +context/auth_key/ +├── mod.rs # pub mod resources; +└── resources/ + ├── mod.rs # pub mod auth_key; + └── auth_key.rs # AuthKey, AddKeyForm, DTOs +``` + +Ports, use-cases, and adapters are flat files named after the context: + +```text +packages/rest-api-application/src/ports/auth_key.rs +packages/rest-api-application/src/use_cases/auth_key.rs +packages/rest-api-runtime-adapter/src/adapters/auth_key.rs +``` + +See the `torrent` and `health_check` contexts for the reference pattern. + **Key considerations**: - `KeyParam` is a path parameter wrapper — it may stay in Axum as an extractor while referencing protocol DTOs. @@ -78,17 +99,17 @@ The auth key context has both command and query operations, and includes form va ## Implementation Plan -| ID | Status | Task | Notes | -| --- | ------ | --------------------------------------------------------------------------------- | ----------------------------- | -| T1 | TODO | Add `auth_key` module to `rest-api-protocol/src/v1/resources/` with `AuthKey` DTO | | -| T2 | TODO | Add `AddKeyRequest` DTO to protocol (or reuse from domain with wrapper) | | -| T3 | TODO | Add auth-key error response types to protocol | | -| T4 | TODO | Define `AuthKeyCommandPort` in `rest-api-application/src/ports/` | Methods for CRUD + reload | -| T5 | TODO | Implement `AuthKeyApiService` in `rest-api-application/src/use_cases/` | | -| T6 | TODO | Implement `TrackerAuthKeyAdapter` in `rest-api-runtime-adapter/src/adapters/` | Wraps `KeysHandler` + `clock` | -| T7 | TODO | Update Axum handlers to use `AuthKeyApiService` | | -| T8 | TODO | Update Axum state/routes to wire the new adapter | | -| T9 | TODO | Verify pre-commit and pre-push checks pass | | +| ID | Status | Task | Notes | +| --- | ------ | ---------------------------------------------------------------------------------------------------------- | ----------------------------- | +| T1 | TODO | Add `auth_key` context module to `rest-api-protocol/src/v1/context/` with `AuthKey` DTO (resources subdir) | | +| T2 | TODO | Add `AddKeyRequest` DTO to protocol (or reuse from domain with wrapper) | | +| T3 | TODO | Add auth-key error response types to protocol | | +| T4 | TODO | Define `AuthKeyCommandPort` in `rest-api-application/src/ports/` | Methods for CRUD + reload | +| T5 | TODO | Implement `AuthKeyApiService` in `rest-api-application/src/use_cases/` | | +| T6 | TODO | Implement `TrackerAuthKeyAdapter` in `rest-api-runtime-adapter/src/adapters/` | Wraps `KeysHandler` + `clock` | +| T7 | TODO | Update Axum handlers to use `AuthKeyApiService` | | +| T8 | TODO | Update Axum state/routes to wire the new adapter | | +| T9 | TODO | Verify pre-commit and pre-push checks pass | | ## Verification / Progress diff --git a/docs/issues/open/1942-1938-si-4-migrate-stats-context.md b/docs/issues/open/1942-1938-si-4-migrate-stats-context.md index 0ec260109..8bd54330e 100644 --- a/docs/issues/open/1942-1938-si-4-migrate-stats-context.md +++ b/docs/issues/open/1942-1938-si-4-migrate-stats-context.md @@ -7,6 +7,7 @@ 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 semantic-links: skill-links: - create-issue @@ -49,6 +50,26 @@ Per the contract-first architecture, this context needs: **Location**: `packages/axum-rest-api-server/src/v1/context/stats/` +All protocol DTOs follow the normalized context-based module structure under `packages/rest-api-protocol/src/v1/context/`: + +```text +context/stats/ +├── mod.rs # pub mod resources; +└── resources/ + ├── mod.rs # pub mod stats; + └── stats.rs # Stats, LabeledStats DTOs (~28 fields) +``` + +Ports, use-cases, and adapters are flat files named after the context: + +```text +packages/rest-api-application/src/ports/stats.rs +packages/rest-api-application/src/use_cases/stats.rs +packages/rest-api-runtime-adapter/src/adapters/stats.rs +``` + +See the `torrent` and `health_check` contexts for the reference pattern. + | Artifact | Details | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Handlers | 2: `get_stats_handler`, `get_metrics_handler` | @@ -73,7 +94,7 @@ Two output formats are supported: JSON (serialize `Stats` struct) and Prometheus ### In Scope -- Define `Stats` DTO (~28 fields) and `LabeledStats` DTO in `rest-api-protocol/src/v1/resources/stats.rs`. +- Define `Stats` DTO (~28 fields) and `LabeledStats` DTO in `rest-api-protocol/src/v1/context/stats/resources/stats.rs`. - Define `StatsQueryPort` trait in `rest-api-application/src/ports/` (methods: `get_stats`, `get_labeled_stats`). - Implement `StatsApiService` use-case in `rest-api-application/src/use_cases/`. - Implement `TrackerStatsAdapter` in `rest-api-runtime-adapter/src/adapters/`. @@ -122,18 +143,18 @@ The use-case maps domain errors to protocol error codes and returns protocol DTO ## Implementation Plan -| ID | Status | Task | Notes | -| --- | ------ | --------------------------------------------------------------------------------------- | ----------------------------------- | -| T1 | TODO | Define `Stats` and `LabeledStats` DTOs in `rest-api-protocol/src/v1/resources/stats.rs` | Match current serialization exactly | -| T2 | TODO | Define `StatsQueryPort` trait in `rest-api-application/src/ports/` | | -| T3 | TODO | Implement `StatsApiService` use-case in `rest-api-application/src/use_cases/` | | -| T4 | TODO | Implement `TrackerStatsAdapter` in `rest-api-runtime-adapter/src/adapters/` | Consume SI-30 traits | -| T5 | TODO | Add conversion functions for domain→protocol stats types | | -| T6 | TODO | Handle Prometheus serialization — keep as transport concern in Axum (Option A) | | -| T7 | TODO | Rewire Axum handlers to use `StatsApiService` | | -| T8 | TODO | Update Axum state to inject `TrackerStatsAdapter` (replacing 6+ tuples) | | -| T9 | TODO | Remove direct internal deps from `axum-rest-api-server` stats wiring | | -| T10 | TODO | Verify pre-commit and pre-push checks pass | | +| ID | Status | Task | Notes | +| --- | ------ | ----------------------------------------------------------------------------------------------------- | ----------------------------------- | +| T1 | TODO | Define `Stats` and `LabeledStats` DTOs in `rest-api-protocol/src/v1/context/stats/resources/stats.rs` | Match current serialization exactly | +| T2 | TODO | Define `StatsQueryPort` trait in `rest-api-application/src/ports/` | | +| T3 | TODO | Implement `StatsApiService` use-case in `rest-api-application/src/use_cases/` | | +| T4 | TODO | Implement `TrackerStatsAdapter` in `rest-api-runtime-adapter/src/adapters/` | Consume SI-30 traits | +| T5 | TODO | Add conversion functions for domain→protocol stats types | | +| T6 | TODO | Handle Prometheus serialization — keep as transport concern in Axum (Option A) | | +| T7 | TODO | Rewire Axum handlers to use `StatsApiService` | | +| T8 | TODO | Update Axum state to inject `TrackerStatsAdapter` (replacing 6+ tuples) | | +| T9 | TODO | Remove direct internal deps from `axum-rest-api-server` stats wiring | | +| T10 | TODO | Verify pre-commit and pre-push checks pass | | ## Verification / Progress diff --git a/packages/axum-rest-api-server/src/v1/context/health_check/handlers.rs b/packages/axum-rest-api-server/src/v1/context/health_check/handlers.rs index dfcad1f56..c7851d996 100644 --- a/packages/axum-rest-api-server/src/v1/context/health_check/handlers.rs +++ b/packages/axum-rest-api-server/src/v1/context/health_check/handlers.rs @@ -1,9 +1,8 @@ -//! API handlers for the [`stats`](crate::v1::context::health_check) +//! API handlers for the [`health_check`](crate::v1::context::health_check) //! API context. use axum::Json; - -use super::resources::{Report, Status}; +use torrust_tracker_rest_api_protocol::v1::context::health_check::resources::report::{Report, Status}; /// Endpoint for container health check. pub async fn health_check_handler() -> Json { diff --git a/packages/axum-rest-api-server/src/v1/context/health_check/mod.rs b/packages/axum-rest-api-server/src/v1/context/health_check/mod.rs index 6b1a1475f..bd932778f 100644 --- a/packages/axum-rest-api-server/src/v1/context/health_check/mod.rs +++ b/packages/axum-rest-api-server/src/v1/context/health_check/mod.rs @@ -22,13 +22,12 @@ //! //! ```json //! { -//! "status": "Ok", -//! } +//! "status": "Ok" +//! } //! ``` //! //! **Resource** //! -//! Refer to the API [`Stats`](crate::context::health_check::resources::Report) -//! resource for more information about the response attributes. +//! Refer to the API `Report` resource in [`torrust_tracker_rest_api_protocol::v1::context::health_check::resources::report`] +//! for more information about the response attributes. pub mod handlers; -pub mod resources; diff --git a/packages/axum-rest-api-server/src/v1/context/health_check/resources.rs b/packages/axum-rest-api-server/src/v1/context/health_check/resources.rs deleted file mode 100644 index 5ea5871f8..000000000 --- a/packages/axum-rest-api-server/src/v1/context/health_check/resources.rs +++ /dev/null @@ -1,14 +0,0 @@ -//! API resources for the [`stats`](crate::v1::context::health_check) -//! API context. -use serde::{Deserialize, Serialize}; - -#[derive(Serialize, Deserialize, Debug, PartialEq, Eq)] -pub enum Status { - Ok, - Error, -} - -#[derive(Serialize, Deserialize, Debug, PartialEq, Eq)] -pub struct Report { - pub status: Status, -} diff --git a/packages/axum-rest-api-server/src/v1/context/torrent/resources/torrent.rs b/packages/axum-rest-api-server/src/v1/context/torrent/resources/torrent.rs index 930cd1c44..dc158a187 100644 --- a/packages/axum-rest-api-server/src/v1/context/torrent/resources/torrent.rs +++ b/packages/axum-rest-api-server/src/v1/context/torrent/resources/torrent.rs @@ -12,7 +12,7 @@ mod tests { use torrust_info_hash::InfoHash; use torrust_tracker_core::torrent::services::{BasicInfo, Info}; use torrust_tracker_primitives::{AnnounceEvent, NumberOfBytes, PeerId, peer}; - use torrust_tracker_rest_api_protocol::v1::resources::torrent::{ListItem, Torrent}; + use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::{ListItem, Torrent}; use torrust_tracker_rest_api_runtime_adapter::conversion; fn sample_peer() -> peer::Peer { diff --git a/packages/axum-rest-api-server/src/v1/context/torrent/responses.rs b/packages/axum-rest-api-server/src/v1/context/torrent/responses.rs index 0c3f62ae9..8a769b444 100644 --- a/packages/axum-rest-api-server/src/v1/context/torrent/responses.rs +++ b/packages/axum-rest-api-server/src/v1/context/torrent/responses.rs @@ -2,17 +2,17 @@ //! API context. use axum::response::{IntoResponse, Json, Response}; use serde_json::json; -use torrust_tracker_rest_api_protocol::v1::resources::torrent::{ListItem, Torrent}; +use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::{ListItem, Torrent}; /// `200` response that contains an array of -/// [`ListItem`](torrust_tracker_rest_api_protocol::v1::resources::torrent::ListItem) +/// [`ListItem`](torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::ListItem) /// resources as json. pub fn torrent_list_response(items: Vec) -> Json> { Json(items) } /// `200` response that contains a -/// [`Torrent`](torrust_tracker_rest_api_protocol::v1::resources::torrent::Torrent) +/// [`Torrent`](torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::Torrent) /// resources as json. pub fn torrent_info_response(torrent: Torrent) -> Json { Json(torrent) diff --git a/packages/axum-rest-api-server/tests/server/v1/asserts.rs b/packages/axum-rest-api-server/tests/server/v1/asserts.rs index 77186106c..2be8d356c 100644 --- a/packages/axum-rest-api-server/tests/server/v1/asserts.rs +++ b/packages/axum-rest-api-server/tests/server/v1/asserts.rs @@ -3,7 +3,7 @@ use reqwest::Response; use torrust_tracker_axum_rest_api_server::v1::context::auth_key::resources::AuthKey; use torrust_tracker_axum_rest_api_server::v1::context::stats::resources::Stats; -use torrust_tracker_rest_api_protocol::v1::resources::torrent::{ListItem, Torrent}; +use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::{ListItem, Torrent}; // Resource responses diff --git a/packages/axum-rest-api-server/tests/server/v1/contract/context/health_check.rs b/packages/axum-rest-api-server/tests/server/v1/contract/context/health_check.rs index c7dad01f8..14508f5f6 100644 --- a/packages/axum-rest-api-server/tests/server/v1/contract/context/health_check.rs +++ b/packages/axum-rest-api-server/tests/server/v1/contract/context/health_check.rs @@ -1,6 +1,6 @@ use torrust_tracker_axum_rest_api_server::testing::environment::Started; -use torrust_tracker_axum_rest_api_server::v1::context::health_check::resources::{Report, Status}; use torrust_tracker_rest_api_client::v1::client::get; +use torrust_tracker_rest_api_protocol::v1::context::health_check::resources::report::{Report, Status}; use torrust_tracker_test_helpers::{configuration, logging}; use url::Url; diff --git a/packages/axum-rest-api-server/tests/server/v1/contract/context/torrent.rs b/packages/axum-rest-api-server/tests/server/v1/contract/context/torrent.rs index c194b6e97..052bed556 100644 --- a/packages/axum-rest-api-server/tests/server/v1/contract/context/torrent.rs +++ b/packages/axum-rest-api-server/tests/server/v1/contract/context/torrent.rs @@ -5,7 +5,7 @@ use torrust_tracker_axum_rest_api_server::testing::environment::Started; use torrust_tracker_primitives::peer::fixture::PeerBuilder; use torrust_tracker_rest_api_client::common::http::{Query, QueryParam}; use torrust_tracker_rest_api_client::v1::client::{Client, headers_with_request_id}; -use torrust_tracker_rest_api_protocol::v1::resources::torrent::{self, Torrent}; +use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::{self, Torrent}; use torrust_tracker_rest_api_runtime_adapter::conversion; use torrust_tracker_test_helpers::logging::logs_contains_a_line_with; use torrust_tracker_test_helpers::{configuration, logging}; diff --git a/packages/rest-api-application/src/ports/torrent.rs b/packages/rest-api-application/src/ports/torrent.rs index f63fe6d18..00d326c68 100644 --- a/packages/rest-api-application/src/ports/torrent.rs +++ b/packages/rest-api-application/src/ports/torrent.rs @@ -2,7 +2,7 @@ use async_trait::async_trait; use torrust_info_hash::InfoHash; use torrust_tracker_primitives::pagination::Pagination; -use torrust_tracker_rest_api_protocol::v1::resources::torrent::{ListItem, Torrent}; +use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::{ListItem, Torrent}; /// Port for querying torrent data from the tracker runtime. /// diff --git a/packages/rest-api-application/src/use_cases/torrent.rs b/packages/rest-api-application/src/use_cases/torrent.rs index 0a5d66d1f..47c182e10 100644 --- a/packages/rest-api-application/src/use_cases/torrent.rs +++ b/packages/rest-api-application/src/use_cases/torrent.rs @@ -1,7 +1,7 @@ //! Use-case service for torrent API operations. use torrust_info_hash::InfoHash; use torrust_tracker_primitives::pagination::Pagination; -use torrust_tracker_rest_api_protocol::v1::resources::torrent::{ListItem, Torrent}; +use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::{ListItem, Torrent}; use crate::ports::torrent::TorrentQueryPort; diff --git a/packages/rest-api-protocol/src/v1/context/health_check/mod.rs b/packages/rest-api-protocol/src/v1/context/health_check/mod.rs new file mode 100644 index 000000000..9831bcc56 --- /dev/null +++ b/packages/rest-api-protocol/src/v1/context/health_check/mod.rs @@ -0,0 +1,5 @@ +//! Health check context — `/api/health_check` endpoint. +//! +//! Refer to the [`axum-rest-api-server`] counterpart at +//! `v1::context::health_check` for the HTTP routing and handler layer. +pub mod resources; diff --git a/packages/rest-api-protocol/src/v1/context/health_check/resources/mod.rs b/packages/rest-api-protocol/src/v1/context/health_check/resources/mod.rs new file mode 100644 index 000000000..e91a5e341 --- /dev/null +++ b/packages/rest-api-protocol/src/v1/context/health_check/resources/mod.rs @@ -0,0 +1,2 @@ +//! Resources for the [`health_check`](super) context. +pub mod report; diff --git a/packages/rest-api-protocol/src/v1/context/health_check/resources/report.rs b/packages/rest-api-protocol/src/v1/context/health_check/resources/report.rs new file mode 100644 index 000000000..4fb54716e --- /dev/null +++ b/packages/rest-api-protocol/src/v1/context/health_check/resources/report.rs @@ -0,0 +1,22 @@ +//! API resources for the health check endpoint. +//! +//! These types define the serialization contract for the `/api/health_check` +//! endpoint response. They are transport-agnostic and do not depend on Axum +//! or any HTTP framework. +use serde::{Deserialize, Serialize}; + +/// Health status of the API. +#[derive(Serialize, Deserialize, Debug, PartialEq, Eq)] +pub enum Status { + /// The API is healthy and running. + Ok, + /// The API has encountered an error. + Error, +} + +/// Health check report returned by the `/api/health_check` endpoint. +#[derive(Serialize, Deserialize, Debug, PartialEq, Eq)] +pub struct Report { + /// The overall health status. + pub status: Status, +} diff --git a/packages/rest-api-protocol/src/v1/context/mod.rs b/packages/rest-api-protocol/src/v1/context/mod.rs new file mode 100644 index 000000000..40e1954bb --- /dev/null +++ b/packages/rest-api-protocol/src/v1/context/mod.rs @@ -0,0 +1,6 @@ +//! API resources (DTOs) for the v1 REST API contract, organized by context. +//! +//! Each submodule corresponds to an API context. Resources for each context +//! live under its `resources/` subdirectory. +pub mod health_check; +pub mod torrent; diff --git a/packages/rest-api-protocol/src/v1/context/torrent/mod.rs b/packages/rest-api-protocol/src/v1/context/torrent/mod.rs new file mode 100644 index 000000000..0c2d05240 --- /dev/null +++ b/packages/rest-api-protocol/src/v1/context/torrent/mod.rs @@ -0,0 +1,2 @@ +//! Torrent context — protocol DTOs for the torrent API group. +pub mod resources; diff --git a/packages/rest-api-protocol/src/v1/context/torrent/resources/mod.rs b/packages/rest-api-protocol/src/v1/context/torrent/resources/mod.rs new file mode 100644 index 000000000..dc30da1c2 --- /dev/null +++ b/packages/rest-api-protocol/src/v1/context/torrent/resources/mod.rs @@ -0,0 +1,3 @@ +//! Resources for the [`torrent`](super) context. +pub mod peer; +pub mod torrent; diff --git a/packages/rest-api-protocol/src/v1/resources/peer.rs b/packages/rest-api-protocol/src/v1/context/torrent/resources/peer.rs similarity index 100% rename from packages/rest-api-protocol/src/v1/resources/peer.rs rename to packages/rest-api-protocol/src/v1/context/torrent/resources/peer.rs diff --git a/packages/rest-api-protocol/src/v1/resources/torrent.rs b/packages/rest-api-protocol/src/v1/context/torrent/resources/torrent.rs similarity index 95% rename from packages/rest-api-protocol/src/v1/resources/torrent.rs rename to packages/rest-api-protocol/src/v1/context/torrent/resources/torrent.rs index 45abce767..59ac1740b 100644 --- a/packages/rest-api-protocol/src/v1/resources/torrent.rs +++ b/packages/rest-api-protocol/src/v1/context/torrent/resources/torrent.rs @@ -1,7 +1,7 @@ //! `Torrent` and `ListItem` API resources. use serde::{Deserialize, Serialize}; -use crate::v1::resources::peer::Peer; +use crate::v1::context::torrent::resources::peer::Peer; /// `Torrent` API resource. #[derive(Serialize, Deserialize, Debug, PartialEq, Eq)] diff --git a/packages/rest-api-protocol/src/v1/mod.rs b/packages/rest-api-protocol/src/v1/mod.rs index 79588ca0d..bd0da6701 100644 --- a/packages/rest-api-protocol/src/v1/mod.rs +++ b/packages/rest-api-protocol/src/v1/mod.rs @@ -10,5 +10,5 @@ //! - Error schemas and status codes belong here. //! - `From` conversions from domain types belong in the runtime adapter layer, //! not in this package. -pub mod resources; +pub mod context; pub mod responses; diff --git a/packages/rest-api-protocol/src/v1/resources/mod.rs b/packages/rest-api-protocol/src/v1/resources/mod.rs deleted file mode 100644 index a2f068e4d..000000000 --- a/packages/rest-api-protocol/src/v1/resources/mod.rs +++ /dev/null @@ -1,5 +0,0 @@ -//! API resources (DTOs) for the v1 REST API contract. -//! -//! Each module corresponds to a resource group in the API. -pub mod peer; -pub mod torrent; diff --git a/packages/rest-api-runtime-adapter/src/adapters/torrent.rs b/packages/rest-api-runtime-adapter/src/adapters/torrent.rs index 20aca653d..0f69cde44 100644 --- a/packages/rest-api-runtime-adapter/src/adapters/torrent.rs +++ b/packages/rest-api-runtime-adapter/src/adapters/torrent.rs @@ -7,7 +7,7 @@ use torrust_tracker_core::torrent::repository::in_memory::InMemoryTorrentReposit use torrust_tracker_core::torrent::services; use torrust_tracker_primitives::pagination::Pagination; use torrust_tracker_rest_api_application::ports::torrent::TorrentQueryPort; -use torrust_tracker_rest_api_protocol::v1::resources::torrent::{ListItem, Torrent}; +use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::{ListItem, Torrent}; use super::super::conversion; diff --git a/packages/rest-api-runtime-adapter/src/conversion.rs b/packages/rest-api-runtime-adapter/src/conversion.rs index 00fc9f984..65f668a97 100644 --- a/packages/rest-api-runtime-adapter/src/conversion.rs +++ b/packages/rest-api-runtime-adapter/src/conversion.rs @@ -4,8 +4,8 @@ //! `BasicInfo`, `peer::Peer`) with transport-agnostic protocol DTOs. use torrust_tracker_core::torrent::services::{BasicInfo, Info}; use torrust_tracker_primitives::{PeerId, peer as domain_peer}; -use torrust_tracker_rest_api_protocol::v1::resources::peer as protocol_peer; -use torrust_tracker_rest_api_protocol::v1::resources::torrent::{ListItem, Torrent}; +use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::peer as protocol_peer; +use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::{ListItem, Torrent}; /// Convert a domain [`domain_peer::Peer`] into a protocol [`protocol_peer::Peer`]. #[must_use] diff --git a/src/console/ci/qbittorrent_e2e/scenario_steps/tracker/verify_tracker_swarm.rs b/src/console/ci/qbittorrent_e2e/scenario_steps/tracker/verify_tracker_swarm.rs index a607e0dce..a60b505a2 100644 --- a/src/console/ci/qbittorrent_e2e/scenario_steps/tracker/verify_tracker_swarm.rs +++ b/src/console/ci/qbittorrent_e2e/scenario_steps/tracker/verify_tracker_swarm.rs @@ -1,5 +1,5 @@ use anyhow::Context; -use torrust_tracker_rest_api_protocol::v1::resources::torrent::Torrent; +use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::Torrent; use super::super::super::tracker::TrackerApiClient; use super::super::super::types::InfoHash; diff --git a/src/console/ci/qbittorrent_e2e/tracker/client.rs b/src/console/ci/qbittorrent_e2e/tracker/client.rs index 0d77f599a..f517d0af5 100644 --- a/src/console/ci/qbittorrent_e2e/tracker/client.rs +++ b/src/console/ci/qbittorrent_e2e/tracker/client.rs @@ -6,7 +6,7 @@ use anyhow::Context; use torrust_tracker_rest_api_client::connection_info::{ConnectionInfo, Origin}; use torrust_tracker_rest_api_client::v1::client::Client; -use torrust_tracker_rest_api_protocol::v1::resources::torrent::Torrent; +use torrust_tracker_rest_api_protocol::v1::context::torrent::resources::torrent::Torrent; use super::super::types::InfoHash; use super::config_builder::TrackerConfig;