The Complete Production SOP: How to Deploy and Run Axum Ergonomic Modular Web Framework for Rust in Autonomous AI Agents

---
name: "axum-tokio-tower-hyper-framework"
description: "Build modular, type-safe web APIs in Rust built directly on Tokio, Tower, and Hyper."
metadata:
  author: "Tokio"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "create axum router"
  - "axum with_state extractor"
  - "tower middleware axum"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Axum Ergonomic Modular Web Framework for Rust

Architects APIs with Axum: Router with nested route merging, type-safe extractors (Path, Query, Json, Extension), state management with with_state, Tower middleware layers, and WebSocket upgrades.

## When to Invoke
Invoke this skill whenever you need to:
- create axum router
- axum with_state extractor
- tower middleware axum

## Execution SOP & Rules
1. Create router: let app = Router::new().route('/users', get(list_users).post(create_user)).with_state(state);
2. Extract state and params: async fn get_user(State(state): State<AppState>, Path(id): Path<u64>) -> Result<Json<User>, StatusCode> { ... }.
3. Attach Tower middleware: app.layer(TraceLayer::new_for_http()).
4. Serve with tokio: let listener = tokio::net::TcpListener::bind('0.0.0.0:3000').await?; axum::serve(listener, app).await?;

## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.

[dependencies]
axum = { version = "0.7", features = ["macros", "ws"] }
tokio = { version = "1.38", features = ["full"] }
tower = { version = "0.5", features = ["util"] }
tower-http = { version = "0.6", features = ["trace", "cors"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

use axum::{
    extract::{Path, State},
    http::StatusCode,
    response::IntoResponse,
    routing::{get, post},
    Json,
    Router,
};
use serde::{Deserialize, Serialize};
use std::sync::Arc;
use tower_http::trace::TraceLayer;

#[derive(Clone)]
pub struct AppState {
    pub db_name: Arc<String>,
}

#[derive(Serialize, Deserialize)]
pub struct User {
    pub id: u64,
    pub username: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    let state = AppState {
        db_name: Arc::new("production_db".to_string()),
    };

    let app = Router::new()
        .route("/users", get(list_users).post(create_user))
        .route("/users/:id", get(get_user))
        .layer(TraceLayer::new_for_http())
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
    tracing::info!("Server running on port 3000");
    axum::serve(listener, app).await?;

    Ok(())
}

async fn list_users(State(state): State<AppState>) -> impl IntoResponse {
    Json(vec![User { id: 1, username: format!("user_{}", state.db_name) }])
}

async fn create_user(
    State(_state): State<AppState>,
    Json(payload): Json<User>,
) -> Result<(StatusCode, Json<User>), StatusCode> {
    Ok((StatusCode::CREATED, Json(payload)))
}

async fn get_user(
    State(_state): State<AppState>,
    Path(id): Path<u64>,
) -> Result<Json<User>, StatusCode> {
    Ok(Json(User {
        id,
        username: "alice".to_string(),
    }))
}