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):

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.

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.

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

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