Expand description
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 Failure
s, users can catch Forward
s by requesting
a type of Option<S>
. If an Outcome
is a Forward
, the Option
will be
None
.
Macros
Enums
- An enum representing success (
Success
), failure (Failure
), or forwarding (Forward
).
Traits
- Conversion trait from some type into an Outcome type.