Struct rocket::response::ResponseBuilder

source ·
pub struct ResponseBuilder<'r> { /* private fields */ }
Expand description

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();

Implementations§

source§

impl<'r> ResponseBuilder<'r>

source

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());
source

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();
source

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();
source

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);
source

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);
source

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);
source

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);
source

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();
source

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();
source

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();
source

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();
source

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"]);
source

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"]);
source

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

Retrieve the built Response.

§Example
use rocket::Response;

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

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());

Auto Trait Implementations§

§

impl<'r> Freeze for ResponseBuilder<'r>

§

impl<'r> !RefUnwindSafe for ResponseBuilder<'r>

§

impl<'r> !Send for ResponseBuilder<'r>

§

impl<'r> !Sync for ResponseBuilder<'r>

§

impl<'r> Unpin for ResponseBuilder<'r>

§

impl<'r> !UnwindSafe for ResponseBuilder<'r>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T, I> AsResult<T, I> for T
where I: Input,

source§

fn as_result(self) -> Result<T, ParseErr<I>>

source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> IntoCollection<T> for T

§

fn into_collection<A>(self) -> SmallVec<A>
where A: Array<Item = T>,

Converts self into a collection.
§

fn mapped<U, F, A>(self, f: F) -> SmallVec<A>
where F: FnMut(T) -> U, A: Array<Item = U>,

source§

impl<T> Same for T

source§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> Typeable for T
where T: Any,

source§

fn get_type(&self) -> TypeId

Get the TypeId of this object.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V