Struct trillium_http::ReceivedBody

source ·
pub struct ReceivedBody<'conn, Transport> { /* private fields */ }
Expand description

A received http body

This type represents a body that will be read from the underlying transport, which it may either borrow from a Conn or own.

let mut conn = Conn::new_synthetic(Method::Get, "/", "hello");
let body = conn.request_body().await;
assert_eq!(body.read_string().await?, "hello");

§Bounds checking

Every ReceivedBody has a maximum length beyond which it will return an error, expressed as a u64. To override this on the specific ReceivedBody, use ReceivedBody::with_max_len or ReceivedBody::set_max_len

The default maximum length is currently set to 500mb. In the next semver-minor release, this value will decrease substantially.

§Large chunks, small read buffers

Attempting to read a chunked body with a buffer that is shorter than the chunk size in hex will result in an error. This limitation is temporary.

Implementations§

source§

impl<'conn, Transport> ReceivedBody<'conn, Transport>
where Transport: AsyncRead + Unpin + Send + Sync + 'static,

source

pub fn content_length(&self) -> Option<u64>

Returns the content-length of this body, if available. This usually is derived from the content-length header. If the http request or response that this body is attached to uses transfer-encoding chunked, this will be None.

let mut conn = Conn::new_synthetic(Method::Get, "/", "hello");
let body = conn.request_body().await;
assert_eq!(body.content_length(), Some(5));
source

pub async fn read_string(self) -> Result<String>

§Reads entire body to String.

This uses the encoding determined by the content-type (mime) charset. If an encoding problem is encountered, the String returned by ReceivedBody::read_string will contain utf8 replacement characters.

Note that this can only be performed once per Conn, as the underlying data is not cached anywhere. This is the only copy of the body contents.

§Errors

This will return an error if there is an IO error on the underlying transport such as a disconnect

This will also return an error if the length exceeds the maximum length. To override this value on this specific body, use ReceivedBody::with_max_len or ReceivedBody::set_max_len

source

pub fn set_max_len(&mut self, max_len: u64)

Set the maximum length that can be read from this body before error

See also HttpConfig::received_body_max_len

source

pub fn with_max_len(self, max_len: u64) -> Self

chainable setter for the maximum length that can be read from this body before error

See also HttpConfig::received_body_max_len

source

pub async fn read_bytes(self) -> Result<Vec<u8>>

Similar to ReceivedBody::read_string, but returns the raw bytes. This is useful for bodies that are not text.

You can use this in conjunction with encoding if you need different handling of malformed character encoding than the lossy conversion provided by ReceivedBody::read_string.

§Errors

This will return an error if there is an IO error on the underlying transport such as a disconnect

This will also return an error if the length exceeds received_body_max_len. To override this value on this specific body, use ReceivedBody::with_max_len or ReceivedBody::set_max_len

source

pub fn encoding(&self) -> &'static Encoding

returns the character encoding of this body, usually determined from the content type (mime-type) of the associated Conn.

source

pub async fn drain(self) -> Result<u64>

Consumes the remainder of this body from the underlying transport by reading it to the end and discarding the contents. This is important for http1.1 keepalive, but most of the time you do not need to directly call this. It returns the number of bytes consumed.

§Errors

This will return an std::io::Result::Err if there is an io error on the underlying transport, such as a disconnect

source§

impl<T> ReceivedBody<'static, T>

source

pub fn take_transport(&mut self) -> Option<T>

takes the static transport from this received body

Trait Implementations§

source§

impl<'conn, Transport> AsyncRead for ReceivedBody<'conn, Transport>
where Transport: AsyncRead + Unpin + Send + Sync + 'static,

source§

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

Attempt to read from the AsyncRead into buf. Read more
§

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize, Error>>

Attempt to read from the AsyncRead into bufs using vectored IO operations. Read more
source§

impl<'conn, Transport> Debug for ReceivedBody<'conn, Transport>

source§

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

Formats the value using the given formatter. Read more
source§

impl<Transport> From<ReceivedBody<'static, Transport>> for Body
where Transport: AsyncRead + AsyncWrite + Send + Sync + Unpin + 'static,

source§

fn from(rb: ReceivedBody<'static, Transport>) -> Self

Converts to this type from the input type.
source§

impl<'a, Transport> IntoFuture for ReceivedBody<'a, Transport>
where Transport: AsyncRead + Unpin + Send + Sync + 'static,

§

type Output = Result<String, Error>

The output that the future will produce on completion.
§

type IntoFuture = Pin<Box<dyn Future<Output = <ReceivedBody<'a, Transport> as IntoFuture>::Output> + Send + 'a>>

Which kind of future are we turning this into?
source§

fn into_future(self) -> Self::IntoFuture

Creates a future from a value. Read more
source§

impl<'conn, Transport> Stream for ReceivedBody<'conn, Transport>
where Transport: AsyncRead + Unpin + Send + Sync + 'static,

§

type Item = Vec<u8>

Values yielded by the stream.
source§

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted. Read more
§

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream. Read more

Auto Trait Implementations§

§

impl<'conn, Transport> Freeze for ReceivedBody<'conn, Transport>
where Transport: Freeze,

§

impl<'conn, Transport> !RefUnwindSafe for ReceivedBody<'conn, Transport>

§

impl<'conn, Transport> Send for ReceivedBody<'conn, Transport>
where Transport: Send,

§

impl<'conn, Transport> Sync for ReceivedBody<'conn, Transport>
where Transport: Sync,

§

impl<'conn, Transport> Unpin for ReceivedBody<'conn, Transport>
where Transport: Unpin,

§

impl<'conn, Transport> !UnwindSafe for ReceivedBody<'conn, Transport>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<R> AsyncReadExt for R
where R: AsyncRead + ?Sized,

§

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

Reads some bytes from the byte stream. Read more
§

fn read_vectored<'a>( &'a mut self, bufs: &'a mut [IoSliceMut<'a>], ) -> ReadVectoredFuture<'a, Self>
where Self: Unpin,

