Add "Retry after" support to QosException.Throttle (#40)

Author: Robert Fink

errors/src/main/java/com/palantir/remoting/api/errors/QosException.java

@@ -20,8 +20,10 @@
 import com.palantir.logsafe.SafeArg;
 import com.palantir.logsafe.SafeLoggable;
 import java.net.URL;
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Optional;
 
 /**
  * An exception raised by a service to indicate a potential Quality-of-Service problem, specifically requesting that the
@@ -32,7 +34,9 @@
 public abstract class QosException extends RuntimeException {
 
     // Not meant for external subclassing.
-    private QosException() {}
+    private QosException(String message) {
+        super(message);
+    }
 
     abstract <T> T accept(Visitor<T> visitor);
 
@@ -47,7 +51,15 @@ public interface Visitor<T> {
      * may retry against an arbitrary node of this service.
      */
     public static Throttle throttle() {
-        return new Throttle();
+        return new Throttle(Optional.empty());
+    }
+
+    /**
+     * Like {@link #throttle()}, but additionally requests that the client wait for at least the given duration before
+     * retrying the request.
+     */
+    public static Throttle throttle(Duration duration) {
+        return new Throttle(Optional.of(duration));
     }
 
     /**
@@ -59,16 +71,25 @@ public static RetryOther retryOther(URL redirectTo) {
     }
 
     /**
-     * An exception indicating that (this node of) this service are currently unavailable and the client may try again
-     * at a later time, possibly against a different node of this service.
+     * An exception indicating that (this node of) this service is currently unavailable and the client may try again at
+     * a later time, possibly against a different node of this service.
      */
     public static Unavailable unavailable() {
         return new Unavailable();
     }
 
     /** See {@link #throttle}. */
     public static final class Throttle extends QosException {
-        private Throttle() {}
+        private final Optional<Duration> retryAfter;
+
+        private Throttle(Optional<Duration> retryAfter) {
+            super("Suggesting request throttling with optional retryAfter duration: " + retryAfter);
+            this.retryAfter = retryAfter;
+        }
+
+        public Optional<Duration> getRetryAfter() {
+            return retryAfter;
+        }
 
         @Override
         <T> T accept(Visitor<T> visitor) {
@@ -81,6 +102,7 @@ public static final class RetryOther extends QosException implements SafeLoggabl
         private final URL redirectTo;
 
         private RetryOther(URL redirectTo) {
+            super("Suggesting request retry against: " + redirectTo.toString());
             this.redirectTo = redirectTo;
         }
 
@@ -109,7 +131,9 @@ public List<Arg<?>> getArgs() {
 
     /** See {@link #unavailable}. */
     public static final class Unavailable extends QosException {
-        private Unavailable() {}
+        private Unavailable() {
+            super("Server unavailable");
+        }
 
         @Override
         <T> T accept(Visitor<T> visitor) {

errors/src/test/java/com/palantir/remoting/api/errors/QosExceptionTest.java

@@ -19,6 +19,7 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
+import java.net.URL;
 import org.junit.Test;
 
 public final class QosExceptionTest {
@@ -43,7 +44,8 @@ public Class visit(QosException.Unavailable exception) {
         };
 
         assertThat(QosException.throttle().accept(visitor)).isEqualTo(QosException.Throttle.class);
-        assertThat(QosException.retryOther(null).accept(visitor)).isEqualTo(QosException.RetryOther.class);
+        assertThat(QosException.retryOther(new URL("http://foo")).accept(visitor))
+                .isEqualTo(QosException.RetryOther.class);
         assertThat(QosException.unavailable().accept(visitor)).isEqualTo(QosException.Unavailable.class);
     }
 }