Beginner

// Cargo.toml dependencies needed:
// axum = "0.8"
// tokio = { version = "1", features = ["full"] }

use axum::{routing::get, Router};  // => axum::Router builds the route tree
                                    // => routing::get attaches GET method handlers

#[tokio::main]                      // => Macro expands to tokio runtime setup
                                    // => Equivalent to: tokio::runtime::Builder::new_multi_thread()...
async fn main() {
    // Build the application router
    let app = Router::new()         // => Creates empty Router (no routes yet)
        .route("/", get(root));     // => Maps GET / to the root() handler function
                                    // => route() returns a new Router (immutable, builder pattern)

    // Bind to a local TCP address
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await                      // => .await suspends until TCP bind completes
        .unwrap();                  // => Panics if port 3000 is already in use
                                    // => In production use .expect("Failed to bind") or handle Error

    println!("Listening on http://0.0.0.0:3000");

    // Start the server - blocks until shutdown signal
    axum::serve(listener, app)      // => Ties the TcpListener to the Router
        .await                      // => Drives the server; never returns on success
        .unwrap();                  // => Propagates any fatal server errors
}

// Handler functions are plain async functions
async fn root() -> &'static str {  // => &'static str implements IntoResponse
                                    // => Axum converts it to 200 OK with text/plain body
    "Hello, World!"                 // => Response body: "Hello, World!"
                                    // => Status: 200 OK
}

use axum::{
    routing::{delete, get, post, put}, // => Import method-specific routing helpers
    Router,
};