Like [read()][AsyncReadExt::read()], except it reads into a slice of buffers. Read more
§

fn read_to_end<'a>( &'a mut self, buf: &'a mut Vec<u8>, ) -> ReadToEndFuture<'a, Self>
where Self: Unpin,

Reads the entire contents and appends them to a Vec. Read more
§

fn read_to_string<'a>( &'a mut self, buf: &'a mut String, ) -> ReadToStringFuture<'a, Self>
where Self: Unpin,

Reads the entire contents and appends them to a String. Read more
§

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

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

fn take(self, limit: u64) -> Take<Self>
where Self: Sized,

Creates an adapter which will read at most limit bytes from it. Read more
§

fn bytes(self) -> Bytes<Self>
where Self: Sized,

Converts this [AsyncRead] into a [Stream] of bytes. Read more
§

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

Creates an adapter which will chain this stream with another. Read more
§

fn boxed_reader<'a>(self) -> Pin<Box<dyn AsyncRead + Send + 'a>>
where Self: Sized + Send + 'a,

Boxes the reader and changes its type to dyn AsyncRead + Send + 'a. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<S> StreamExt for S
where S: Stream + ?Sized,

§

fn poll_next(&mut self, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>
where Self: Unpin,

A convenience for calling [Stream::poll_next()] on !Unpin types.
§

fn next(&mut self) -> NextFuture<'_, Self>
where Self: Unpin,

Retrieves the next item in the stream. Read more
§

fn try_next<T, E>(&mut self) -> TryNextFuture<'_, Self>
where Self: Stream<Item = Result<T, E>> + Unpin,

Retrieves the next item in the stream. Read more
§

fn count(self) -> CountFuture<Self>
where Self: Sized,

Counts the number of items in the stream. Read more
§

fn map<T, F>(self, f: F) -> Map<Self, F>
where Self: Sized, F: FnMut(Self::Item) -> T,

Maps items of the stream to new values using a closure. Read more
§

fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F>
where Self: Sized, U: Stream, F: FnMut(Self::Item) -> U,

Maps items to streams and then concatenates them. Read more
§

fn flatten(self) -> Flatten<Self>
where Self: Sized, Self::Item: Stream,

Concatenates inner streams. Read more
§

fn then<F, Fut>(self, f: F) -> Then<Self, F, Fut>
where Self: Sized, F: FnMut(Self::Item) -> Fut, Fut: Future,

Maps items of the stream to new values using an async closure. Read more
§

fn filter<P>(self, predicate: P) -> Filter<Self, P>
where Self: Sized, P: FnMut(&Self::Item) -> bool,

Keeps items of the stream for which predicate returns true. Read more
§

fn filter_map<T, F>(self, f: F) -> FilterMap<Self, F>
where Self: Sized, F: FnMut(Self::Item) -> Option<T>,

Filters and maps items of the stream using a closure. Read more
§

fn take(self, n: usize) -> Take<Self>
where Self: Sized,

Takes only the first n items of the stream. Read more
§

fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P>
where Self: Sized, P: FnMut(&Self::Item) -> bool,

Takes items while predicate returns true. Read more
§

fn skip(self, n: usize) -> Skip<Self>
where Self: Sized,

Skips the first n items of the stream. Read more
§

fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P>
where Self: Sized, P: FnMut(&Self::Item) -> bool,

Skips items while predicate returns true. Read more
§

fn step_by(self, step: usize) -> StepBy<Self>
where Self: Sized,

Yields every stepth item. Read more
§

fn chain<U>(self, other: U) -> Chain<Self, U>
where Self: Sized, U: Stream<Item = Self::Item>,

Appends another stream to the end of this one. Read more
§

fn cloned<'a, T>(self) -> Cloned<Self>
where Self: Sized + Stream<Item = &'a T>, T: Clone + 'a,

Clones all items. Read more
§

fn copied<'a, T>(self) -> Copied<Self>
where Self: Sized + Stream<Item = &'a T>, T: Copy + 'a,

Copies all items. Read more
§

fn collect<C>(self) -> CollectFuture<Self, C>
where Self: Sized, C: Default + Extend<Self::Item>,

Collects all items in the stream into a collection. Read more
§

fn try_collect<T, E, C>(self) -> TryCollectFuture<Self, C>
where Self: Sized + Stream<Item = Result<T, E>>, C: Default + Extend<T>,

Collects all items in the fallible stream into a collection. Read more
§

fn partition<B, P>(self, predicate: P) -> PartitionFuture<Self, P, B>
where Self: Sized, B: Default + Extend<Self::Item>, P: FnMut(&Self::Item) -> bool,

Partitions items into those for which predicate is true and those for which it is false, and then collects them into two collections. Read more
§

fn fold<T, F>(self, init: T, f: F) -> FoldFuture<Self, F, T>
where Self: Sized, F: FnMut(T, Self::Item) -> T,

Accumulates a computation over the stream. Read more
§

fn try_fold<T, E, F, B>( &mut self, init: B, f: F, ) -> TryFoldFuture<'_, Self, F, B>
where Self: Sized + Stream<Item = Result<T, E>> + Unpin, F: FnMut(B, T) -> Result<B, E>,

Accumulates a fallible computation over the stream. Read more
§

fn scan<St, B, F>(self, initial_state: St, f: F) -> Scan<Self, St, F>
where Self: Sized, F: FnMut(&mut St, Self::Item) -> Option<B>,

Maps items of the stream to new values using a state value and a closure. Read more
§

fn fuse(self) -> Fuse<Self>
where Self: Sized,

Fuses the stream so that it stops yielding items after the first None. Read more
§

fn cycle(self) -> Cycle<Self>
where Self: Sized + Clone,

Repeats the stream from beginning to end, forever. Read more
§

fn enumerate(self) -> Enumerate<Self>
where Self: Sized,

Enumerates items, mapping them to (index, item). Read more
§

fn inspect<F>(self, f: F) -> Inspect<Self, F>
where Self: Sized, F: FnMut(&Self::Item),

Calls a closure on each item and passes it on. Read more
§

fn nth(&mut self, n: usize) -> NthFuture<'_, Self>
where Self: Unpin,

Gets the nth item of the stream. Read more
§

fn last(self) -> LastFuture<Self>
where Self: Sized,

Returns the last item in the stream. Read more
§

fn find<P>(&mut self, predicate: P) -> FindFuture<'_, Self, P>
where Self: Unpin, P: FnMut(&Self::Item) -> bool,

Finds the first item of the stream for which predicate returns true. Read more
§

fn find_map<F, B>(&mut self, f: F) -> FindMapFuture<'_, Self, F>
where Self: Unpin, F: FnMut(Self::Item) -> Option<B>,

Applies a closure to items in the stream and returns the first Some result. Read more
§

fn position<P>(&mut self, predicate: P) -> PositionFuture<'_, Self, P>
where Self: Unpin, P: FnMut(Self::Item) -> bool,

Finds the index of the first item of the stream for which predicate returns true. Read more
§

fn all<P>(&mut self, predicate: P) -> AllFuture<'_, Self, P>
where Self: Unpin, P: FnMut(Self::Item) -> bool,

Tests if predicate returns true for all items in the stream. Read more
§

fn any<P>(&mut self, predicate: P) -> AnyFuture<'_, Self, P>
where Self: Unpin, P: FnMut(Self::Item) -> bool,

Tests if predicate returns true for any item in the stream. Read more
§

fn for_each<F>(self, f: F) -> ForEachFuture<Self, F>
where Self: Sized, F: FnMut(Self::Item),

Calls a closure on each item of the stream. Read more
§

fn try_for_each<F, E>(&mut self, f: F) -> TryForEachFuture<'_, Self, F>
where Self: Unpin, F: FnMut(Self::Item) -> Result<(), E>,

Calls a fallible closure on each item of the stream, stopping on first error. Read more
§

fn zip<U>(self, other: U) -> Zip<Self, U>
where Self: Sized, U: Stream,

Zips up two streams into a single stream of pairs. Read more
§

fn unzip<A, B, FromA, FromB>(self) -> UnzipFuture<Self, FromA, FromB>
where FromA: Default + Extend<A>, FromB: Default + Extend<B>, Self: Sized + Stream<Item = (A, B)>,

Collects a stream of pairs into a pair of collections. Read more
§

fn or<S>(self, other: S) -> Or<Self, S>
where Self: Sized, S: Stream<Item = Self::Item>,

Merges with other stream, preferring items from self whenever both streams are ready. Read more
§

fn race<S>(self, other: S) -> Race<Self, S>
where Self: Sized, S: Stream<Item = Self::Item>,

Merges with other stream, with no preference for either stream when both are ready. Read more
§

fn drain(&mut self) -> Drain<'_, Self>

Yields all immediately available values from a stream. Read more
§

fn boxed<'a>(self) -> Pin<Box<dyn Stream<Item = Self::Item> + Send + 'a>>
where Self: Sized + Send + 'a,

Boxes the stream and changes its type to dyn Stream + Send + 'a. Read more
§

fn boxed_local<'a>(self) -> Pin<Box<dyn Stream<Item = Self::Item> + 'a>>
where Self: Sized + 'a,

Boxes the stream and changes its type to dyn Stream + 'a. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

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

The type returned in the event of a conversion error.
source§

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

Performs the conversion.