Add support for automatic request retries (#900)

Author: ob-stripe

src/main/java/com/stripe/net/HttpClient.java

@@ -1,14 +1,44 @@
 package com.stripe.net;
 
 import com.stripe.Stripe;
+import com.stripe.exception.ApiConnectionException;
 import com.stripe.exception.StripeException;
 import com.stripe.util.Stopwatch;
+import java.net.ConnectException;
+import java.time.Duration;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.concurrent.ThreadLocalRandom;
 
 /** Base abstract class for HTTP clients used to send requests to Stripe's API. */
 public abstract class HttpClient {
-  private static final RequestTelemetry requestTelemetry = new RequestTelemetry();
+  /** Maximum sleep time between tries to send HTTP requests after network failure. */
+  public static final Duration maxNetworkRetriesDelay = Duration.ofSeconds(5);
+
+  /** Minimum sleep time between tries to send HTTP requests after network failure. */
+  public static final Duration minNetworkRetriesDelay = Duration.ofMillis(500);
+
+  private final int maxNetworkRetries;
+
+  private final RequestTelemetry requestTelemetry = new RequestTelemetry();
+
+  /** A value indicating whether the client should sleep between automatic request retries. */
+  boolean networkRetriesSleep = true;
+
+  /** Initializes a new instance of the {@link HttpClient} class with default parameters. */
+  public HttpClient() {
+    this(0);
+  }
+
+  /**
+   * Initializes a new instance of the {@link HttpClient} class.
+   *
+   * @param maxNetworkRetries the maximum number of times the client will retry requests that fail
+   *     due to an intermittent problem.
+   */
+  public HttpClient(int maxNetworkRetries) {
+    this.maxNetworkRetries = maxNetworkRetries;
+  }
 
   /**
    * Sends the given request to Stripe's API.
@@ -40,6 +70,50 @@ public StripeResponse requestWithTelemetry(StripeRequest request) throws StripeE
     return response;
   }
 
+  /**
+   * Sends the given request to Stripe's API, retrying the request in cases of intermittent
+   * problems.
+   *
+   * @param request the request
+   * @return the response
+   * @throws StripeException If the request fails for any reason
+   */
+  public StripeResponse requestWithRetries(StripeRequest request) throws StripeException {
+    ApiConnectionException requestException = null;
+    StripeResponse response = null;
+    int retry = 0;
+
+    while (true) {
+      requestException = null;
+
+      try {
+        response = this.requestWithTelemetry(request);
+      } catch (ApiConnectionException e) {
+        requestException = e;
+      }
+
+      if (!this.shouldRetry(retry, requestException, response)) {
+        break;
+      }
+
+      retry += 1;
+
+      try {
+        Thread.sleep(this.sleepTime(retry).toMillis());
+      } catch (InterruptedException e) {
+        Thread.currentThread().interrupt();
+      }
+    }
+
+    if (requestException != null) {
+      throw requestException;
+    }
+
+    response.setNumRetries(retry);
+
+    return response;
+  }
+
   /**
    * Builds the value of the {@code User-Agent} header.
    *
@@ -98,4 +172,76 @@ private static String formatAppInfo(Map<String, String> info) {
 
     return str;
   }
+
+  private boolean shouldRetry(int numRetries, StripeException exception, StripeResponse response) {
+    // Do not retry if we are out of retries.
+    if (numRetries >= this.maxNetworkRetries) {
+      return false;
+    }
+
+    // Retry on connection error.
+    if ((exception != null)
+        && (exception.getCause() != null)
+        && (exception.getCause() instanceof ConnectException)) {
+      return true;
+    }
+
+    // The API may ask us not to retry (eg; if doing so would be a no-op)
+    // or advise us to retry (eg; in cases of lock timeouts); we defer to that.
+    if ((response != null) && (response.headers() != null)) {
+      String value = response.headers().get("Stripe-Should-Retry");
+
+      if ("true".equals(value)) {
+        return true;
+      }
+
+      if ("false".equals(value)) {
+        return false;
+      }
+    }
+
+    // Retry on conflict errors.
+    if ((response != null) && (response.code() == 409)) {
+      return true;
+    }
+
+    // Retry on 500, 503, and other internal errors.
+    //
+    // Note that we expect the Stripe-Should-Retry header to be false
+    // in most cases when a 500 is returned, since our idempotency framework
+    // would typically replay it anyway.
+    if ((response != null) && (response.code() >= 500)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  private Duration sleepTime(int numRetries) {
+    // We disable sleeping in some cases for tests.
+    if (!this.networkRetriesSleep) {
+      return Duration.ZERO;
+    }
+
+    // Apply exponential backoff with MinNetworkRetriesDelay on the number of numRetries
+    // so far as inputs.
+    Duration delay =
+        Duration.ofNanos((long) (minNetworkRetriesDelay.toNanos() * Math.pow(2, numRetries - 1)));
+
+    // Do not allow the number to exceed MaxNetworkRetriesDelay
+    if (delay.compareTo(maxNetworkRetriesDelay) > 0) {
+      delay = maxNetworkRetriesDelay;
+    }
+
+    // Apply some jitter by randomizing the value in the range of 75%-100%.
+    double jitter = ThreadLocalRandom.current().nextDouble(0.75, 1.0);
+    delay = Duration.ofNanos((long) (delay.toNanos() * jitter));
+
+    // But never sleep less than the base sleep seconds.
+    if (delay.compareTo(minNetworkRetriesDelay) < 0) {
+      delay = minNetworkRetriesDelay;
+    }
+
+    return delay;
+  }
 }

src/main/java/com/stripe/net/HttpURLConnectionClient.java

@@ -15,6 +15,24 @@
 import lombok.Cleanup;
 
 public class HttpURLConnectionClient extends HttpClient {
+  /**
+   * Initializes a new instance of the {@link HttpURLConnectionClient} class with default
+   * parameters.
+   */
+  public HttpURLConnectionClient() {
+    super();
+  }
+
+  /**
+   * Initializes a new instance of the {@link HttpURLConnectionClient} class.
+   *
+   * @param maxNetworkRetries the maximum number of times the client will retry requests that fail
+   *     due to an intermittent problem.
+   */
+  public HttpURLConnectionClient(int maxNetworkRetries) {
+    super(maxNetworkRetries);
+  }
+
   /**
    * Sends the given request to Stripe's API.
    *

src/main/java/com/stripe/net/LiveStripeResponseGetter.java

@@ -22,7 +22,24 @@
 import java.util.Map;
 
 public class LiveStripeResponseGetter implements StripeResponseGetter {
-  private final HttpClient httpClient = new HttpURLConnectionClient();
+  private final HttpClient httpClient;
+
+  /**
+   * Initializes a new instance of the {@link LiveStripeResponseGetter} class with default
+   * parameters.
+   */
+  public LiveStripeResponseGetter() {
+    this(null);
+  }
+
+  /**
+   * Initializes a new instance of the {@link LiveStripeResponseGetter} class.
+   *
+   * @param httpClient the HTTP client to use
+   */
+  public LiveStripeResponseGetter(HttpClient httpClient) {
+    this.httpClient = (httpClient != null) ? httpClient : buildDefaultHttpClient();
+  }
 
   @Override
   public <T> T request(
@@ -33,7 +50,7 @@ public <T> T request(
       RequestOptions options)
       throws StripeException {
     StripeRequest request = new StripeRequest(method, url, params, options);
-    StripeResponse response = httpClient.requestWithTelemetry(request);
+    StripeResponse response = httpClient.requestWithRetries(request);
 
     int responseCode = response.code();
     String responseBody = response.body();
@@ -67,7 +84,7 @@ public <T> T oauthRequest(
       RequestOptions options)
       throws StripeException {
     StripeRequest request = new StripeRequest(method, url, params, options);
-    StripeResponse response = this.httpClient.requestWithTelemetry(request);
+    StripeResponse response = this.httpClient.requestWithRetries(request);
 
     int responseCode = response.code();
     String responseBody = response.body();
@@ -92,6 +109,10 @@ public <T> T oauthRequest(
     return resource;
   }
 
+  private static HttpClient buildDefaultHttpClient() {
+    return new HttpURLConnectionClient();
+  }
+
   private static void raiseMalformedJsonError(
       String responseBody, int responseCode, String requestId) throws ApiException {
     throw new ApiException(

src/main/java/com/stripe/net/StripeResponse.java

@@ -8,6 +8,7 @@ public class StripeResponse {
   int code;
   String body;
   StripeHeaders headers;
+  int numRetries;
 
   /** Constructs a Stripe response with the specified status code and body. */
   public StripeResponse(int code, String body) {
@@ -42,4 +43,12 @@ public String idempotencyKey() {
   public String requestId() {
     return (headers != null) ? headers.get("Request-Id") : null;
   }
+
+  public int numRetries() {
+    return this.numRetries;
+  }
+
+  void setNumRetries(int numRetries) {
+    this.numRetries = numRetries;
+  }
 }