Module rocket::outcome

Success, error, and forward handling.

The Outcome<S, E, F> type is similar to the standard library’s Result<S, E> type. It is an enum with three variants, each containing a value: Success(S), which represents a successful outcome, Error(E), which represents an erroring outcome, and Forward(F), which represents neither a success or error, but instead, indicates that processing could not be handled and should instead be forwarded to whatever can handle the processing next.

The Outcome type is the return type of many of the core Rocket traits, including FromRequest, FromData Responder. It is also the return type of request handlers via the Response type.

Success

A successful Outcome<S, E, F>, Success(S), is returned from functions that complete successfully. The meaning of a Success outcome depends on the context. For instance, the Outcome of the from_data method of the FromData trait will be matched against the type expected by the user. For example, consider the following handler:

#[post("/", data = "<my_val>")]
fn hello(my_val: S) { /* ... */  }

The FromData implementation for the type S returns an Outcome with a Success(S). If from_data returns a Success, the Success value will be unwrapped and the value will be used as the value of my_val.

Error

An error Outcome<S, E, F>, Error(E), is returned when a function fails with some error and no processing can or should continue as a result. The meaning of an error depends on the context.

In Rocket, an Error generally means that a request is taken out of normal processing. The request is then given to the catcher corresponding to some status code. Users can catch errors by requesting a type of Result<S, E> or Option<S> in request handlers. For example, if a user’s handler looks like:

#[post("/", data = "<my_val>")]
fn hello(my_val: Result<S, E>) { /* ... */ }

The FromData implementation for the type S returns an Outcome with a Success(S) and Error(E). If from_data returns an Error, the Error value will be unwrapped and the value will be used as the Err value of my_val while a Success will be unwrapped and used the Ok value.

Forward

A forward Outcome<S, E, F>, Forward(F), is returned when a function wants to indicate that the requested processing should be forwarded to the next available processor. Again, the exact meaning depends on the context.

In Rocket, a Forward generally means that a request is forwarded to the next available request handler. For example, consider the following request handler:

#[post("/", data = "<my_val>")]
fn hello(my_val: S) { /* ... */ }

The FromData implementation for the type S returns an Outcome with a Success(S), Error(E), and Forward(F). If the Outcome is a Forward, the hello handler isn’t called. Instead, the incoming request is forwarded, or passed on to, the next matching route, if any. Ultimately, if there are no non-forwarding routes, forwarded requests are handled by the 404 catcher. Similar to Errors, users can catch Forwards by requesting a type of Option<S>. If an Outcome is a Forward, the Option will be None.

Macros

• try_outcome
  Unwraps a Success or propagates a Forward or Error by returning early.

Enums

• Outcome
  An enum representing success (Success), error (Error), or forwarding (Forward).

Traits

• IntoOutcome
  Conversion trait from some type into an Outcome type.