Axum Idioms

Axum Idioms and Patterns

Core Philosophy

Axum (0.8+) rewards composability via Tower, type-safe extractors, and zero-cost abstractions. Idiomatic Axum = thin handlers, tower middleware, typed errors.

Version note: This skill targets Axum 0.8+ (released 2025). Key changes from 0.7: path parameter syntax changed from :name to {name}, State extractor is now in axum::extract, and axum::serve replaces axum::Server. If you encounter an existing codebase on 0.7, check the Axum 0.8 changelog before applying these patterns.

Scope: Axum-specific patterns. For Rust fundamentals: @.agents/skills/rust-idioms/SKILL.md. For project structure: @.agents/skills/rust-idioms/references/project-structure.md.

Router and Route Organization

1. Build routers with Router::new() and method routing:

   // ✅ Group by resource, nest for versioning
   fn task_routes() -> Router<AppState> {
       Router::new()
           .route("/tasks", get(list_tasks).post(create_task))
           .route("/tasks/{id}", get(get_task).put(update_task).delete(delete_task))
   }
   
   fn app(state: Arc<AppState>) -> Router {
       let api = Router::new()
           .merge(task_routes())   // .merge() combines peer routers
           .merge(user_routes());
   
       Router::new()
           .nest("/api/v1", api)   // .nest() adds prefix to sub-router
           .fallback(handle_404)   // typed error, not Axum's default plain-text 404
           .with_state(state)
   }

2. Path parameters use {name} syntax (not :name).

Extractors

1. Built-in extractors — Path, Query, Json, State, HeaderMap:

   // ✅ Typed and validated at compile time
   async fn get_task(
       State(state): State<Arc<AppState>>,
       Path(id): Path<Uuid>,
   ) -> Result<Json<TaskResponse>, AppError> {
       let task = state.task_service.find(id).await?;
       Ok(Json(task.into()))
   }

2. Extractor ordering — body-consuming extractors MUST be last:

   // ✅ Path before Json (Json consumes the body)
   async fn update_task(
       State(state): State<Arc<AppState>>,
       Path(id): Path<Uuid>,
       Json(body): Json<UpdateTaskRequest>,
   ) -> Result<Json<TaskResponse>, AppError> { ... }
   
   // ❌ Json before Path — won't compile or will fail at runtime
   async fn update_task(Json(body): Json<UpdateTaskRequest>, Path(id): Path<Uuid>) { ... }

3. Custom extractors via FromRequestParts (non-body) or FromRequest (body):

   // ✅ Custom extractor for authenticated user
   impl<S: Send + Sync> FromRequestParts<S> for AuthUser {
       type Rejection = AppError;
       async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result<Self, Self::Rejection> {
           let token = parts.headers.get(AUTHORIZATION)
               .and_then(|v| v.to_str().ok())
               .and_then(|v| v.strip_prefix("Bearer "))
               .ok_or(AppError::Unauthorized)?;
           decode_jwt(token).map_err(|_| AppError::Unauthorized)
       }
   }

4. Handle rejections with custom types — never let Axum's default messages leak to clients.

Application State

1. Wrap in Arc, pass via State:

   pub struct AppState {
       pub db: sqlx::PgPool,
       pub task_service: TaskService,
       pub config: AppConfig,
   }
   
   let state = Arc::new(AppState { db: pool, task_service, config });
   let app = Router::new().route("/tasks", get(list_tasks)).with_state(state);

2. Compose state for feature isolation — each feature defines its own state struct, combined at app level.

3. Never clone AppState directly — wrap in Arc, clone the Arc.

Middleware (Tower)

1. ServiceBuilder for layer composition:

   // ✅ Full middleware stack — order matters (outermost runs first)
   let app = Router::new()
       .nest("/api/v1", api_routes())
       .layer(
           ServiceBuilder::new()
               .layer(TraceLayer::new_for_http())
               .layer(CompressionLayer::new())
               .layer(CorsLayer::permissive()) // development ONLY — see below
               .layer(TimeoutLayer::new(Duration::from_secs(30)))
       )
       .with_state(state);

   Never ship CorsLayer::permissive() to production. It allows any origin, any method, any header, and sends no Access-Control-Allow-Credentials. Use an explicit, allow-listed layer instead. Load allowed origins from config, not literals:

    use tower_http::cors::CorsLayer;
   use http::HeaderValue;
   
   // ✅ Production-safe — explicit allow-list
   fn cors_layer(allowed_origins: &[String]) -> CorsLayer {
       let origins: Vec<HeaderValue> = allowed_origins
           .iter()
           .filter_map(|o| HeaderValue::try_from(o).ok())
           .collect();
       CorsLayer::new()
           .allow_origin(origins)                                      // explicit list, NEVER Any in prod
           .allow_methods([                                            // methods you actually serve
               axum::http::Method::GET,
               axum::http::Method::POST,
               axum::http::Method::PUT,
               axum::http::Method::DELETE,
           ])
           .allow_headers([
               axum::http::header::AUTHORIZATION,
               axum::http::header::CONTENT_TYPE,
               axum::http::header::ACCEPT,
           ])
           .allow_credentials(true)                                    // required for cookies / auth
           .max_age(Duration::from_secs(3600))                         // cache preflight 1h
   }
   // .layer(cors_layer(&config.cors.allowed_origins))

   Rule: allow_credentials(true) is incompatible with allow_origin(Any) — browsers reject it. If you need credentials, you MUST enumerate origins. See security-principles.md §CORS.

