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 upgrade<P, H>(&mut self, protocol: P, handler: H) -> &mut Builder<'r>where
P: Into<Uncased<'r>>,
H: IoHandler + 'r,
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: Pin<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();
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());
Auto Trait Implementations§
impl<'r> !RefUnwindSafe for Builder<'r>
impl<'r> Send for Builder<'r>
impl<'r> !Sync for Builder<'r>
impl<'r> Unpin for Builder<'r>
impl<'r> !UnwindSafe for Builder<'r>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoCollection<T> for T
impl<T> IntoCollection<T> for T
source§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere T: ?Sized,
source§fn fg(&self, value: Color) -> Painted<&T>
fn fg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the foreground set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like red()
and
green()
, which have the same functionality but are
pithier.
Example
Set foreground color to white using fg()
:
use yansi::{Paint, Color};
painted.fg(Color::White);
Set foreground color to white using white()
.
use yansi::Paint;
painted.white();
source§fn bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
source§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
source§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
source§fn bright_yellow(&self) -> Painted<&T>
fn bright_yellow(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightYellow
.
Example
println!("{}", value.bright_yellow());
source§fn bright_blue(&self) -> Painted<&T>
fn bright_blue(&self) -> Painted<&T>
source§fn bright_magenta(&self) -> Painted<&T>
fn bright_magenta(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightMagenta
.
Example
println!("{}", value.bright_magenta());
source§fn bright_cyan(&self) -> Painted<&T>
fn bright_cyan(&self) -> Painted<&T>
source§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
source§fn bg(&self, value: Color) -> Painted<&T>
fn bg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the background set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like on_red()
and
on_green()
, which have the same functionality but
are pithier.
Example
Set background color to red using fg()
:
use yansi::{Paint, Color};
painted.bg(Color::Red);
Set background color to red using on_red()
.
use yansi::Paint;
painted.on_red();
source§fn on_primary(&self) -> Painted<&T>
fn on_primary(&self) -> Painted<&T>
source§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
source§fn on_bright_black(&self) -> Painted<&T>
fn on_bright_black(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightBlack
.
Example
println!("{}", value.on_bright_black());
source§fn on_bright_red(&self) -> Painted<&T>
fn on_bright_red(&self) -> Painted<&T>
source§fn on_bright_green(&self) -> Painted<&T>
fn on_bright_green(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightGreen
.
Example
println!("{}", value.on_bright_green());
source§fn on_bright_yellow(&self) -> Painted<&T>
fn on_bright_yellow(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightYellow
.
Example
println!("{}", value.on_bright_yellow());
source§fn on_bright_blue(&self) -> Painted<&T>
fn on_bright_blue(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightBlue
.
Example
println!("{}", value.on_bright_blue());
source§fn on_bright_magenta(&self) -> Painted<&T>
fn on_bright_magenta(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightMagenta
.
Example
println!("{}", value.on_bright_magenta());
source§fn on_bright_cyan(&self) -> Painted<&T>
fn on_bright_cyan(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightCyan
.
Example
println!("{}", value.on_bright_cyan());
source§fn on_bright_white(&self) -> Painted<&T>
fn on_bright_white(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightWhite
.
Example
println!("{}", value.on_bright_white());
source§fn attr(&self, value: Attribute) -> Painted<&T>
fn attr(&self, value: Attribute) -> Painted<&T>
Enables the styling Attribute
value
.
This method should be used rarely. Instead, prefer to use
attribute-specific builder methods like bold()
and
underline()
, which have the same functionality
but are pithier.
Example
Make text bold using attr()
:
use yansi::{Paint, Attribute};
painted.attr(Attribute::Bold);
Make text bold using using bold()
.
use yansi::Paint;
painted.bold();
source§fn underline(&self) -> Painted<&T>
fn underline(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::Underline
.
Example
println!("{}", value.underline());
source§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::RapidBlink
.
Example
println!("{}", value.rapid_blink());
source§fn quirk(&self, value: Quirk) -> Painted<&T>
fn quirk(&self, value: Quirk) -> Painted<&T>
Enables the yansi
Quirk
value
.
This method should be used rarely. Instead, prefer to use quirk-specific
builder methods like mask()
and
wrap()
, which have the same functionality but are
pithier.
Example
Enable wrapping using .quirk()
:
use yansi::{Paint, Quirk};
painted.quirk(Quirk::Wrap);
Enable wrapping using wrap()
.
use yansi::Paint;
painted.wrap();
source§fn whenever(&self, value: Condition) -> Painted<&T>
fn whenever(&self, value: Condition) -> Painted<&T>
Conditionally enable styling based on whether the Condition
value
applies. Replaces any previous condition.
See the crate level docs for more details.
Example
Enable styling painted
only when both stdout
and stderr
are TTYs:
use yansi::{Paint, Condition};
painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);