#[tokio::main]
async fn main() {
    let app = Router::new()
        // Each route maps (path, method) to a handler
        .route("/users", get(list_users))     // => GET /users → list_users()
        .route("/users", post(create_user))   // => POST /users → create_user()
        // Chaining on same path is idiomatic in Axum 0.8
        .route("/users/:id", get(get_user))   // => GET /users/:id → get_user()
                                               // => :id is a named capture segment
        .route("/users/:id", put(update_user))  // => PUT /users/:id → update_user()
        .route("/users/:id", delete(delete_user)); // => DELETE /users/:id → delete_user()
                                                    // => CRUD pattern complete

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

// Handlers return &'static str for brevity; real handlers return Json or Html
async fn list_users() -> &'static str { "list users" }   // => GET /users
async fn create_user() -> &'static str { "created" }     // => POST /users
async fn get_user() -> &'static str { "one user" }       // => GET /users/:id
async fn update_user() -> &'static str { "updated" }     // => PUT /users/:id
async fn delete_user() -> &'static str { "deleted" }     // => DELETE /users/:id

use axum::{
    extract::Path,  // => Path<T> extractor for URL segments
    routing::get,
    Router,
};

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/users/:id", get(get_user))
        // Multiple segments: /orders/:user_id/items/:item_id
        .route("/orders/:user_id/items/:item_id", get(get_item));

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

// Single path param - Axum parses ":id" into the given type
async fn get_user(
    Path(user_id): Path<u64>,  // => Destructure Path<u64> directly
                                // => Axum parses the ":id" segment as u64
                                // => Returns 400 Bad Request if parsing fails
                                // => e.g. GET /users/42 → user_id = 42
) -> String {
    format!("User ID: {}", user_id)  // => "User ID: 42"
}

// Multiple path params - use a tuple or struct
async fn get_item(
    Path((user_id, item_id)): Path<(u64, u64)>,  // => Tuple destructuring
                                                   // => First :user_id → user_id: u64
                                                   // => Second :item_id → item_id: u64
) -> String {
    format!("User {}, Item {}", user_id, item_id)  // => "User 5, Item 12"
}

use axum::{
    extract::Query,           // => Query<T> extractor for ?key=value pairs
    routing::get,
    Router,
};
use serde::Deserialize;       // => Serde trait for deserialization

// Define a struct matching expected query parameters
#[derive(Deserialize)]        // => Auto-generate deserialization from query string
struct Pagination {
    page: Option<u32>,        // => ?page=2  (optional, defaults to None)
    per_page: Option<u32>,    // => ?per_page=20 (optional)
}

#[derive(Deserialize)]
struct SearchParams {
    q: String,                // => ?q=rust  (required - returns 400 if missing)
    lang: Option<String>,     // => ?lang=en (optional)
}

async fn list_posts(
    Query(pagination): Query<Pagination>,  // => Deserializes ?page=&per_page= into Pagination
                                            // => All fields Optional → never returns 400
) -> String {
    let page = pagination.page.unwrap_or(1);           // => page=1 if not provided
    let per_page = pagination.per_page.unwrap_or(20);  // => per_page=20 if not provided
    format!("Page {}, {} per page", page, per_page)
}

async fn search(
    Query(params): Query<SearchParams>,    // => Deserializes ?q= into SearchParams
                                            // => Returns 400 if required field "q" missing
) -> String {
    format!("Search: {} (lang: {:?})", params.q, params.lang)
    // => "Search: rust (lang: Some(\"en\"))"
    // => "Search: axum (lang: None)" if ?lang not provided
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/posts", get(list_posts))
        .route("/search", get(search));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

use axum::{
    extract::Json,       // => Json<T> extractor for application/json bodies
    http::StatusCode,    // => HTTP status code constants
    routing::post,
    Router,
};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]   // => Allows Json extractor to parse request body
struct CreateUser {
    username: String,    // => Required JSON field "username"
    email: String,       // => Required JSON field "email"
    age: Option<u8>,     // => Optional JSON field "age"
}

#[derive(Serialize)]     // => Allows Json<T> response to serialize to JSON
struct UserCreated {
    id: u64,             // => Assigned user ID
    username: String,    // => Echo back the username
    message: String,     // => Confirmation message
}

async fn create_user(
    Json(payload): Json<CreateUser>,  // => Extracts and deserializes JSON body
                                       // => Returns 422 Unprocessable Entity if body is invalid JSON
                                       // => Returns 400 Bad Request if Content-Type is not application/json
) -> (StatusCode, Json<UserCreated>) { // => Return tuple: (status, json body)
    let user = UserCreated {
        id: 1,                          // => Would be DB-assigned in real code
        username: payload.username,     // => Move username from request into response
        message: "User created".into(), // => Confirmation string
    };
    (StatusCode::CREATED, Json(user))  // => 201 Created + JSON body
    // => Response: {"id":1,"username":"alice","message":"User created"}
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/users", post(create_user));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

use axum::{
    extract::State,      // => State<T> extractor injects shared state
    routing::get,
    Router,
};
use std::sync::Arc;      // => Arc for shared ownership across threads

// Define your application state
#[derive(Clone)]         // => Clone required by State extractor
struct AppState {
    db_url: String,      // => Database connection string
    app_name: String,    // => Application name for headers/logging
}

async fn health_check(
    State(state): State<Arc<AppState>>,  // => Clones the Arc (cheap - increments ref count)
                                          // => Arc<AppState> for shared ownership across threads
                                          // => State<T> clones T on each request; use Arc for cheap clone
) -> String {
    format!("OK: {}", state.app_name)   // => "OK: my-api"
    // => state.db_url is accessible too: state.db_url
}

async fn config(
    State(state): State<Arc<AppState>>,  // => Same Arc clone, different handler
) -> String {
    format!("DB: {}", state.db_url)     // => "DB: postgres://localhost/mydb"
}

#[tokio::main]
async fn main() {
    let state = Arc::new(AppState {      // => Wrap in Arc for cheap clone in handlers
        db_url: "postgres://localhost/mydb".into(),
        app_name: "my-api".into(),
    });

    let app = Router::new()
        .route("/health", get(health_check))
        .route("/config", get(config))
        .with_state(state);              // => Attach state to the router
                                          // => All child routes inherit this state

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

use axum::{
    extract::State,
    routing::{get, post},
    Json, Router,
};
use serde::{Deserialize, Serialize};
use std::sync::{Arc, RwLock};

// Counter state - wraps mutable u64 in RwLock for safe concurrent access
type SharedCounter = Arc<RwLock<u64>>;  // => Type alias for readability
                                         // => Arc = shared ownership, RwLock = interior mutability

#[derive(Serialize)]
struct CounterResponse {
    count: u64,   // => Current counter value to serialize to JSON
}

async fn get_count(
    State(counter): State<SharedCounter>,  // => Clones the Arc (cheap)
) -> Json<CounterResponse> {
    let count = counter.read()             // => Acquires read lock (non-blocking if no writer)
        .unwrap()                          // => Panics if lock is poisoned (writer panicked)
        .clone();                          // => Copy the u64 value before dropping lock
                                            // => Lock released here (guard dropped)
    Json(CounterResponse { count })        // => {"count": 42}
}

async fn increment(
    State(counter): State<SharedCounter>,  // => Clones the Arc
) -> Json<CounterResponse> {
    let mut count = counter.write()        // => Acquires exclusive write lock
        .unwrap();                          // => Blocks until all readers release
    *count += 1;                           // => Dereference MutexGuard to modify value
    let current = *count;                  // => Copy value before dropping lock
                                            // => Lock released when `count` drops at end of scope
    Json(CounterResponse { count: current })
}

#[tokio::main]
async fn main() {
    let counter: SharedCounter = Arc::new(RwLock::new(0));  // => Initialize counter to 0

    let app = Router::new()
        .route("/count", get(get_count))
        .route("/increment", post(increment))
        .with_state(counter);

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

use axum::{
    http::{header, HeaderMap, StatusCode},  // => HTTP primitives
    response::{Html, IntoResponse, Response},  // => Response types
    routing::get,
    Json, Router,
};
use serde::Serialize;

// 1. Plain string - 200 OK with text/plain
async fn plain_text() -> &'static str {
    "Hello"                        // => Status: 200, Content-Type: text/plain
}

// 2. HTML response
async fn html_page() -> Html<String> {
    Html("<h1>Hello</h1>".to_string())  // => Status: 200, Content-Type: text/html
}

// 3. Status code only
async fn no_content() -> StatusCode {
    StatusCode::NO_CONTENT         // => Status: 204, no body
}

// 4. Tuple: (StatusCode, body) - override default 200
async fn created() -> (StatusCode, &'static str) {
    (StatusCode::CREATED, "Created")  // => Status: 201, body: "Created"
}

// 5. Custom headers via HeaderMap
async fn with_headers() -> impl IntoResponse {  // => impl IntoResponse is idiomatic
    let mut headers = HeaderMap::new();
    headers.insert(
        header::CACHE_CONTROL,
        "max-age=3600".parse().unwrap(),  // => Cache-Control: max-age=3600
    );
    (headers, "Cached response")           // => Tuple of (headers, body)
}

// 6. Full custom response
async fn custom_response() -> Response {
    Response::builder()                     // => Start building a response
        .status(StatusCode::ACCEPTED)       // => 202 Accepted
        .header("X-Job-Id", "abc-123")     // => Custom header
        .body("Processing".into())          // => String body as axum::body::Body
        .unwrap()                           // => Building always succeeds here
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/text", get(plain_text))
        .route("/html", get(html_page))
        .route("/empty", get(no_content))
        .route("/created", get(created))
        .route("/cached", get(with_headers))
        .route("/custom", get(custom_response));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
    routing::get,
    Json, Router,
};
use serde::Serialize;

// Define application error types
#[derive(Debug)]
enum AppError {
    NotFound(String),       // => Maps to 404 Not Found
    BadRequest(String),     // => Maps to 400 Bad Request
    InternalError(String),  // => Maps to 500 Internal Server Error
}

// Error response body
#[derive(Serialize)]
struct ErrorBody {
    error: String,   // => Human-readable error message
    code: u16,       // => HTTP status code for client parsing
}

// Implement IntoResponse for our error enum
impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            AppError::NotFound(msg) => (StatusCode::NOT_FOUND, msg),
            // => 404 + message
            AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg),
            // => 400 + message
            AppError::InternalError(msg) => (StatusCode::INTERNAL_SERVER_ERROR, msg),
            // => 500 + message (scrub details in production!)
        };
        let body = ErrorBody {
            code: status.as_u16(),  // => e.g. 404
            error: message,          // => e.g. "User not found"
        };
        (status, Json(body)).into_response()  // => Compose status + JSON body
    }
}

