logo
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:

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 otherwords, 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

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

The present value is 4096.

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

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

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

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

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

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

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

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

Attempts to read from the AsyncRead into buf. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Creates a new AsyncRead instance that chains this stream with next. Read more

Pulls some bytes from this source into the specified buffer, returning how many bytes were read. Read more

Pulls some bytes from this source into the specified buffer, advancing the buffer’s internal cursor. Read more

Reads the exact number of bytes required to fill buf. Read more

Reads an unsigned 8 bit integer from the underlying reader. Read more

Reads a signed 8 bit integer from the underlying reader. Read more

Reads an unsigned 16-bit integer in big-endian order from the underlying reader. Read more

Reads a signed 16-bit integer in big-endian order from the underlying reader. Read more

Reads an unsigned 32-bit integer in big-endian order from the underlying reader. Read more

Reads a signed 32-bit integer in big-endian order from the underlying reader. Read more

Reads an unsigned 64-bit integer in big-endian order from the underlying reader. Read more

Reads an signed 64-bit integer in big-endian order from the underlying reader. Read more

Reads an unsigned 128-bit integer in big-endian order from the underlying reader. Read more

Reads an signed 128-bit integer in big-endian order from the underlying reader. Read more

Reads an 32-bit floating point type in big-endian order from the underlying reader. Read more

Reads an 64-bit floating point type in big-endian order from the underlying reader. Read more

Reads an unsigned 16-bit integer in little-endian order from the underlying reader. Read more

Reads a signed 16-bit integer in little-endian order from the underlying reader. Read more

Reads an unsigned 32-bit integer in little-endian order from the underlying reader. Read more

Reads a signed 32-bit integer in little-endian order from the underlying reader. Read more

Reads an unsigned 64-bit integer in little-endian order from the underlying reader. Read more

Reads an signed 64-bit integer in little-endian order from the underlying reader. Read more

Reads an unsigned 128-bit integer in little-endian order from the underlying reader. Read more

Reads an signed 128-bit integer in little-endian order from the underlying reader. Read more

Reads an 32-bit floating point type in little-endian order from the underlying reader. Read more

Reads an 64-bit floating point type in little-endian order from the underlying reader. Read more

Reads all bytes until EOF in this source, placing them into buf. Read more

Reads all bytes until EOF in this source, appending them to buf. Read more

Creates an adaptor which reads at most limit bytes from it. 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