From 686958fe0c11112e412e3e6fc918b4284fb28e8c Mon Sep 17 00:00:00 2001
From: Marcus Griep <marcus@griep.us>
Date: Thu, 2 May 2019 17:21:42 -0400
Subject: [PATCH 1/3] Add reciprical compatibility layer for tower

---
 actix-tower/src/lib.rs | 387 +++++++++++++++++++++++++++++------------
 1 file changed, 275 insertions(+), 112 deletions(-)

diff --git a/actix-tower/src/lib.rs b/actix-tower/src/lib.rs
index 1e985db2..a57dad0f 100644
--- a/actix-tower/src/lib.rs
+++ b/actix-tower/src/lib.rs
@@ -6,40 +6,40 @@ use tower_service::Service as TowerService;
 
 /// Compatibility wrapper associating a `tower_service::Service` with a particular
 /// `Request` type, so that it can be used as an `actix_service::Service`.
-pub struct TowerCompat<S, R> {
+pub struct ActixCompat<S, R> {
     inner: S,
     _phantom: PhantomData<R>,
 }
 
-impl<S, R> TowerCompat<S, R> {
+impl<S, R> ActixCompat<S, R> {
     /// Wraps a `tower_service::Service` in a compatibility wrapper.
     pub fn new(inner: S) -> Self {
-        TowerCompat {
+        ActixCompat {
             inner,
             _phantom: PhantomData,
         }
     }
 }
 
-/// Extension trait for wrapping `tower_service::Service` instances for use as
+/// Extension trait for wrapping a `tower_service::Service` instance for use as
 /// an `actix_service::Service`.
 pub trait TowerServiceExt {
     /// Wraps a `tower_service::Service` in a compatibility wrapper.
-    fn compat<R>(self) -> TowerCompat<Self, R>
+    fn into_actix_service<R>(self) -> ActixCompat<Self, R>
     where
         Self: TowerService<R> + Sized;
 }
 
 impl<S> TowerServiceExt for S {
-    fn compat<R>(self) -> TowerCompat<Self, R>
+    fn into_actix_service<R>(self) -> ActixCompat<Self, R>
     where
         Self: TowerService<R> + Sized
     {
-        TowerCompat::new(self)
+        ActixCompat::new(self)
     }
 }
 
-impl<S, R> ActixService for TowerCompat<S, R>
+impl<S, R> ActixService for ActixCompat<S, R>
 where
     S: TowerService<R>,
 {
@@ -57,135 +57,298 @@ where
     }
 }
 
+/// Compatibility wrapper associating an `actix_service::Service` with a particular
+/// `Request` type, so that it can be used as a `tower_service::Service`.
+pub struct TowerCompat<S> {
+    inner: S,
+}
+
+impl<S> TowerCompat<S> {
+    /// Wraps an `actix_service::Service` in a compatibility wrapper.
+    pub fn new(inner: S) -> Self {
+        TowerCompat {
+            inner,
+        }
+    }
+}
+
+/// Extension trait for wrapping an `actix_service::Service` instance for use as
+/// a `tower_service::Service`.
+pub trait ActixServiceExt: ActixService + Sized {
+    /// Wraps a `tower_service::Service` in a compatibility wrapper.
+    fn into_tower_service(self) -> TowerCompat<Self>;
+}
+
+impl<S> ActixServiceExt for S
+where
+    S: ActixService + Sized
+{
+    fn into_tower_service(self) -> TowerCompat<Self>
+    {
+        TowerCompat::new(self)
+    }
+}
+
+impl<S> TowerService<S::Request> for TowerCompat<S>
+where
+    S: ActixService,
+{
+    type Response = S::Response;
+    type Error = S::Error;
+    type Future = S::Future;
+
+    fn poll_ready(&mut self) -> futures::Poll<(), Self::Error> {
+        ActixService::poll_ready(&mut self.inner)
+    }
+
+    fn call(&mut self, req: S::Request) -> Self::Future {
+        ActixService::call(&mut self.inner, req)
+    }
+}
+
 #[cfg(test)]
 mod tests {
-    use super::TowerServiceExt;
-    use actix_service::{Service as ActixService, ServiceExt, Transform};
-    use futures::{future::FutureResult, Async, Poll, Future};
-    use tower_service::Service as TowerService;
+    mod tower_service_into_actix_service {
+        use crate::TowerServiceExt;
+        use actix_service::{Service as ActixService, ServiceExt, Transform};
+        use futures::{future::FutureResult, Async, Poll, Future};
+        use tower_service::Service as TowerService;
 
-    struct RandomService;
-    impl<R> TowerService<R> for RandomService {
-        type Response = u32;
-        type Error = ();
-        type Future = FutureResult<Self::Response, Self::Error>;
 
-        fn poll_ready(&mut self) -> Poll<(), Self::Error> {
-            Ok(Async::Ready(()))
+        #[test]
+        fn random_service_returns_4() {
+            let mut s = RandomService.into_actix_service();
+
+            assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+
+            assert_eq!(Ok(Async::Ready(4)), s.call(()).poll());
         }
 
-        fn call(&mut self, _req: R) -> Self::Future {
-            futures::finished(4)
+        #[test]
+        fn random_service_can_combine() {
+            let mut s = RandomService.into_actix_service().map(|x| x + 1);
+
+            assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+
+            assert_eq!(Ok(Async::Ready(5)), s.call(()).poll());
+        }
+
+        #[test]
+        fn random_service_and_add_service_chained() {
+            let s1 = RandomService.into_actix_service();
+            let s2 = AddOneService.into_actix_service();
+            let s3 = AddOneService.into_actix_service();
+
+            let mut s = s1.and_then(s2).and_then(s3);
+
+            assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+
+            assert_eq!(Ok(Async::Ready(6)), s.call(()).poll());
+        }
+
+        #[test]
+        fn random_service_and_add_service_and_ignoring_service_chained() {
+            let s1 = RandomService.into_actix_service();
+            let s2 = AddOneService.into_actix_service();
+            let s3 = AddOneService.into_actix_service();
+            let s4 = RandomService.into_actix_service();
+
+            let mut s = s1.and_then(s2).and_then(s3).and_then(s4);
+
+            assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+
+            assert_eq!(Ok(Async::Ready(4)), s.call(()).poll());
+        }
+
+        #[test]
+        fn random_service_can_be_transformed_to_do_math() {
+            let transform = DoMath;
+
+            let mut s = transform.new_transform(RandomService.into_actix_service()).wait().unwrap();
+
+            assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+
+            assert_eq!(Ok(Async::Ready(68)), s.call(()).poll());
+        }
+
+        struct RandomService;
+        impl<R> TowerService<R> for RandomService {
+            type Response = u32;
+            type Error = ();
+            type Future = FutureResult<Self::Response, Self::Error>;
+
+            fn poll_ready(&mut self) -> Poll<(), Self::Error> {
+                Ok(Async::Ready(()))
+            }
+
+            fn call(&mut self, _req: R) -> Self::Future {
+                futures::finished(4)
+            }
+        }
+
+        struct AddOneService;
+        impl TowerService<u32> for AddOneService {
+            type Response = u32;
+            type Error = ();
+            type Future = FutureResult<Self::Response, Self::Error>;
+
+            fn poll_ready(&mut self) -> Poll<(), Self::Error> {
+                Ok(Async::Ready(()))
+            }
+
+            fn call(&mut self, req: u32) -> Self::Future {
+                futures::finished(req + 1)
+            }
+        }
+
+        struct DoMathTransform<S>(S);
+        impl<S> ActixService for DoMathTransform<S>
+        where
+            S: ActixService<Response = u32>,
+            S::Future: 'static,
+        {
+            type Request = S::Request;
+            type Response = u32;
+            type Error = S::Error;
+            type Future = Box<dyn Future<Item = Self::Response, Error = Self::Error>>;
+
+            fn poll_ready(&mut self) -> Poll<(), Self::Error> {
+                self.0.poll_ready()
+            }
+
+            fn call(&mut self, req: Self::Request) -> Self::Future {
+                let fut = self.0.call(req).map(|x| x * 17);
+                Box::new(fut)
+            }
+        }
+
+        struct DoMath;
+        impl<S> Transform<S> for DoMath
+        where
+            S: ActixService<Response = u32>,
+            S::Future: 'static,
+        {
+            type Request = S::Request;
+            type Response = u32;
+            type Error = S::Error;
+            type Transform = DoMathTransform<S>;
+            type InitError = ();
+            type Future = FutureResult<Self::Transform, Self::InitError>;
+
+            fn new_transform(&self, service: S) -> Self::Future {
+                futures::finished(DoMathTransform(service))
+            }
         }
     }
 
-    #[test]
-    fn tower_service_as_actix_service_returns_4() {
-        let mut s = RandomService.compat();
+    mod actix_service_into_tower_service {
+        use crate::{ActixServiceExt, TowerServiceExt};
+        use actix_service::{Service as ActixService, ServiceExt};
+        use futures::{future::FutureResult, Async, Poll, Future};
+        use tower_service::Service as TowerService;
 
-        assert_eq!(Ok(Async::Ready(())), s.poll_ready());
 
-        assert_eq!(Ok(Async::Ready(4)), s.call(()).poll());
-    }
+        #[test]
+        fn random_service_returns_4() {
+            let mut s = RandomService.into_tower_service();
 
-    #[test]
-    fn tower_service_as_actix_service_can_combine() {
-        let mut s = RandomService.compat().map(|x| x + 1);
+            assert_eq!(Ok(Async::Ready(())), s.poll_ready());
 
-        assert_eq!(Ok(Async::Ready(())), s.poll_ready());
-
-        assert_eq!(Ok(Async::Ready(5)), s.call(()).poll());
-    }
-
-    struct AddOneService;
-    impl TowerService<u32> for AddOneService {
-        type Response = u32;
-        type Error = ();
-        type Future = FutureResult<Self::Response, Self::Error>;
-
-        fn poll_ready(&mut self) -> Poll<(), Self::Error> {
-            Ok(Async::Ready(()))
+            assert_eq!(Ok(Async::Ready(4)), s.call(()).poll());
         }
 
-        fn call(&mut self, req: u32) -> Self::Future {
-            futures::finished(req + 1)
-        }
-    }
+        #[test]
+        fn random_service_can_use_tower_middleware() {
+            let mut s = AddOneService::wrap(RandomService.into_tower_service()).into_actix_service();
 
-    #[test]
-    fn tower_services_as_actix_services_chained() {
-        let s1 = RandomService.compat();
-        let s2 = AddOneService.compat();
-        let s3 = AddOneService.compat();
+            assert_eq!(Ok(Async::Ready(())), s.poll_ready());
 
-        let mut s = s1.and_then(s2).and_then(s3);
-
-        assert_eq!(Ok(Async::Ready(())), s.poll_ready());
-
-        assert_eq!(Ok(Async::Ready(6)), s.call(()).poll());
-    }
-
-    #[test]
-    fn tower_services_as_actix_services_chained_2() {
-        let s1 = RandomService.compat();
-        let s2 = AddOneService.compat();
-        let s3 = AddOneService.compat();
-        let s4 = RandomService.compat();
-
-        let mut s = s1.and_then(s2).and_then(s3).and_then(s4);
-
-        assert_eq!(Ok(Async::Ready(())), s.poll_ready());
-
-        assert_eq!(Ok(Async::Ready(4)), s.call(()).poll());
-    }
-
-    struct DoMathTransform<S>(S);
-    impl<S> ActixService for DoMathTransform<S>
-    where
-        S: ActixService<Response = u32>,
-        S::Future: 'static,
-    {
-        type Request = S::Request;
-        type Response = u32;
-        type Error = S::Error;
-        type Future = Box<dyn Future<Item = Self::Response, Error = Self::Error>>;
-
-        fn poll_ready(&mut self) -> Poll<(), Self::Error> {
-            self.0.poll_ready()
+            assert_eq!(Ok(Async::Ready(5)), s.call(()).poll());
         }
 
-        fn call(&mut self, req: Self::Request) -> Self::Future {
-            let fut = self.0.call(req).map(|x| x * 17);
-            Box::new(fut)
+        #[test]
+        fn do_math_service_can_use_tower_middleware() {
+            let mut s = AddOneService::wrap(DoMathService.into_tower_service()).into_actix_service();
+
+            assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+
+            assert_eq!(Ok(Async::Ready(188)), s.call(11).poll());
         }
-    }
 
-    struct DoMath;
-    impl<S> Transform<S> for DoMath
-    where
-        S: ActixService<Response = u32>,
-        S::Future: 'static,
-    {
-        type Request = S::Request;
-        type Response = u32;
-        type Error = S::Error;
-        type Transform = DoMathTransform<S>;
-        type InitError = ();
-        type Future = FutureResult<Self::Transform, Self::InitError>;
+        #[test]
+        fn random_service_and_add_service_and_ignoring_service_chained() {
+            let s1 = AddOneService::wrap(RandomService.into_tower_service()).into_actix_service();
+            let s2 = AddOneService::wrap(DoMathService.into_tower_service()).into_actix_service();
 
-        fn new_transform(&self, service: S) -> Self::Future {
-            futures::finished(DoMathTransform(service))
+            let mut s = s1.and_then(s2);
+
+            assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+
+            assert_eq!(Ok(Async::Ready(86)), s.call(()).poll());
         }
-    }
 
-    #[test]
-    fn tower_service_as_actix_service_can_be_transformed() {
-        let transform = DoMath;
+        struct RandomService;
+        impl ActixService for RandomService {
+            type Request = ();
+            type Response = u32;
+            type Error = ();
+            type Future = FutureResult<Self::Response, Self::Error>;
 
-        let mut s = transform.new_transform(RandomService.compat()).wait().unwrap();
+            fn poll_ready(&mut self) -> Poll<(), Self::Error> {
+                Ok(Async::Ready(()))
+            }
 
-        assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+            fn call(&mut self, _req: Self::Request) -> Self::Future {
+                futures::finished(4)
+            }
+        }
 
-        assert_eq!(Ok(Async::Ready(68)), s.call(()).poll());
-    }
+        struct AddOneService<S> {
+            inner: S
+        }
+
+        impl<S> AddOneService<S> {
+            fn wrap(inner: S) -> Self {
+                AddOneService {
+                    inner,
+                }
+            }
+        }
+
+        impl<S, R> TowerService<R> for AddOneService<S>
+        where
+            S: TowerService<R, Response = u32>,
+            S::Future: 'static,
+        {
+            type Response = u32;
+            type Error = S::Error;
+            type Future = Box<dyn Future<Item = Self::Response, Error = Self::Error>>;
+
+            fn poll_ready(&mut self) -> Poll<(), Self::Error> {
+                self.inner.poll_ready()
+            }
+
+            fn call(&mut self, req: R) -> Self::Future {
+                let fut = self.inner.call(req)
+                    .map(|x| x + 1);
+
+                Box::new(fut)
+            }
+        }
+
+        struct DoMathService;
+        impl ActixService for DoMathService {
+            type Request = u32;
+            type Response = u32;
+            type Error = ();
+            type Future = FutureResult<Self::Response, Self::Error>;
+
+            fn poll_ready(&mut self) -> Poll<(), Self::Error> {
+                Ok(Async::Ready(()))
+            }
+
+            fn call(&mut self, req: Self::Request) -> Self::Future {
+                futures::finished(req * 17)
+            }
+        }}
 }
\ No newline at end of file

From ecf7a11a202bf97fd1f3987356aa72e01a1e614b Mon Sep 17 00:00:00 2001
From: Marcus Griep <marcus@griep.us>
Date: Thu, 2 May 2019 17:47:37 -0400
Subject: [PATCH 2/3] Add convenience methods to wrap with middleware

---
 actix-tower/src/lib.rs | 64 +++++++++++++++++++++++++++++-------------
 1 file changed, 44 insertions(+), 20 deletions(-)

diff --git a/actix-tower/src/lib.rs b/actix-tower/src/lib.rs
index a57dad0f..78311a90 100644
--- a/actix-tower/src/lib.rs
+++ b/actix-tower/src/lib.rs
@@ -23,22 +23,29 @@ impl<S, R> ActixCompat<S, R> {
 
 /// Extension trait for wrapping a `tower_service::Service` instance for use as
 /// an `actix_service::Service`.
-pub trait TowerServiceExt {
+pub trait TowerServiceExt<R> : TowerService<R> + Sized {
     /// Wraps a `tower_service::Service` in a compatibility wrapper.
-    fn into_actix_service<R>(self) -> ActixCompat<Self, R>
-    where
-        Self: TowerService<R> + Sized;
-}
-
-impl<S> TowerServiceExt for S {
-    fn into_actix_service<R>(self) -> ActixCompat<Self, R>
-    where
-        Self: TowerService<R> + Sized
-    {
+    fn into_actix_service(self) -> ActixCompat<Self, R> {
         ActixCompat::new(self)
     }
+
+    /// Takes a function that, when provided with an `actix_service::Service` wraps it
+    /// and returns a new service. Useful for wrapping a `tower_service::Service` with
+    /// middleware built for `actix_service`.
+    fn wrap_with_actix_middleware<F, U>(self, f: F) -> TowerCompat<U>
+    where
+        F: FnOnce(ActixCompat<Self, R>) -> U,
+        U: ActixService<Request = R>
+    {
+        f(self.into_actix_service()).into_tower_service()
+    }
 }
 
+impl<S, R> TowerServiceExt<R> for S
+where
+    S: TowerService<R> + Sized
+{}
+
 impl<S, R> ActixService for ActixCompat<S, R>
 where
     S: TowerService<R>,
@@ -76,18 +83,26 @@ impl<S> TowerCompat<S> {
 /// a `tower_service::Service`.
 pub trait ActixServiceExt: ActixService + Sized {
     /// Wraps a `tower_service::Service` in a compatibility wrapper.
-    fn into_tower_service(self) -> TowerCompat<Self>;
+    fn into_tower_service(self) -> TowerCompat<Self> {
+        TowerCompat::new(self)
+    }
+
+    /// Takes a function that, when provided with a `tower_service::Service` wraps it
+    /// and returns a new service. Useful for wrapping an `actix_service::Service` with
+    /// middleware built for `tower_service`.
+    fn wrap_with_tower_middleware<F, U>(self, f: F) -> ActixCompat<U, Self::Request>
+    where
+        F: FnOnce(TowerCompat<Self>) -> U,
+        U: TowerService<Self::Request>
+    {
+        f(self.into_tower_service()).into_actix_service()
+    }
 }
 
 impl<S> ActixServiceExt for S
 where
     S: ActixService + Sized
-{
-    fn into_tower_service(self) -> TowerCompat<Self>
-    {
-        TowerCompat::new(self)
-    }
-}
+{}
 
 impl<S> TowerService<S::Request> for TowerCompat<S>
 where
@@ -133,6 +148,15 @@ mod tests {
             assert_eq!(Ok(Async::Ready(5)), s.call(()).poll());
         }
 
+        #[test]
+        fn random_service_can_use_actix_middleware() {
+            let mut s = RandomService.wrap_with_actix_middleware(DoMathTransform);
+
+            assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+
+            assert_eq!(Ok(Async::Ready(68)), s.call(()).poll());
+        }
+
         #[test]
         fn random_service_and_add_service_chained() {
             let s1 = RandomService.into_actix_service();
@@ -277,8 +301,8 @@ mod tests {
 
         #[test]
         fn random_service_and_add_service_and_ignoring_service_chained() {
-            let s1 = AddOneService::wrap(RandomService.into_tower_service()).into_actix_service();
-            let s2 = AddOneService::wrap(DoMathService.into_tower_service()).into_actix_service();
+            let s1 = RandomService.wrap_with_tower_middleware(AddOneService::wrap);
+            let s2 = DoMathService.wrap_with_tower_middleware(AddOneService::wrap);
 
             let mut s = s1.and_then(s2);
 

From c7676df697f0117135cac7a9a94bbe93f14bf256 Mon Sep 17 00:00:00 2001
From: Marcus Griep <marcus@griep.us>
Date: Fri, 3 May 2019 10:08:49 -0400
Subject: [PATCH 3/3] Add documentation and doctests

---
 actix-tower/src/lib.rs | 211 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 210 insertions(+), 1 deletion(-)

diff --git a/actix-tower/src/lib.rs b/actix-tower/src/lib.rs
index 78311a90..891b5017 100644
--- a/actix-tower/src/lib.rs
+++ b/actix-tower/src/lib.rs
@@ -1,4 +1,60 @@
-//! Utilities to ease interoperability with services based on the `tower-service` crate.
+//! Utilities to provide interoperability between services based on the
+//! `actix-service` and `tower-service` crates.
+//!
+//! ## Example
+//!
+//! In the following example, we take a `RandomService`—which will always
+//! return 4—and wraps it with a middleware that will always add 1 to the
+//! result. This pattern can be further used to wrap services from either
+//! `tower-service` or `actix-service` with middleware provided by the other.
+//!
+//! ```
+//! use actix_tower::ActixServiceExt;
+//! # use futures::{Async, Future};
+//! use actix_service::Service;
+//!
+//! struct RandomService;
+//! impl Service for RandomService {
+//!     // …
+//! #    type Request = ();
+//! #    type Response = u32;
+//! #    type Error = ();
+//! #    type Future = futures::future::FutureResult<Self::Response, Self::Error>;
+//! #
+//! #    fn poll_ready(&mut self) -> futures::Poll<(), Self::Error> {
+//! #        Ok(Async::Ready(()))
+//! #    }
+//! #
+//! #    fn call(&mut self, _req: Self::Request) -> Self::Future {
+//! #        futures::finished(4)
+//! #     }
+//! }
+//!
+//! struct AddOneMiddleware<S>(S);
+//! impl<S, R> tower_service::Service<R> for AddOneMiddleware<S>
+//! where
+//!     S: tower_service::Service<R, Response = u32>,
+//!     S::Future: 'static,
+//! {
+//!     /// …
+//! #    type Response = u32;
+//! #    type Error = S::Error;
+//! #    type Future = Box<dyn Future<Item = Self::Response, Error = Self::Error>>;
+//! #
+//! #    fn poll_ready(&mut self) -> futures::Poll<(), Self::Error> {
+//! #        self.0.poll_ready()
+//! #    }
+//! #
+//! #    fn call(&mut self, req: R) -> Self::Future {
+//! #        let fut = self.0.call(req).map(|x| x + 1);
+//! #        Box::new(fut)
+//! #    }
+//! }
+//!
+//! let mut s = RandomService.wrap_with_tower_middleware(AddOneMiddleware);
+//! assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+//! assert_eq!(Ok(Async::Ready(5)), s.call(()).poll());
+//! ```
 
 use actix_service::Service as ActixService;
 use std::marker::PhantomData;
@@ -6,6 +62,8 @@ use tower_service::Service as TowerService;
 
 /// Compatibility wrapper associating a `tower_service::Service` with a particular
 /// `Request` type, so that it can be used as an `actix_service::Service`.
+///
+/// Generally created through convenience methods on the `TowerServiceExt<R>` trait.
 pub struct ActixCompat<S, R> {
     inner: S,
     _phantom: PhantomData<R>,
@@ -25,6 +83,32 @@ impl<S, R> ActixCompat<S, R> {
 /// an `actix_service::Service`.
 pub trait TowerServiceExt<R> : TowerService<R> + Sized {
     /// Wraps a `tower_service::Service` in a compatibility wrapper.
+    ///
+    /// ```
+    /// use actix_service::Service;
+    /// use actix_tower::TowerServiceExt;
+    /// # use futures::{Async, Future};
+    ///
+    /// struct RandomService;
+    /// impl<R> tower_service::Service<R> for RandomService {
+    ///     // …
+    /// #    type Response = u32;
+    /// #    type Error = ();
+    /// #    type Future = futures::future::FutureResult<Self::Response, Self::Error>;
+    /// #
+    /// #    fn poll_ready(&mut self) -> futures::Poll<(), Self::Error> {
+    /// #        Ok(Async::Ready(()))
+    /// #    }
+    /// #
+    /// #    fn call(&mut self, _req: R) -> Self::Future {
+    /// #        futures::finished(4)
+    /// #     }
+    /// }
+    ///
+    /// let mut s = RandomService.into_actix_service();
+    /// assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+    /// assert_eq!(Ok(Async::Ready(4)), s.call(()).poll());
+    /// ```
     fn into_actix_service(self) -> ActixCompat<Self, R> {
         ActixCompat::new(self)
     }
@@ -32,6 +116,54 @@ pub trait TowerServiceExt<R> : TowerService<R> + Sized {
     /// Takes a function that, when provided with an `actix_service::Service` wraps it
     /// and returns a new service. Useful for wrapping a `tower_service::Service` with
     /// middleware built for `actix_service`.
+    ///
+    /// ```
+    /// use actix_tower::TowerServiceExt;
+    /// # use futures::{Async, Future};
+    /// use tower_service::Service;
+    ///
+    /// struct RandomService;
+    /// impl<R> Service<R> for RandomService {
+    ///     // …
+    /// #    type Response = u32;
+    /// #    type Error = ();
+    /// #    type Future = futures::future::FutureResult<Self::Response, Self::Error>;
+    /// #
+    /// #    fn poll_ready(&mut self) -> futures::Poll<(), Self::Error> {
+    /// #        Ok(Async::Ready(()))
+    /// #    }
+    /// #
+    /// #    fn call(&mut self, _req: R) -> Self::Future {
+    /// #        futures::finished(4)
+    /// #     }
+    /// }
+    ///
+    /// struct AddOneTransform<S>(S);
+    /// impl<S> actix_service::Service for AddOneTransform<S>
+    /// where
+    ///     S: actix_service::Service<Response = u32>,
+    ///     S::Future: 'static,
+    /// {
+    ///     /// …
+    /// #    type Request = S::Request;
+    /// #    type Response = u32;
+    /// #    type Error = S::Error;
+    /// #    type Future = Box<dyn Future<Item = Self::Response, Error = Self::Error>>;
+    /// #
+    /// #    fn poll_ready(&mut self) -> futures::Poll<(), Self::Error> {
+    /// #        self.0.poll_ready()
+    /// #    }
+    /// #
+    /// #    fn call(&mut self, req: Self::Request) -> Self::Future {
+    /// #        let fut = self.0.call(req).map(|x| x + 1);
+    /// #        Box::new(fut)
+    /// #    }
+    /// }
+    ///
+    /// let mut s = RandomService.wrap_with_actix_middleware(AddOneTransform);
+    /// assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+    /// assert_eq!(Ok(Async::Ready(5)), s.call(()).poll());
+    /// ```
     fn wrap_with_actix_middleware<F, U>(self, f: F) -> TowerCompat<U>
     where
         F: FnOnce(ActixCompat<Self, R>) -> U,
@@ -66,6 +198,8 @@ where
 
 /// Compatibility wrapper associating an `actix_service::Service` with a particular
 /// `Request` type, so that it can be used as a `tower_service::Service`.
+///
+/// Generally created through convenience methods on the `ActixServiceExt<R>` trait.
 pub struct TowerCompat<S> {
     inner: S,
 }
@@ -83,6 +217,33 @@ impl<S> TowerCompat<S> {
 /// a `tower_service::Service`.
 pub trait ActixServiceExt: ActixService + Sized {
     /// Wraps a `tower_service::Service` in a compatibility wrapper.
+    ///
+    /// ```
+    /// use actix_tower::ActixServiceExt;
+    /// # use futures::{Async, Future};
+    /// use tower_service::Service;
+    ///
+    /// struct RandomService;
+    /// impl actix_service::Service for RandomService {
+    ///     // …
+    /// #    type Request = ();
+    /// #    type Response = u32;
+    /// #    type Error = ();
+    /// #    type Future = futures::future::FutureResult<Self::Response, Self::Error>;
+    /// #
+    /// #    fn poll_ready(&mut self) -> futures::Poll<(), Self::Error> {
+    /// #        Ok(Async::Ready(()))
+    /// #    }
+    /// #
+    /// #    fn call(&mut self, _req: Self::Request) -> Self::Future {
+    /// #        futures::finished(4)
+    /// #     }
+    /// }
+    ///
+    /// let mut s = RandomService.into_tower_service();
+    /// assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+    /// assert_eq!(Ok(Async::Ready(4)), s.call(()).poll());
+    /// ```
     fn into_tower_service(self) -> TowerCompat<Self> {
         TowerCompat::new(self)
     }
@@ -90,6 +251,54 @@ pub trait ActixServiceExt: ActixService + Sized {
     /// Takes a function that, when provided with a `tower_service::Service` wraps it
     /// and returns a new service. Useful for wrapping an `actix_service::Service` with
     /// middleware built for `tower_service`.
+    ///
+    /// ```
+    /// use actix_tower::ActixServiceExt;
+    /// # use futures::{Async, Future};
+    /// use actix_service::Service;
+    ///
+    /// struct RandomService;
+    /// impl Service for RandomService {
+    ///     // …
+    /// #    type Request = ();
+    /// #    type Response = u32;
+    /// #    type Error = ();
+    /// #    type Future = futures::future::FutureResult<Self::Response, Self::Error>;
+    /// #
+    /// #    fn poll_ready(&mut self) -> futures::Poll<(), Self::Error> {
+    /// #        Ok(Async::Ready(()))
+    /// #    }
+    /// #
+    /// #    fn call(&mut self, _req: Self::Request) -> Self::Future {
+    /// #        futures::finished(4)
+    /// #     }
+    /// }
+    ///
+    /// struct AddOneMiddleware<S>(S);
+    /// impl<S, R> tower_service::Service<R> for AddOneMiddleware<S>
+    /// where
+    ///     S: tower_service::Service<R, Response = u32>,
+    ///     S::Future: 'static,
+    /// {
+    ///     /// …
+    /// #    type Response = u32;
+    /// #    type Error = S::Error;
+    /// #    type Future = Box<dyn Future<Item = Self::Response, Error = Self::Error>>;
+    /// #
+    /// #    fn poll_ready(&mut self) -> futures::Poll<(), Self::Error> {
+    /// #        self.0.poll_ready()
+    /// #    }
+    /// #
+    /// #    fn call(&mut self, req: R) -> Self::Future {
+    /// #        let fut = self.0.call(req).map(|x| x + 1);
+    /// #        Box::new(fut)
+    /// #    }
+    /// }
+    ///
+    /// let mut s = RandomService.wrap_with_tower_middleware(AddOneMiddleware);
+    /// assert_eq!(Ok(Async::Ready(())), s.poll_ready());
+    /// assert_eq!(Ok(Async::Ready(5)), s.call(()).poll());
+    /// ```
     fn wrap_with_tower_middleware<F, U>(self, f: F) -> ActixCompat<U, Self::Request>
     where
         F: FnOnce(TowerCompat<Self>) -> U,