Struct Body

pub struct Body<'r> { /* private fields */ }

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

impl<'r> Body<'r>

pub const DEFAULT_MAX_CHUNK: usize = 4_096usize

The default max size, in bytes, of chunks for streamed responses.

The present value is 4096.

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

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

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

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

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

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

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

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

impl AsyncRead for Body<'_>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl<'r> Debug for Body<'r>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Body<'_>

fn default() -> Self

Returns the “default value” for a type.