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

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

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

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

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

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::Header;
use rocket::http::hyper::header::ACCEPT;

let response = Response::build()
    .header_adjoin(Header::new(ACCEPT.as_str(), "application/json"))
    .header_adjoin(Header::new(ACCEPT.as_str(), "text/plain"))
    .finalize();

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

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

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

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

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

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

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

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

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

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

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

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

Converts self into a collection.

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more