route_controller

Generate Axum routers from controller-style implementations with declarative extractors

Features

• Clean controller-style API similar to Routing Controller (JS) or Rocket
• Route prefixing for organizing endpoints
• Declarative extractor syntax with extract() attribute
• Built-in extractors:
  • Body extractors: Json, Form, Bytes, Text, Html, Xml, JavaScript
  • URL extractors: Path, Query
  • State extractor: State
• Optional extractors (with feature flags):
  • HeaderParam - Extract from HTTP headers (requires headers feature)
  • CookieParam - Extract from cookies (requires cookies feature)
  • SessionParam - Extract from session storage (requires sessions feature)
• Response header support: header() and content_type() attributes
  • Controller-level headers: Apply headers to all routes in a controller
  • Route-level override: Route headers override controller headers with the same name
• Middleware support at the controller level
• HTTP method attributes: #[get], #[post], #[put], #[delete], #[patch], #[head], #[options], #[trace]

Installation

[dependencies]
route_controller = "0.2.0"
axum = "0.8"  # Also works with axum 0.7 and earlier versions
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }

Path Parameter Syntax

The path parameter syntax depends on your Axum version:

• Axum 0.8+: Use curly braces {id} for path parameters

#[get("/{id}", extract(id = Path))]
async fn get_user(id: u32) -> String {
    format!("User {}", id)
}

• Axum 0.7 and earlier: Use colon syntax :id for path parameters

#[get("/:id", extract(id = Path))]
async fn get_user(id: u32) -> String {
    format!("User {}", id)
}

Optional Dependencies

For additional extractors, enable features and add required dependencies:

[dependencies]
route_controller = { version = "0.2.0", features = ["headers", "cookies", "sessions"] }
axum-extra = { version = "0.12", features = ["cookie"] }  # Required for cookies
tower-sessions = "0.14"  # Required for sessions

Quick Start

use route_controller::{controller, get, post};
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
struct User {
    name: String,
    email: String,
}

struct UserController;

#[controller(path = "/users")]
impl UserController {
    #[get]
    async fn list() -> &'static str {
        "User list"
    }

    #[get("/{id}", extract(id = Path))]
    async fn get_one(id: u32) -> axum::Json<User> {
        let user = User {
            name: format!("User{}", id),
            email: format!("user{}@example.com", id),
        };
        axum::Json(user)
    }

    #[post(extract(user = Json))]
    async fn create(user: User) -> String {
        format!("Created user: {} ({})", user.name, user.email)
    }
}

#[tokio::main]
async fn main() {
    let app = UserController::router();

    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .unwrap();

    println!("🚀 Server running on http://127.0.0.1:3000");
    axum::serve(listener, app).await.unwrap();
}

Controller Types

The extract() Attribute

Use the extract() attribute to specify how each parameter should be extracted from the request. The order of extractors in the attribute can differ from the parameter order:

#[controller(path = "/api/users")]
impl ApiController {
    // Single extractor
    #[post("/", extract(user = Json))]
    async fn create(user: User) -> String {
        format!("Created: {}", user.name)
    }

    // Multiple Path extractors (order independent)
    #[get("/{id}/posts/{post_id}", extract(post_id = Path, id = Path))]
    async fn get_user_post(id: u32, post_id: u32) -> String {
        format!("User {} - Post {}", id, post_id)
    }

    // Mixed extractors: Path + Json
    #[put("/{id}", extract(id = Path, user = Json))]
    async fn update(id: u32, user: User) -> String {
        format!("Updated user {}", id)
    }

    // Path + Query extractors
    #[get("/{id}/search", extract(id = Path, filters = Query))]
    async fn search(id: u32, filters: SearchFilters) -> String {
        format!("Searching for user {}", id)
    }
}

Available Extractors

Request Body Extractors

• Json - Extract JSON request body: extract(data = Json)

  • Type: Any deserializable struct (T where T: serde::Deserialize)
  • Content-Type: application/json

• Form - Extract form data (form-data or x-www-form-urlencoded): extract(data = Form)

  • Type: Any deserializable struct (T where T: serde::Deserialize)
  • Content-Type: application/x-www-form-urlencoded or multipart/form-data

• Bytes - Extract raw binary data: extract(data = Bytes)

  • Type: Vec<u8>
  • Useful for file uploads, binary protocols, etc.

• Text - Extract plain text: extract(content = Text)

  • Type: String
  • Content-Type: text/plain

• Html - Extract HTML content: extract(content = Html)

  • Type: String
  • Content-Type: text/html

• Xml - Extract XML content: extract(content = Xml)

  • Type: String
  • Content-Type: application/xml or text/xml

• JavaScript - Extract JavaScript content: extract(code = JavaScript)

  • Type: String
  • Content-Type: application/javascript or text/javascript

