util: unify and rename combinators (#499)

Currently, the `ServiceExt` trait has `with` and `try_with` methods for
composing a `Service` with functions that modify the request type, and
`map_err` and `map_ok` methods for composing a service with functions
that modify the response type. Meanwhile, `ServiceBuilder` has
`map_request` for composing a service with a request mapping function,
and `map_response` for composing a service with a response-mapping
function. These combinators are very similar in purpose, but are
implemented using different middleware types that essentially duplicate
the same behavior.

Before releasing 0.4, we should probably unify these APIs. In
particular, it would be good to de-duplicate the middleware service
types, and to unify the naming.

This commit makes the following changes:
- Rename the `ServiceExt::with` and `ServiceExt::try_with` combinators
  to `map_request` and `try_map_request`
  - Rename the `ServiceExt::map_ok` combinator to `map_response`
- Unify the `ServiceBuilder::map_request` and `ServiceExt::map_request`
  combinators to use the same `Service` type
- Unify the `ServiceBuilder::map_response` and
  `ServiceExt::map_response` combinators to use the same `Service` type
- Unify the `ServiceBuilder::map_err` and `ServiceExt::map_err`
  combinators to use the same `Service` type
- Only take `FnOnce + Clone` when in response/err combinators, which
  require cloning into the future type. `MapRequest` and `TryMapRequest`
  now take `FnMut(Request)`s and don't clone them every time they're
  called
- Reexport future types for combinators where it makes sense.
- Add a `try_map_request` method to `ServiceBuilder`

Closes #498

Signed-off-by: Eliza Weisman <[email protected]>

Author: hawkw

tower/src/builder/mod.rs

@@ -197,11 +197,23 @@ impl<L> ServiceBuilder<L> {
         f: F,
     ) -> ServiceBuilder<Stack<crate::util::MapRequestLayer<F>, L>>
     where
-        F: Fn(R1) -> R2,
+        F: FnMut(R1) -> R2 + Clone,
     {
         self.layer(crate::util::MapRequestLayer::new(f))
     }
 
+    /// Fallibly one request type to another, or to an error.
+    #[cfg(feature = "util")]
+    pub fn try_map_request<F, R1, R2, E>(
+        self,
+        f: F,
+    ) -> ServiceBuilder<Stack<crate::util::TryMapRequestLayer<F>, L>>
+    where
+        F: FnMut(R1) -> Result<R2, E> + Clone,
+    {
+        self.layer(crate::util::TryMapRequestLayer::new(f))
+    }
+
     /// Map one response type to another.
     #[cfg(feature = "util")]
     pub fn map_response<F>(
@@ -211,6 +223,12 @@ impl<L> ServiceBuilder<L> {
         self.layer(crate::util::MapResponseLayer::new(f))
     }
 
+    /// Map one error type to another.
+    #[cfg(feature = "util")]
+    pub fn map_err<F>(self, f: F) -> ServiceBuilder<Stack<crate::util::MapErrLayer<F>, L>> {
+        self.layer(crate::util::MapErrLayer::new(f))
+    }
+
     /// Obtains the underlying `Layer` implementation.
     pub fn into_inner(self) -> L {
         self.layer

tower/src/util/map/mod.rs

@@ -1,8 +1,11 @@
-use futures_util::{future::MapErr as MapErrFut, TryFutureExt};
+use futures_util::TryFutureExt;
 use std::task::{Context, Poll};
 use tower_layer::Layer;
 use tower_service::Service;
 
+#[allow(unreachable_pub)] // https://github.com/rust-lang/rust/issues/57411
+pub use futures_util::future::MapErr as MapErrFuture;
+
 /// Service returned by the [`map_err`] combinator.
 ///
 /// [`map_err`]: crate::util::ServiceExt::map_err
@@ -12,6 +15,14 @@ pub struct MapErr<S, F> {
     f: F,
 }
 
+/// A [`Layer`] that produces a [`MapErr`] service.
+///
+/// [`Layer`]: tower_layer::Layer
+#[derive(Debug)]
+pub struct MapErrLayer<F> {
+    f: F,
+}
+
 impl<S, F> MapErr<S, F> {
     /// Creates a new [`MapErr`] service.
     pub fn new(inner: S, f: F) -> Self {
@@ -26,25 +37,19 @@ where
 {
     type Response = S::Response;
     type Error = Error;
-    type Future = MapErrFut<S::Future, F>;
+    type Future = MapErrFuture<S::Future, F>;
 
+    #[inline]
     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
         self.inner.poll_ready(cx).map_err(self.f.clone())
     }
 
+    #[inline]
     fn call(&mut self, request: Request) -> Self::Future {
         self.inner.call(request).map_err(self.f.clone())
     }
 }
 
-/// A [`Layer`] that produces a [`MapErr`] service.
-///
-/// [`Layer`]: tower_layer::Layer
-#[derive(Debug)]
-pub struct MapErrLayer<F> {
-    f: F,
-}
-
 impl<F> MapErrLayer<F> {
     /// Creates a new [`MapErrLayer`].
     pub fn new(f: F) -> Self {