logo

Trait actix_web::body::MessageBody

source · [−]
pub trait MessageBody {
    type Error: Into<Box<dyn Error + 'static, Global>>;
    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> { ... }

    fn boxed(self) -> BoxBody
    where
        Self: '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)))
    }
}

Associated Types

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

Body size hint.

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

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

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.

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

Implementors