URL Extractors

• Path - Extract path parameters: extract(id = Path)
• Query - Extract query parameters: extract(params = Query)

Other Extractors

• State - Extract application state: extract(state = State)

Feature-Gated Extractors

Enable additional extractors with Cargo features:

[dependencies]
route_controller = { version = "0.2.0", features = ["headers", "cookies", "sessions"] }
axum-extra = { version = "0.12", features = ["cookie"] }  # Required for cookies
tower-sessions = "0.14"  # Required for sessions

• HeaderParam - Extract from HTTP headers (requires headers feature)

  #[get("/api/data", extract(authorization = HeaderParam))]
  async fn get_data(authorization: String) -> String {
      format!("Auth: {}", authorization)
  }
  

• CookieParam - Extract from cookies (requires cookies feature + axum-extra)

  #[get("/profile", extract(session_id = CookieParam))]
  async fn get_profile(session_id: String) -> String {
      format!("Session: {}", session_id)
  }
  

• SessionParam - Extract from session storage (requires sessions feature + tower-sessions)

  #[get("/profile", extract(user_id = SessionParam))]
  async fn get_profile(user_id: String) -> String {
      format!("User ID: {}", user_id)
  }
  

Using State

Extract application state in your handlers using the State extractor:

use std::sync::Arc;
use tokio::sync::RwLock;

#[derive(Clone)]
struct AppState {
    counter: Arc<RwLock<i32>>,
}

struct CounterController;

#[controller(path = "/counter")]
impl CounterController {
    #[get(extract(state = State))]
    async fn get_count(state: AppState) -> axum::Json<i32> {
        let count = *state.counter.read().await;
        axum::Json(count)
    }

    #[post("/increment", extract(state = State))]
    async fn increment(state: AppState) -> axum::Json<i32> {
        let mut counter = state.counter.write().await;
        *counter += 1;
        axum::Json(*counter)
    }
}

#[tokio::main]
async fn main() {
    let app_state = AppState {
        counter: Arc::new(RwLock::new(0)),
    };

    let app = axum::Router::new()
        .merge(CounterController::router())
        .with_state(app_state);

    // Start server...
}

Body Extractor Examples

Form Data

Handle form submissions with the Form extractor:

#[derive(Deserialize)]
struct LoginForm {
    username: String,
    password: String,
}

#[controller(path = "/auth")]
impl AuthController {
    #[post("/login", extract(form = Form))]
    async fn login(form: LoginForm) -> String {
        format!("Logging in user: {}", form.username)
    }
}

Test with:

curl -X POST http://localhost:3000/auth/login \
  -d 'username=john&password=secret123'

Binary Data

Handle file uploads or binary data with the Bytes extractor:

#[controller(path = "/files")]
impl FileController {
    #[post("/upload", extract(data = Bytes))]
    async fn upload(data: Vec<u8>) -> String {
        format!("Received {} bytes", data.len())
    }
}

Text Content Types

Handle various text-based content types:

#[controller(path = "/content")]
impl ContentController {
    // Plain text
    #[post("/text", extract(content = Text))]
    async fn handle_text(content: String) -> String {
        format!("Received text: {}", content)
    }

    // HTML content
    #[post("/html", extract(html = Html))]
    async fn handle_html(html: String) -> String {
        format!("Received {} chars of HTML", html.len())
    }

    // XML content
    #[post("/xml", extract(xml = Xml))]
    async fn handle_xml(xml: String) -> String {
        format!("Received XML: {}", xml)
    }

    // JavaScript code
    #[post("/script", extract(code = JavaScript))]
    async fn handle_script(code: String) -> String {
        format!("Received {} chars of JavaScript", code.len())
    }
}

Response Headers

Add custom headers to your responses using the header() and content_type() attributes at both the controller and route levels.

Controller-Level Headers

Apply headers to all routes in a controller. Route-level headers with the same name will override controller-level headers:

#[controller(
    path = "/api",
    header("x-api-version", "1.0"),
    header("x-powered-by", "route-controller")
)]
impl ApiController {
    // Inherits both controller headers
    #[get("/data")]
    async fn get_data() -> String {
        "Data with controller headers".to_string()
    }

    // Overrides x-api-version, keeps x-powered-by
    #[get("/v2", header("x-api-version", "2.0"))]
    async fn get_data_v2() -> String {
        "Data with overridden version".to_string()
    }

    // Adds route-specific header, keeps controller headers
    #[get("/special", header("x-request-id", "abc-123"))]
    async fn special() -> String {
        "Special endpoint".to_string()
    }
}

Route-Level Headers

