[−][src]Trait rocket::response::Responder

pub trait Responder<'r> {
    fn respond_to(self, request: &Request) -> 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 the Responder was successful in generating a Response. The Response will be written out to the client.
An Err variant means that the Responder could not or did not generate a Response. The contained Status 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 Responders to be used at once, depending on the variant.

&str

Sets the Content-Type to text/plain. The string is used as the body of the response, which is fixed size and not streamed. To stream a raw string, use Stream::from(Cursor::new(string)).
String

Sets the Content-Type to text/plain. The string is used as the body of the response, which is fixed size and not streamed. To stream a string, use Stream::from(Cursor::new(string)).
Vec

Sets the Content-Type to application/octet-stream. The vector's data is used as the body of the response, which is fixed size and not streamed. To stream a vector of bytes, use Stream::from(Cursor::new(vec)).
File

Responds with a streamed body containing the data in the File. No Content-Type is set. To automatically have a Content-Type set based on the file's extension, use NamedFile.
()

Responds with an empty body. No Content-Type is set.
Option<T>

If the Option is Some, the wrapped responder is used to respond to the client. Otherwise, an Err with status 404 Not Found is returned and a warning is printed to the console.
Result<T, E> where E: Debug

If the Result is Ok, the wrapped responder is used to respond to the client. Otherwise, an Err with status 500 Internal Server Error is returned and the error is printed to the console using the Debug implementation.
Result<T, E> where E: Debug + Responder

If the Result is Ok, the wrapped Ok responder is used to respond to the client. If the Result is Err, the wrapped Err 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 Responders, use the merge or join methods on the Response or ResponseBuilder struct. Ensure that you document the merging or joining behavior appropriately.

Inspecting Requests

A Responder has access to the request it is responding to. Even so, you should avoid using the Request value as much as possible. This is because using the Request object makes your responder inpure, and so the use of the type as a Responder has less intrinsic meaning associated with it. If the Responder were pure, however, it always respond in the same manner, regardless of the incoming request. Thus, knowing the type is sufficient to fully determine its functionality.

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::request::Request;
use rocket::response::{self, Response, Responder};
use rocket::http::ContentType;

impl<'r> Responder<'r> for Person {
    fn respond_to(self, _: &Request) -> 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_to(self, request: &Request) -> Result<Response<'r>, Status>`

Returns Ok if a Response could be generated successfully. Otherwise, returns an Err with a failing Status.

The request parameter is the Request that this Responder is responding to.

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.

Implementations on Foreign Types

`impl<'r> Responder<'r> for &'r str`
[src]

Returns a response with Content-Type text/plain and a fixed-size body containing the string self. Always returns Ok.

`impl<'r> Responder<'r> for String`
[src]

Returns a response with Content-Type text/plain and a fixed-size body containing the string self. Always returns Ok.

`impl<'r> Responder<'r> for Vec<u8>`
[src]

Returns a response with Content-Type application/octet-stream and a fixed-size body containing the data in self. Always returns Ok.

`impl<'r> Responder<'r> for File`
[src]

Returns a response with a sized body for the file. Always returns Ok.

`impl<'r> Responder<'r> for ()`
[src]

Returns an empty, default Response. Always returns Ok.

`impl<'r, R: Responder<'r>> Responder<'r> for Option<R>`
[src]

If self is Some, responds with the wrapped Responder. Otherwise prints a warning message and returns an Err of Status::NotFound.

`impl<'r, R: Responder<'r>, E: Debug> Responder<'r> for Result<R, E>`
[src]

If self is Ok, responds with the wrapped Responder. Otherwise prints an error message with the Err value returns an Err of Status::InternalServerError.

`impl<'r, R: Responder<'r>, E: Responder<'r> + Debug> Responder<'r> for Result<R, E>`
[src]

Responds with the wrapped Responder in self, whether it is Ok or Err.

Implementors

`impl Responder<'static> for Reset`
[src]

Sets the status code of the response to 205 Reset Content. The body of the response will be empty.

`impl Responder<'static> for Failure`
[src]

`impl Responder<'static> for Redirect`
[src]

Constructs a response with the appropriate status code and the given URL in the Location header field. The body of the response is empty. This responder does not fail.

`impl<'r> Responder<'r> for NoContent`
[src]

Sets the status code of the response to 204 No Content. The body of the response will be empty.

`impl<'r> Responder<'r> for NamedFile`
[src]

Streams the named file to the client. Sets or overrides the Content-Type in the response according to the file's extension if the extension is recognized. See ContentType::from_extension for more information. If you would like to stream a file with a different Content-Type than that implied by its extension, use a File directly.

`impl<'r> Responder<'r> for Response<'r>`
[src]

`fn respond_to(self, _: &Request) -> Result<Response<'r>, Status>`
[src]

This is the identity implementation. It simply returns Ok(self).

`impl<'r, R: Responder<'r> + Hash> Responder<'r> for Created<R>`
[src]

In addition to setting the status code, Location header, and finalizing the response with the Responder, the ETag header is set conditionally if a Responder is provided that implements Hash. The ETag header is set to a hash value of the responder.

`impl<'r, R: Responder<'r>> Responder<'r> for Content<R>`
[src]

Overrides the Content-Type of the response to the wrapped ContentType then delegates the remainder of the response to the wrapped responder.