Rust Web Axum

Rust Web Axum

Core Workflow

1. Identify the Axum version, Tokio runtime flavour (#[tokio::main] vs. manual Builder), and project layout (src/main.rs, src/lib.rs, src/routes/, src/handlers/).
2. Keep transport (handlers/extractors), business logic (domain services), and persistence (repository traits + impls) in separate modules; never leak axum::extract or http types past the handler boundary.
3. Define application-wide shared resources in a typed AppState struct passed via Router::with_state; use FromRef for sub-state extraction instead of wrapping everything in Arc<Mutex<…>>.
4. Validate and deserialize request input through Axum extractors (Json<T>, Query<T>, Path<T>) with serde derive; apply additional validation (e.g., validator crate) before entering business logic.
5. Implement a unified error type that implements IntoResponse; map internal errors to appropriate HTTP status codes in one place, never expose internal details or backtraces to clients.
6. Layer Tower middleware deliberately: TraceLayer → request-id → CORS → auth → rate-limit → body-limit → application middleware; apply layers via Router::layer or ServiceBuilder.
7. Keep all I/O operations (sqlx, reqwest, HTTP clients, file I/O) fully async on Tokio; never call blocking code on the async executor — use tokio::task::spawn_blocking for CPU-bound or synchronous FFI work.
8. Propagate cancellation through CancellationToken or tokio::select! where long-running tasks need cooperative shutdown; respect request timeouts via tower_http::timeout::TimeoutLayer.
9. Emit structured traces with tracing and tracing-subscriber; expose /health and /ready endpoints; propagate OpenTelemetry context when distributed tracing is present.
10. Implement graceful shutdown: bind with tokio::net::TcpListener, serve via axum::serve(…).with_graceful_shutdown(signal), and drain in-flight connections before exiting the Tokio runtime.
11. Run cargo clippy -- -D warnings, cargo fmt --check, and cargo test before marking the task complete; confirm no new unsafe blocks without justification.

Reference Guide

Constraints

• Do not mix HTTP transport concerns, domain logic, and persistence in one handler function or module.
• Do not hold MutexGuard or any lock across .await points; prefer message passing or tokio::sync primitives.
• Do not use unwrap() / expect() on fallible operations in handler paths; convert to the unified error type.
• Do not spawn detached tasks (tokio::spawn) from handlers without lifecycle tracking (e.g., TaskTracker, JoinSet).
• Do not expose raw sqlx::Error, reqwest::Error, or panic backtraces in HTTP responses.
• Treat dependency upgrades, middleware reordering, extractor ordering changes, and Send/Sync bound modifications as high-risk.

Source: Shubchynskyi/garda-agent-orchestrator — distributed by TomeVault.