agentleFS
G1JoshiG1Joshi/Agent-Skills/skills/frameworks/axum/SKILL.md

axum

Skill15 starsChanged 46 days agoMITView on GitHub

Expert Axum web framework assistance covering routing, extractors, tower middleware, and hyper-powered Rust async microservices. Use when building idiomatic, type-safe, ergonomic REST APIs in Rust.

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use Router::with_state and State extractor:

    line 165
  2. Very specific:

    Use axum::serve and tokio::net::TcpListener for modern Axum 0.7+ applications.

    line 190
  3. Very specific:

    Place State extractors as the last extractor argument in handler signatures.

    line 191
  4. Very specific:

    Use Router::with_state to ensure compiler verification of matching state types across nested subrouters.

    line 192
  5. Distinctive:

    Create separate Tokio runtimes inside handlers.

    line 199

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Axum

Axum is an ergonomic, modular web application framework built on Tokio, Tower, and Hyper for high-throughput, type-safe asynchronous Rust services.

When to Use

  • Modern Asynchronous Rust Web Services: Building RESTful APIs and microservices directly within the Tokio ecosystem.
  • Tower Middleware Integration: Leveraging Tower's rich ecosystem of rate-limiting, timeouts, retries, and tracing.
  • Modular Type-Safe Route Handlers: Combining extractors, route routers, and shared state seamlessly.
  • High-Performance WebSockets & SSE: Real-time event streaming and live pub/sub endpoints in Rust.

Quick Start

use axum::{routing::get, Json, Router};
use serde::Serialize;
use std::net::SocketAddr;

#[derive(Serialize)]
struct Status {
    healthy: bool,
}

async fn health_check() -> Json<Status> {
    Json(Status { healthy: true })
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/health", get(health_check));
    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    let listener = tokio::net::TcpListener::bind(addr).await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Core Concepts

Type-Safe State & Modular Routers

Sharing dependency-injected state across route modules:

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

#[derive(Clone)]
struct AppState {
    db_pool: Arc<String>, // Mock connection pool
}

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

async fn get_user(
    Path(user_id): Path<u64>,
    State(state): State<AppState>,
) -> Result<Json<User>, StatusCode> {
    Ok(Json(User {
        id: user_id,
        username: format!("user_{user_id}"),
    }))
}

#[tokio::main]
async fn main() {
    let state = AppState {
        db_pool: Arc::new("postgres://localhost:5432/app".into()),
    };

    let app = Router::new()
        .route("/users/{id}", get(get_user))
        .with_state(state);

    let listener = TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Tower Middleware & Tracing Layers

Adding structured logging, timeouts, and CORS layers:

use axum::Router;
use tower_http::cors::{Any, CorsLayer};
use tower_http::trace::TraceLayer;
use tower::ServiceBuilder;
use std::time::Duration;

fn configure_middleware(app: Router) -> Router {
    let middleware_stack = ServiceBuilder::new()
        .layer(TraceLayer::new_for_http())
        .layer(
            CorsLayer::new()
                .allow_origin(Any)
                .allow_methods(Any)
                .allow_headers(Any),
        )
        .layer(tower_http::timeout::TimeoutLayer::new(Duration::from_secs(10)));

    app.layer(middleware_stack)
}

Custom Extractor with Error Rejections

Validating custom headers or authentication tokens:

use axum::{
    async_trait,
    extract::FromRequestParts,
    http::{request::Parts, StatusCode},
};

struct AuthToken(String);

#[async_trait]
impl<S> FromRequestParts<S> for AuthToken
where
    S: Send + Sync,
{
    type Rejection = (StatusCode, &'static str);

    async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result<Self, Self::Rejection> {
        let auth_header = parts
            .headers
            .get("Authorization")
            .and_then(|val| val.to_str().ok());

        match auth_header {
            Some(token) if token.starts_with("Bearer ") => {
                Ok(AuthToken(token[7..].to_string()))
            }
            _ => Err((StatusCode::UNAUTHORIZED, "Missing or invalid token")),
        }
    }
}

Common Patterns

Dependency Injection with State Extractor

Problem: Sharing connection pools and config structs across handlers safely in Axum.

Solution: Use Router::with_state and State extractor:

use axum::{extract::State, routing::get, Router};
use std::sync::Arc;

#[derive(Clone)]
struct AppConfig {
    api_key: Arc<String>,
}

async fn show_config(State(config): State<AppConfig>) -> String {
    format!("Configured key: {}", config.api_key)
}

fn create_app() -> Router {
    let config = AppConfig { api_key: Arc::new("secret-token".into()) };
    Router::new().route("/config", get(show_config)).with_state(config)
}

Best Practices

Do:

  • Use axum::serve and tokio::net::TcpListener for modern Axum 0.7+ applications.
  • Place State extractors as the last extractor argument in handler signatures.
  • Use Router::with_state to ensure compiler verification of matching state types across nested subrouters.
  • Implement IntoResponse for domain error enums to decouple error formatting from route handlers.

Don't:

  • Block async worker threads; offload blocking operations with tokio::task::spawn_blocking.
  • Expose internal database error details directly in HTTP error responses.
  • Create separate Tokio runtimes inside handlers; utilize the existing ambient runtime.

Troubleshooting

ErrorCauseSolution
the trait Bound '...: FromRef<...>' is not satisfiedSub-state extractor cannot be derived from global state.Implement FromRef for child state fields or derive Clone on entire State struct.
the trait 'Handler' is not implemented for fn ...Handler signature has invalid parameter order; State/Body extractor not last.Ensure Json or body extractor is the final parameter in the handler argument list.
connection closed before message completedHandler dropped response future without finishing write.Check for panics in background tasks or Tokio runtime shutdown.

References

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.