Struct Response 

pub struct Response { /* private fields */ }

HTTP response.

Implementations

impl Response

pub fn with_status(status: StatusCode) -> Response

Create a response with the given status.

Examples found in repository

examples/crud_api.rs (line 126)

fn json_error(status: StatusCode, detail: &str) -> Response {
    let body = serde_json::json!({ "detail": detail });
    Response::with_status(status)
        .header("content-type", b"application/json".to_vec())
        .body(ResponseBody::Bytes(body.to_string().into_bytes()))
}

fn json_response(status: StatusCode, value: &impl Serialize) -> Response {
    match serde_json::to_string(value) {
        Ok(text) => Response::with_status(status)
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(text.into_bytes())),
        Err(err) => json_error(
            StatusCode::INTERNAL_SERVER_ERROR,
            &format!("JSON serialization failed: {err}"),
        ),
    }
}

fn validate_input(input: &UserInput) -> Option<Response> {
    if input.name.trim().is_empty() {
        return Some(json_error(
            StatusCode::BAD_REQUEST,
            "name must not be empty",
        ));
    }
    if !input.email.contains('@') {
        return Some(json_error(
            StatusCode::BAD_REQUEST,
            "email must contain '@'",
        ));
    }
    None
}

// ============================================================================
// Handlers
// ============================================================================

fn create_user(_ctx: &RequestContext, req: &mut Request) -> std::future::Ready<Response> {
    let input = match parse_json_body::<UserInput>(req) {
        Ok(v) => v,
        Err(r) => return std::future::ready(r),
    };
    if let Some(r) = validate_input(&input) {
        return std::future::ready(r);
    }

    let user = with_db(|db| {
        let id = db.next_id;
        db.next_id += 1;
        let user = User {
            id,
            name: input.name,
            email: input.email,
        };
        db.users.insert(id, user.clone());
        user
    });

    std::future::ready(json_response(StatusCode::CREATED, &user))
}

fn list_users(_ctx: &RequestContext, _req: &mut Request) -> std::future::Ready<Response> {
    let users = with_db(|db| {
        let mut v: Vec<User> = db.users.values().cloned().collect();
        v.sort_by_key(|u| u.id);
        v
    });
    std::future::ready(json_response(StatusCode::OK, &users))
}

fn get_user(_ctx: &RequestContext, req: &mut Request) -> std::future::Ready<Response> {
    let id = match extract_user_id(req) {
        Ok(id) => id,
        Err(r) => return std::future::ready(r),
    };
    let result = with_db(|db| db.users.get(&id).cloned());
    match result {
        Some(user) => std::future::ready(json_response(StatusCode::OK, &user)),
        None => std::future::ready(json_error(
            StatusCode::NOT_FOUND,
            &format!("User {id} not found"),
        )),
    }
}

fn update_user(_ctx: &RequestContext, req: &mut Request) -> std::future::Ready<Response> {
    let id = match extract_user_id(req) {
        Ok(id) => id,
        Err(r) => return std::future::ready(r),
    };
    let input = match parse_json_body::<UserInput>(req) {
        Ok(v) => v,
        Err(r) => return std::future::ready(r),
    };
    if let Some(r) = validate_input(&input) {
        return std::future::ready(r);
    }

    let result = with_db(|db| {
        db.users.get_mut(&id).map(|user| {
            user.name = input.name;
            user.email = input.email;
            user.clone()
        })
    });
    match result {
        Some(user) => std::future::ready(json_response(StatusCode::OK, &user)),
        None => std::future::ready(json_error(
            StatusCode::NOT_FOUND,
            &format!("User {id} not found"),
        )),
    }
}

fn delete_user(_ctx: &RequestContext, req: &mut Request) -> std::future::Ready<Response> {
    let id = match extract_user_id(req) {
        Ok(id) => id,
        Err(r) => return std::future::ready(r),
    };
    let removed = with_db(|db| db.users.remove(&id).is_some());
    if removed {
        std::future::ready(Response::with_status(StatusCode::NO_CONTENT))
    } else {
        std::future::ready(json_error(
            StatusCode::NOT_FOUND,
            &format!("User {id} not found"),
        ))
    }
}

examples/auth_example.rs (line 121)

