feat(util): add InspectErr, InspectFrame combinators (#161)

fixes #160.

the standard library has introduced conventions for combinators that
accept callbacks that "inspect" a value, upon being provided a reference
to a yielded value.

for example, `Result::inspect()` and `Result::inspect_err()` allow
callers to e.g. log an `Ok(_)` or `Err(_)` value. `Iterator::inspect()`
similarly allows callers to apply a layer of functionality to inspect
items as they are yielded by the inner iterator.

this commit introduces a pair of combinators to `http_body_util`, called
`InspectErr<B, F>` and `InspectFrame<B, F>`. these allow callers to
inspect errors and frames yielded by an inner body. these are
constructed by calling `BodyExt::inspect_err()` and
`BodyExt::inspect_frame()`, respectively.

Signed-off-by: katelyn martin <[email protected]>

Author: cratelyn

http-body-util/src/combinators/inspect_err.rs

@@ -0,0 +1,92 @@
+use http_body::{Body, Frame};
+use pin_project_lite::pin_project;
+use std::{
+    any::type_name,
+    fmt,
+    pin::Pin,
+    task::{Context, Poll},
+};
+
+pin_project! {
+    /// Body returned by the [`inspect_err()`] combinator.
+    ///
+    /// [`inspect_err()`]: crate::BodyExt::inspect_err
+    #[derive(Clone, Copy)]
+    pub struct InspectErr<B, F> {
+        #[pin]
+        inner: B,
+        f: F
+    }
+}
+
+impl<B, F> InspectErr<B, F> {
+    #[inline]
+    pub(crate) fn new(body: B, f: F) -> Self {
+        Self { inner: body, f }
+    }
+
+    /// Get a reference to the inner body
+    pub fn get_ref(&self) -> &B {
+        &self.inner
+    }
+
+    /// Get a mutable reference to the inner body
+    pub fn get_mut(&mut self) -> &mut B {
+        &mut self.inner
+    }
+
+    /// Get a pinned mutable reference to the inner body
+    pub fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut B> {
+        self.project().inner
+    }
+
+    /// Consume `self`, returning the inner body
+    pub fn into_inner(self) -> B {
+        self.inner
+    }
+}
+
+impl<B, F> Body for InspectErr<B, F>
+where
+    B: Body,
+    F: FnMut(&B::Error),
+{
+    type Data = B::Data;
+    type Error = B::Error;
+
+    fn poll_frame(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+    ) -> Poll<Option<Result<Frame<Self::Data>, Self::Error>>> {
+        let this = self.project();
+        match this.inner.poll_frame(cx) {
+            Poll::Pending => Poll::Pending,
+            Poll::Ready(None) => Poll::Ready(None),
+            Poll::Ready(Some(Ok(frame))) => Poll::Ready(Some(Ok(frame))),
+            Poll::Ready(Some(Err(err))) => {
+                (this.f)(&err);
+                Poll::Ready(Some(Err(err)))
+            }
+        }
+    }
+
+    fn size_hint(&self) -> http_body::SizeHint {
+        self.inner.size_hint()
+    }
+
+    fn is_end_stream(&self) -> bool {
+        self.inner.is_end_stream()
+    }
+}
+
+impl<B, F> fmt::Debug for InspectErr<B, F>
+where
+    B: fmt::Debug,
+{
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        f.debug_struct("InspectErr")
+            .field("inner", &self.inner)
+            .field("f", &type_name::<F>())
+            .finish()
+    }
+}

http-body-util/src/combinators/inspect_frame.rs