#[controller(path = "/api")]
impl ApiController {
    #[get("/data", header("x-api-version", "1.0"))]
    async fn get_data() -> String {
        "Data with custom header".to_string()
    }
}

Multiple Headers

#[controller(path = "/api")]
impl ApiController {
    #[get(
        "/info",
        header("x-api-version", "2.0"),
        header("x-request-id", "abc-123")
    )]
    async fn get_info() -> String {
        "Info with multiple headers".to_string()
    }
}

Content-Type Header

Set content-type at controller or route level:

// Controller-level content-type applies to all routes
#[controller(path = "/api", content_type("application/json"))]
impl ApiController {
    // Inherits application/json content-type
    #[get("/data")]
    async fn get_data() -> String {
        r#"{"status":"ok"}"#.to_string()
    }

    // Route overrides to XML
    #[get("/xml", content_type("application/xml"))]
    async fn get_xml() -> String {
        r#"<?xml version="1.0"?>
<response>
    <message>Hello XML</message>
</response>"#.to_string()
    }

    // Route overrides to plain text
    #[get("/text", content_type("text/plain; charset=utf-8"))]
    async fn get_text() -> String {
        "Plain text response".to_string()
    }
}

Combining Controller and Route Headers

Controller headers provide a base set of headers, and routes can override or extend them:

// Controller provides base headers and content-type
#[controller(
    path = "/api",
    content_type("application/json"),
    header("x-api-version", "1.0"),
    header("x-service", "my-api")
)]
impl ApiController {
    // Inherits all controller headers
    #[get("/info")]
    async fn get_info() -> axum::Json<Response> {
        axum::Json(Response { status: "ok".to_string() })
    }

    // Override version and content-type, keep x-service
    #[post(
        "/data",
        content_type("application/json; charset=utf-8"),
        header("x-api-version", "2.0"),
        header("x-rate-limit", "100")
    )]
    async fn post_data() -> axum::Json<Response> {
        axum::Json(Response { status: "ok".to_string() })
    }
}

Test with:

# Check inherited headers
curl -v http://localhost:3000/api/info
# Output: x-api-version: 1.0, x-service: my-api, content-type: application/json

# Check overridden headers
curl -v http://localhost:3000/api/data
# Output: x-api-version: 2.0, x-service: my-api, x-rate-limit: 100

Examples

The crate includes 15 comprehensive examples demonstrating different features:

# 1. Basic routing with different HTTP methods (GET, POST, PUT, DELETE)
cargo run --example 01_basic_routing

# 2. Path parameter extraction
cargo run --example 02_path_params

# 3. Query parameter extraction
cargo run --example 03_query_params

# 4. JSON body extraction
cargo run --example 04_json_body

# 5. Form data handling (form-data and x-www-form-urlencoded)
cargo run --example 05_form_data

# 6. Text body extraction
cargo run --example 06_text_body

# 7. Binary data (bytes) handling
cargo run --example 07_bytes

# 8. Header extraction (requires 'headers' feature)
cargo run --example 08_headers --features headers

# 9. Cookie handling (requires 'cookies' feature)
cargo run --example 09_cookies --features cookies

# 10. Session management (requires 'sessions' feature)
cargo run --example 10_sessions --features sessions

# 11. Application state management
cargo run --example 11_state

# 12. Response headers and content types
cargo run --example 12_response_headers

# 13. Middleware application
cargo run --example 13_middleware

# 14. Mixed extractors (Path + Query + Json)
cargo run --example 14_mixed_extractors

# 15. Multiple controllers with merged routers
cargo run --example 15_multiple_controllers

Each example includes:

• Clear comments explaining the feature
• Test commands using curl
• Working code that can be run immediately

With Middleware

Apply middleware at the controller level:

use axum::{
    middleware::Next,
    extract::Request,
    response::Response,
};

async fn log_middleware(request: Request, next: Next) -> Response {
    println!("Request: {} {}", request.method(), request.uri());
    next.run(request).await
}

#[controller(path = "/api", middleware = log_middleware)]
impl ApiController {
    #[get("/data")]
    async fn get_data() -> String {
        "Protected data".to_string()
    }
}

You can also apply multiple middlewares:

#[controller(
    path = "/api",
    middleware = middleware_a,
    middleware = middleware_b
)]
impl MultiMiddlewareController {
    #[get("/test")]
    async fn test() -> &'static str {
        "ok"
    }
}

See examples/13_middleware.rs for a complete example.

Verbose Logging

Enable verbose logging during compilation by setting the ROUTE_CONTROLLER_VERBOSE environment variable:

ROUTE_CONTROLLER_VERBOSE=1 cargo build
ROUTE_CONTROLLER_VERBOSE=1 cargo run --example basic

This shows detailed information about route registration during compilation.

License

MIT