Struct Builder

pub struct Builder<'r> { /* private fields */ }

Builder for the Response type.

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

Usage

Builder 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 Response 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 body = "Brewing the best coffee!";
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(body.len(), Cursor::new(body))
    .finalize();

Implementations

impl<'r> Builder<'r>

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

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

Example

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

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

pub fn status(&mut self, status: Status) -> &mut Builder<'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 header<'h: 'r, H>(&mut self, header: H) -> &mut Builder<'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>. See trait implementations.

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 Builder<'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>. See trait implementations.

Example

use rocket::Response;
use rocket::http::{Header, Accept};

let response = Response::build()
    .header_adjoin(Header::new("Accept", "application/json"))
    .header_adjoin(Accept::XML)
    .finalize();

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

pub fn raw_header<'a, 'b, N, V>( &mut self, name: N, value: V, ) -> &mut Builder<'r>

where N: Into<Cow<'a, str>>, V: Into<Cow<'b, str>>, 'a: 'r, 'b: 'r,

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, 'b, N, V>( &mut self, name: N, value: V, ) -> &mut Builder<'r>

where N: Into<Cow<'a, str>>, V: Into<Cow<'b, str>>, 'a: 'r, 'b: 'r,

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, S>(&mut self, size: S, body: B) -> &mut Builder<'r>

where B: AsyncRead + AsyncSeek + Send + 'r, S: Into<Option<usize>>,

Sets the body of the Response to be the fixed-sized body with size size, which may be None. If size is None, the body’s size will be computed with calls to seek when the response is written out.

Example

use std::io::Cursor;
use rocket::Response;

let body = "Hello, world!";
let response = Response::build()
    .sized_body(body.len(), Cursor::new(body))
    .finalize();

pub fn streamed_body<B>(&mut self, body: B) -> &mut Builder<'r>

where B: AsyncRead + Send + 'r,

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

Example

use std::io::Cursor;
use rocket::Response;

let response = Response::build()
    .streamed_body(Cursor::new("Hello, world!"))
    .finalize();

pub fn upgrade<P, H>(&mut self, protocol: P, handler: H) -> &mut Builder<'r>

where P: Into<Uncased<'r>>, H: IoHandler + 'r,

Registers handler as the I/O handler for upgrade protocol protocol.

This is equivalent to Response::add_upgrade().

NOTE: Responses registering I/O handlers for upgraded protocols should not set the response status to 101 Switching Protocols, nor set the Connection or Upgrade headers. Rocket automatically sets these headers as needed. See Response#upgrading for details.

Example

use std::pin::Pin;

use rocket::Response;
use rocket::data::{IoHandler, IoStream};
use rocket::tokio::io;

struct EchoHandler;

#[rocket::async_trait]
impl IoHandler for EchoHandler {
    async fn io(self: Box<Self>, io: IoStream) -> io::Result<()> {
        let (mut reader, mut writer) = io::split(io);
        io::copy(&mut reader, &mut writer).await?;
        Ok(())
    }
}

let response = Response::build()
    .upgrade("raw-echo", EchoHandler)
    .streamed_body(std::io::Cursor::new("We didn't upgrade!"))
    .finalize();

pub fn max_chunk_size(&mut self, size: usize) -> &mut Builder<'r>

Sets the max chunk size of a body, if any, to size.

See Response::set_max_chunk_size() for notes.

Example

use std::io::Cursor;
use rocket::Response;

let response = Response::build()
    .streamed_body(Cursor::new("Hello, world!"))
    .max_chunk_size(3072)
    .finalize();

pub fn merge(&mut self, other: Response<'r>) -> &mut Builder<'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 Builder<'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>

Return the Response structure that was being built by this builder. After calling this method, self is cleared and must be rebuilt as if from new().

Example

use std::io::Cursor;

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

let body = "Brewing the best coffee!";
let response = Response::build()
    .status(Status::ImATeapot)
    .sized_body(body.len(), Cursor::new(body))
    .raw_header("X-Custom", "value 2")
    .finalize();

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

Retrieve the built Response wrapped in Ok. After calling this method, self is cleared and must be rebuilt as if from new().

Example

use rocket::Response;

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

assert!(response.is_ok());