feat: add ratelimiter to allow transparent retry of 429 (#89)

* feat: add ratelimiter to allow transparent retry of 429

* fix: change configuration to be done via HttpOptions

Author: dpittner

.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
+
 /.idea
 /target/
 .classpath
@@ -8,7 +9,7 @@ venv
 .factorypath
 /test-output/
 config
-.iml
+*.iml
 .pre-commit-config.yaml
 .secrets.baseline
 .vscode/

src/main/java/com/ibm/cloud/sdk/core/http/HttpClientSingleton.java

@@ -14,6 +14,7 @@
 package com.ibm.cloud.sdk.core.http;
 
 import com.ibm.cloud.sdk.core.http.HttpConfigOptions.LoggingLevel;
+import com.ibm.cloud.sdk.core.http.ratelimit.RateLimitInterceptor;
 import com.ibm.cloud.sdk.core.service.BaseService;
 import com.ibm.cloud.sdk.core.service.security.DelegatingSSLSocketFactory;
 import okhttp3.Authenticator;
@@ -308,6 +309,14 @@ public OkHttpClient configureClient(OkHttpClient client, HttpConfigOptions optio
       if (options.getLoggingLevel() != null) {
         client = setLoggingLevel(client, options.getLoggingLevel());
       }
+      if (options.getDefaultRetryInterval() > 0) {
+        client = client.newBuilder()
+                .addInterceptor(new RateLimitInterceptor(
+                        options.getAuthenticator()
+                        , options.getDefaultRetryInterval()
+                        , options.getMaxRetries()))
+                .build();
+      }
     }
     return client;
   }

src/main/java/com/ibm/cloud/sdk/core/http/HttpConfigOptions.java

@@ -13,6 +13,7 @@
 
 package com.ibm.cloud.sdk.core.http;
 
+import com.ibm.cloud.sdk.core.http.ratelimit.RateLimitConstants;
 import okhttp3.Authenticator;
 
 import java.net.Proxy;
