improve flexiblity of retry policy

tower/src/retry/future.rs

@@ -73,9 +73,9 @@ where
 
         loop {
             match this.state.as_mut().project() {
-                StateProj::Called(future) => {
+                StateProj::Called { future } => {
                     let mut result = ready!(future.poll(cx));
-                    if let Some(ref mut req) = this.request {
+                    if let Some(req) = &mut this.request {
                         match this.retry.policy.retry(req, &mut result) {
                             Some(checking) => {
                                 this.state.set(State::Checking { checking });

tower/src/retry/policy.rs

@@ -56,6 +56,21 @@ pub trait Policy<Req, Res, E>: Sized {
     /// If the request *should* be retried, return `Some` future of a new
     /// policy that would apply for the next request attempt.
     ///
+    /// ## Mutating Requests
+    ///
+    /// The policy MAY chose to mutate the `req`: if the request is mutated, the mutated request
+    /// will be sent to the inner service in the next retry. This can be helpful for use cases like
+    /// tracking the retry count in a header.
+    ///
+    /// ## Mutating Results
+    ///
+    /// The policy MAY chose to mutate the result. This can enable the retry policy to convert a failure
+    /// into a success and vice versa. For example, if the policy is used to poll while waiting for a state
+    /// change, you can switch the result to failure such that running out of retries returns a specific failure.
+    ///
+    /// You can also record metadata on the request to include information about the number of retries required
+    /// or to record that a failure failed after exhausting all retries.
+    ///
     /// [`Service::Response`]: crate::Service::Response
     /// [`Service::Error`]: crate::Service::Error
     fn retry(&self, req: &mut Req, result: &mut Result<Res, E>) -> Option<Self::Future>;

tower/tests/retry/main.rs

@@ -94,17 +94,14 @@ async fn success_with_cannot_clone() {
 async fn retry_mutating_policy() {
     let _t = support::trace_init();
 
-    // Even though the request couldn't be cloned, if the first request succeeds,
-    // it should succeed overall.
     let (mut service, mut handle) = new_service(MutatingPolicy { remaining: 2 });
 
     assert_ready_ok!(service.poll_ready());
     let mut fut = task::spawn(service.call("hello"));
 
     assert_request_eq!(handle, "hello").send_response("world");
     assert_pending!(fut.poll());
-    // the policy alters the request. in real life, this might be setting
-    // a header
+    // the policy alters the request. in real life, this might be setting a header
     assert_request_eq!(handle, "retrying").send_response("world");
 
     assert_pending!(fut.poll());
@@ -191,6 +188,8 @@ impl Policy<Req, Res, Error> for CannotClone {
     }
 }
 
+/// Test policy that changes the request to `retrying` during retries and the result to `"out of retries"`
+/// when retries are exhausted.
 #[derive(Clone)]
 struct MutatingPolicy {
     remaining: usize,