pub struct Body<'r> { /* private fields */ }
Expand description
The body of a Response
.
A Body
is never created directly, but instead, through the following
methods on Response
and Builder
:
Builder::sized_body()
Response::set_sized_body()
Builder::streamed_body()
Response::set_streamed_body()
An unset body in a Response
begins as a Body::default()
, a None
body with a preset size of 0
.
Sizing
A response body may be sized or unsized (“streamed”). A “sized” body is
transferred with a Content-Length
equal to its size while an “unsized”
body is chunk-encoded. The body data is streamed in all cases and is never
buffered in memory beyond a minimal amount for efficient transmission.
Sized
A sized body may have a preset size (Body::preset_size()
) or may have
its size computed on the fly by seeking (Body::size()
). As such, sized
bodies must implement AsyncSeek
. If a body does not have a preset size
and the fails to be computed dynamically, a sized body is treated as an
unsized body when written out to the network.
Unsized
An unsized body’s data is streamed as it arrives. In other words, as soon as
the body’s AsyncRead
implementation returns bytes, the bytes are written
to the network. Individual unsized bodies may use an internal buffer to
curtail writes to the network.
The maximum number of bytes written to the network at once is controlled via
the Body::max_chunk_size()
parameter which can be set via
Response::set_max_chunk_size()
and Builder::max_chunk_size()
.
Reading
The contents of a body, decoded, can be read through Body::to_bytes()
,
Body::to_string()
, or directly though Body
’s AsyncRead
implementation.
Implementations§
source§impl<'r> Body<'r>
impl<'r> Body<'r>
sourcepub const DEFAULT_MAX_CHUNK: usize = 4_096usize
pub const DEFAULT_MAX_CHUNK: usize = 4_096usize
The default max size, in bytes, of chunks for streamed responses.
The present value is 4096
.
sourcepub fn is_none(&self) -> bool
pub fn is_none(&self) -> bool
Returns true
if the body is None
or unset, the default.
Example
use rocket::response::Response;
let r = Response::build().finalize();
assert!(r.body().is_none());
sourcepub fn is_some(&self) -> bool
pub fn is_some(&self) -> bool
Returns true
if the body is not None
, anything other than the
default.
Example
use std::io::Cursor;
use rocket::response::Response;
let body = "Brewing the best coffee!";
let r = Response::build()
.sized_body(body.len(), Cursor::new(body))
.finalize();
assert!(r.body().is_some());
sourcepub fn preset_size(&self) -> Option<usize>
pub fn preset_size(&self) -> Option<usize>
A body’s preset size, which may have been computed by a previous call to
Body::size()
.
Unsized bodies always return None
, while sized bodies return Some
if the body size was supplied directly on creation or a call to
Body::size()
successfully computed the size and None
otherwise.
Example
use std::io::Cursor;
use rocket::response::Response;
let body = "Brewing the best coffee!";
let r = Response::build()
.sized_body(body.len(), Cursor::new(body))
.finalize();
// This will _always_ return `Some`.
assert_eq!(r.body().preset_size(), Some(body.len()));
let r = Response::build()
.streamed_body(Cursor::new(body))
.finalize();
// This will _never_ return `Some`.
assert_eq!(r.body().preset_size(), None);
let mut r = Response::build()
.sized_body(None, Cursor::new(body))
.finalize();
// This returns `Some` only after a call to `size()`.
assert_eq!(r.body().preset_size(), None);
assert_eq!(r.body_mut().size().await, Some(body.len()));
assert_eq!(r.body().preset_size(), Some(body.len()));
sourcepub fn max_chunk_size(&self) -> usize
pub fn max_chunk_size(&self) -> usize
Returns the maximum chunk size for chunked transfers.
If none is explicitly set, defaults to Body::DEFAULT_MAX_CHUNK
.
Example
use std::io::Cursor;
use rocket::response::{Response, Body};
let body = "Brewing the best coffee!";
let r = Response::build()
.sized_body(body.len(), Cursor::new(body))
.finalize();
assert_eq!(r.body().max_chunk_size(), Body::DEFAULT_MAX_CHUNK);
let r = Response::build()
.sized_body(body.len(), Cursor::new(body))
.max_chunk_size(1024)
.finalize();
assert_eq!(r.body().max_chunk_size(), 1024);
sourcepub async fn size(&mut self) -> Option<usize>
pub async fn size(&mut self) -> Option<usize>
Attempts to compute the body’s size and returns it if the body is sized.
If the size was preset (see Body::preset_size()
), the value is
returned immediately as Some
. If the body is unsized or computing the
size fails, returns None
. Otherwise, the size is computed by seeking,
and the preset_size
is updated to reflect the known value.
Note: the number of bytes read from the reader and/or written to the network may differ from the value returned by this method. Some examples include:
- bodies in response to
HEAD
requests are never read or written - the client may close the connection before the body is read fully
- reading the body may fail midway
- a preset size may differ from the actual body size
Example
use std::io::Cursor;
use rocket::response::Response;
let body = "Hello, Rocketeers!";
let mut r = Response::build()
.sized_body(None, Cursor::new(body))
.finalize();
assert_eq!(r.body().preset_size(), None);
assert_eq!(r.body_mut().size().await, Some(body.len()));
assert_eq!(r.body().preset_size(), Some(body.len()));
sourcepub fn take(&mut self) -> Self
pub fn take(&mut self) -> Self
Moves the body out of self
and returns it, leaving a
Body::default()
in its place.
Example
use std::io::Cursor;
use rocket::response::Response;
let mut r = Response::build()
.sized_body(None, Cursor::new("Hi"))
.finalize();
assert!(r.body().is_some());
let body = r.body_mut().take();
assert!(body.is_some());
assert!(r.body().is_none());
sourcepub async fn to_bytes(&mut self) -> Result<Vec<u8>>
pub async fn to_bytes(&mut self) -> Result<Vec<u8>>
Reads all of self
into a vector of bytes, consuming the contents.
If reading fails, returns Err
. Otherwise, returns Ok
. Calling this
method may partially or fully consume the body’s content. As such,
subsequent calls to to_bytes()
will likely return different result.
Example
use std::io;
use rocket::response::Response;
let mut r = Response::build()
.streamed_body(io::Cursor::new(&[1, 2, 3, 11, 13, 17]))
.finalize();
assert_eq!(r.body_mut().to_bytes().await?, &[1, 2, 3, 11, 13, 17]);
sourcepub async fn to_string(&mut self) -> Result<String>
pub async fn to_string(&mut self) -> Result<String>
Reads all of self
into a string, consuming the contents.
If reading fails, or the body contains invalid UTF-8 characters, returns
Err
. Otherwise, returns Ok
. Calling this method may partially or
fully consume the body’s content. As such, subsequent calls to
to_string()
will likely return different result.
Example
use std::io;
use rocket::response::Response;
let mut r = Response::build()
.streamed_body(io::Cursor::new("Hello, Rocketeers!"))
.finalize();
assert_eq!(r.body_mut().to_string().await?, "Hello, Rocketeers!");
Trait Implementations§
Auto Trait Implementations§
impl<'r> !RefUnwindSafe for Body<'r>
impl<'r> Send for Body<'r>
impl<'r> !Sync for Body<'r>
impl<'r> Unpin for Body<'r>
impl<'r> !UnwindSafe for Body<'r>
Blanket Implementations§
source§impl<R> AsyncReadExt for Rwhere
R: AsyncRead + ?Sized,
impl<R> AsyncReadExt for Rwhere R: AsyncRead + ?Sized,
source§fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self>where
Self: Unpin,
fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self>where Self: Unpin,
source§fn read_buf<B, 'a>(&'a mut self, buf: &'a mut B) -> ReadBuf<'a, Self, B>where
Self: Sized + Unpin,
B: BufMut,
fn read_buf<B, 'a>(&'a mut self, buf: &'a mut B) -> ReadBuf<'a, Self, B>where Self: Sized + Unpin, B: BufMut,
source§fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self>where
Self: Unpin,
fn read_exact<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self>where Self: Unpin,
buf
. Read moresource§fn read_u8(&mut self) -> ReadU8<&mut Self>where
Self: Unpin,
fn read_u8(&mut self) -> ReadU8<&mut Self>where Self: Unpin,
source§fn read_i8(&mut self) -> ReadI8<&mut Self>where
Self: Unpin,
fn read_i8(&mut self) -> ReadI8<&mut Self>where Self: Unpin,
source§fn read_u16(&mut self) -> ReadU16<&mut Self>where
Self: Unpin,
fn read_u16(&mut self) -> ReadU16<&mut Self>where Self: Unpin,
source§fn read_i16(&mut self) -> ReadI16<&mut Self>where
Self: Unpin,
fn read_i16(&mut self) -> ReadI16<&mut Self>where Self: Unpin,
source§fn read_u32(&mut self) -> ReadU32<&mut Self>where
Self: Unpin,
fn read_u32(&mut self) -> ReadU32<&mut Self>where Self: Unpin,
source§fn read_i32(&mut self) -> ReadI32<&mut Self>where
Self: Unpin,
fn read_i32(&mut self) -> ReadI32<&mut Self>where Self: Unpin,
source§fn read_u64(&mut self) -> ReadU64<&mut Self>where
Self: Unpin,
fn read_u64(&mut self) -> ReadU64<&mut Self>where Self: Unpin,
source§fn read_i64(&mut self) -> ReadI64<&mut Self>where
Self: Unpin,
fn read_i64(&mut self) -> ReadI64<&mut Self>where Self: Unpin,
source§fn read_u128(&mut self) -> ReadU128<&mut Self>where
Self: Unpin,
fn read_u128(&mut self) -> ReadU128<&mut Self>where Self: Unpin,
source§fn read_i128(&mut self) -> ReadI128<&mut Self>where
Self: Unpin,
fn read_i128(&mut self) -> ReadI128<&mut Self>where Self: Unpin,
source§fn read_f32(&mut self) -> ReadF32<&mut Self>where
Self: Unpin,
fn read_f32(&mut self) -> ReadF32<&mut Self>where Self: Unpin,
source§fn read_f64(&mut self) -> ReadF64<&mut Self>where
Self: Unpin,
fn read_f64(&mut self) -> ReadF64<&mut Self>where Self: Unpin,
source§fn read_u16_le(&mut self) -> ReadU16Le<&mut Self>where
Self: Unpin,
fn read_u16_le(&mut self) -> ReadU16Le<&mut Self>where Self: Unpin,
source§fn read_i16_le(&mut self) -> ReadI16Le<&mut Self>where
Self: Unpin,
fn read_i16_le(&mut self) -> ReadI16Le<&mut Self>where Self: Unpin,
source§fn read_u32_le(&mut self) -> ReadU32Le<&mut Self>where
Self: Unpin,
fn read_u32_le(&mut self) -> ReadU32Le<&mut Self>where Self: Unpin,
source§fn read_i32_le(&mut self) -> ReadI32Le<&mut Self>where
Self: Unpin,
fn read_i32_le(&mut self) -> ReadI32Le<&mut Self>where Self: Unpin,
source§fn read_u64_le(&mut self) -> ReadU64Le<&mut Self>where
Self: Unpin,
fn read_u64_le(&mut self) -> ReadU64Le<&mut Self>where Self: Unpin,
source§fn read_i64_le(&mut self) -> ReadI64Le<&mut Self>where
Self: Unpin,
fn read_i64_le(&mut self) -> ReadI64Le<&mut Self>where Self: Unpin,
source§fn read_u128_le(&mut self) -> ReadU128Le<&mut Self>where
Self: Unpin,
fn read_u128_le(&mut self) -> ReadU128Le<&mut Self>where Self: Unpin,
source§fn read_i128_le(&mut self) -> ReadI128Le<&mut Self>where
Self: Unpin,
fn read_i128_le(&mut self) -> ReadI128Le<&mut Self>where Self: Unpin,
source§fn read_f32_le(&mut self) -> ReadF32Le<&mut Self>where
Self: Unpin,
fn read_f32_le(&mut self) -> ReadF32Le<&mut Self>where Self: Unpin,
source§fn read_f64_le(&mut self) -> ReadF64Le<&mut Self>where
Self: Unpin,
fn read_f64_le(&mut self) -> ReadF64Le<&mut Self>where Self: Unpin,
source§fn read_to_end<'a>(
&'a mut self,
buf: &'a mut Vec<u8, Global>
) -> ReadToEnd<'a, Self>where
Self: Unpin,
fn read_to_end<'a>( &'a mut self, buf: &'a mut Vec<u8, Global> ) -> ReadToEnd<'a, Self>where Self: Unpin,
buf
. Read moresource§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);