Struct App 

pub struct App { /* private fields */ }

A configured web application.

The App holds all routes, middleware, state, and lifecycle hooks, and provides methods to handle incoming requests.

Implementations

impl App

pub fn builder() -> AppBuilder

Creates a new application builder.

Examples found in repository

examples/hello_world.rs (line 62)

fn main() {
    println!("fastapi_rust Hello World Example");
    println!("================================\n");

    // Build the application
    //
    // App::builder() creates a new application builder that lets you:
    // - Add routes for different HTTP methods
    // - Configure middleware
    // - Set application state
    // - Define exception handlers
    let app = App::builder()
        // Register a GET handler for the root path "/"
        //
        // This is equivalent to:
        //   @app.get("/")
        //   def hello():
        //       return "Hello, World!"
        // in Python FastAPI
        .get("/", hello_handler)
        // Build the final immutable App
        .build();

    println!("App created with {} route(s)\n", app.route_count());

    // Create a test client to make requests to our app
    //
    // TestClient wraps any Handler (including App) and provides
    // a convenient API for making HTTP requests in tests.
    let client = TestClient::new(app);

    // Make a GET request to "/"
    println!("Making request: GET /");
    let response = client.get("/").send();

    // Check the response
    println!(
        "GET / -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    println!("Response: {}\n", response.text());

    // Verify success
    assert_eq!(response.status().as_u16(), 200);
    assert_eq!(response.text(), "Hello, World!");

    // Try a path that doesn't exist - should get 404
    println!("Making request: GET /not-found");
    let response = client.get("/not-found").send();
    println!(
        "GET /not-found -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(response.status().as_u16(), 404);

    println!("\nAll assertions passed!");
}

examples/getting_started.rs (line 29)

fn main() {
    println!("Getting Started Guide - Code Validation\n");

    // === Basic App Example ===
    println!("1. Basic app with two routes:");
    let app = App::builder()
        .get("/", hello)
        .get("/health", health)
        .build();

    println!("   Routes: {}", app.route_count());
    let client = TestClient::new(app);

    let response = client.get("/").send();
    println!(
        "   GET / -> {} ({})",
        response.status().as_u16(),
        response.text()
    );
    assert_eq!(response.status().as_u16(), 200);
    assert_eq!(response.text(), "Hello, World!");

    let response = client.get("/health").send();
    println!(
        "   GET /health -> {} ({})",
        response.status().as_u16(),
        response.text()
    );
    assert_eq!(response.status().as_u16(), 200);

    // === App with Middleware ===
    println!("\n2. App with middleware:");
    let app = App::builder()
        .middleware(RequestIdMiddleware::new())
        .middleware(SecurityHeaders::new())
        .get("/", hello)
        .build();

    let client = TestClient::new(app);
    let response = client.get("/").send();
    println!("   GET / -> {}", response.status().as_u16());
    assert_eq!(response.status().as_u16(), 200);

    // === App with Configuration ===
    println!("\n3. App with configuration:");
    let config = AppConfig::new()
        .name("My API")
        .version("1.0.0")
        .debug(true)
        .max_body_size(10 * 1024 * 1024)
        .request_timeout_ms(30_000);

    let app = App::builder().config(config).get("/", hello).build();

    println!("   App name: {}", app.config().name);
    println!("   Version: {}", app.config().version);
    assert_eq!(app.config().name, "My API");
    assert_eq!(app.config().version, "1.0.0");

    // === 404 for unknown routes ===
    println!("\n4. 404 for unknown routes:");
    let app = App::builder().get("/", hello).build();

    let client = TestClient::new(app);
    let response = client.get("/nonexistent").send();
    println!("   GET /nonexistent -> {}", response.status().as_u16());
    assert_eq!(response.status().as_u16(), 404);

    println!("\nAll getting started examples validated successfully!");
}

examples/crud_api.rs (line 262)

fn main() {
    // Initialize the global store
    *STORE.lock().unwrap() = Some(UserDb {
        users: HashMap::new(),
        next_id: 1,
    });

    println!("fastapi_rust CRUD API Example");
    println!("=============================\n");

    let app = App::builder()
        .post("/users", create_user)
        .get("/users", list_users)
        .get("/users/{id}", get_user)
        .put("/users/{id}", update_user)
        .delete("/users/{id}", delete_user)
        .build();

    println!("App created with {} route(s)\n", app.route_count());
    let client = TestClient::new(app);

    // 1. Create users
    println!("1. Create users");
    let resp = client
        .post("/users")
        .header("content-type", "application/json")
        .body(r#"{"name": "Alice", "email": "alice@example.com"}"#)
        .send();
    println!(
        "   POST /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 201);

    let resp = client
        .post("/users")
        .header("content-type", "application/json")
        .body(r#"{"name": "Bob", "email": "bob@example.com"}"#)
        .send();
    println!(
        "   POST /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 201);

    // 2. List users
    println!("\n2. List all users");
    let resp = client.get("/users").send();
    println!(
        "   GET /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 200);

    // 3. Get user by ID
    println!("\n3. Get user by ID");
    let resp = client.get("/users/1").send();
    println!(
        "   GET /users/1 -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 200);

    // 4. Get nonexistent user
    println!("\n4. Get nonexistent user");
    let resp = client.get("/users/999").send();
    println!(
        "   GET /users/999 -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 404);

    // 5. Update user
    println!("\n5. Update user");
    let resp = client
        .put("/users/1")
        .header("content-type", "application/json")
        .body(r#"{"name": "Alice Smith", "email": "alice.smith@example.com"}"#)
        .send();
    println!(
        "   PUT /users/1 -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 200);

    // 6. Validation: empty name
    println!("\n6. Validation error (empty name)");
    let resp = client
        .post("/users")
        .header("content-type", "application/json")
        .body(r#"{"name": "", "email": "bad@example.com"}"#)
        .send();
    println!(
        "   POST /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 400);

    // 7. Validation: invalid email
    println!("\n7. Validation error (invalid email)");
    let resp = client
        .post("/users")
        .header("content-type", "application/json")
        .body(r#"{"name": "Charlie", "email": "not-an-email"}"#)
        .send();
    println!(
        "   POST /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 400);

    // 8. Wrong Content-Type
    println!("\n8. Wrong Content-Type");
    let resp = client
        .post("/users")
        .header("content-type", "text/plain")
        .body(r#"{"name": "Dan", "email": "dan@example.com"}"#)
        .send();
    println!(
        "   POST /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 415);

    // 9. Delete user
    println!("\n9. Delete user");
    let resp = client.delete("/users/2").send();
    println!("   DELETE /users/2 -> {}", resp.status().as_u16());
    assert_eq!(resp.status().as_u16(), 204);

    // 10. Verify deletion
    println!("\n10. Verify deletion");
    let resp = client.get("/users/2").send();
    println!(
        "   GET /users/2 -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 404);

    let resp = client.get("/users").send();
    println!(
        "   GET /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 200);

    println!("\nAll CRUD operations passed!");
}

examples/auth_example.rs (line 253)

fn main() {
    println!("fastapi_rust Authentication Example");
    println!("====================================\n");

    // Build the application with public and protected routes
    let app = App::builder()
        // Public endpoints - accessible to everyone
        .get("/public", public_handler)
        // Login endpoint - returns a token
        .post("/login", login_handler)
        // Protected endpoint - requires valid bearer token
        .get("/protected", protected_handler)
        .build();

    println!("App created with {} route(s)\n", app.route_count());

    // Create a test client
    let client = TestClient::new(app);

    // =========================================================================
    // Test 1: Public endpoint - no auth required
    // =========================================================================
    println!("1. Public endpoint - no auth required");
    let response = client.get("/public").send();
    println!(
        "   GET /public -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(response.status().as_u16(), 200);
    assert!(response.text().contains("public endpoint"));

    // =========================================================================
    // Test 2: Protected endpoint - without token (should get 401)
    // =========================================================================
    println!("\n2. Protected endpoint - without token");
    let response = client.get("/protected").send();
    println!(
        "   GET /protected -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(
        response.status().as_u16(),
        401,
        "Protected endpoint should return 401 without token"
    );

    // Check for WWW-Authenticate header
    let has_www_auth = response
        .headers()
        .iter()
        .any(|(name, value)| name == "www-authenticate" && value == b"Bearer");
    assert!(
        has_www_auth,
        "401 response should include WWW-Authenticate: Bearer header"
    );

    // =========================================================================
    // Test 3: Login endpoint - get a token
    // =========================================================================
    println!("\n3. Login endpoint - get a token");
    let response = client
        .post("/login")
        .header("content-type", "application/json")
        .body(r#"{"username":"test","password":"test123"}"#)
        .send();
    println!(
        "   POST /login -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(response.status().as_u16(), 200);

    // Parse the response to get the token
    let body: serde_json::Value = serde_json::from_str(response.text()).unwrap();
    let token = body["access_token"].as_str().unwrap();
    println!("   Token: {token}");
    assert_eq!(token, SECRET_TOKEN);

    // =========================================================================
    // Test 4: Protected endpoint - with valid token (should get 200)
    // =========================================================================
    println!("\n4. Protected endpoint - with valid token");
    let response = client
        .get("/protected")
        .header("authorization", format!("Bearer {SECRET_TOKEN}"))
        .send();
    println!(
        "   GET /protected (Authorization: Bearer {}) -> {} {}",
        SECRET_TOKEN,
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(
        response.status().as_u16(),
        200,
        "Protected endpoint should return 200 with valid token"
    );
    assert!(response.text().contains("protected resource"));

    // =========================================================================
    // Test 5: Protected endpoint - with invalid token (should get 403)
    // =========================================================================
    println!("\n5. Protected endpoint - with invalid token");
    let response = client
        .get("/protected")
        .header("authorization", "Bearer wrong_token")
        .send();
    println!(
        "   GET /protected (Authorization: Bearer wrong_token) -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(
        response.status().as_u16(),
        403,
        "Protected endpoint should return 403 with invalid token"
    );

    // =========================================================================
    // Test 6: Protected endpoint - with wrong auth scheme (should get 401)
    // =========================================================================
    println!("\n6. Protected endpoint - with wrong auth scheme");
    let response = client
        .get("/protected")
        .header("authorization", "Basic dXNlcjpwYXNz")
        .send();
    println!(
        "   GET /protected (Authorization: Basic ...) -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(
        response.status().as_u16(),
        401,
        "Protected endpoint should return 401 with wrong auth scheme"
    );

    // =========================================================================
    // Test 7: Login with wrong Content-Type (should get 415)
    // =========================================================================
    println!("\n7. Login with wrong Content-Type");
    let response = client
        .post("/login")
        .header("content-type", "text/plain")
        .body("username=test&password=test123")
        .send();
    println!(
        "   POST /login (Content-Type: text/plain) -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(
        response.status().as_u16(),
        415,
        "Login should return 415 with wrong Content-Type"
    );

    // =========================================================================
    // Test 8: Token case sensitivity (lowercase 'bearer')
    // =========================================================================
    println!("\n8. Token case sensitivity (lowercase 'bearer')");
    let response = client
        .get("/protected")
        .header("authorization", format!("bearer {SECRET_TOKEN}"))
        .send();
    println!(
        "   GET /protected (Authorization: bearer {}) -> {} {}",
        SECRET_TOKEN,
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(
        response.status().as_u16(),
        200,
        "Bearer scheme should be case-insensitive (lowercase accepted)"
    );

    println!("\nAll authentication tests passed!");
}

pub fn config(&self) -> &AppConfig

Returns the application configuration.

Examples found in repository

examples/getting_started.rs (line 78)

fn main() {
    println!("Getting Started Guide - Code Validation\n");

    // === Basic App Example ===
    println!("1. Basic app with two routes:");
    let app = App::builder()
        .get("/", hello)
        .get("/health", health)
        .build();

    println!("   Routes: {}", app.route_count());
    let client = TestClient::new(app);

    let response = client.get("/").send();
    println!(
        "   GET / -> {} ({})",
        response.status().as_u16(),
        response.text()
    );
    assert_eq!(response.status().as_u16(), 200);
    assert_eq!(response.text(), "Hello, World!");

    let response = client.get("/health").send();
    println!(
        "   GET /health -> {} ({})",
        response.status().as_u16(),
        response.text()
    );
    assert_eq!(response.status().as_u16(), 200);

    // === App with Middleware ===
    println!("\n2. App with middleware:");
    let app = App::builder()
        .middleware(RequestIdMiddleware::new())
        .middleware(SecurityHeaders::new())
        .get("/", hello)
        .build();

    let client = TestClient::new(app);
    let response = client.get("/").send();
    println!("   GET / -> {}", response.status().as_u16());
    assert_eq!(response.status().as_u16(), 200);

    // === App with Configuration ===
    println!("\n3. App with configuration:");
    let config = AppConfig::new()
        .name("My API")
        .version("1.0.0")
        .debug(true)
        .max_body_size(10 * 1024 * 1024)
        .request_timeout_ms(30_000);

    let app = App::builder().config(config).get("/", hello).build();

    println!("   App name: {}", app.config().name);
    println!("   Version: {}", app.config().version);
    assert_eq!(app.config().name, "My API");
    assert_eq!(app.config().version, "1.0.0");

    // === 404 for unknown routes ===
    println!("\n4. 404 for unknown routes:");
    let app = App::builder().get("/", hello).build();

    let client = TestClient::new(app);
    let response = client.get("/nonexistent").send();
    println!("   GET /nonexistent -> {}", response.status().as_u16());
    assert_eq!(response.status().as_u16(), 404);

    println!("\nAll getting started examples validated successfully!");
}

pub fn route_count(&self) -> usize

Returns the number of registered routes.

Examples found in repository

examples/hello_world.rs (line 74)

fn main() {
    println!("fastapi_rust Hello World Example");
    println!("================================\n");

    // Build the application
    //
    // App::builder() creates a new application builder that lets you:
    // - Add routes for different HTTP methods
    // - Configure middleware
    // - Set application state
    // - Define exception handlers
    let app = App::builder()
        // Register a GET handler for the root path "/"
        //
        // This is equivalent to:
        //   @app.get("/")
        //   def hello():
        //       return "Hello, World!"
        // in Python FastAPI
        .get("/", hello_handler)
        // Build the final immutable App
        .build();

    println!("App created with {} route(s)\n", app.route_count());

    // Create a test client to make requests to our app
    //
    // TestClient wraps any Handler (including App) and provides
    // a convenient API for making HTTP requests in tests.
    let client = TestClient::new(app);

    // Make a GET request to "/"
    println!("Making request: GET /");
    let response = client.get("/").send();

    // Check the response
    println!(
        "GET / -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    println!("Response: {}\n", response.text());

    // Verify success
    assert_eq!(response.status().as_u16(), 200);
    assert_eq!(response.text(), "Hello, World!");

    // Try a path that doesn't exist - should get 404
    println!("Making request: GET /not-found");
    let response = client.get("/not-found").send();
    println!(
        "GET /not-found -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(response.status().as_u16(), 404);

    println!("\nAll assertions passed!");
}

examples/getting_started.rs (line 34)

fn main() {
    println!("Getting Started Guide - Code Validation\n");

    // === Basic App Example ===
    println!("1. Basic app with two routes:");
    let app = App::builder()
        .get("/", hello)
        .get("/health", health)
        .build();

    println!("   Routes: {}", app.route_count());
    let client = TestClient::new(app);

    let response = client.get("/").send();
    println!(
        "   GET / -> {} ({})",
        response.status().as_u16(),
        response.text()
    );
    assert_eq!(response.status().as_u16(), 200);
    assert_eq!(response.text(), "Hello, World!");

    let response = client.get("/health").send();
    println!(
        "   GET /health -> {} ({})",
        response.status().as_u16(),
        response.text()
    );
    assert_eq!(response.status().as_u16(), 200);

    // === App with Middleware ===
    println!("\n2. App with middleware:");
    let app = App::builder()
        .middleware(RequestIdMiddleware::new())
        .middleware(SecurityHeaders::new())
        .get("/", hello)
        .build();

    let client = TestClient::new(app);
    let response = client.get("/").send();
    println!("   GET / -> {}", response.status().as_u16());
    assert_eq!(response.status().as_u16(), 200);

    // === App with Configuration ===
    println!("\n3. App with configuration:");
    let config = AppConfig::new()
        .name("My API")
        .version("1.0.0")
        .debug(true)
        .max_body_size(10 * 1024 * 1024)
        .request_timeout_ms(30_000);

    let app = App::builder().config(config).get("/", hello).build();

    println!("   App name: {}", app.config().name);
    println!("   Version: {}", app.config().version);
    assert_eq!(app.config().name, "My API");
    assert_eq!(app.config().version, "1.0.0");

    // === 404 for unknown routes ===
    println!("\n4. 404 for unknown routes:");
    let app = App::builder().get("/", hello).build();

    let client = TestClient::new(app);
    let response = client.get("/nonexistent").send();
    println!("   GET /nonexistent -> {}", response.status().as_u16());
    assert_eq!(response.status().as_u16(), 404);

    println!("\nAll getting started examples validated successfully!");
}

examples/crud_api.rs (line 270)

fn main() {
    // Initialize the global store
    *STORE.lock().unwrap() = Some(UserDb {
        users: HashMap::new(),
        next_id: 1,
    });

    println!("fastapi_rust CRUD API Example");
    println!("=============================\n");

    let app = App::builder()
        .post("/users", create_user)
        .get("/users", list_users)
        .get("/users/{id}", get_user)
        .put("/users/{id}", update_user)
        .delete("/users/{id}", delete_user)
        .build();

    println!("App created with {} route(s)\n", app.route_count());
    let client = TestClient::new(app);

    // 1. Create users
    println!("1. Create users");
    let resp = client
        .post("/users")
        .header("content-type", "application/json")
        .body(r#"{"name": "Alice", "email": "alice@example.com"}"#)
        .send();
    println!(
        "   POST /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 201);

    let resp = client
        .post("/users")
        .header("content-type", "application/json")
        .body(r#"{"name": "Bob", "email": "bob@example.com"}"#)
        .send();
    println!(
        "   POST /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 201);

    // 2. List users
    println!("\n2. List all users");
    let resp = client.get("/users").send();
    println!(
        "   GET /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 200);

    // 3. Get user by ID
    println!("\n3. Get user by ID");
    let resp = client.get("/users/1").send();
    println!(
        "   GET /users/1 -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 200);

    // 4. Get nonexistent user
    println!("\n4. Get nonexistent user");
    let resp = client.get("/users/999").send();
    println!(
        "   GET /users/999 -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 404);

    // 5. Update user
    println!("\n5. Update user");
    let resp = client
        .put("/users/1")
        .header("content-type", "application/json")
        .body(r#"{"name": "Alice Smith", "email": "alice.smith@example.com"}"#)
        .send();
    println!(
        "   PUT /users/1 -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 200);

    // 6. Validation: empty name
    println!("\n6. Validation error (empty name)");
    let resp = client
        .post("/users")
        .header("content-type", "application/json")
        .body(r#"{"name": "", "email": "bad@example.com"}"#)
        .send();
    println!(
        "   POST /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 400);

    // 7. Validation: invalid email
    println!("\n7. Validation error (invalid email)");
    let resp = client
        .post("/users")
        .header("content-type", "application/json")
        .body(r#"{"name": "Charlie", "email": "not-an-email"}"#)
        .send();
    println!(
        "   POST /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 400);

    // 8. Wrong Content-Type
    println!("\n8. Wrong Content-Type");
    let resp = client
        .post("/users")
        .header("content-type", "text/plain")
        .body(r#"{"name": "Dan", "email": "dan@example.com"}"#)
        .send();
    println!(
        "   POST /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 415);

    // 9. Delete user
    println!("\n9. Delete user");
    let resp = client.delete("/users/2").send();
    println!("   DELETE /users/2 -> {}", resp.status().as_u16());
    assert_eq!(resp.status().as_u16(), 204);

    // 10. Verify deletion
    println!("\n10. Verify deletion");
    let resp = client.get("/users/2").send();
    println!(
        "   GET /users/2 -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 404);

    let resp = client.get("/users").send();
    println!(
        "   GET /users -> {} {}",
        resp.status().as_u16(),
        resp.text()
    );
    assert_eq!(resp.status().as_u16(), 200);

    println!("\nAll CRUD operations passed!");
}

examples/auth_example.rs (line 262)

fn main() {
    println!("fastapi_rust Authentication Example");
    println!("====================================\n");

    // Build the application with public and protected routes
    let app = App::builder()
        // Public endpoints - accessible to everyone
        .get("/public", public_handler)
        // Login endpoint - returns a token
        .post("/login", login_handler)
        // Protected endpoint - requires valid bearer token
        .get("/protected", protected_handler)
        .build();

    println!("App created with {} route(s)\n", app.route_count());

    // Create a test client
    let client = TestClient::new(app);

    // =========================================================================
    // Test 1: Public endpoint - no auth required
    // =========================================================================
    println!("1. Public endpoint - no auth required");
    let response = client.get("/public").send();
    println!(
        "   GET /public -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(response.status().as_u16(), 200);
    assert!(response.text().contains("public endpoint"));

    // =========================================================================
    // Test 2: Protected endpoint - without token (should get 401)
    // =========================================================================
    println!("\n2. Protected endpoint - without token");
    let response = client.get("/protected").send();
    println!(
        "   GET /protected -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(
        response.status().as_u16(),
        401,
        "Protected endpoint should return 401 without token"
    );

    // Check for WWW-Authenticate header
    let has_www_auth = response
        .headers()
        .iter()
        .any(|(name, value)| name == "www-authenticate" && value == b"Bearer");
    assert!(
        has_www_auth,
        "401 response should include WWW-Authenticate: Bearer header"
    );

    // =========================================================================
    // Test 3: Login endpoint - get a token
    // =========================================================================
    println!("\n3. Login endpoint - get a token");
    let response = client
        .post("/login")
        .header("content-type", "application/json")
        .body(r#"{"username":"test","password":"test123"}"#)
        .send();
    println!(
        "   POST /login -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(response.status().as_u16(), 200);

    // Parse the response to get the token
    let body: serde_json::Value = serde_json::from_str(response.text()).unwrap();
    let token = body["access_token"].as_str().unwrap();
    println!("   Token: {token}");
    assert_eq!(token, SECRET_TOKEN);

    // =========================================================================
    // Test 4: Protected endpoint - with valid token (should get 200)
    // =========================================================================
    println!("\n4. Protected endpoint - with valid token");
    let response = client
        .get("/protected")
        .header("authorization", format!("Bearer {SECRET_TOKEN}"))
        .send();
    println!(
        "   GET /protected (Authorization: Bearer {}) -> {} {}",
        SECRET_TOKEN,
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(
        response.status().as_u16(),
        200,
        "Protected endpoint should return 200 with valid token"
    );
    assert!(response.text().contains("protected resource"));

    // =========================================================================
    // Test 5: Protected endpoint - with invalid token (should get 403)
    // =========================================================================
    println!("\n5. Protected endpoint - with invalid token");
    let response = client
        .get("/protected")
        .header("authorization", "Bearer wrong_token")
        .send();
    println!(
        "   GET /protected (Authorization: Bearer wrong_token) -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(
        response.status().as_u16(),
        403,
        "Protected endpoint should return 403 with invalid token"
    );

    // =========================================================================
    // Test 6: Protected endpoint - with wrong auth scheme (should get 401)
    // =========================================================================
    println!("\n6. Protected endpoint - with wrong auth scheme");
    let response = client
        .get("/protected")
        .header("authorization", "Basic dXNlcjpwYXNz")
        .send();
    println!(
        "   GET /protected (Authorization: Basic ...) -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(
        response.status().as_u16(),
        401,
        "Protected endpoint should return 401 with wrong auth scheme"
    );

    // =========================================================================
    // Test 7: Login with wrong Content-Type (should get 415)
    // =========================================================================
    println!("\n7. Login with wrong Content-Type");
    let response = client
        .post("/login")
        .header("content-type", "text/plain")
        .body("username=test&password=test123")
        .send();
    println!(
        "   POST /login (Content-Type: text/plain) -> {} {}",
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(
        response.status().as_u16(),
        415,
        "Login should return 415 with wrong Content-Type"
    );

    // =========================================================================
    // Test 8: Token case sensitivity (lowercase 'bearer')
    // =========================================================================
    println!("\n8. Token case sensitivity (lowercase 'bearer')");
    let response = client
        .get("/protected")
        .header("authorization", format!("bearer {SECRET_TOKEN}"))
        .send();
    println!(
        "   GET /protected (Authorization: bearer {}) -> {} {}",
        SECRET_TOKEN,
        response.status().as_u16(),
        response.status().canonical_reason()
    );
    assert_eq!(
        response.status().as_u16(),
        200,
        "Bearer scheme should be case-insensitive (lowercase accepted)"
    );

    println!("\nAll authentication tests passed!");
}

pub fn state(&self) -> &Arc<RwLock<RawRwLock, StateContainer>>

Returns the shared state container (protected by RwLock for lifespan mutation).

pub fn get_state<T>(&self) -> Option<Arc<T>>

where T: Send + Sync + 'static,

Gets a reference to shared state of type T.

pub fn dependency_overrides(&self) -> &Arc<DependencyOverrides>

Returns the dependency overrides registry.

pub fn override_dependency<T, F, Fut>(&self, f: F)

where T: FromDependency, F: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<T, <T as FromDependency>::Error>> + Send + 'static,

Registers a dependency override for this application (useful in tests).

pub fn override_dependency_value<T>(&self, value: T)

where T: FromDependency,

Registers a fixed dependency override value.

pub fn clear_dependency_overrides(&self)

Clears all registered dependency overrides.

pub fn exception_handlers(&self) -> &Arc<ExceptionHandlers>

Returns the exception handlers registry.

pub fn handle_error<E>(&self, ctx: &RequestContext, err: E) -> Option<Response>

where E: Error + Send + Sync + 'static,

Handles an error using registered exception handlers.

If a handler is registered for the error type, it will be invoked. Otherwise, returns None.

pub fn handle_error_or_default<E>( &self, ctx: &RequestContext, err: E, ) -> Response

where E: Error + Send + Sync + 'static,

Handles an error, returning a 500 response if no handler is registered.

pub fn mounted_apps(&self) -> &[MountedApp]

Returns the mounted sub-applications.

pub async fn handle(&self, ctx: &RequestContext, req: &mut Request) -> Response

Handles an incoming request.

This first checks mounted sub-applications (in registration order), then matches against registered routes, runs middleware, and returns the response. Path parameters are extracted and stored in request extensions for use by the Path extractor.

Mounted App Handling

When a request path matches a mounted app’s prefix, the request is forwarded to that app with the prefix stripped from the path. The mounted app’s middleware runs instead of the parent’s middleware.

Special Parameter Injection

• ResponseMutations: Headers and cookies set by handlers are automatically applied to the final response.
• BackgroundTasks: Tasks are stored in request extensions via BackgroundTasksInner. The HTTP server should retrieve and execute these after sending the response using take_background_tasks().

pub fn take_background_tasks(req: &mut Request) -> Option<BackgroundTasks>

Take background tasks from a request after handling.

This should be called by the HTTP server after handle() returns and the response has been sent to the client. The returned tasks should be executed asynchronously.

Example

let response = app.handle(&ctx, &mut request).await;
// Send response to client...
if let Some(tasks) = App::take_background_tasks(&mut request) {
    tasks.execute_all().await;
}

pub async fn run_startup_hooks(&self) -> StartupOutcome

Runs all startup hooks.

Hooks run in registration order (FIFO). If a hook returns an error with abort: true, execution stops and returns StartupOutcome::Aborted.

This consumes the startup hooks - they can only be run once.

Returns

• StartupOutcome::Success if all hooks succeeded
• StartupOutcome::PartialSuccess if some hooks had non-fatal errors
• StartupOutcome::Aborted if a fatal hook error occurred

pub async fn run_shutdown_hooks(&self)

Runs all shutdown hooks.

Hooks run in reverse registration order (LIFO). Errors are logged but do not stop other hooks from running.

This consumes the shutdown hooks - they can only be run once.

pub fn transfer_shutdown_hooks(&self, controller: &ShutdownController)

Transfers shutdown hooks to a ShutdownController.

This moves all registered shutdown hooks to the controller, which will run them during the appropriate shutdown phase.

Call this when integrating with the server’s shutdown mechanism.

pub fn pending_startup_hooks(&self) -> usize

Returns the number of pending startup hooks.

pub fn pending_shutdown_hooks(&self) -> usize

Returns the number of pending shutdown hooks.

pub fn test_client(self: Arc<App>) -> TestClient<Arc<App>>

Creates a crate::TestClient for this application.

The test client provides in-process testing without network overhead, simulating HTTP requests against the full application stack including middleware, routing, and handlers.

Example

use fastapi_core::{App, Request, Response, RequestContext, Method};

async fn hello(ctx: &RequestContext, req: &mut Request) -> Response {
    Response::ok().body_text("Hello!")
}

let app = App::builder()
    .route("/hello", Method::Get, hello)
    .build();

// Create test client from app
let client = app.test_client();

// Make requests
let response = client.get("/hello").send();
assert_eq!(response.status().as_u16(), 200);
assert_eq!(response.text(), "Hello!");

pub fn test_client_with_seed(self: Arc<App>, seed: u64) -> TestClient<Arc<App>>

Creates a crate::TestClient with a specific seed for deterministic testing.

Using the same seed produces reproducible behavior for tests involving concurrent operations or random elements.

Example

let app = Arc::new(App::builder().build());
let client = app.test_client_with_seed(42);
// Tests will be deterministic with this seed

Trait Implementations

impl AppServeExt for App

fn serve( self, addr: impl Into<String>, ) -> impl Future<Output = Result<(), ServeError>> + Send

Starts the HTTP server and begins accepting connections.

fn serve_with_config( self, config: ServerConfig, ) -> impl Future<Output = Result<(), ServeError>> + Send

Starts the HTTP server with custom configuration.

impl Debug for App

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Handler for App

fn call<'a>( &'a self, ctx: &'a RequestContext, req: &'a mut Request, ) -> Pin<Box<dyn Future<Output = Response> + Send + 'a>>

Process a request and return a response.

fn dependency_overrides(&self) -> Option<Arc<DependencyOverrides>>

Optional dependency overrides to apply when building request contexts.