Trait rocket::response::Responder
[−]
[src]
pub trait Responder<'r> { fn respond(self) -> Result<Response<'r>, Status>; }
Trait implemented by types that generate responses for clients.
Types that implement this trait can be used as the return type of a handler, as illustrated below:
#[get("/")] fn index() -> T { ... }
In this example, T
can be any type that implements Responder
.
Return Value
A Responder
returns an Ok(Response)
or an Err(Status)
:
An
Ok
variant means that theResponder
was successful in generating aResponse
. TheResponse
will be written out to the client.An
Err
variant means that theResponder
could not or did not generate aResponse
. The containedStatus
will be used to find the relevant error catcher which then generates an error response.
Provided Implementations
Rocket implements Responder
for several standard library types. Their
behavior is documented here. Note that the Result
implementation is
overloaded, allowing for two Responder
s to be used at once, depending on
the variant.
&str
Sets the
Content-Type
totext/plain
. The string is used as the body of the response, which is fixed size and not streamed. To stream a raw string, useStream::from(Cursor::new(string))
.String
Sets the
Content-Type
t totext/html
. The string is used as the body of the response, which is fixed size and not streamed. To stream a string, useStream::from(Cursor::new(string))
.File
Streams the
File
to the client. This is essentially an alias toStream::from(file)
.()
Responds with an empty body. No Content-Type is set.
Option<T>
If the
Option
isSome
, the wrapped responder is used to respond to the client. Otherwise, anErr
with status 404 Not Found is returned and a warning is printed to the console.Result<T, E> where E: Debug
If the
Result
isOk
, the wrapped responder is used to respond to the client. Otherwise, anErr
with status 500 Internal Server Error is returned and the error is printed to the console using theDebug
implementation.Result<T, E> where E: Debug + Responder
If the
Result
isOk
, the wrappedOk
responder is used to respond to the client. If theResult
isErr
, the wrappedErr
responder is used to respond to the client.
Implementation Tips
This section describes a few best practices to take into account when
implementing Responder
.
Debug
A type implementing Responder
should implement the Debug
trait when
possible. This is because the Responder
implementation for Result
requires its Err
type to implement Debug
. Therefore, a type implementing
Debug
can more easily be composed.
Joining and Merging
When chaining/wrapping other Responder
s, use the
merge or
join methods on the Response
or ResponseBuilder
struct. Ensure that you document the merging or joining
behavior appropriately.
Example
Say that you have a custom type, Person
:
struct Person { name: String, age: u16 }
You'd like to use Person
as a Responder
so that you can return a
Person
directly from a handler:
#[get("/person/<id>")] fn person(id: usize) -> Option<Person> { Person::from_id(id) }
You want the Person
responder to set two header fields: X-Person-Name
and X-Person-Age
as well as supply a custom representation of the object
(Content-Type: application/x-person
) in the body of the response. The
following Responder
implementation accomplishes this:
use std::io::Cursor; use rocket::response::{self, Response, Responder}; use rocket::http::ContentType; impl<'r> Responder<'r> for Person { fn respond(self) -> response::Result<'r> { Response::build() .sized_body(Cursor::new(format!("{}:{}", self.name, self.age))) .raw_header("X-Person-Name", self.name) .raw_header("X-Person-Age", self.age.to_string()) .header(ContentType::new("application", "x-person")) .ok() } }
Required Methods
fn respond(self) -> Result<Response<'r>, Status>
Returns Ok
if a Response
could be generated successfully. Otherwise,
returns an Err
with a failing Status
.
When using Rocket's code generation, if an Ok(Response)
is returned,
the response will be written out to the client. If an Err(Status)
is
returned, the error catcher for the given status is retrieved and called
to generate a final error response, which is then written out to the
client.
Implementors
impl<'r> Responder<'r> for &'r str
impl Responder<'static> for String
impl Responder<'static> for File
impl Responder<'static> for ()
impl<'r, R: Responder<'r>> Responder<'r> for Option<R>
impl<'r, R: Responder<'r>, E: Debug> Responder<'r> for core::result::Result<R, E>
impl<'r, R: Responder<'r>, E: Responder<'r> + Debug> Responder<'r> for core::result::Result<R, E>
impl Responder<'static> for Redirect
impl<'r, R: Responder<'r>> Responder<'r> for Flash<R>
impl<'r> Responder<'r> for NamedFile
impl<'r, T: Read + 'r> Responder<'r> for Stream<T>
impl<'r> Responder<'r> for Response<'r>
impl<'r> Responder<'r> for Failure
impl<'r, R: Responder<'r>> Responder<'r> for Content<R>
impl<'r, R: Responder<'r>> Responder<'r> for JSON<R>
impl<'r, R: Responder<'r>> Responder<'r> for XML<R>
impl<'r, R: Responder<'r>> Responder<'r> for HTML<R>
impl<'r, R: Responder<'r>> Responder<'r> for Plain<R>
impl<'r, R: Responder<'r>> Responder<'r> for CSS<R>
impl<'r, R: Responder<'r>> Responder<'r> for JavaScript<R>
impl<'r, R: Responder<'r>> Responder<'r> for rocket::response::status::Created<R>
impl<'r, R: Responder<'r> + Hash> Responder<'r> for rocket::response::status::Created<R>
impl<'r, R: Responder<'r>> Responder<'r> for Accepted<R>
impl<'r> Responder<'r> for NoContent
impl<'r> Responder<'r> for Reset
impl<'r, R: Responder<'r>> Responder<'r> for Custom<R>