@@ -0,0 +1,92 @@
+use http_body::{Body, Frame};
+use pin_project_lite::pin_project;
+use std::{
+    any::type_name,
+    fmt,
+    pin::Pin,
+    task::{Context, Poll},
+};
+
+pin_project! {
+    /// Body returned by the [`inspect_frame()`] combinator.
+    ///
+    /// [`inspect_frame()`]: crate::BodyExt::inspect_frame
+    #[derive(Clone, Copy)]
+    pub struct InspectFrame<B, F> {
+        #[pin]
+        inner: B,
+        f: F
+    }
+}
+
+impl<B, F> InspectFrame<B, F> {
+    #[inline]
+    pub(crate) fn new(body: B, f: F) -> Self {
+        Self { inner: body, f }
+    }
+
+    /// Get a reference to the inner body
+    pub fn get_ref(&self) -> &B {
+        &self.inner
+    }
+
+    /// Get a mutable reference to the inner body
+    pub fn get_mut(&mut self) -> &mut B {
+        &mut self.inner
+    }
+
+    /// Get a pinned mutable reference to the inner body
+    pub fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut B> {
+        self.project().inner
+    }
+
+    /// Consume `self`, returning the inner body
+    pub fn into_inner(self) -> B {
+        self.inner
+    }
+}
+
+impl<B, F> Body for InspectFrame<B, F>
+where
+    B: Body,
+    F: FnMut(&Frame<B::Data>),
+{
+    type Data = B::Data;
+    type Error = B::Error;
+
+    fn poll_frame(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+    ) -> Poll<Option<Result<Frame<Self::Data>, Self::Error>>> {
+        let this = self.project();
+        match this.inner.poll_frame(cx) {
+            Poll::Pending => Poll::Pending,
+            Poll::Ready(None) => Poll::Ready(None),
+            Poll::Ready(Some(Err(err))) => Poll::Ready(Some(Err(err))),
+            Poll::Ready(Some(Ok(frame))) => {
+                (this.f)(&frame);
+                Poll::Ready(Some(Ok(frame)))
+            }
+        }
+    }
+
+    fn size_hint(&self) -> http_body::SizeHint {
+        self.inner.size_hint()
+    }
+
+    fn is_end_stream(&self) -> bool {
+        self.inner.is_end_stream()
+    }
+}
+
+impl<B, F> fmt::Debug for InspectFrame<B, F>
+where
+    B: fmt::Debug,
+{
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        f.debug_struct("InspectFrame")
+            .field("inner", &self.inner)
+            .field("f", &type_name::<F>())
+            .finish()
+    }
+}

http-body-util/src/combinators/mod.rs

@@ -4,6 +4,8 @@ mod box_body;
 mod collect;
 mod frame;
 mod fuse;
+mod inspect_err;
+mod inspect_frame;
 mod map_err;
 mod map_frame;
 mod with_trailers;
@@ -13,6 +15,8 @@ pub use self::{
     collect::Collect,
     frame::Frame,
     fuse::Fuse,
+    inspect_err::InspectErr,
+    inspect_frame::InspectFrame,
     map_err::MapErr,
     map_frame::MapFrame,
     with_trailers::WithTrailers,

http-body-util/src/lib.rs

@@ -55,6 +55,15 @@ pub trait BodyExt: http_body::Body {
         MapFrame::new(self, f)
     }
 
+    /// A body that calls a function with a reference to each frame before yielding it.
+    fn inspect_frame<F>(self, f: F) -> combinators::InspectFrame<Self, F>
+    where
+        Self: Sized,
+        F: FnMut(&http_body::Frame<Self::Data>),
+    {
+        combinators::InspectFrame::new(self, f)
+    }
+
     /// Maps this body's error value to a different value.
     fn map_err<F, E>(self, f: F) -> MapErr<Self, F>
     where
@@ -64,6 +73,15 @@ pub trait BodyExt: http_body::Body {
         MapErr::new(self, f)
     }
 
+    /// A body that calls a function with a reference to an error before yielding it.
+    fn inspect_err<F>(self, f: F) -> combinators::InspectErr<Self, F>
+    where
+        Self: Sized,
+        F: FnMut(&Self::Error),
+    {
+        combinators::InspectErr::new(self, f)
+    }
+
     /// Turn this body into a boxed trait object.
     fn boxed(self) -> BoxBody<Self::Data, Self::Error>
     where