@@ -37,6 +38,11 @@ public enum LoggingLevel {
   private Authenticator proxyAuthenticator;
   private LoggingLevel loggingLevel;
 
+  // Ratelimiting properties
+  private com.ibm.cloud.sdk.core.security.Authenticator authenticator;
+  private int defaultInterval = 0;
+  private int maxRetries = 0;
+
   public boolean shouldDisableSslVerification() {
     return this.disableSslVerification;
   }
@@ -53,12 +59,29 @@ public LoggingLevel getLoggingLevel() {
     return this.loggingLevel;
   }
 
+  public com.ibm.cloud.sdk.core.security.Authenticator getAuthenticator() {
+    return authenticator;
+  }
+
+  public int getDefaultRetryInterval() {
+    return defaultInterval;
+  }
+
+  public int getMaxRetries() {
+    return maxRetries;
+  }
+
   public static class Builder {
     private boolean disableSslVerification;
     private Proxy proxy;
     private Authenticator proxyAuthenticator;
     private LoggingLevel loggingLevel;
 
+    // Ratelimiting properties
+    private com.ibm.cloud.sdk.core.security.Authenticator authenticator;
+    private int defaultInterval = 0;
+    private int maxRetries = 0;
+
     public HttpConfigOptions build() {
       return new HttpConfigOptions(this);
     }
@@ -75,6 +98,22 @@ public Builder disableSslVerification(boolean disableSslVerification) {
       return this;
     }
 
+    /**
+     * Sets retry on rate limiting policy (429). See  {@link RateLimitConstants} for defaults to use
+     *
+     * @param authenticator to use for retries, the {@link Authenticator} used by the client
+     * @param defaultInterval if not specified in the response, how long to wait until the next attempt
+     * @param maxRetries the maximum amount of retries for an request
+     * @return the builder
+     */
+    public Builder enableRateLimitRetry(com.ibm.cloud.sdk.core.security.Authenticator authenticator
+            , int defaultInterval, int maxRetries) {
+      this.authenticator = authenticator;
+      this.defaultInterval = defaultInterval;
+      this.maxRetries = maxRetries;
+      return this;
+    }
+
     /**
      * Sets HTTP proxy to be used by connections with the current client.
      *
@@ -114,5 +153,9 @@ private HttpConfigOptions(Builder builder) {
     this.proxy = builder.proxy;
     this.proxyAuthenticator = builder.proxyAuthenticator;
     this.loggingLevel = builder.loggingLevel;
+    // rate limiting related
+    this.authenticator = builder.authenticator;
+    this.defaultInterval = builder.defaultInterval;
+    this.maxRetries = builder.maxRetries;
   }
 }

src/main/java/com/ibm/cloud/sdk/core/http/ratelimit/RateLimitConstants.java

@@ -0,0 +1,16 @@
+package com.ibm.cloud.sdk.core.http.ratelimit;
+
+
+/**
+ * This class encapsulate constants that can be passed as defaults to {@link RateLimitInterceptor}.
+ */
+public interface RateLimitConstants {
+    /**
+     * Time to wait before retrying in absence of information from server.
+     */
+    int DEFAULT_INTERVAL = 5000;
+    /**
+     * Maximum amount of times a request will be retried.
+     */
+    int MAX_RETRIES = Integer.MAX_VALUE;
+}

src/main/java/com/ibm/cloud/sdk/core/http/ratelimit/RateLimitContext.java

@@ -0,0 +1,25 @@
+package com.ibm.cloud.sdk.core.http.ratelimit;
+
+/**
+ * Carries per request state for {@link RateLimitInterceptor}.
+ */
+public class RateLimitContext {
+    private int remainingRetries;
+
+    public RateLimitContext(int maxRetries) {
+
+        this.remainingRetries = maxRetries;
+    }
+
+    public boolean decrementAndCheck() {
+        remainingRetries--;
+        return remainingRetries > 0;
+    }
+
+    @Override
+    public String toString() {
+        return "RateLimitContext{"
+                + "remainingRetries="
+                + remainingRetries + '}';
+    }
+}

src/main/java/com/ibm/cloud/sdk/core/http/ratelimit/RateLimitInterceptor.java

@@ -0,0 +1,115 @@
+package com.ibm.cloud.sdk.core.http.ratelimit;
+
+import com.ibm.cloud.sdk.core.security.Authenticator;
+import okhttp3.Interceptor;
+import okhttp3.Request;
+import okhttp3.Response;
+
+import java.io.IOException;
+import java.util.logging.Logger;
+
+/**
+ * Provides means to retry requests on RateLimiting (429).
+ */
+public class RateLimitInterceptor implements Interceptor {
+
+    private static final Logger LOG = Logger.getLogger(RateLimitInterceptor.class.getName());
+
+    private int defaultInterval;
+    private int maxRetries;
+    private Authenticator authenticator;
+
+    public RateLimitInterceptor(Authenticator authenticator, int defaultInterval, int maxRetries) {
+        this.defaultInterval = defaultInterval;
+        this.maxRetries = maxRetries;
+        this.authenticator = authenticator;
+    }
+
+
+    /**
+     * Checks response and retries with delay in case of a 429, time between attempts is taken from
+     * response, if no valid information is on the response, the default is used.
+     */
+    @Override
+    public Response intercept(Interceptor.Chain chain) throws IOException {
+        Request request = chain.request();
+        Response response = chain.proceed(request);
+
+        // 429 indicates a rate limit error
+        while (shouldRetry(response, request)) {
+            int interval = getInterval(response);
+
+            // wait & retry
+            // A dispatcher based model may be more efficient.
+            try {
+                LOG.info("Will retry after: " + interval + "ms");
+                Thread.sleep(interval);
+            } catch (InterruptedException e) {
+                LOG.fine("Thread was interrupted, likely call cancelled");
+            }
+
+            // At this point, time has passed, so we want to ensure auth is up-to date,
+            // as well as ensure we embed a context to carry state forward
+            Request.Builder builder = request.newBuilder();
+
+            // if this is the first round, no tag exists yet
+            if (request.tag(RateLimitContext.class) == null) {
+                builder = builder.tag(RateLimitContext.class, new RateLimitContext(maxRetries));
+            }
+            if (authenticator != null) {
+                authenticator.authenticate(builder);
+            }
+            response.close();
+            request = builder.build();
+            response = chain.proceed(request);
+        }
+
+        return response;
+    }
+
+    private int getInterval(Response response) {
+        // if the server didn't provide details, we'll still wait default interval
+        int interval = defaultInterval;
+
+        // Both headers can be used concurrently, but need to be consistent.
+        // draft allows for more fine-grained control, we just cover the basics for now
+        // https://tools.ietf.org/id/draft-polli-ratelimit-headers-00.html
+        String headerVal = response.header("RateLimit-Reset");
+
+        // RFC 7231, section 7.1.3: Retry-After
+        if (headerVal == null) {
+            headerVal = response.header("Retry-After");
+        }
+
+        // According to spec, this will be a integer, if it's not, we're falling back to default
+        if (headerVal != null) {
+            try {
+                int responseInterval = Integer.parseInt(headerVal, 10) * 1000;
+                // just in case it's a negative number
+                if (responseInterval > 0) {
+                    interval = responseInterval;
+                }
+            } catch (NumberFormatException e) {
+                LOG.info("Response included a non-numeric value for Retry-After/RateLimit-Reset");
+            }
+        }
+        return interval;
+    }
+
+    private boolean shouldRetry(Response response, Request request) {
+        // if we got 429, and we didn't exhaust maxRetries, we should retry
+        if (!response.isSuccessful() && response.code() == 429) {
+            // the first attempt won't have a context yet, so we need to check
+            RateLimitContext context = request.tag(RateLimitContext.class);
+            if (context != null && !context.decrementAndCheck()) {
+                LOG.info("Retries exhausted for RateLimit, giving up");
+                return false;
+            }
+            if (context != null) {
+                LOG.fine(context.toString());
+            }
+            return true;
+        }
+        return false;
+    }
+}