Struct rocket::response::ResponseBuilder

pub struct ResponseBuilder<'r> { /* fields omitted */ }

Type for easily building Responses.

Building a Response can be a low-level ordeal; this structure presents a higher-level API that simplifies building Responses.

Usage

ResponseBuilder follows the builder pattern and is usually obtained by calling Response::build() on Response. Almost all methods take the current builder as a mutable reference and return the same mutable reference with field(s) modified in the Responder being built. These method calls can be chained: build.a().b().

To finish building and retrieve the built Response, use the finalize() or ok() methods.

Headers

When building a Response, headers can either be replaced or adjoined; the default behavior (using header(..)) is to replace. When a header is replaced, any existing values for headers with the same name are removed, and the new value is set. If no header exists, the header is simply added. On the other hand, when a header is adjoined, all existing values will remain, and the value of the adjoined header will be added to the set of existing values, if any. Adjoining maintains order: headers adjoined first will appear first in the Response.

Joining and Merging

It is often necessary to combine multiple Responses in some way. The merge and join methods facilitate this. The merge method replaces all of the fields in self with those present in other. The join method sets any fields not set in self to the value in other. See their documentation for more details.

Example

The following example builds a Response with:

• Status: 418 I'm a teapot
• Content-Type header: text/plain; charset=utf-8
• X-Teapot-Make header: Rocket
• X-Teapot-Model headers: Utopia, Series 1
• Body: fixed-size string "Brewing the best coffee!"

use std::io::Cursor;
use rocket::response::Response;
use rocket::http::{Status, ContentType};

let response = Response::build()
    .status(Status::ImATeapot)
    .header(ContentType::Plain)
    .raw_header("X-Teapot-Make", "Rocket")
    .raw_header("X-Teapot-Model", "Utopia")
    .raw_header_adjoin("X-Teapot-Model", "Series 1")
    .sized_body(Cursor::new("Brewing the best coffee!"))
    .finalize();

Methods

impl<'r> ResponseBuilder<'r>

pub fn new(base: Response<'r>) -> ResponseBuilder<'r>

Creates a new ResponseBuilder that will build on top of the base Response.

Example

use rocket::response::{ResponseBuilder, Response};

let builder = ResponseBuilder::new(Response::new());

pub fn status(&mut self, status: Status) -> &mut ResponseBuilder<'r>

Sets the status of the Response being built to status.

Example

use rocket::Response;
use rocket::http::Status;

let response = Response::build()
    .status(Status::NotFound)
    .finalize();

pub fn raw_status(
    &mut self,
    code: u16,
    reason: &'static str
) -> &mut ResponseBuilder<'r>

Sets the status of the Response being built to a custom status constructed from the code and reason phrase.

Example

use rocket::Response;

let response = Response::build()
    .raw_status(699, "Alien Encounter")
    .finalize();

pub fn header<'h: 'r, H>(&mut self, header: H) -> &mut ResponseBuilder<'r> where
    H: Into<Header<'h>>, 

Adds header to the Response, replacing any header with the same name that already exists in the response. If multiple headers with the same name exist, they are all removed, and only the new header and value will remain.

The type of header can be any type that implements Into<Header>. This includes Header itself, ContentType and hyper::header types.

Example

use rocket::Response;
use rocket::http::ContentType;

let response = Response::build()
    .header(ContentType::JSON)
    .header(ContentType::HTML)
    .finalize();

assert_eq!(response.headers().get("Content-Type").count(), 1);

pub fn header_adjoin<'h: 'r, H>(
    &mut self,
    header: H
) -> &mut ResponseBuilder<'r> where
    H: Into<Header<'h>>, 

Adds header to the Response by adjoining the header with any existing headers with the same name that already exist in the Response. This allows for multiple headers with the same name and potentially different values to be present in the Response.

The type of header can be any type that implements Into<Header>. This includes Header itself, ContentType and hyper::header types.

Example

use rocket::Response;
use rocket::http::hyper::header::Accept;

let response = Response::build()
    .header_adjoin(Accept::json())
    .header_adjoin(Accept::text())
    .finalize();

assert_eq!(response.headers().get("Accept").count(), 2);

pub fn raw_header<'a: 'r, 'b: 'r, N, V>(
    &mut self,
    name: N,
    value: V
) -> &mut ResponseBuilder<'r> where
    N: Into<Cow<'a, str>>,
    V: Into<Cow<'b, str>>, 

Adds a custom header to the Response with the given name and value, replacing any header with the same name that already exists in the response. If multiple headers with the same name exist, they are all removed, and only the new header and value will remain.

Example

use rocket::Response;

let response = Response::build()
    .raw_header("X-Custom", "first")
    .raw_header("X-Custom", "second")
    .finalize();

assert_eq!(response.headers().get("X-Custom").count(), 1);

pub fn raw_header_adjoin<'a: 'r, 'b: 'r, N, V>(
    &mut self,
    name: N,
    value: V
) -> &mut ResponseBuilder<'r> where
    N: Into<Cow<'a, str>>,
    V: Into<Cow<'b, str>>, 

Adds custom header to the Response with the given name and value, adjoining the header with any existing headers with the same name that already exist in the Response. This allows for multiple headers with the same name and potentially different values to be present in the Response.

Example

use rocket::Response;

let response = Response::build()
    .raw_header_adjoin("X-Custom", "first")
    .raw_header_adjoin("X-Custom", "second")
    .finalize();

assert_eq!(response.headers().get("X-Custom").count(), 2);

pub fn sized_body<B>(&mut self, body: B) -> &mut ResponseBuilder<'r> where
    B: Read + Seek + 'r, 

Sets the body of the Response to be the fixed-sized body.

Example

use rocket::Response;
use std::fs::File;

let response = Response::build()
    .sized_body(File::open("body.txt")?)
    .finalize();

pub fn streamed_body<B>(&mut self, body: B) -> &mut ResponseBuilder<'r> where
    B: Read + 'r, 

Sets the body of the Response to be the streamed body.

Example

use rocket::Response;
use std::fs::File;

let response = Response::build()
    .streamed_body(File::open("body.txt")?)
    .finalize();

pub fn chunked_body<B: Read + 'r>(
    &mut self,
    body: B,
    chunk_size: u64
) -> &mut ResponseBuilder<'r>

