pub trait MessageBody {
type Error: Into<Box<dyn Error>>;
// 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:
- 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§
Required Methods§
sourcefn size(&self) -> BodySize
fn size(&self) -> BodySize
Body size hint.
If BodySize::None is returned, optimizations that skip reading the body are allowed.
sourcefn poll_next(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
) -> Poll<Option<Result<Bytes, Self::Error>>>
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::Pendingmeans 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 subsequentpoll_nextcalls.Poll::Ready(None)means that the body is complete, andpoll_nextshould 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§
sourcefn try_into_bytes(self) -> Result<Bytes, Self>where
Self: Sized,
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.
sourcefn boxed(self) -> BoxBodywhere
Self: Sized + 'static,
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.