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 Response
s.
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 Response
s 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§
source§impl<'r> Builder<'r>
impl<'r> Builder<'r>
sourcepub fn new(base: Response<'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());
sourcepub fn status(&mut self, status: Status) -> &mut Builder<'r>
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();
sourcepub fn header<'h: 'r, H>(&mut self, header: H) -> &mut Builder<'r>where
H: Into<Header<'h>>,
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>
.
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);
sourcepub fn header_adjoin<'h: 'r, H>(&mut self, header: H) -> &mut Builder<'r>where
H: Into<Header<'h>>,
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>
.
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);
sourcepub 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,
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);
sourcepub 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,
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);
sourcepub fn sized_body<B, S>(&mut self, size: S, body: B) -> &mut Builder<'r>where
B: AsyncRead + AsyncSeek + Send + 'r,
S: Into<Option<usize>>,
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();
sourcepub fn streamed_body<B>(&mut self, body: B) -> &mut Builder<'r>where
B: AsyncRead + Send + 'r,
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();
sourcepub fn max_chunk_size(&mut self, size: usize) -> &mut Builder<'r>
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();
sourcepub fn merge(&mut self, other: Response<'r>) -> &mut Builder<'r>
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"]);
sourcepub fn join(&mut self, other: Response<'r>) -> &mut Builder<'r>
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"]);
sourcepub fn finalize(&mut self) -> Response<'r>
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();
sourcepub fn ok<E>(&mut self) -> Result<Response<'r>, E>
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());