Struct rocket::response::Body[][src]

pub struct Body<'r> { /* fields omitted */ }
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

impl<'r> Body<'r>[src]

pub const DEFAULT_MAX_CHUNK: usize[src]

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

The present value is 4096.

pub fn is_none(&self) -> bool[src]

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[src]

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>[src]

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[src]

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>[src]

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[src]

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>>[src]

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>[src]

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<'_>[src]

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

Attempts to read from the AsyncRead into buf. Read more

impl<'r> Debug for Body<'r>[src]

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

Formats the value using the given formatter. Read more

impl Default for Body<'_>[src]

fn default() -> Self[src]

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

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

impl<T> Any for T where
    T: 'static + ?Sized
[src]

pub fn type_id(&self) -> TypeId[src]

Gets the TypeId of self. Read more

impl<R> AsyncReadExt for R where
    R: AsyncRead + ?Sized
[src]

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: AsyncRead
[src]

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

fn read(&'a mut self, buf: &'a mut [u8]) -> Read<'a, Self> where
    Self: Unpin
[src]

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

fn read_buf<B>(&'a mut self, buf: &'a mut B) -> ReadBuf<'a, Self, B> where
    Self: Unpin,
    B: BufMut
[src]

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

fn read_exact(&'a mut self, buf: &'a mut [u8]) -> ReadExact<'a, Self> where
    Self: Unpin
[src]

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

fn read_u8(&'a mut self) -> ReadU8<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_i8(&'a mut self) -> ReadI8<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_u16(&'a mut self) -> ReadU16<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_i16(&'a mut self) -> ReadI16<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_u32(&'a mut self) -> ReadU32<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_i32(&'a mut self) -> ReadI32<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_u64(&'a mut self) -> ReadU64<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_i64(&'a mut self) -> ReadI64<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_u128(&'a mut self) -> ReadU128<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_i128(&'a mut self) -> ReadI128<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_u16_le(&'a mut self) -> ReadU16Le<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_i16_le(&'a mut self) -> ReadI16Le<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_u32_le(&'a mut self) -> ReadU32Le<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_i32_le(&'a mut self) -> ReadI32Le<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_u64_le(&'a mut self) -> ReadU64Le<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_i64_le(&'a mut self) -> ReadI64Le<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_u128_le(&'a mut self) -> ReadU128Le<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_i128_le(&'a mut self) -> ReadI128Le<&'a mut Self> where
    Self: Unpin
[src]

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

fn read_to_end(
    &'a mut self,
    buf: &'a mut Vec<u8, Global>
) -> ReadToEnd<'a, Self> where
    Self: Unpin
[src]

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

fn read_to_string(&'a mut self, dst: &'a mut String) -> ReadToString<'a, Self> where
    Self: Unpin
[src]

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

fn take(self, limit: u64) -> Take<Self>[src]

Creates an adaptor which reads at most limit bytes from it. Read more

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

pub fn borrow(&self) -> &T[src]

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

pub fn borrow_mut(&mut self) -> &mut T[src]

Mutably borrows from an owned value. Read more

impl<T> From<T> for T[src]

pub fn from(t: T) -> T[src]

Performs the conversion.

impl<T> Instrument for T[src]

fn instrument(self, span: Span) -> Instrumented<Self>[src]

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

fn in_current_span(self) -> Instrumented<Self>[src]

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

pub fn into(self) -> U[src]

Performs the conversion.

impl<T> IntoCollection<T> for T

pub fn into_collection<A>(self) -> SmallVec<A> where
    A: Array<Item = T>, 

Converts self into a collection.

pub fn mapped<U, F, A>(self, f: F) -> SmallVec<A> where
    F: FnMut(T) -> U,
    A: Array<Item = U>, 

impl<T> Same<T> for T

type Output = T

Should always be Self

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]

Performs the conversion.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>[src]

Performs the conversion.

impl<V, T> VZip<V> for T where
    V: MultiLane<T>, 

pub fn vzip(self) -> V