Sets the body of the Response to be the streamed body with a custom chunk size, in bytes.

Example

use rocket::Response;
use std::fs::File;

let response = Response::build()
    .chunked_body(File::open("body.txt")?, 8096)
    .finalize();

pub fn raw_body<T: Read + 'r>(
    &mut self,
    body: Body<T>
) -> &mut ResponseBuilder<'r>

Sets the body of self to be body. This method should typically not be used, opting instead for one of sized_body, streamed_body, or chunked_body.

Example

use std::io::Cursor;
use rocket::response::{Response, Body};

let response = Response::build()
    .raw_body(Body::Sized(Cursor::new("Hello!"), 6))
    .finalize();

pub fn merge(&mut self, other: Response<'r>) -> &mut ResponseBuilder<'r>

Merges the other Response into self by setting any fields in self to the corresponding value in other if they are set in other. Fields in self are unchanged if they are not set in other. If a header is set in both self and other, the values in other are kept. Headers set only in self remain.

Example

use rocket::Response;
use rocket::http::{Status, ContentType};

let base = Response::build()
    .status(Status::NotFound)
    .header(ContentType::HTML)
    .raw_header("X-Custom", "value 1")
    .finalize();

let response = Response::build()
    .status(Status::ImATeapot)
    .raw_header("X-Custom", "value 2")
    .raw_header_adjoin("X-Custom", "value 3")
    .merge(base)
    .finalize();

assert_eq!(response.status(), Status::NotFound);

let ctype: Vec<_> = response.headers().get("Content-Type").collect();
assert_eq!(ctype, vec![ContentType::HTML.to_string()]);

let custom_values: Vec<_> = response.headers().get("X-Custom").collect();
assert_eq!(custom_values, vec!["value 1"]);

pub fn join(&mut self, other: Response<'r>) -> &mut ResponseBuilder<'r>

Joins the other Response into self by setting any fields in self to the corresponding value in other if they are set in self. Fields in self are unchanged if they are already set. If a header is set in both self and other, the values are adjoined, with the values in self coming first. Headers only in self or other are set in self.

Example

use rocket::Response;
use rocket::http::{Status, ContentType};

let other = Response::build()
    .status(Status::NotFound)
    .header(ContentType::HTML)
    .raw_header("X-Custom", "value 1")
    .finalize();

let response = Response::build()
    .status(Status::ImATeapot)
    .raw_header("X-Custom", "value 2")
    .raw_header_adjoin("X-Custom", "value 3")
    .join(other)
    .finalize();

assert_eq!(response.status(), Status::ImATeapot);

let ctype: Vec<_> = response.headers().get("Content-Type").collect();
assert_eq!(ctype, vec![ContentType::HTML.to_string()]);

let custom_values: Vec<_> = response.headers().get("X-Custom").collect();
assert_eq!(custom_values, vec!["value 2", "value 3", "value 1"]);

pub fn finalize(&mut self) -> Response<'r>

Retrieve the built Response.

Example

use rocket::Response;

let response = Response::build()
    // build the response
    .finalize();

pub fn ok<T>(&mut self) -> Result<Response<'r>, T>

Retrieve the built Response wrapped in Ok.

Example

use rocket::Response;

let response: Result<Response, ()> = Response::build()
    // build the response
    .ok();

assert!(response.is_ok());