Struct rocket::catcher::Catcher[][src]

pub struct Catcher {
    pub name: Option<Cow<'static, str>>,
    pub base: Origin<'static>,
    pub code: Option<u16>,
    pub handler: Box<dyn Handler>,
}
Expand description

An error catching route.

Catchers are routes that run when errors are produced by the application. They consist of a Handler and an optional status code to match against arising errors. Errors arise from the the following sources:

  • A failing guard.
  • A failing responder.
  • Routing failure.

Each failure is paired with a status code. Guards and responders indicate the status code themselves via their Err return value while a routing failure is always a 404. Rocket invokes the error handler for the catcher with the error’s status code.

Error Handler Restrictions

Because error handlers are a last resort, they should not fail to produce a response. If an error handler does fail, Rocket invokes its default 500 error catcher. Error handlers cannot forward.

Routing

An error arising from a particular request matches a catcher iff:

  • It is a default catcher or has a status code matching the error code.
  • Its base is a prefix of the normalized/decoded request URI path.

A default catcher is a catcher with no explicit status code: None. The catcher’s base is provided as the first argument to Rocket::register().

Collisions

Two catchers are said to collide if there exists an error that matches both catchers. Colliding catchers present a routing ambiguity and are thus disallowed by Rocket. Because catchers can be constructed dynamically, collision checking is done at ignite time, after it becomes statically impossible to register any more catchers on an instance of Rocket.

Built-In Default

Rocket’s provides a built-in default catcher that can handle all errors. It produces HTML or JSON, depending on the value of the Accept header. As such, catchers only need to be registered if an error needs to be handled in a custom fashion. The built-in default never conflicts with any user-registered catchers.

Code Generation

Catchers should rarely be constructed or used directly. Instead, they are typically generated via the catch attribute, as follows:

#[macro_use] extern crate rocket;

use rocket::Request;
use rocket::http::Status;

#[catch(500)]
fn internal_error() -> &'static str {
    "Whoops! Looks like we messed up."
}

#[catch(404)]
fn not_found(req: &Request) -> String {
    format!("I couldn't find '{}'. Try something else?", req.uri())
}

#[catch(default)]
fn default(status: Status, req: &Request) -> String {
    format!("{} ({})", status, req.uri())
}

#[launch]
fn rocket() -> _ {
    rocket::build().register("/", catchers![internal_error, not_found, default])
}

A function decorated with #[catch] may take zero, one, or two arguments. It’s type signature must be one of the following, where R:Responder:

See the catch documentation for full details.

Fields

name: Option<Cow<'static, str>>

The name of this catcher, if one was given.

base: Origin<'static>

The mount point.

code: Option<u16>

The HTTP status to match against if this route is not default.

handler: Box<dyn Handler>

The catcher’s associated error handler.

Implementations

Creates a catcher for the given status, or a default catcher if status is None, using the given error handler. This should only be used when routing manually.

Examples

use rocket::request::Request;
use rocket::catcher::{Catcher, BoxFuture};
use rocket::response::Responder;
use rocket::http::Status;

fn handle_404<'r>(status: Status, req: &'r Request<'_>) -> BoxFuture<'r> {
   let res = (status, format!("404: {}", req.uri()));
   Box::pin(async move { res.respond_to(req) })
}

fn handle_500<'r>(_: Status, req: &'r Request<'_>) -> BoxFuture<'r> {
    Box::pin(async move{ "Whoops, we messed up!".respond_to(req) })
}

fn handle_default<'r>(status: Status, req: &'r Request<'_>) -> BoxFuture<'r> {
   let res = (status, format!("{}: {}", status, req.uri()));
   Box::pin(async move { res.respond_to(req) })
}

let not_found_catcher = Catcher::new(404, handle_404);
let internal_server_error_catcher = Catcher::new(500, handle_500);
let default_error_catcher = Catcher::new(None, handle_default);

Panics

Panics if code is not in the HTTP status code error range [400, 600).

Maps the base of this catcher using mapper, returning a new Catcher with the returned base.

mapper is called with the current base. The returned String is used as the new base if it is a valid URI. If the returned base URI contains a query, it is ignored. Returns an error if the base produced by mapper is not a valid origin URI.

Example

use rocket::request::Request;
use rocket::catcher::{Catcher, BoxFuture};
use rocket::response::Responder;
use rocket::http::Status;

fn handle_404<'r>(status: Status, req: &'r Request<'_>) -> BoxFuture<'r> {
   let res = (status, format!("404: {}", req.uri()));
   Box::pin(async move { res.respond_to(req) })
}

