Module xitca_web::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 produce error.
async fn handler() -> Error {
    Error::from_service(xitca_web::error::BadRequest)
}

// 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 type. the error is treated
    // as it's onw type on the other branch of the Result type.  

    // 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 Ok(Html(html).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§

  • BadRequest
    error type that produce minimal “400 BadRequest” response.
  • 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.
  • Internal
    error type that produce minimal “500 InternalServerError” response.
  • MatchError
    error type indicate Router can not find a matching route.
  • MethodNotAllowed
    Error type of Method not allow for route.
  • StdError
    new type for Box<dyn std::error::Error + Send + Sync>. produce minimal “500 InternalServerError” response and forward formatting, error handling to inner type.

Enums§

Type Aliases§

  • BodyError
    Default Request/Response body error.