Struct ExceptionHandlers

Source

pub struct ExceptionHandlers { /* private fields */ }

Expand description

Registry for custom exception handlers.

This allows applications to register handlers for specific error types, converting errors into HTTP responses in a customizable way.

§Default Handlers

The registry comes with default handlers for common error types:

HttpError → JSON response with status/detail
ValidationErrors → 422 with error list
CancelledError → 499 Client Closed Request

§Panic Handler

The registry also supports a panic handler that is invoked when a panic is caught during request handling. This is typically used by the HTTP server layer via catch_unwind. The default panic handler returns a 500 Internal Server Error.

§Example

use fastapi_core::app::ExceptionHandlers;
use fastapi_core::{RequestContext, Response, HttpError};

#[derive(Debug)]
struct MyCustomError(String);

impl std::fmt::Display for MyCustomError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Custom error: {}", self.0)
    }
}

impl std::error::Error for MyCustomError {}

let handlers = ExceptionHandlers::new()
    .handler(|_ctx, err: MyCustomError| {
        Response::with_status(StatusCode::BAD_REQUEST)
            .body_json(&serde_json::json!({"error": err.0}))
    });

Implementations§

Source §

impl ExceptionHandlers

Source

pub fn new() -> Self

Creates a new empty exception handler registry.

Source

pub fn with_defaults() -> Self

Creates a registry with default handlers for common error types.

Source

pub fn register<E>( &mut self, handler: impl Fn(&RequestContext, E) -> Response + Send + Sync + 'static, )
where E: Error + Send + Sync + 'static,

Registers a handler for a specific error type.

The handler receives the error value directly (not boxed) for type safety. If a handler for the same type already exists, it is replaced.

Source

pub fn handler<E>( self, handler: impl Fn(&RequestContext, E) -> Response + Send + Sync + 'static, ) -> Self
where E: Error + Send + Sync + 'static,

Registers a handler for a specific error type (builder pattern).

Source

pub fn handle<E>(&self, ctx: &RequestContext, err: E) -> Option<Response>
where E: Error + Send + Sync + 'static,

Handles an error by finding and invoking the appropriate handler.

Returns Some(Response) if a handler was found for the error type, or None if no handler is registered.

Source

pub fn handle_or_default<E>(&self, ctx: &RequestContext, err: E) -> Response
where E: Error + Send + Sync + 'static,

Handles an error, falling back to a default 500 response if no handler is found.

Source

pub fn has_handler<E: 'static>(&self) -> bool

Returns true if a handler is registered for the given error type.

Source

pub fn len(&self) -> usize

Returns the number of registered handlers.

Source

pub fn is_empty(&self) -> bool

Returns true if no handlers are registered.

Source

pub fn merge(&mut self, other: ExceptionHandlers)

Merges another handler registry into this one.

Handlers from other will override handlers in self for the same error types.

Source

pub fn panic_handler<F>(self, handler: F) -> Self
where F: Fn(Option<&RequestContext>, &str) -> Response + Send + Sync + 'static,

Sets a custom panic handler.

The panic handler is called by the HTTP server layer when a panic is caught during request handling via catch_unwind. The handler receives the RequestContext (if available) and a panic message string.

§Example

let handlers = ExceptionHandlers::with_defaults()
    .panic_handler(|ctx, panic_msg| {
        // Log the panic
        eprintln!("Request panicked: {}", panic_msg);

        // Return a custom error response
        Response::with_status(StatusCode::INTERNAL_SERVER_ERROR)
            .body_json(&serde_json::json!({
                "error": "internal_server_error",
                "message": "An unexpected error occurred"
            }))
    });