pub trait MessageBody {
    type Error: Into<Box<dyn Error, Global>>;

    // Required methods
    fn size(&self) -> BodySize;
    fn poll_next(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>
    ) -> Poll<Option<Result<Bytes, Self::Error>>>;

    // Provided methods
    fn try_into_bytes(self) -> Result<Bytes, Self>
       where Self: Sized { ... }
    fn boxed(self) -> BoxBody
       where Self: Sized + 'static { ... }
}
Expand description

An interface for types that can be used as a response body.

It is not usually necessary to create custom body types, this trait is already implemented for a large number of sensible body types including:

Examples

struct Repeat {
    chunk: String,
    n_times: usize,
}

impl MessageBody for Repeat {
    type Error = Infallible;

    fn size(&self) -> BodySize {
        BodySize::Sized((self.chunk.len() * self.n_times) as u64)
    }

    fn poll_next(
        self: Pin<&mut Self>,
        _cx: &mut Context<'_>,
    ) -> Poll<Option<Result<Bytes, Self::Error>>> {
        let payload_string = self.chunk.repeat(self.n_times);
        let payload_bytes = Bytes::from(payload_string);
        Poll::Ready(Some(Ok(payload_bytes)))
    }
}

Required Associated Types§

source

type Error: Into<Box<dyn Error, Global>>

The type of error that will be returned if streaming body fails.

Since it is not appropriate to generate a response mid-stream, it only requires Error for internal use and logging.

Required Methods§

source

fn size(&self) -> BodySize

Body size hint.

If BodySize::None is returned, optimizations that skip reading the body are allowed.

source

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

Attempt to pull out the next chunk of body bytes.

Return Value

Similar to the Stream interface, there are several possible return values, each indicating a distinct state:

  • Poll::Pending means that this body’s next chunk is not ready yet. Implementations must ensure that the current task will be notified when the next chunk may be ready.
  • Poll::Ready(Some(val)) means that the body has successfully produced a chunk, val, and may produce further values on subsequent poll_next calls.
  • Poll::Ready(None) means that the body is complete, and poll_next should not be invoked again.
Panics

Once a body is complete (i.e., poll_next returned Ready(None)), calling its poll_next method again may panic, block forever, or cause other kinds of problems; this trait places no requirements on the effects of such a call. However, as the poll_next method is not marked unsafe, Rust’s usual rules apply: calls must never cause UB, regardless of its state.

Provided Methods§

source

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

Try to convert into the complete chunk of body bytes.

Override this method if the complete body can be trivially extracted. This is useful for optimizations where poll_next calls can be avoided.

Body types with BodySize::None are allowed to return empty Bytes. Although, if calling this method, it is recommended to check size first and return early.

Errors

The default implementation will error and return the original type back to the caller for further use.

source

fn boxed(self) -> BoxBodywhere Self: Sized + 'static,

Wraps this body into a BoxBody.

No-op when called on a BoxBody, meaning there is no risk of double boxing when calling this on a generic MessageBody. Prefer this over BoxBody::new when a boxed body is required.

Implementations on Foreign Types§

source§

impl MessageBody for Infallible

source§

impl<B> MessageBody for &mut Bwhere B: MessageBody + Unpin + ?Sized,

§

type Error = <B as MessageBody>::Error

source§

fn size(&self) -> BodySize

source§

fn poll_next( self: Pin<&mut &mut B>, cx: &mut Context<'_> ) -> Poll<Option<Result<Bytes, <&mut B as MessageBody>::Error>>>

source§

impl<T, B> MessageBody for Pin<T>where T: DerefMut<Target = B> + Unpin, B: MessageBody + ?Sized,

§

type Error = <B as MessageBody>::Error

source§

fn size(&self) -> BodySize

source§

fn poll_next( self: Pin<&mut Pin<T>>, cx: &mut Context<'_> ) -> Poll<Option<Result<Bytes, <Pin<T> as MessageBody>::Error>>>

source§

impl MessageBody for ()

§

type Error = Infallible

source§

fn size(&self) -> BodySize

source§

fn poll_next( self: Pin<&mut ()>, _cx: &mut Context<'_> ) -> Poll<Option<Result<Bytes, <() as MessageBody>::Error>>>

source§

fn try_into_bytes(self) -> Result<Bytes, ()>

source§

impl MessageBody for &'static [u8]

§

type Error = Infallible

source§

fn size(&self) -> BodySize

source§

fn poll_next( self: Pin<&mut &'static [u8]>, _cx: &mut Context<'_> ) -> Poll<Option<Result<Bytes, <&'static [u8] as MessageBody>::Error>>>

source§

fn try_into_bytes(self) -> Result<Bytes, &'static [u8]>

source§

impl MessageBody for Vec<u8, Global>

source§

impl MessageBody for Cow<'static, str>

§

type Error = Infallible

source§

fn size(&self) -> BodySize

source§

fn poll_next( self: Pin<&mut Cow<'static, str>>, _cx: &mut Context<'_> ) -> Poll<Option<Result<Bytes, <Cow<'static, str> as MessageBody>::Error>>>

source§

fn try_into_bytes(self) -> Result<Bytes, Cow<'static, str>>

source§

impl MessageBody for &'static str

§

type Error = Infallible

source§

fn size(&self) -> BodySize

source§

fn poll_next( self: Pin<&mut &'static str>, _cx: &mut Context<'_> ) -> Poll<Option<Result<Bytes, <&'static str as MessageBody>::Error>>>

source§

fn try_into_bytes(self) -> Result<Bytes, &'static str>

source§

impl MessageBody for ByteString

source§

impl MessageBody for String

source§

impl<B> MessageBody for Box<B, Global>where B: MessageBody + Unpin + ?Sized,

§

type Error = <B as MessageBody>::Error

source§

fn size(&self) -> BodySize

source§

fn poll_next( self: Pin<&mut Box<B, Global>>, cx: &mut Context<'_> ) -> Poll<Option<Result<Bytes, <Box<B, Global> as MessageBody>::Error>>>

source§

impl MessageBody for Cow<'static, [u8]>

§

type Error = Infallible

source§

fn size(&self) -> BodySize

source§

fn poll_next( self: Pin<&mut Cow<'static, [u8]>>, _cx: &mut Context<'_> ) -> Poll<Option<Result<Bytes, <Cow<'static, [u8]> as MessageBody>::Error>>>

source§

fn try_into_bytes(self) -> Result<Bytes, Cow<'static, [u8]>>

Implementors§

source§

impl MessageBody for Bytes

source§

impl MessageBody for BytesMut

source§

impl MessageBody for BoxBody

§

type Error = Box<dyn Error, Global>

source§

impl MessageBody for None

source§

impl<B> MessageBody for Encoder<B>where B: MessageBody,

§

type Error = EncoderError

source§

impl<L, R> MessageBody for EitherBody<L, R>where L: MessageBody + 'static, R: MessageBody + 'static,

§

type Error = Error

source§

impl<S, E> MessageBody for BodyStream<S>where S: Stream<Item = Result<Bytes, E>>, E: Into<Box<dyn Error, Global>> + 'static,

§

type Error = E

source§

impl<S, E> MessageBody for SizedStream<S>where S: Stream<Item = Result<Bytes, E>>, E: Into<Box<dyn Error, Global>> + 'static,

§

type Error = E