Struct rocket::Catcher

pub struct Catcher {
    pub name: Option<Cow<'static, str>>,
    pub code: Option<u16>,
    pub handler: Box<dyn Handler>,
    /* private fields */
}

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

If a route fails by returning a failure Outcome, Rocket routes the erroring request to the highest precedence catcher among all the catchers that match. See Catcher::matches() for details on matching. Precedence is determined by the catcher’s base, which is provided as the first argument to Rocket::register(). Catchers with more non-empty segments have a higher precedence.

Rocket provides built-in defaults, but default catchers can also be registered. A default catcher is a catcher with no explicit status code: None.

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:

• fn() -> R
• fn(&Request) -> R
• fn(Status, &Request) -> R

See the catch documentation for full details.

Fields

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

The name of this catcher, if one was given.

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

impl Catcher

pub fn new<S, H>(code: S, handler: H) -> Catcherwhere S: Into<Option<u16>>, H: Handler,

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).

pub fn base(&self) -> Path<'_>

Returns the mount point (base) of the catcher, which defaults to /.

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(), "/");

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

pub fn rebase(self, base: Origin<'_>) -> Self

Prefix base to the current base in self.

If the the current base is /, then the base is replaced by base. Otherwise, base is prefixed to the existing base.

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(), "/");

// Since the base is `/`, rebasing replaces the base.
let rebased = catcher.rebase(uri!("/boo"));
assert_eq!(rebased.base(), "/boo");

// Now every rebase prefixes.
let rebased = rebased.rebase(uri!("/base"));
assert_eq!(rebased.base(), "/base/boo");

// Note that trailing slashes have no effect and are thus removed:
let catcher = Catcher::new(404, handle_404);
let rebased = catcher.rebase(uri!("/boo/"));
assert_eq!(rebased.base(), "/boo");

pub fn map_base<'a, F>(self, mapper: F) -> Result<Self, Error<'static>>where F: FnOnce(Origin<'a>) -> String,

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

Note: Prefer to use Catcher::rebase() whenever possible!

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(), "/");

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

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

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

impl Catcher

pub fn collides_with(&self, other: &Self) -> bool

Returns true if self collides with other.

A collision between two catchers occurs when there exists a request and ensuing error that could match both catchers. That is, a routing ambiguity would ensue if both catchers were made available to the router.

Specifically, a collision occurs when two catchers:

• Have the same base.
• Have the same status code or are both default.

Collisions are symmetric: for any catchers a and b, a.collides_with(b) => b.collides_with(a).

Example

use rocket::Catcher;

// Two catchers with the same status code and base collide.
let a = Catcher::new(404, handler).map_base(|_| format!("/foo")).unwrap();
let b = Catcher::new(404, handler).map_base(|_| format!("/foo")).unwrap();
assert!(a.collides_with(&b));

// Two catchers with a different base _do not_ collide.
let a = Catcher::new(404, handler);
let b = a.clone().map_base(|_| format!("/bar")).unwrap();
assert_eq!(a.base(), "/");
assert_eq!(b.base(), "/bar");
assert!(!a.collides_with(&b));

// Two catchers with a different codes _do not_ collide.
let a = Catcher::new(404, handler);
let b = Catcher::new(500, handler);
assert_eq!(a.base(), "/");
assert_eq!(b.base(), "/");
assert!(!a.collides_with(&b));

// A catcher _with_ a status code and one _without_ do not collide.
let a = Catcher::new(404, handler);
let b = Catcher::new(None, handler);
assert!(!a.collides_with(&b));

impl Catcher

pub fn matches(&self, status: Status, request: &Request<'_>) -> bool

Returns true if self matches errors with status that occured during request.

A match between a Catcher and a (Status, &Request) pair occurs when:

• The catcher has the same code as status or is default.
• The catcher’s base is a prefix of the request’s normalized URI.

For an error arising from a request to be routed to a particular catcher, that catcher must both match and have higher precedence than any other catcher that matches. In other words, a match is a necessary but insufficient condition to determine if a catcher will handle a particular error.

The precedence of a catcher is determined by:

1. The number of complete segments in the catcher’s base.
2. Whether the catcher is default or not.

Non-default routes, and routes with more complete segments in their base, have higher precedence.

Example

use rocket::Catcher;
use rocket::http::Status;

// This catcher handles 404 errors with a base of `/`.
let a = Catcher::new(404, handler);

// This catcher handles 404 errors with a base of `/bar`.
let b = a.clone().map_base(|_| format!("/bar")).unwrap();

// Let's say `request` is `GET /` that 404s. The error matches only `a`:
let request = client.get("/");
assert!(a.matches(Status::NotFound, &request));
assert!(!b.matches(Status::NotFound, &request));

// Now `request` is a 404 `GET /bar`. The error matches `a` and `b`:
let request = client.get("/bar");
assert!(a.matches(Status::NotFound, &request));
assert!(b.matches(Status::NotFound, &request));

// Note that because `b`'s base' has more complete segments that `a's,
// Rocket would route the error to `b`, not `a`, even though both match.
let a_count = a.base().segments().filter(|s| !s.is_empty()).count();
let b_count = b.base().segments().filter(|s| !s.is_empty()).count();
assert!(b_count > a_count);

Trait Implementations

impl Clone for Catcher

fn clone(&self) -> Catcher

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Catcher

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

Formats the value using the given formatter.

impl Default for Catcher

fn default() -> Self

Returns the “default value” for a type.

impl Display for Catcher

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

Formats the value using the given formatter.