Module rocket::outcome

Success, failure, 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, Failure(E), which represents a failing outcome, and Forward(F), which represents neither a success or failure, 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.

Failure

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

In Rocket, a Failure 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 failures 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 Failure(E). If from_data returns a Failure, the Failure 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), Failure(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 Failures, users can catch Forwards by requesting a type of Option<S>. If an Outcome is a Forward, the Option will be None.

Enums

Outcome

An enum representing success (Success), failure (Failure), or forwarding (Forward).

Traits

IntoOutcome

Conversion trait from some type into an Outcome type.