feat(rest-api-application): migrate stats context to contract-first architecture

[josecelano]

Description

Implements SI-4: Migrate stats context to contract-first architecture (sub-issue of #1938).

Changes

• rest-api-protocol: Added v1::context::stats/ with Stats (28 fields) and LabeledStats DTOs. Added torrust-metrics dep for MetricCollection.
• rest-api-application: Defined StatsQueryPort trait and StatsApiService use-case.
• rest-api-runtime-adapter: Implemented TrackerStatsAdapter — aggregation logic moved here from rest-api-core (Option 3). Added deps: http-core, udp-core, udp-server, swarm-coordination-registry.
• axum-rest-api-server: Rewired handlers to single Arc<StatsApiService> instead of 7-element tuple state. Prometheus serialization stays in Axum (Option A).
• deny.toml: Updated wrapper lists for udp-server, http-core, udp-core to allow the adapter.

Architecture flow

Handlers → StatsApiService (use-case)
         → StatsQueryPort (trait)
         → TrackerStatsAdapter (adapter, owns aggregation)
         → 7 tracker repositories/services

Aggregation Strategy

Three options were considered (see spec for details). Option 3 (applied): move aggregation from rest-api-core into the adapter, advancing SI-5's deprecation goal.

Verification

• Stats and LabeledStats DTOs defined in protocol
• StatsQueryPort trait defined in application
• StatsApiService use-case implemented
• TrackerStatsAdapter implemented (aggregation moved from rest-api-core)
• Axum handlers dispatch through use-case (no more tuple state)
• Prometheus serialization preserved in Axum (Option A)
• Pre-commit checks pass
• Pre-push checks (CI)

[Copilot]

Pull request overview

Migrates the REST API stats context to the contract-first layered architecture (protocol → application → runtime-adapter → axum transport), moving aggregation out of rest-api-core into a dedicated runtime adapter and rewiring Axum handlers to call a single application-layer use-case service.

Changes:

• Added Stats / LabeledStats DTOs to rest-api-protocol and introduced torrust-metrics for MetricCollection.
• Added StatsQueryPort + StatsApiService in rest-api-application, and implemented TrackerStatsAdapter in rest-api-runtime-adapter to own aggregation.
• Rewired Axum stats/metrics handlers to use Arc<StatsApiService> state; updated dependency-layer deny rules and supporting docs.

Reviewed changes

Copilot reviewed 23 out of 24 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
project-words.txt	Adds new dictionary words and reorders entries to keep cspell dictionary tidy.
packages/rest-api-runtime-adapter/src/adapters/stats.rs	Introduces TrackerStatsAdapter implementing StatsQueryPort and performing stats aggregation/metric merges.
packages/rest-api-runtime-adapter/src/adapters/mod.rs	Exposes the new stats adapter module.
packages/rest-api-runtime-adapter/Cargo.toml	Adds runtime-adapter dependencies required for stats aggregation (http-core, udp-*, swarm-*, tokio, torrust-metrics).
packages/rest-api-protocol/src/v1/context/stats/resources/stats.rs	Defines contract DTOs for /api/v1/stats and /api/v1/metrics.
packages/rest-api-protocol/src/v1/context/stats/resources/mod.rs	Registers the stats resources module.
packages/rest-api-protocol/src/v1/context/stats/mod.rs	Adds the stats context module in the protocol layer.
packages/rest-api-protocol/src/v1/context/mod.rs	Registers the new stats context.
packages/rest-api-protocol/Cargo.toml	Adds torrust-metrics dependency to support MetricCollection in protocol DTOs.
packages/rest-api-application/src/use_cases/stats.rs	Adds the StatsApiService application use-case that delegates to the port.
packages/rest-api-application/src/use_cases/mod.rs	Registers the new stats use-case module.
packages/rest-api-application/src/ports/stats.rs	Introduces StatsQueryPort defining the application boundary for stats queries.
packages/rest-api-application/src/ports/mod.rs	Registers the new stats port module.
packages/axum-rest-api-server/tests/server/v1/contract/context/stats.rs	Updates tests to import Stats from rest-api-protocol (contract-first).
packages/axum-rest-api-server/tests/server/v1/asserts.rs	Updates asserts to use protocol Stats type.
packages/axum-rest-api-server/src/v1/routes.rs	Wires TrackerStatsAdapter + StatsApiService and injects into stats routes.
packages/axum-rest-api-server/src/v1/context/stats/routes.rs	Switches stats routing state from tuple repositories to Arc<StatsApiService>.
packages/axum-rest-api-server/src/v1/context/stats/responses.rs	Keeps Prometheus serialization in Axum, now using protocol DTOs directly.
packages/axum-rest-api-server/src/v1/context/stats/resources.rs	Removes Axum-local stats DTOs (now owned by protocol).
packages/axum-rest-api-server/src/v1/context/stats/mod.rs	Removes resources module export (DTOs moved to protocol).
packages/axum-rest-api-server/src/v1/context/stats/handlers.rs	Refactors handlers to call StatsApiService instead of rest-api-core aggregation.
docs/issues/open/1942-1938-si-4-migrate-stats-context.md	Updates SI-4 spec with applied aggregation strategy and task statuses.
deny.toml	Allows rest-api-runtime-adapter to wrap udp-server, http-core, and udp-core per layer rules.
Cargo.lock	Locks new dependency graph including torrust-metrics and tokio for runtime-adapter.

---

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

[josecelano]

ACK bb10343