2. Custom middleware with from_fn:

   async fn auth_middleware(
       State(state): State<Arc<AppState>>,
       request: Request,
       next: Next,
   ) -> Result<Response, AppError> {
       let token = request.headers().get(AUTHORIZATION)
           .and_then(|v| v.to_str().ok())
           .and_then(|v| v.strip_prefix("Bearer "))
           .ok_or(AppError::Unauthorized)?;
       state.auth_service.validate(token).await?;
       Ok(next.run(request).await)
   }
   
   // Apply to specific routes with route_layer
   let protected = Router::new()
       .route("/tasks", get(list_tasks))
       .route_layer(middleware::from_fn_with_state(state.clone(), auth_middleware));

3. Layer ordering: ServiceBuilder applies bottom-to-top — last .layer() wraps closest to handler.

4. Propagate correlation IDs with TraceLayer:

   use tower_http::trace::TraceLayer;
   use tracing::Span;
   
   // ✅ Inject x-request-id into every span for log correlation
   let trace_layer = TraceLayer::new_for_http()
       .make_span_with(|request: &Request<_>| {
            let request_id = request
                .headers()
                .get("x-request-id")
                .and_then(|v| v.to_str().ok())
                .map(String::from)
                .unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
           tracing::info_span!(
               "request",
               method = %request.method(),
               uri = %request.uri(),
               request_id = %request_id,
           )
       });
   
   let app = Router::new()
       .nest("/api/v1", api_routes())
       .layer(trace_layer)
       .with_state(state);

   All tracing::info!, warn!, error! calls inside a handler will automatically inherit the span fields above (method, uri, request_id). This satisfies the correlationId requirement from the Logging Mandate. See logging-implementation/SKILL.md §Rust for the full init_tracing() setup.

5. Request body size limits — prevent denial-of-service via large payloads:

   use axum::extract::DefaultBodyLimit;
   
   let app = Router::new()
       .nest("/api/v1", api_routes())
       .layer(DefaultBodyLimit::max(1024 * 1024))  // 1 MB global limit
       .with_state(state);
   
   // Per-route override for file uploads:
   let upload_routes = Router::new()
       .route("/upload", post(upload_file))
       .layer(DefaultBodyLimit::max(50 * 1024 * 1024));  // 50 MB for uploads

Error Handling

1. Unified AppError enum with IntoResponse:

   #[derive(Debug, thiserror::Error)]
   pub enum AppError {
       #[error("not found: {0}")]       NotFound(String),
       #[error("validation failed: {0}")] Validation(String),
       #[error("unauthorized")]          Unauthorized,
       #[error("forbidden")]             Forbidden,
       #[error(transparent)]             Internal(#[from] anyhow::Error),
   }
   
   impl IntoResponse for AppError {
       fn into_response(self) -> Response {
           let (status, msg) = match &self {
               Self::NotFound(m) => (StatusCode::NOT_FOUND, m.clone()),
               Self::Validation(m) => (StatusCode::UNPROCESSABLE_ENTITY, m.clone()),
               Self::Unauthorized => (StatusCode::UNAUTHORIZED, "unauthorized".into()),
               Self::Forbidden => (StatusCode::FORBIDDEN, "forbidden".into()),
               Self::Internal(e) => {
                   tracing::error!(error = %e, "internal server error");
                   (StatusCode::INTERNAL_SERVER_ERROR, "internal server error".into())
               }
           };
           (status, Json(serde_json::json!({ "error": msg }))).into_response()
       }
   }

2. Handler return type: always Result<impl IntoResponse, AppError>.

3. Convert rejections into AppError for consistent JSON error shape.

Response Types

1. Json<T> for standard responses, (StatusCode, Json<T>) tuple for non-200:

   async fn list_tasks(...) -> Result<Json<Vec<TaskResponse>>, AppError> { ... }
   async fn create_task(...) -> Result<(StatusCode, Json<TaskResponse>), AppError> {
       Ok((StatusCode::CREATED, Json(task.into())))
   }

2. Response builder for headers, streaming, or non-JSON (CSV, files).