feat(axum-server): [#2274] add token-aware drain helper

[josecelano]

Summary

Adds the token-aware Axum graceful-drain helper with typed Drained and TimedOut outcomes while preserving the legacy Halted-based helper and all current consumer call sites.

Adds deterministic cancellation tests and a retained local loopback verifier that proves new connections are refused after cancellation, an in-flight request can drain, and a held request returns TimedOut with caller-owned task cleanup.

Records manual verification, compatibility evidence, independent review results, and the implementation retrospective for #2274.

Adds direct tracker-process regression evidence: a configured tracker with an HTTP listener became healthy, received SIGTERM at its exact binary PID, exited cleanly, and immediately restarted on the same bindings. Since SI-10 is additive and has no production consumer, this proves legacy-path compatibility only; SI-11 owns the first production execution of the token-aware helper.

Documents an EPIC-wide executable-boundary verification protocol for applicable shutdown subissues, including direct-PID signaling, bounded completion, exit status, and listener/resource release evidence.

Validation

• cargo run -p torrust-tracker-axum-server --example token_aware_drain
• cargo test -p torrust-tracker-axum-server
• cargo test -p torrust-tracker-axum-http-server -p torrust-tracker-axum-rest-api-server -p torrust-tracker-axum-health-check-api-server
• Direct target/debug/torrust-tracker verification with configured HTTP and health-check services: two successful SIGTERM exits and immediate listener rebind
• cargo machete --with-metadata
• linter all
• Repository pre-commit hook
• Repository pre-push hook: nightly formatting, workspace check, documentation build, and full test suite

Closes #2274

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.86%. Comparing base (cfb9315) to head (f9ec91b).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #2282      +/-   ##
===========================================
+ Coverage    84.79%   84.86%   +0.06%     
===========================================
  Files          354      354              
  Lines        31838    31970     +132     
  Branches     31838    31970     +132     
===========================================
+ Hits         26998    27131     +133     
  Misses        4464     4464              
+ Partials       376      375       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

Review effort: Lite
Findings: 2 · 3

Open (5)

• This file uses the Future trait in a bound but does not import it (and it’s not fully qualified),… · New
• drain_deadline - Instant::now() can panic if Instant::now() is later than drain_deadline… · New
• The handler is cloned and invoked for each request, so FnOnce is a confusing signal for readers… · New
• These log lines use drain_timeout.as_secs(), which will print 0 seconds for sub-second timeouts… · New
• These log lines use drain_timeout.as_secs(), which will print 0 seconds for sub-second timeouts… · New

What changed in this PR

Adds a token-driven graceful-drain helper for Axum that reports typed outcomes (Drained vs TimedOut) without changing existing Halted-based shutdown behavior, and backs it with deterministic tests plus a manual loopback example and verification docs.

Changes:

• Introduces graceful_shutdown_on_cancellation and GracefulShutdownOutcome in signals.rs.
• Adds deterministic cancellation/drain timeout tests and a retained token_aware_drain example.
• Updates Cargo.toml dependencies and records verification/retrospective evidence for #2274.

File	Description
packages/​axum-server/​src/​signals.rs	Adds the token-aware drain helper + outcome enum and new deterministic tests.
packages/​axum-server/​examples/​token_aware_drain.rs	Adds a loopback example that demonstrates drained vs timed-out scenarios.
packages/​axum-server/​Cargo.toml	Promotes tokio-util to runtime deps and adds dev-deps needed by tests/examples.
docs/​issues/​open/​2274-1488-si-10-add-token-aware-axum-drain-helper/​verification.md	Records focused verification evidence for the new helper.
docs/​issues/​open/​2274-1488-si-10-add-token-aware-axum-drain-helper/​manual-verification-evidence.md	Adds manual verification procedure and observed results.
docs/​issues/​open/​2274-1488-si-10-add-token-aware-axum-drain-helper/​implementation-retrospective.md	Adds implementation retrospective and links to evidence/artifacts.
docs/​issues/​open/​2274-1488-si-10-add-token-aware-axum-drain-helper/​agent-review-reports.md	Records independent review outcomes and follow-ups.
docs/​issues/​open/​2274-1488-si-10-add-token-aware-axum-drain-helper/​ISSUE.md	Updates issue status/tasks/acceptance criteria to DONE with evidence links.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[josecelano]

ACK f9ec91b