fn login_handler(_ctx: &RequestContext, req: &mut Request) -> std::future::Ready<Response> {
    // For this demo, we only check Content-Type and return a fixed token.
    // Real applications should parse the body and validate credentials.

    // Check Content-Type
    let is_json = req
        .headers()
        .get("content-type")
        .is_some_and(|ct| ct.starts_with(b"application/json"));

    if !is_json {
        let error = serde_json::json!({
            "detail": "Content-Type must be application/json"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNSUPPORTED_MEDIA_TYPE)
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(error.to_string().into_bytes())),
        );
    }

    // For demo purposes, we don't validate credentials - just return the token
    // In production:
    // 1. Parse the request body as LoginRequest
    // 2. Verify username/password against your database
    // 3. Generate a unique, cryptographically secure token
    // 4. Store token -> user_id mapping (with expiration)

    let response = LoginResponse {
        access_token: DEMO_BEARER_VALUE.to_string(),
        token_type: "bearer",
    };

    std::future::ready(
        Response::ok()
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(json_bytes(&response))),
    )
}

/// Handler for protected endpoint - requires valid bearer token.
///
/// This handler manually extracts and validates the bearer token:
/// 1. Gets the Authorization header
/// 2. Verifies it uses the Bearer scheme
/// 3. Validates the token against our secret using constant-time comparison
///
/// Returns appropriate error responses for each failure mode.
fn protected_handler(_ctx: &RequestContext, req: &mut Request) -> std::future::Ready<Response> {
    // Step 1: Get the Authorization header
    let Some(auth_header) = req.headers().get("authorization") else {
        // Missing header -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Not authenticated"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    };

    // Step 2: Parse the Authorization header
    let Ok(auth_str) = std::str::from_utf8(auth_header) else {
        // Invalid UTF-8 -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Invalid authentication credentials"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    };

    // Step 3: Check for "Bearer " prefix (case-insensitive for the scheme)
    let Some(bearer_value) = auth_str
        .strip_prefix("Bearer ")
        .or_else(|| auth_str.strip_prefix("bearer "))
    else {
        // Wrong scheme -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Invalid authentication credentials"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    };

    let bearer_value = bearer_value.trim();
    if bearer_value.is_empty() {
        // Empty token -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Invalid authentication credentials"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    }

    // Step 4: Validate the bearer value using constant-time comparison
    if !bearer_value.secure_eq(DEMO_BEARER_VALUE) {
        // Invalid token -> 403 Forbidden
        let body = serde_json::json!({
            "detail": "Invalid token"
        });
        return std::future::ready(
            Response::with_status(StatusCode::FORBIDDEN)
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    }

    // Token is valid - return protected data
    let user_info = UserInfo {
        username: "demo_user".to_string(),
        message: "You have accessed a protected resource!".to_string(),
    };

    std::future::ready(
        Response::ok()
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(json_bytes(&user_info))),
    )
}

pub fn ok() -> Response

Create a 200 OK response.

Examples found in repository

examples/getting_started.rs (line 14)

fn hello(_ctx: &RequestContext, _req: &mut Request) -> std::future::Ready<Response> {
    std::future::ready(Response::ok().body(ResponseBody::Bytes(b"Hello, World!".to_vec())))
}

/// Handler for GET /health
fn health(_ctx: &RequestContext, _req: &mut Request) -> std::future::Ready<Response> {
    std::future::ready(
        Response::ok().body(ResponseBody::Bytes(b"{\"status\":\"healthy\"}".to_vec())),
    )
}

examples/hello_world.rs (line 48)

fn hello_handler(_ctx: &RequestContext, _req: &mut Request) -> std::future::Ready<Response> {
    // Create a 200 OK response with a plain text body
    std::future::ready(Response::ok().body(ResponseBody::Bytes(b"Hello, World!".to_vec())))
}

examples/auth_example.rs (line 91)

fn public_handler(_ctx: &RequestContext, _req: &mut Request) -> std::future::Ready<Response> {
    let body = serde_json::json!({
        "message": "This is a public endpoint - no authentication required!"
    });
    std::future::ready(
        Response::ok()
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(body.to_string().into_bytes())),
    )
}

/// Handler for the login endpoint.
///
/// In a real application:
/// 1. Validate username/password against a database
/// 2. Generate a unique token (JWT or random)
/// 3. Store the token with associated user info
/// 4. Return the token to the client
///
/// For this demo, we accept any credentials and return a fixed token.
fn login_handler(_ctx: &RequestContext, req: &mut Request) -> std::future::Ready<Response> {
    // For this demo, we only check Content-Type and return a fixed token.
    // Real applications should parse the body and validate credentials.

    // Check Content-Type
    let is_json = req
        .headers()
        .get("content-type")
        .is_some_and(|ct| ct.starts_with(b"application/json"));

    if !is_json {
        let error = serde_json::json!({
            "detail": "Content-Type must be application/json"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNSUPPORTED_MEDIA_TYPE)
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(error.to_string().into_bytes())),
        );
    }

    // For demo purposes, we don't validate credentials - just return the token
    // In production:
    // 1. Parse the request body as LoginRequest
    // 2. Verify username/password against your database
    // 3. Generate a unique, cryptographically secure token
    // 4. Store token -> user_id mapping (with expiration)

    let response = LoginResponse {
        access_token: DEMO_BEARER_VALUE.to_string(),
        token_type: "bearer",
    };

    std::future::ready(
        Response::ok()
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(json_bytes(&response))),
    )
}

/// Handler for protected endpoint - requires valid bearer token.
///
/// This handler manually extracts and validates the bearer token:
/// 1. Gets the Authorization header
/// 2. Verifies it uses the Bearer scheme
/// 3. Validates the token against our secret using constant-time comparison
///
/// Returns appropriate error responses for each failure mode.
fn protected_handler(_ctx: &RequestContext, req: &mut Request) -> std::future::Ready<Response> {
    // Step 1: Get the Authorization header
    let Some(auth_header) = req.headers().get("authorization") else {
        // Missing header -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Not authenticated"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    };

    // Step 2: Parse the Authorization header
    let Ok(auth_str) = std::str::from_utf8(auth_header) else {
        // Invalid UTF-8 -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Invalid authentication credentials"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    };

    // Step 3: Check for "Bearer " prefix (case-insensitive for the scheme)
    let Some(bearer_value) = auth_str
        .strip_prefix("Bearer ")
        .or_else(|| auth_str.strip_prefix("bearer "))
    else {
        // Wrong scheme -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Invalid authentication credentials"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    };

    let bearer_value = bearer_value.trim();
    if bearer_value.is_empty() {
        // Empty token -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Invalid authentication credentials"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    }

    // Step 4: Validate the bearer value using constant-time comparison
    if !bearer_value.secure_eq(DEMO_BEARER_VALUE) {
        // Invalid token -> 403 Forbidden
        let body = serde_json::json!({
            "detail": "Invalid token"
        });
        return std::future::ready(
            Response::with_status(StatusCode::FORBIDDEN)
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    }

    // Token is valid - return protected data
    let user_info = UserInfo {
        username: "demo_user".to_string(),
        message: "You have accessed a protected resource!".to_string(),
    };

    std::future::ready(
        Response::ok()
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(json_bytes(&user_info))),
    )
}

pub fn created() -> Response

Create a 201 Created response.

pub fn no_content() -> Response

Create a 204 No Content response.

pub fn internal_error() -> Response

Create a 500 Internal Server Error response.

pub fn partial_content() -> Response

Create a 206 Partial Content response.

Used for range requests. You should also set the Content-Range header.

Example

use fastapi_core::{Response, ResponseBody};

let response = Response::partial_content()
    .header("Content-Range", b"bytes 0-499/1000".to_vec())
    .header("Accept-Ranges", b"bytes".to_vec())
    .body(ResponseBody::Bytes(partial_data));

pub fn range_not_satisfiable() -> Response

Create a 416 Range Not Satisfiable response.

Used when a Range header specifies a range that cannot be satisfied. You should also set the Content-Range header with the resource size.

Example

use fastapi_core::Response;

let response = Response::range_not_satisfiable()
    .header("Content-Range", b"bytes */1000".to_vec());

pub fn not_modified() -> Response

Create a 304 Not Modified response.

Used for conditional requests where the resource has not changed. The response body is empty per HTTP spec.

pub fn precondition_failed() -> Response

Create a 412 Precondition Failed response.

Used when a conditional request’s precondition (e.g., If-Match) fails.

pub fn with_etag(self, etag: impl Into<String>) -> Response

Set the ETag header on this response.

Example

let response = Response::ok()
    .with_etag("\"abc123\"")
    .body(b"content".to_vec());

pub fn with_weak_etag(self, etag: impl Into<String>) -> Response

Set a weak ETag header on this response.

Automatically prefixes with W/ if not already present.

pub fn header( self, name: impl Into<String>, value: impl Into<Vec<u8>>, ) -> Response

Add a header.

Security

Header names are validated to contain only valid token characters. Header values are sanitized to prevent CRLF injection attacks. Invalid characters in names will cause the header to be silently dropped.

Examples found in repository

examples/crud_api.rs (line 127)

fn json_error(status: StatusCode, detail: &str) -> Response {
    let body = serde_json::json!({ "detail": detail });
    Response::with_status(status)
        .header("content-type", b"application/json".to_vec())
        .body(ResponseBody::Bytes(body.to_string().into_bytes()))
}

fn json_response(status: StatusCode, value: &impl Serialize) -> Response {
    match serde_json::to_string(value) {
        Ok(text) => Response::with_status(status)
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(text.into_bytes())),
        Err(err) => json_error(
            StatusCode::INTERNAL_SERVER_ERROR,
            &format!("JSON serialization failed: {err}"),
        ),
    }
}

examples/auth_example.rs (line 92)

fn public_handler(_ctx: &RequestContext, _req: &mut Request) -> std::future::Ready<Response> {
    let body = serde_json::json!({
        "message": "This is a public endpoint - no authentication required!"
    });
    std::future::ready(
        Response::ok()
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(body.to_string().into_bytes())),
    )
}

/// Handler for the login endpoint.
///
/// In a real application:
/// 1. Validate username/password against a database
/// 2. Generate a unique token (JWT or random)
/// 3. Store the token with associated user info
/// 4. Return the token to the client
///
/// For this demo, we accept any credentials and return a fixed token.
fn login_handler(_ctx: &RequestContext, req: &mut Request) -> std::future::Ready<Response> {
    // For this demo, we only check Content-Type and return a fixed token.
    // Real applications should parse the body and validate credentials.

    // Check Content-Type
    let is_json = req
        .headers()
        .get("content-type")
        .is_some_and(|ct| ct.starts_with(b"application/json"));

    if !is_json {
        let error = serde_json::json!({
            "detail": "Content-Type must be application/json"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNSUPPORTED_MEDIA_TYPE)
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(error.to_string().into_bytes())),
        );
    }

    // For demo purposes, we don't validate credentials - just return the token
    // In production:
    // 1. Parse the request body as LoginRequest
    // 2. Verify username/password against your database
    // 3. Generate a unique, cryptographically secure token
    // 4. Store token -> user_id mapping (with expiration)

    let response = LoginResponse {
        access_token: DEMO_BEARER_VALUE.to_string(),
        token_type: "bearer",
    };

    std::future::ready(
        Response::ok()
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(json_bytes(&response))),
    )
}

/// Handler for protected endpoint - requires valid bearer token.
///
/// This handler manually extracts and validates the bearer token:
/// 1. Gets the Authorization header
/// 2. Verifies it uses the Bearer scheme
/// 3. Validates the token against our secret using constant-time comparison
///
/// Returns appropriate error responses for each failure mode.
fn protected_handler(_ctx: &RequestContext, req: &mut Request) -> std::future::Ready<Response> {
    // Step 1: Get the Authorization header
    let Some(auth_header) = req.headers().get("authorization") else {
        // Missing header -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Not authenticated"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    };

    // Step 2: Parse the Authorization header
    let Ok(auth_str) = std::str::from_utf8(auth_header) else {
        // Invalid UTF-8 -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Invalid authentication credentials"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    };

    // Step 3: Check for "Bearer " prefix (case-insensitive for the scheme)
    let Some(bearer_value) = auth_str
        .strip_prefix("Bearer ")
        .or_else(|| auth_str.strip_prefix("bearer "))
    else {
        // Wrong scheme -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Invalid authentication credentials"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    };

    let bearer_value = bearer_value.trim();
    if bearer_value.is_empty() {
        // Empty token -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Invalid authentication credentials"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    }

    // Step 4: Validate the bearer value using constant-time comparison
    if !bearer_value.secure_eq(DEMO_BEARER_VALUE) {
        // Invalid token -> 403 Forbidden
        let body = serde_json::json!({
            "detail": "Invalid token"
        });
        return std::future::ready(
            Response::with_status(StatusCode::FORBIDDEN)
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    }

    // Token is valid - return protected data
    let user_info = UserInfo {
        username: "demo_user".to_string(),
        message: "You have accessed a protected resource!".to_string(),
    };

    std::future::ready(
        Response::ok()
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(json_bytes(&user_info))),
    )
}

pub fn remove_header(self, name: &str) -> Response

Remove all headers matching name (case-insensitive).

This is useful for middleware that needs to suppress or replace headers produced by handlers or other middleware.

pub fn body(self, body: ResponseBody) -> Response

Set the body.

Examples found in repository

examples/getting_started.rs (line 14)

fn hello(_ctx: &RequestContext, _req: &mut Request) -> std::future::Ready<Response> {
    std::future::ready(Response::ok().body(ResponseBody::Bytes(b"Hello, World!".to_vec())))
}

/// Handler for GET /health
fn health(_ctx: &RequestContext, _req: &mut Request) -> std::future::Ready<Response> {
    std::future::ready(
        Response::ok().body(ResponseBody::Bytes(b"{\"status\":\"healthy\"}".to_vec())),
    )
}

examples/hello_world.rs (line 48)

fn hello_handler(_ctx: &RequestContext, _req: &mut Request) -> std::future::Ready<Response> {
    // Create a 200 OK response with a plain text body
    std::future::ready(Response::ok().body(ResponseBody::Bytes(b"Hello, World!".to_vec())))
}

examples/crud_api.rs (line 128)

fn json_error(status: StatusCode, detail: &str) -> Response {
    let body = serde_json::json!({ "detail": detail });
    Response::with_status(status)
        .header("content-type", b"application/json".to_vec())
        .body(ResponseBody::Bytes(body.to_string().into_bytes()))
}

fn json_response(status: StatusCode, value: &impl Serialize) -> Response {
    match serde_json::to_string(value) {
        Ok(text) => Response::with_status(status)
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(text.into_bytes())),
        Err(err) => json_error(
            StatusCode::INTERNAL_SERVER_ERROR,
            &format!("JSON serialization failed: {err}"),
        ),
    }
}

examples/auth_example.rs (line 93)

fn public_handler(_ctx: &RequestContext, _req: &mut Request) -> std::future::Ready<Response> {
    let body = serde_json::json!({
        "message": "This is a public endpoint - no authentication required!"
    });
    std::future::ready(
        Response::ok()
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(body.to_string().into_bytes())),
    )
}

/// Handler for the login endpoint.
///
/// In a real application:
/// 1. Validate username/password against a database
/// 2. Generate a unique token (JWT or random)
/// 3. Store the token with associated user info
/// 4. Return the token to the client
///
/// For this demo, we accept any credentials and return a fixed token.
fn login_handler(_ctx: &RequestContext, req: &mut Request) -> std::future::Ready<Response> {
    // For this demo, we only check Content-Type and return a fixed token.
    // Real applications should parse the body and validate credentials.

    // Check Content-Type
    let is_json = req
        .headers()
        .get("content-type")
        .is_some_and(|ct| ct.starts_with(b"application/json"));

    if !is_json {
        let error = serde_json::json!({
            "detail": "Content-Type must be application/json"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNSUPPORTED_MEDIA_TYPE)
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(error.to_string().into_bytes())),
        );
    }

    // For demo purposes, we don't validate credentials - just return the token
    // In production:
    // 1. Parse the request body as LoginRequest
    // 2. Verify username/password against your database
    // 3. Generate a unique, cryptographically secure token
    // 4. Store token -> user_id mapping (with expiration)

    let response = LoginResponse {
        access_token: DEMO_BEARER_VALUE.to_string(),
        token_type: "bearer",
    };

    std::future::ready(
        Response::ok()
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(json_bytes(&response))),
    )
}

/// Handler for protected endpoint - requires valid bearer token.
///
/// This handler manually extracts and validates the bearer token:
/// 1. Gets the Authorization header
/// 2. Verifies it uses the Bearer scheme
/// 3. Validates the token against our secret using constant-time comparison
///
/// Returns appropriate error responses for each failure mode.
fn protected_handler(_ctx: &RequestContext, req: &mut Request) -> std::future::Ready<Response> {
    // Step 1: Get the Authorization header
    let Some(auth_header) = req.headers().get("authorization") else {
        // Missing header -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Not authenticated"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    };

    // Step 2: Parse the Authorization header
    let Ok(auth_str) = std::str::from_utf8(auth_header) else {
        // Invalid UTF-8 -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Invalid authentication credentials"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    };

    // Step 3: Check for "Bearer " prefix (case-insensitive for the scheme)
    let Some(bearer_value) = auth_str
        .strip_prefix("Bearer ")
        .or_else(|| auth_str.strip_prefix("bearer "))
    else {
        // Wrong scheme -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Invalid authentication credentials"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    };

    let bearer_value = bearer_value.trim();
    if bearer_value.is_empty() {
        // Empty token -> 401 Unauthorized
        let body = serde_json::json!({
            "detail": "Invalid authentication credentials"
        });
        return std::future::ready(
            Response::with_status(StatusCode::UNAUTHORIZED)
                .header("www-authenticate", b"Bearer".to_vec())
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    }

    // Step 4: Validate the bearer value using constant-time comparison
    if !bearer_value.secure_eq(DEMO_BEARER_VALUE) {
        // Invalid token -> 403 Forbidden
        let body = serde_json::json!({
            "detail": "Invalid token"
        });
        return std::future::ready(
            Response::with_status(StatusCode::FORBIDDEN)
                .header("content-type", b"application/json".to_vec())
                .body(ResponseBody::Bytes(body.to_string().into_bytes())),
        );
    }

    // Token is valid - return protected data
    let user_info = UserInfo {
        username: "demo_user".to_string(),
        message: "You have accessed a protected resource!".to_string(),
    };

    std::future::ready(
        Response::ok()
            .header("content-type", b"application/json".to_vec())
            .body(ResponseBody::Bytes(json_bytes(&user_info))),
    )
}

pub fn set_cookie(self, cookie: SetCookie) -> Response

Set a cookie on the response.

Adds a Set-Cookie header with the serialized cookie value. Multiple cookies can be set by calling this method multiple times.

Example

use fastapi_core::{Response, SameSite, SetCookie};

let response = Response::ok()
    .set_cookie(SetCookie::new("session", "abc123").http_only(true))
    .set_cookie(SetCookie::new("prefs", "dark").same_site(SameSite::Lax));

pub fn delete_cookie(self, name: &str) -> Response

Delete a cookie by setting it to expire immediately.

This sets the cookie with an empty value and Max-Age=0, which tells the browser to remove the cookie.

Example

use fastapi_core::Response;

let response = Response::ok()
    .delete_cookie("session");

pub fn json<T>(value: &T) -> Result<Response, Error>

where T: Serialize,

Create a JSON response.

Errors

Returns an error if serialization fails.

pub fn status(&self) -> StatusCode

Get the status code.

pub fn headers(&self) -> &[(String, Vec<u8>)]

Get the headers.

pub fn body_ref(&self) -> &ResponseBody

Get the body.

pub fn into_parts(self) -> (StatusCode, Vec<(String, Vec<u8>)>, ResponseBody)

Decompose this response into its parts.

pub fn rebuild_with_headers(self, headers: Vec<(String, Vec<u8>)>) -> Response

Rebuilds this response with the given headers, preserving status and body.

This is useful for middleware that needs to modify the response but preserve original headers.

Example

let (status, headers, body) = response.into_parts();
// ... modify headers ...
let new_response = Response::with_status(status)
    .body(body)
    .rebuild_with_headers(headers);

Trait Implementations

impl Debug for Response

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

Formats the value using the given formatter.

impl IntoResponse for Response

fn into_response(self) -> Response

Convert into a response.

impl StreamingResponseExt for Response

fn stream_file<P>( path: P, cx: Cx, content_type: &[u8], ) -> Result<Response, Error>

where P: AsRef<Path>,

Create a streaming response from a file.

fn stream_file_with_config<P>( path: P, cx: Cx, content_type: &[u8], config: StreamConfig, ) -> Result<Response, Error>

where P: AsRef<Path>,

Create a streaming response from a file with custom config.

fn stream_file_range<P>( path: P, range: ByteRange, total_size: u64, cx: Cx, content_type: &[u8], ) -> Result<Response, Error>

where P: AsRef<Path>,

Create a 206 Partial Content response for a byte range of a file.

fn stream_file_range_with_config<P>( path: P, range: ByteRange, total_size: u64, cx: Cx, content_type: &[u8], config: StreamConfig, ) -> Result<Response, Error>

where P: AsRef<Path>,

Create a 206 Partial Content response with custom streaming config.