xitca_web

Module error

Source
Expand description

web error types.

In xitca-web error is treated as high level type and handled lazily.

  • high level: An error type is represented firstly and mostly as a Rust type with useful trait bounds.It doesn’t necessarily mapped and/or converted into http response immediately. User is encouraged to pass the error value around and convert it to http response on condition they prefer.

  • lazy: Since an error is passed as value mostly the error is handled lazily when the value is needed. Including but not limiting to: formatting, logging, generating http response.

§Example

// a handler function always produce error.
async fn handler() -> Error {
    Error::from(StatusCode::BAD_REQUEST)
}

// construct application with handler function and middleware.
App::new()
    .at("/", handler_service(handler))
    .enclosed_fn(error_handler);

// a handler middleware observe route services output.
async fn error_handler<S>(service: &S, mut ctx: WebContext<'_>) -> Result<WebResponse, Error>
where
    S: for<'r> Service<WebContext<'r>, Response = WebResponse, Error = Error>
{
    // unlike WebResponse which is already a valid http response. the error is treated as it's
    // onw type on the other branch of the Result enum.  

    // since the handler function at the start of example always produce error. our middleware
    // will always observe the Error type value so let's unwrap it.
    let err = service.call(ctx.reborrow()).await.err().unwrap();
     
    // now we have the error value we can start to interact with it and add our logic of
    // handling it.

    // we can print the error.
    println!("{err}");

    // we can log the error.
    tracing::error!("{err}");

    // we can render the error to html and convert it to http response.
    let html = format!("<!DOCTYPE html>\
        <html>\
        <body>\
        <h1>{err}</h1>\
        </body>\
        </html>");
    return (Html(html), StatusCode::BAD_REQUEST).respond(ctx).await;

    // or by default the error value is returned in Result::Err and passed to parent services
    // of App or other middlewares where eventually it would be converted to WebResponse.
     
    // "eventually" can either mean a downstream user provided error handler middleware/service
    // or the implicit catch all error middleware xitca-web offers. In the latter case a default
    // WebResponse is generated with minimal information describing the reason of error.

    Err(err)
}

Structs§

BodyOverFlow
Error
type erased error object. can be used for dynamic access to error’s debug/display info. it also support upcasting and downcasting.
ErrorStatus
error type derive from http status code. produce minimal “StatusCode Reason” response and stack backtrace of the location status code error occurs.
ExtensionNotFound
error type for typed instance can’t be found from Extensions
HeaderNotFound
error type when named header is not found from request.
InvalidHeaderValue
error type when named header is not associated with valid header value.
MatchError
error type indicate Router can not find a matching route.
MethodNotAllowed
Error type of Method not allow for route.
Request
container for dynamic type provided by Error’s default Service impl
ThreadJoinError
error happens when joining a thread. typically caused by code panic inside thread. CatchUnwind middleware is able to produce this error type.

Enums§

RouterError
Error type of Router service.

Type Aliases§

BodyError
Default Request/Response body error.