let catcher = Catcher::new(404, handle_404);
assert_eq!(catcher.base.path(), "/");

let catcher = catcher.map_base(|_| format!("/bar")).unwrap();
assert_eq!(catcher.base.path(), "/bar");

let catcher = catcher.map_base(|base| format!("/foo{}", base)).unwrap();
assert_eq!(catcher.base.path(), "/foo/bar");

let catcher = catcher.map_base(|base| format!("/foo ? {}", base));
assert!(catcher.is_err());

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Formats the value using the given formatter. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Converts self into T using Into<T>. Read more

Converts self into a target type. Read more

Causes self to use its Binary implementation when Debug-formatted.

Causes self to use its Display implementation when Debug-formatted. Read more

Causes self to use its LowerExp implementation when Debug-formatted. Read more

Causes self to use its LowerHex implementation when Debug-formatted. Read more

Causes self to use its Octal implementation when Debug-formatted.

Causes self to use its Pointer implementation when Debug-formatted. Read more

Causes self to use its UpperExp implementation when Debug-formatted. Read more

Causes self to use its UpperHex implementation when Debug-formatted. Read more

Performs the conversion.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Performs the conversion.

Converts self into a collection.

Pipes by value. This is generally the method you want to use. Read more

Borrows self and passes that borrow into the pipe function. Read more

Mutably borrows self and passes that borrow into the pipe function. Read more

Borrows self, then passes self.borrow() into the pipe function. Read more

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more

Borrows self, then passes self.as_ref() into the pipe function.

Mutably borrows self, then passes self.as_mut() into the pipe function. Read more

Borrows self, then passes self.deref() into the pipe function.

Mutably borrows self, then passes self.deref_mut() into the pipe function. Read more

Pipes a value into a function that cannot ordinarily be called in suffix position. Read more

Pipes a trait borrow into a function that cannot normally be called in suffix position. Read more

Pipes a trait mutable borrow into a function that cannot normally be called in suffix position. Read more

Pipes a trait borrow into a function that cannot normally be called in suffix position. Read more

Pipes a trait mutable borrow into a function that cannot normally be called in suffix position. Read more

Pipes a dereference into a function that cannot normally be called in suffix position. Read more

Pipes a mutable dereference into a function that cannot normally be called in suffix position. Read more

Pipes a reference into a function that cannot ordinarily be called in suffix position. Read more

Pipes a mutable reference into a function that cannot ordinarily be called in suffix position. Read more

Should always be Self

Immutable access to a value. Read more

Mutable access to a value. Read more

Immutable access to the Borrow<B> of a value. Read more

Mutable access to the BorrowMut<B> of a value. Read more

Immutable access to the AsRef<R> view of a value. Read more

Mutable access to the AsMut<R> view of a value. Read more

Immutable access to the Deref::Target of a value. Read more

Mutable access to the Deref::Target of a value. Read more

Calls .tap() only in debug builds, and is erased in release builds.

Calls .tap_mut() only in debug builds, and is erased in release builds. Read more

Calls .tap_borrow() only in debug builds, and is erased in release builds. Read more

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds. Read more

Calls .tap_ref() only in debug builds, and is erased in release builds. Read more

Calls .tap_ref_mut() only in debug builds, and is erased in release builds. Read more

Calls .tap_deref() only in debug builds, and is erased in release builds. Read more

Calls .tap_deref_mut() only in debug builds, and is erased in release builds. Read more

Provides immutable access for inspection. Read more

Calls tap in debug builds, and does nothing in release builds.

Provides mutable access for modification. Read more

Calls tap_mut in debug builds, and does nothing in release builds.

Provides immutable access to the reference for inspection.

Calls tap_ref in debug builds, and does nothing in release builds.

Provides mutable access to the reference for modification.

Calls tap_ref_mut in debug builds, and does nothing in release builds.

Provides immutable access to the borrow for inspection. Read more

Calls tap_borrow in debug builds, and does nothing in release builds.

Provides mutable access to the borrow for modification.

Calls tap_borrow_mut in debug builds, and does nothing in release builds. Read more

Immutably dereferences self for inspection.

Calls tap_deref in debug builds, and does nothing in release builds.

Mutably dereferences self for modification.

Calls tap_deref_mut in debug builds, and does nothing in release builds. Read more

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

Attempts to convert self into T using TryInto<T>. Read more

Attempts to convert self into a target type. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.