Trait actix_http::body::MessageBody

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

    // 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 { ... }
}

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:

• Empty body: ()
• Text-based: String, &'static str, ByteString.
• Byte-based: Bytes, BytesMut, Vec<u8>, &'static [u8];
• Streams: BodyStream, SizedStream

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

type Error: Into<Box<dyn StdError>>

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

fn size(&self) -> BodySize

Body size hint.

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

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

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.

fn boxed(self) -> BoxBody

where 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

impl MessageBody for &'static str

type Error = Infallible

fn size(&self) -> BodySize

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

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

impl MessageBody for &'static [u8]

type Error = Infallible

fn size(&self) -> BodySize

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

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

impl MessageBody for Cow<'static, str>

type Error = Infallible

fn size(&self) -> BodySize

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

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

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

type Error = Infallible

fn size(&self) -> BodySize

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

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

impl MessageBody for Infallible

type Error = Infallible

fn size(&self) -> BodySize

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

impl MessageBody for ()

type Error = Infallible

fn size(&self) -> BodySize

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

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

impl MessageBody for String

type Error = Infallible

fn size(&self) -> BodySize

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

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

impl MessageBody for Vec<u8>

type Error = Infallible

fn size(&self) -> BodySize

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

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

impl MessageBody for Bytes

type Error = Infallible

fn size(&self) -> BodySize

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

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

impl MessageBody for BytesMut

type Error = Infallible

fn size(&self) -> BodySize

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

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

impl MessageBody for ByteString

type Error = Infallible

fn size(&self) -> BodySize

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

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

impl<B> MessageBody for &mut B

where B: MessageBody + Unpin + ?Sized,

type Error = <B as MessageBody>::Error

fn size(&self) -> BodySize

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

impl<B> MessageBody for Box<B>

where B: MessageBody + Unpin + ?Sized,

type Error = <B as MessageBody>::Error

fn size(&self) -> BodySize

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

impl<T, B> MessageBody for Pin<T>

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

type Error = <B as MessageBody>::Error

fn size(&self) -> BodySize

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

Implementors

impl MessageBody for BoxBody

type Error = Box<dyn Error>

impl MessageBody for None

type Error = Infallible

impl<B> MessageBody for Encoder<B>

where B: MessageBody,

Available on crate feature __compress only.

type Error = EncoderError

impl<L, R> MessageBody for EitherBody<L, R>

where L: MessageBody + 'static, R: MessageBody + 'static,

type Error = Error

impl<S, E> MessageBody for BodyStream<S>

where S: Stream<Item = Result<Bytes, E>>, E: Into<Box<dyn StdError>> + 'static,

type Error = E

impl<S, E> MessageBody for SizedStream<S>

where S: Stream<Item = Result<Bytes, E>>, E: Into<Box<dyn StdError>> + 'static,

type Error = E