feat(rest-api): adopt contract-first REST API architecture (PoC for #1930)

[josecelano]

Summary

This PR implements a contract-first package architecture for the REST API, as specified in issue #1930 (part of EPIC #1669 — Overhaul: Packages). The PoC validates the architecture with the torrent detail endpoint (GET /api/v1/torrent/{info_hash}) migrated through all four target layers.

Architecture

flowchart LR
    P[rest-api-protocol]
    A[rest-api-application]
    R[rest-api-runtime-adapter]
    T[axum-rest-api-server]
    I[tracker-core / udp-core / http-core]

    T --> A
    T --> P
    A --> P
    R --> A
    R --> I

Loading

Layer	Package	Responsibility
Protocol	rest-api-protocol	Versioned DTOs, error schemas, auth semantics. No Axum, no tracker internals.
Application	rest-api-application	Port traits (TorrentQueryPort), use-case services (TorrentApiService). Depends only on protocol.
Runtime adapter	rest-api-runtime-adapter	TrackerTorrentQueryAdapter, domain→DTO conversion functions. Only layer that depends on tracker internals.
Transport	axum-rest-api-server	HTTP routing, extraction, response serialization. Thin — no business logic.

What's implemented

• rest-api-protocol — contract package with v1 Torrent, Peer, ListItem, ActionStatus DTOs
• rest-api-application — TorrentQueryPort trait + TorrentApiService use case
• rest-api-runtime-adapter — TrackerTorrentQueryAdapter + domain→protocol conversions
• Handler wiring — torrent endpoint dispatches via use case instead of direct tracker-core calls
• Integration test updated to use adapter conversion functions
• ADR documenting the decision, alternatives considered, and long-term vision
• docs/packages.md updated with REST API architecture section, Mermaid diagram, and dependency tables
• deny.toml updated with rest-api-protocol ban enforcement
• Containerfile updated with stub sources for all new packages

Follow-up EPIC #1938

The remaining REST API contexts (health_check, whitelist, auth_key, stats) and client improvements are tracked in the new dedicated EPIC:

• EPIC REST API Contract-First Migration (follow-up to SI-33 PoC) #1938 — REST API Contract-First Migration
  • #1939 — SI-1: Migrate health_check context
  • #1940 — SI-2: Migrate whitelist context
  • #1941 — SI-3: Migrate auth_key context
  • #1942 — SI-4: Migrate stats context
  • #1943 — SI-5: Deprecate rest-api-core
  • #1944 — SI-6: Introduce ApiClient high-level client

Dependency rules satisfied

Edge	Status
axum-rest-api-server → rest-api-application	✅
axum-rest-api-server → rest-api-protocol	✅
rest-api-application → rest-api-protocol	✅
rest-api-runtime-adapter → rest-api-application + tracker-core	✅
axum-rest-api-server → tracker-core (direct)	❌ forbidden (in progress, tracked in EPIC #1938)

The forbidden edge axum-rest-api-server → tracker-core still exists for non-torrent contexts (whitelist, auth keys, stats) and is tracked for follow-up migration in EPIC #1938.

Why is axum-rest-api-server → tracker-core forbidden?

This is a common point of confusion — the direction is structurally allowed (higher-level package depending on a lower-level one). The edge is forbidden anyway because of separation of concerns:

1. Prevents domain types from leaking into the API contract. When the Axum handler imports tracker_core::whitelist::WhitelistManager directly, changes to tracker-core internals ripple into the wire format. The protocol package must be the sole source of truth for API types.

2. Enables testability without the tracker stack. An Axum handler taking State<Arc<WhitelistManager>> needs real tracker infrastructure to test. The same handler taking State<Arc<WhitelistApiService>> can be tested against a mock adapter.

3. Keeps the Axum server a thin transport adapter. Its job: extract HTTP request → call a use-case → serialize to HTTP response. Not: construct KeysHandler, call WhitelistManager::add_torrent_to_whitelist, or map PeerKeyError variants.

4. Enables a tracker-agnostic API. If axum-rest-api-server depends on tracker-core, the REST API is permanently tied to Torrust's tracker. With the contract-first architecture, the same protocol and application layers could serve as the REST API for any BitTorrent tracker implementing the port traits.

The correct lower-level dependency for axum-rest-api-server is rest-api-application (port traits and use-cases). The bridge to tracker-core is rest-api-runtime-adapter — the only layer that imports tracker-internal crates directly.

Design notes

• The orphan rule prevents From<domain_type> for protocol_type when the protocol type comes from a different crate. Free conversion functions in rest-api-runtime-adapter::conversion are the current approach.
• This is a PoC — future work should migrate remaining contexts (whitelist, auth keys, stats) to the same layered pattern.
• The protocol contract package is positioned for potential extraction into a standalone, tracker-agnostic REST API standard.

Documentation

• ADR: docs/adrs/20260623200526_adopt_contract-first_architecture_for_rest_api.md
• Package architecture: docs/packages.md#rest-api-contract-first-architecture

Part of EPIC #1669

[Copilot]

Pull request overview

Implements the contract-first REST API layered package architecture (protocol → application → runtime adapter → axum transport) and migrates the v1 torrent detail/list flow (GET /api/v1/torrent/{info_hash}, GET /api/v1/torrents) to use the new application service + adapter instead of direct tracker-core calls.

Changes:

• Added new workspace crates: rest-api-protocol (v1 DTOs), rest-api-application (ports + use-case), rest-api-runtime-adapter (tracker-backed port impl + conversions).
• Refactored axum-rest-api-server torrent routes/handlers/resources/tests to consume protocol DTOs and dispatch through TorrentApiService.
• Updated documentation and dependency enforcement artifacts (docs/packages.md, ADR index + new ADR, deny.toml, workspace Cargo.toml, Containerfile, lockfile).

Reviewed changes

Copilot reviewed 35 out of 36 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/rest-api-runtime-adapter/src/lib.rs	Declares runtime adapter crate modules.
packages/rest-api-runtime-adapter/src/conversion.rs	Domain → protocol DTO conversion functions.
packages/rest-api-runtime-adapter/src/adapters/mod.rs	Runtime adapter module wiring.
packages/rest-api-runtime-adapter/src/adapters/torrent.rs	Implements TorrentQueryPort against tracker in-memory repo.
packages/rest-api-runtime-adapter/Cargo.toml	New runtime-adapter crate manifest and deps.
packages/rest-api-protocol/src/lib.rs	Declares protocol crate and ownership boundaries.
packages/rest-api-protocol/src/v1/mod.rs	Defines v1 contract module structure.
packages/rest-api-protocol/src/v1/resources/mod.rs	Exposes v1 resource DTO modules.
packages/rest-api-protocol/src/v1/resources/torrent.rs	Adds v1 Torrent/ListItem DTOs.
packages/rest-api-protocol/src/v1/resources/peer.rs	Adds v1 Peer/Id DTOs.
packages/rest-api-protocol/src/v1/responses.rs	Adds v1 response enum ActionStatus.
packages/rest-api-protocol/Cargo.toml	New protocol crate manifest.
packages/rest-api-protocol/README.md	Protocol crate README.
packages/rest-api-protocol/LICENSE	Protocol crate license file.
packages/rest-api-application/src/lib.rs	Declares application layer crate modules.
packages/rest-api-application/src/ports/mod.rs	Port trait module container.
packages/rest-api-application/src/ports/torrent.rs	Defines TorrentQueryPort boundary.
packages/rest-api-application/src/use_cases/mod.rs	Use-case module container.
packages/rest-api-application/src/use_cases/torrent.rs	Adds TorrentApiService use-case.
packages/rest-api-application/Cargo.toml	New application crate manifest and deps.
packages/axum-rest-api-server/src/v1/routes.rs	Wires adapter + use-case into v1 router assembly.
packages/axum-rest-api-server/src/v1/context/torrent/routes.rs	Updates torrent routes to use TorrentApiService state.
packages/axum-rest-api-server/src/v1/context/torrent/handlers.rs	Refactors handlers to call TorrentApiService.
packages/axum-rest-api-server/src/v1/context/torrent/responses.rs	Responses now return protocol DTOs provided by service.
packages/axum-rest-api-server/src/v1/context/torrent/resources/torrent.rs	Re-exports protocol torrent DTOs; tests updated to use adapter conversion.
packages/axum-rest-api-server/src/v1/context/torrent/resources/peer.rs	Re-exports protocol peer DTOs.
packages/axum-rest-api-server/tests/server/v1/contract/context/torrent.rs	Contract test updated to use adapter conversion for peers.
packages/axum-rest-api-server/Cargo.toml	Adds dependencies on new REST API layer crates.
docs/packages.md	Documents the new REST API contract-first architecture and updates package catalog.
docs/issues/open/1930-1669-si-33-rest-api-contract-first-architecture.md	Updates verification/progress checklist.
docs/adrs/index.md	Adds ADR entry for contract-first REST API architecture.
docs/adrs/20260623200526_adopt_contract-first_architecture_for_rest_api.md	New ADR describing decision and dependency rules.
deny.toml	Adds wrapper enforcement for torrust-tracker-rest-api-protocol.
Containerfile	Adds build-stub COPY/mkdir entries for new packages.
Cargo.toml	Registers new crates as workspace members.
Cargo.lock	Records new workspace crates in dependency graph.

Comments suppressed due to low confidence (1)

docs/issues/open/1930-1669-si-33-rest-api-contract-first-architecture.md:438

• The verification checklist still marks the docs update as incomplete, but this PR adds the REST API architecture section to docs/packages.md and introduces an ADR for it. This should be checked to keep the issue spec in sync with the implementation state.

- [x] PoC torrent detail endpoint (`GET /api/v1/torrent/{info_hash}`) migrated through all four target layers:
  - `rest-api-protocol`: Torrent/Peer/ListItem DTOs
  - `rest-api-application`: `TorrentQueryPort` + `TorrentApiService` use case
  - `rest-api-runtime-adapter`: `TrackerTorrentQueryAdapter` + conversion functions
  - `axum-rest-api-server`: handler dispatches via use case instead of direct `tracker-core`
- [ ] Target architecture documented in `docs/packages.md` (or a dedicated ADR).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[josecelano]

Review comments addressed

All Copilot review feedback has been fixed in the latest commits:

1. Broken ADR link (docs/packages.md:63) — ✅ Fixed. Changed docs/adrs/... to adrs/... (relative from docs/).

2. Missing README.md (rest-api-application, rest-api-runtime-adapter) — ✅ Fixed. Added README.md + LICENSE to both new packages.

3. updated_milliseconds_ago field docs — ✅ Fixed. Updated doc comment to: "Milliseconds since the peer's last update (relative to the response generation time)" to clarify it's a relative duration, not a timestamp. Also clarified updated as "Unix timestamp in milliseconds since epoch" to highlight the difference.

4. Issue spec checkbox (docs/issues/open/1930-1669-si-33-rest-api-contract-first-architecture.md:438) — ✅ Fixed. Marked architecture documentation box as completed with reference to ADR 20260623200526 + packages.md REST API section.

[Copilot]

Pull request overview

Copilot reviewed 50 out of 51 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

packages/axum-rest-api-server/src/v1/context/torrent/resources/peer.rs:4

• resources::peer is now an empty module, but older references/imports may still use crate::v1::context::torrent::resources::peer::Peer (and it keeps the module around). Re-exporting the protocol DTOs here maintains a stable public path without reintroducing DTO ownership in the Axum crate.

//! `Peer` and Peer `Id` API resources.
//!
//! Protocol DTOs are defined in `torrust-tracker-rest-api-protocol`.

[josecelano]

ACK bfcafb3