// Handler returns Result; Err variant uses our AppError
async fn find_user(
    axum::extract::Path(id): axum::extract::Path<u64>,
) -> Result<Json<String>, AppError> {  // => Ok = JSON response, Err = error response
    if id == 0 {
        return Err(AppError::BadRequest("ID must be non-zero".into()));
        // => Response: 400 {"error":"ID must be non-zero","code":400}
    }
    if id > 100 {
        return Err(AppError::NotFound(format!("User {} not found", id)));
        // => Response: 404 {"error":"User 42 not found","code":404}
    }
    Ok(Json(format!("User {}", id)))  // => Response: 200 "\"User 5\""
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/users/:id", get(find_user));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

use axum::{
    extract::TypedHeader,             // => Typed header extractor
    http::{HeaderMap, StatusCode},    // => Raw header map
    routing::get,
    Router,
};
use axum_extra::TypedHeader as ExtraTypedHeader;  // => axum-extra crate
// Note: For axum 0.8, use axum::TypedHeader directly

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/raw-headers", get(raw_headers))
        .route("/auth", get(check_auth));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

// Raw header access via HeaderMap
async fn raw_headers(
    headers: HeaderMap,           // => Injects full request HeaderMap
                                   // => No need for Path/Query/State wrappers
) -> String {
    // Get a specific header by name
    let content_type = headers
        .get("content-type")      // => Returns Option<&HeaderValue>
        .and_then(|v| v.to_str().ok())  // => Convert to &str, None if not valid UTF-8
        .unwrap_or("not set");          // => Default if header absent

    // Get the User-Agent header
    let user_agent = headers
        .get("user-agent")
        .and_then(|v| v.to_str().ok())
        .unwrap_or("unknown");

    format!("Content-Type: {}, User-Agent: {}", content_type, user_agent)
    // => "Content-Type: application/json, User-Agent: curl/7.88"
}

// Check Authorization header manually (real apps use middleware)
async fn check_auth(
    headers: HeaderMap,           // => Full header map
) -> Result<String, StatusCode> { // => Return 401 if missing auth
    let auth = headers
        .get("authorization")     // => Look for Authorization header
        .and_then(|v| v.to_str().ok())
        .ok_or(StatusCode::UNAUTHORIZED)?;  // => ? operator: return 401 if None

    if auth.starts_with("Bearer ") {  // => Check for Bearer token scheme
        Ok(format!("Authorized: {}", &auth[7..]))  // => Skip "Bearer " prefix
    } else {
        Err(StatusCode::UNAUTHORIZED)               // => Wrong scheme → 401
    }
}

use axum::{
    http::{header, HeaderMap, HeaderValue},  // => HTTP header types
    routing::{get, post},
    Router,
};

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/set-cookie", post(set_cookie))
        .route("/cached", get(cached_response));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

// Set a cookie in the response
async fn set_cookie() -> (HeaderMap, &'static str) {
    let mut headers = HeaderMap::new();

    // Build a Set-Cookie header value
    let cookie_value = "session_id=abc123; HttpOnly; SameSite=Lax; Path=/; Max-Age=3600";
    // => HttpOnly: JS cannot read this cookie (XSS protection)
    // => SameSite=Lax: sent on same-site navigations (CSRF protection)
    // => Path=/: valid for all paths
    // => Max-Age=3600: expires in 1 hour

    headers.insert(
        header::SET_COOKIE,
        HeaderValue::from_static(cookie_value),  // => Static strings are safe to use directly
    );

    (headers, "Cookie set!")  // => Response includes Set-Cookie header
}

// Return a response with caching headers
async fn cached_response() -> (HeaderMap, String) {
    let mut headers = HeaderMap::new();

    headers.insert(
        header::CACHE_CONTROL,
        "public, max-age=3600, must-revalidate".parse().unwrap(),
        // => public: cacheable by CDNs
        // => max-age=3600: fresh for 1 hour
        // => must-revalidate: recheck after expiry
    );
    headers.insert(
        header::CONTENT_TYPE,
        HeaderValue::from_static("application/json"),
    );

    (headers, r#"{"data": "cached"}"#.to_string())
    // => Returns JSON with caching headers
}

use axum::{
    extract::Form,               // => Form<T> extractor for urlencoded bodies
    response::{Html, Redirect},  // => Html for pages, Redirect for Post/Redirect/Get
    routing::{get, post},
    Router,
};
use serde::Deserialize;

// Fields must match HTML input name attributes
#[derive(Deserialize)]
struct LoginForm {
    username: String,  // => <input name="username">
    password: String,  // => <input name="password">
}

// GET handler: show the login form
async fn login_page() -> Html<&'static str> {
    Html(r#"
        <!DOCTYPE html>
        <html>
        <body>
            <form method="POST" action="/login">
                <input type="text" name="username" placeholder="Username">
                <input type="password" name="password" placeholder="Password">
                <button type="submit">Login</button>
            </form>
        </body>
        </html>
    "#)
    // => Returns HTML form page (200 OK, Content-Type: text/html)
}

// POST handler: process form submission
async fn handle_login(
    Form(credentials): Form<LoginForm>,  // => Parses urlencoded body into LoginForm
                                          // => Returns 422 if body is malformed
                                          // => Returns 400 if Content-Type is wrong
) -> Redirect {
    // In real code: validate credentials against DB
    println!("Login attempt: {}", credentials.username);
    // => Log: "Login attempt: alice"
    // => credentials.password = "secret" (NEVER log passwords!)

    // Post/Redirect/Get pattern prevents duplicate form submission on refresh
    Redirect::to("/dashboard")  // => 303 See Other → GET /dashboard
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/login", get(login_page).post(handle_login));
        // => get() and post() can be chained on same path with .route()
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

// Cargo.toml:
// axum = "0.8"
// tower-http = { version = "0.6", features = ["fs", "trace"] }
// tokio = { version = "1", features = ["full"] }

use axum::{routing::get_service, Router};
use tower_http::services::ServeDir;  // => Static file serving tower service

#[tokio::main]
async fn main() {
    // Serve the ./static directory at the /static URL prefix
    let static_service = ServeDir::new("static")  // => Serve from ./static/ directory
        .append_index_html_on_directories(true);   // => GET /static/ → serves index.html

    let app = Router::new()
        // Mount static file service under /static prefix
        .nest_service("/static", static_service)
        // => GET /static/style.css → reads ./static/style.css
        // => GET /static/js/app.js → reads ./static/js/app.js
        // => Handles ETags and Last-Modified for browser caching
        // => Range requests supported for large files
        .route("/", get(index));

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

async fn index() -> axum::response::Html<&'static str> {
    axum::response::Html(r#"
        <link rel="stylesheet" href="/static/style.css">
        <script src="/static/js/app.js"></script>
        <h1>Hello from Axum</h1>
    "#)
    // => HTML page that loads static files from /static/*
}

// Cargo.toml:
// axum = "0.8"
// askama = "0.12"
// askama_axum = "0.4"

use askama::Template;           // => Template derive macro and trait
use askama_axum::IntoResponse;  // => Implement IntoResponse for templates
use axum::{routing::get, Router};

// The template file lives at templates/index.html (relative to Cargo.toml)
#[derive(Template)]
#[template(path = "index.html")]  // => Compile-time: reads templates/index.html
struct IndexTemplate {
    title: String,                // => {{ title }} in template
    items: Vec<String>,           // => {% for item in items %} in template
    user_count: u32,              // => {{ user_count }} in template
}

// Template file (templates/index.html):
// <!DOCTYPE html>
// <html>
// <head><title>{{ title }}</title></head>
// <body>
//   <h1>{{ title }}</h1>
//   <ul>
//   {% for item in items %}
//     <li>{{ item }}</li>
//   {% endfor %}
//   </ul>
//   <p>{{ user_count }} users online</p>
// </body>
// </html>

async fn index() -> IndexTemplate {  // => askama_axum makes Template impl IntoResponse
    IndexTemplate {
        title: "My Axum App".to_string(),   // => Rendered into {{ title }}
        items: vec![                         // => Rendered in for loop
            "Rust".to_string(),
            "Axum".to_string(),
            "Askama".to_string(),
        ],
        user_count: 42,                      // => Rendered into {{ user_count }}
    }
    // => Response: 200 OK, Content-Type: text/html
    // => Rendered HTML with the template filled in
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/", get(index));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

// Cargo.toml:
// axum = "0.8"
// tower-http = { version = "0.6", features = ["trace"] }
// tracing = "0.1"
// tracing-subscriber = { version = "0.3", features = ["env-filter"] }
// tokio = { version = "1", features = ["full"] }

use axum::{routing::get, Router};
use tower_http::trace::TraceLayer;  // => Adds structured request tracing
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

#[tokio::main]
async fn main() {
    // Initialize tracing subscriber (prints to stdout by default)
    tracing_subscriber::registry()
        .with(
            tracing_subscriber::EnvFilter::try_from_default_env()
                // => Reads RUST_LOG env var: e.g. RUST_LOG=info,tower_http=debug
                .unwrap_or_else(|_| "my_app=info,tower_http=debug".into()),
                // => Fallback: app=info, tower_http=debug
        )
        .with(tracing_subscriber::fmt::layer())  // => Format logs as human-readable text
        .init();                                  // => Install as global default subscriber

    let app = Router::new()
        .route("/", get(handler))
        .layer(TraceLayer::new_for_http());
        // => Wraps the router with tracing middleware
        // => Logs: "request" span with method, uri, version
        // => Logs: "response" event with status, latency
        // => Output: INFO request{method=GET uri=/ version=HTTP/1.1} response{status=200 latency=1ms}

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

async fn handler() -> &'static str {
    tracing::info!("Handler called");  // => Emits INFO event inside request span
                                        // => Automatically includes request context
    "Hello"
}

use axum::{
    http::{Request, StatusCode},
    middleware::{self, Next},  // => from_fn and Next type
    response::Response,
    routing::get,
    Router,
};

// Middleware function signature: (Request, Next) -> Response
async fn auth_middleware(
    request: Request,  // => Incoming HTTP request (mutable via extensions)
    next: Next,        // => The rest of the middleware chain + handler
) -> Result<Response, StatusCode> {
    // Extract Authorization header from request
    let auth_header = request
        .headers()
        .get("Authorization")               // => Look for Authorization header
        .and_then(|v| v.to_str().ok());     // => Convert to &str

    match auth_header {
        Some(token) if token.starts_with("Bearer ") => {
            // Valid token format - continue to next middleware/handler
            let response = next.run(request).await;  // => Call remaining chain
                                                       // => Returns the handler's response
            Ok(response)
        }
        _ => {
            // Missing or malformed token - reject before reaching handler
            Err(StatusCode::UNAUTHORIZED)   // => 401 - handler never called
        }
    }
}

async fn protected_handler() -> &'static str {
    "Secret data"  // => Only reached if auth_middleware passed
}

async fn public_handler() -> &'static str {
    "Public data"  // => No auth required
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/secret", get(protected_handler))
        .layer(middleware::from_fn(auth_middleware))
        // => auth_middleware runs for ALL routes in this router
        .route("/public", get(public_handler));
        // => /public added AFTER layer, so NOT wrapped by auth_middleware
        // => Route order matters: layers apply to routes defined BEFORE them

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

// Cargo.toml:
// tower-http = { version = "0.6", features = ["timeout", "limit"] }
// tower = "0.5"

use axum::{routing::post, Router};
use std::time::Duration;
use tower::ServiceBuilder;         // => Compose multiple layers together
use tower_http::{
    limit::RequestBodyLimitLayer,  // => Reject bodies above size limit
    timeout::TimeoutLayer,         // => Cancel requests that take too long
};

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/upload", post(upload_handler))
        .layer(
            ServiceBuilder::new()
                .layer(TimeoutLayer::new(Duration::from_secs(30)))
                // => Cancel any request taking > 30 seconds
                // => Returns 408 Request Timeout
                // => Protects against slow clients and runaway handlers
                .layer(RequestBodyLimitLayer::new(10 * 1024 * 1024))
                // => Reject bodies larger than 10 MB
                // => Returns 413 Payload Too Large
                // => Prevents memory exhaustion from large uploads
        );

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

async fn upload_handler(body: axum::body::Bytes) -> String {
    // => body is at most 10MB (enforced by RequestBodyLimitLayer)
    // => Handler not called if timeout exceeded
    format!("Received {} bytes", body.len())
}

use axum::{routing::get, Router};

// User-related routes in their own module/function
fn user_router() -> Router {
    Router::new()
        .route("/", get(list_users))         // => GET /users/
        .route("/:id", get(get_user))        // => GET /users/:id
        .route("/:id/posts", get(user_posts)) // => GET /users/:id/posts
}

// Post-related routes
fn post_router() -> Router {
    Router::new()
        .route("/", get(list_posts))         // => GET /posts/
        .route("/:id", get(get_post))        // => GET /posts/:id
}

// API v1 router composes user and post routers
fn api_v1_router() -> Router {
    Router::new()
        .nest("/users", user_router())       // => Mounts user_router at /users prefix
        .nest("/posts", post_router())       // => Mounts post_router at /posts prefix
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .nest("/api/v1", api_v1_router())    // => All v1 routes under /api/v1
        // => GET /api/v1/users/
        // => GET /api/v1/users/:id
        // => GET /api/v1/users/:id/posts
        // => GET /api/v1/posts/
        // => GET /api/v1/posts/:id
        .route("/health", get(health));      // => Top-level /health (no prefix)

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

async fn list_users() -> &'static str { "users list" }
async fn get_user() -> &'static str { "one user" }
async fn user_posts() -> &'static str { "user posts" }
async fn list_posts() -> &'static str { "posts list" }
async fn get_post() -> &'static str { "one post" }
async fn health() -> &'static str { "OK" }

use axum::{
    http::{StatusCode, Uri},   // => Uri extractor for the requested path
    routing::get,
    Json, Router,
};
use serde::Serialize;

#[derive(Serialize)]
struct NotFoundResponse {
    error: String,    // => "Not Found"
    path: String,     // => The unmatched path
    status: u16,      // => 404
}

// Fallback handler receives the unmatched Uri
async fn not_found(uri: Uri) -> (StatusCode, Json<NotFoundResponse>) {
    (
        StatusCode::NOT_FOUND,
        Json(NotFoundResponse {
            error: "Not Found".to_string(),
            path: uri.path().to_string(),  // => The unmatched path, e.g. "/unknown"
            status: 404,
        }),
    )
    // => 404 {"error":"Not Found","path":"/unknown","status":404}
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/", get(|| async { "Home" }))  // => Inline async closure as handler
        .route("/about", get(|| async { "About" }))
        .fallback(not_found);                  // => Catches all unmatched requests
                                                // => Any method, any path
                                                // => Called ONLY if no route matches

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

use axum::{
    extract::{Path, Query, State},  // => Multiple extractors
    routing::get,
    Json, Router,
};
use serde::{Deserialize, Serialize};
use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    api_key: String,   // => Shared config in state
}

#[derive(Deserialize)]
struct ListOptions {
    limit: Option<u32>,   // => ?limit=10
    offset: Option<u32>,  // => ?offset=0
}

#[derive(Serialize)]
struct ItemList {
    user_id: u64,         // => From path
    limit: u32,           // => From query
    offset: u32,          // => From query
    api_key_prefix: String, // => From state
}

async fn list_user_items(
    Path(user_id): Path<u64>,         // => Extractor 1: parse :user_id from path
    Query(options): Query<ListOptions>, // => Extractor 2: parse ?limit=&offset=
    State(state): State<Arc<AppState>>, // => Extractor 3: inject shared state
    // All three run in order; any failure returns an error response
) -> Json<ItemList> {
    Json(ItemList {
        user_id,                                // => From path
        limit: options.limit.unwrap_or(20),     // => From query or default
        offset: options.offset.unwrap_or(0),    // => From query or default
        api_key_prefix: state.api_key.chars().take(4).collect(), // => From state
    })
    // => {"user_id":5,"limit":10,"offset":0,"api_key_prefix":"sk-l"}
}

#[tokio::main]
async fn main() {
    let state = Arc::new(AppState { api_key: "sk-live-abc123".into() });
    let app = Router::new()
        .route("/users/:user_id/items", get(list_user_items))
        .with_state(state);
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}