# Rust Web Axum

> Specialist skill for production Axum-based Rust web services. Use when task involves Axum routers, extractors, typed application state, Tower middleware, or Tokio async service lifecycle. Triggers — Axum, Tower, tower-http, Tokio, Router, handler, extractor, IntoResponse, graceful shutdown. Negative trigger — CLI tools, procedural macros crate, WASM-only targets, pure library crates with no HTTP transport. Use when this capability is needed.

- Skill: `tomevault-io/rust-web-axum` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/rust-web-axum`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/rust-web-axum/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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

| Topic | Reference | Load When |
|---|---|---|
| Delivery checklist | `references/checklist.md` | Any Axum service feature, refactor, or review |

## 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](https://github.com/Shubchynskyi/garda-agent-orchestrator) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->