feat: support user-defined retry interceptors (#169)

This commit provides a pluggable way for users of the java core
to supply their own retry interceptor implementation in order
to customize the conditions under which retries are automatically
attempted.
Included in these changes is the notion of a "retry strategy",
which is a factory for creating retry interceptor instances.
Users of the java core (e.g. an SDK project) can implement
their own retry strategy and then set it with the
HttpClientSingleton.setRetryStrategy() static method.
Once set, the registered factory's createRetryInterceptor()
method will be called whenever the java core needs to initialize an
http client instance when retries are enabled.
The factory's createRetryInterceptor() method returns an implementation
of the IRetryInterceptor interface (which is itself a subclass of
the okhttp3 Interceptor interface).
User's might find it convenient to define their retry interceptor
class as a subclass of the java core's RetryInterceptor class,
thereby relying on RetryInterceptor for most of the functionality,
while overriding specific methods as needed.

Author: padamstx

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "package-lock.json|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2021-11-17T14:53:46Z",
+  "generated_at": "2022-03-16T14:20:41Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -150,15 +150,15 @@
         "hashed_secret": "789cbe0407840b1c2041cb33452ff60f19bf58cc",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 62,
+        "line_number": 63,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "2207d3f3ac68743290fe4affc71c10bec4962232",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 63,
+        "line_number": 64,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -352,7 +352,7 @@
       }
     ]
   },
-  "version": "0.13.1+ibm.46.dss",
+  "version": "0.13.1+ibm.47.dss",
   "word_list": {
     "file": null,
     "hash": null

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

@@ -0,0 +1,28 @@
+/**
+ * (C) Copyright IBM Corp. 2022.  All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+
+package com.ibm.cloud.sdk.core.http;
+
+import com.ibm.cloud.sdk.core.security.Authenticator;
+
+/**
+ * This is the java core's default retry strategy.
+ * It will return instances of our RetryInterceptor implementation class.
+ */
+public class DefaultRetryStrategy implements IRetryStrategy {
+
+  @Override
+  public RetryInterceptor createRetryInterceptor(int maxRetries, int maxRetryInterval, Authenticator authenticator) {
+    return new RetryInterceptor(maxRetries, maxRetryInterval, authenticator);
+  }
+}

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

@@ -15,7 +15,6 @@
 
 import com.ibm.cloud.sdk.core.http.HttpConfigOptions.LoggingLevel;
 import com.ibm.cloud.sdk.core.http.gzip.GzipRequestInterceptor;
-import com.ibm.cloud.sdk.core.service.BaseService;
 import com.ibm.cloud.sdk.core.service.security.DelegatingSSLSocketFactory;
 import okhttp3.Authenticator;
 import okhttp3.ConnectionSpec;
@@ -59,7 +58,21 @@
 public class HttpClientSingleton {
   private static HttpClientSingleton instance = null;
 
-  private static final Logger LOG = Logger.getLogger(BaseService.class.getName());
+  private static final Logger LOG = Logger.getLogger(HttpClientSingleton.class.getName());
+
+  // retryStrategy serves as a factory for creating retry interceptors.
+  private static IRetryStrategy retryStrategy = new DefaultRetryStrategy();
+
+  /**
+   * Sets the factory to be used to construct retry interceptor instances.
+   * @param strategy the IRetryStrategy implementation to be set as the factory
+   * @return the previous factory
+   */
+  public static synchronized IRetryStrategy setRetryStrategy(IRetryStrategy strategy) {
+    IRetryStrategy previousStrategy = retryStrategy;
+    retryStrategy = strategy;
+    return previousStrategy;
+  }
 
   /**
    * TrustManager for disabling SSL verification, which essentially lets everything through.
@@ -310,7 +323,7 @@ private void setupTLSProtocol(final OkHttpClient.Builder builder) {
    * Sets a new list of interceptors for the specified {@link OkHttpClient} instance by removing the specified
    * interceptor and returns a new instance with the interceptors configured as requested.
    *
-   * @param client the {@link OkHttpClient} instance to set the proxy authenticator on
+   * @param client the {@link OkHttpClient} instance to remove the interceptors from
    * @param interceptorToRemove the class name of the interceptor to remove
    * @return the new {@link OkHttpClient} instance with the new list of interceptors
    */
@@ -320,9 +333,33 @@ private OkHttpClient reconfigureClientInterceptors(OkHttpClient client, String i
     if (!builder.interceptors().isEmpty()) {
       for (Iterator<Interceptor> iter = builder.interceptors().iterator(); iter.hasNext(); ) {
         Interceptor element = iter.next();
-        String currentInterceptor = element.getClass().getSimpleName();
-        if (currentInterceptor.equals(interceptorToRemove)) {
-          LOG.log(Level.FINE, "Removing interceptor " + currentInterceptor + " from http client instance.");
+        if (interceptorToRemove.equals(element.getClass().getSimpleName())) {
+          LOG.log(Level.FINE, "Removing interceptor " + element.getClass().getName() + " from http client instance.");
+          iter.remove();
+        }
+      }
+    }
+
+    return builder.build();
+  }
+
+  /**
+   * Sets a new list of interceptors for the specified {@link OkHttpClient} instance by removing any interceptors
+   * that implement "interfaceToRemove".
+   *
+   * @param client the {@link OkHttpClient} instance to remove the interceptors from
+   * @param interfaceToRemove the specific interface for which interceptor instances should be removed
+   * @return the new {@link OkHttpClient} instance with the updated list of interceptors
+   */
+  private OkHttpClient reconfigureClientInterceptors(OkHttpClient client,
+      Class<? extends Interceptor> interfaceToRemove) {
+    OkHttpClient.Builder builder = client.newBuilder();
+
+    if (!builder.interceptors().isEmpty()) {
+      for (Iterator<Interceptor> iter = builder.interceptors().iterator(); iter.hasNext(); ) {
+        Interceptor element = iter.next();
+        if (interfaceToRemove.isAssignableFrom(element.getClass())) {
+          LOG.log(Level.FINE, "Removing interceptor " + element.getClass().getName() + " from http client instance.");
           iter.remove();
         }
       }
@@ -381,11 +418,17 @@ public OkHttpClient configureClient(OkHttpClient client, HttpConfigOptions optio
       // Configure the retry interceptor.
       Boolean enableRetries = options.getRetries();
       if (enableRetries != null) {
-        client = reconfigureClientInterceptors(client, "RetryInterceptor");
+        client = reconfigureClientInterceptors(client, IRetryInterceptor.class);
         if (enableRetries.booleanValue()) {
-          client = client.newBuilder().addInterceptor(
-              new RetryInterceptor(options.getMaxRetries(), options.getMaxRetryInterval(), options.getAuthenticator()))
-              .build();
+          IRetryInterceptor retryInterceptor =
+              retryStrategy.createRetryInterceptor(options.getMaxRetries(), options.getMaxRetryInterval(),
+                  options.getAuthenticator());
+          if (retryInterceptor != null) {
+            client = client.newBuilder().addInterceptor(retryInterceptor).build();
+          } else {
+            LOG.log(Level.WARNING,
+                "The retry interceptor factory returned a null IRetryInterceptor instance. Retries are disabled.");
+          }
         }
       }
 

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

@@ -0,0 +1,24 @@
+/**
+ * (C) Copyright IBM Corp. 2022.  All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+
+package com.ibm.cloud.sdk.core.http;
+
+import okhttp3.Interceptor;
+
+/**
+ * This is a marker interface used to identify retry interceptor implementations
+ * within the java core library.
+ */
+public interface IRetryInterceptor extends Interceptor {
+
+}

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

@@ -0,0 +1,39 @@
+/**
+ * (C) Copyright IBM Corp. 2022.  All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+
+package com.ibm.cloud.sdk.core.http;
+
+import com.ibm.cloud.sdk.core.security.Authenticator;
+
+/**
+ * IRetryStrategy is an interface that is implemented by retry interceptor factories.
+ * This interface is used by the java core to create a retry interceptor implementation when
+ * automatic retries are enabled.
+ * The java core defines a default implementation of this interface in the
+ * DefaultRetryStrategy class.
+ * Users can implement their own factory in order to supply their own retry interceptor
+ * implementation, perhaps to customize the criteria under which failed requests will be retried.
+ */
+public interface IRetryStrategy {
+
+  /**
+   * Return an implementation of the {@link IRetryInterceptor} interface
+   * that is capable of retrying failed requests.
+   *
+   * @param maxRetries the maximum number of retries to be attempted by the retry interceptor
+   * @param maxRetryInterval the maximum interval (in seconds)
+   * @param authenticator the Authenticator instance to be used to authenticate retried requests
+   * @return an okhttp3.Interceptor instance
+   */
+  IRetryInterceptor createRetryInterceptor(int maxRetries, int maxRetryInterval, Authenticator authenticator);
+}

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

@@ -1,5 +1,5 @@
 /**
- * (C) Copyright IBM Corp. 2021.
+ * (C) Copyright IBM Corp. 2021, 2022.
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
  * the License. You may obtain a copy of the License at
@@ -30,9 +30,16 @@
 import org.apache.commons.lang3.StringUtils;
 
 /**
- * This interceptor checks the responses and retries the request if it's possible.
+ * This class is an okhttp Interceptor implementation that will try to automatically retry
+ * failed requests, based on the type of failure that occurred.
+ * This class is configured with the following:
+ * <ul>
+ * <li>the maximum number of retries to attempt for a failed request
+ * <li>the maximum retry interval (in seconds) to wait between retry attempts
+ * <li>the {@link Authenticator} instance to use to authenticate each retry attempt
+ * </ul>
  */
-public class RetryInterceptor implements Interceptor {
+public class RetryInterceptor implements IRetryInterceptor {
 
   private static final Logger LOG = Logger.getLogger(RetryInterceptor.class.getName());
 
@@ -43,7 +50,7 @@ public class RetryInterceptor implements Interceptor {
   private int maxRetries;
   private int maxRetryInterval;
 
-  private class RetryContext {
+  public class RetryContext {
     private int retryCount;
 
     private RetryContext() {
@@ -59,13 +66,36 @@ private boolean incCountAndCheck() {
     }
   }
 
+  // Hide the default ctor to force the use of the non-default ctor below.
+  protected RetryInterceptor() { }
+
+  /**
+   * This ctor configures the RetryInterceptor instance with the max retries,
+   * retry interval and an authenticator.
+   * @param maxRetries the maximum number of retries to attempt for a failed request
+   * @param maxRetryInterval the maximum retry interval (in seconds) to wait between retry attempts
+   * @param authenticator the {@link Authenticator} instance to use to authenticate retried requests
+   */
   public RetryInterceptor(int maxRetries, int maxRetryInterval, Authenticator authenticator) {
     this.authenticator = authenticator;
     this.maxRetries = maxRetries;
     // Convert the interval from seconds to milliseconds.
     this.maxRetryInterval = maxRetryInterval * 1000;
   }
 
+  /**
+   * The "intercept()" method is the primary method of the interceptor.
+   * The chain of interceptors registered for a particular okhttp Client instance
+   * is in the form of an ordered list.  When a request is invoked, each interceptor's
+   * "intercept" method is invoked and is passed the interceptor chain.
+   * The interceptor can inspect the request to determine how to proceed, and will invoke the interceptor
+   * chain's "proceed()" method to call the next interceptor in the chain.
+   * When the last interceptor invokes the chain's "proceed()" method, the request is sent over the wire
+   * and the response is returned via the return value of the proceed() method.
+   * The interceptor can then inspect the response and determine how to proceed.
+   * Ultimately the response is returned from this intercept() method and is ultimately propagated
+   * back through the chain's "proceed()" methods.
+   */
   @Override
   public Response intercept(Interceptor.Chain chain) throws IOException {
     // Make the first request.
@@ -89,7 +119,7 @@ public Response intercept(Interceptor.Chain chain) throws IOException {
         builder.tag(RetryContext.class, new RetryContext());
       }
 
-      // If we have a valid authenticator authenticate the request.
+      // If we have a valid authenticator, then authenticate the request.
       // This is mostly here for backward compatibility.
       if (authenticator != null) {
         authenticator.authenticate(builder);
@@ -103,8 +133,13 @@ public Response intercept(Interceptor.Chain chain) throws IOException {
     return response;
   }
 
-  // Get the time we should wait before fire the next request in milliseconds.
-  private int getInterval(Response response, Request request) {
+  /**
+   * Determine the retry interval to wait before attempting the next retry.
+   * @param response the response from the previously attempted request
+   * @param request the previously attempted request
+   * @return the retry interval in milliseconds
+   */
+  protected int getInterval(Response response, Request request) {
     Integer interval = null;
 
     String headerVal = response.header("Retry-After");
@@ -143,9 +178,13 @@ private int getInterval(Response response, Request request) {
     return interval;
   }
 
-  // Check the response and the retry context then decide should we have make
-  // another request.
-  private boolean shouldRetry(Response response, Request request) {
+  /**
+   * Determine whether or not to attempt a retry of the specified request.
+   * @param response the response obtained from the previously-attempted request
+   * @param request the previously-attempted request
+   * @return true if the specified request should be retried, false otherwise
+   */
+  protected boolean shouldRetry(Response response, Request request) {
     // First check the response.
     if (response.code() == 429 || (response.code() >= 500 && response.code() != 501)) {
       // Now check if we exhausted the max number of retries or not.
@@ -160,10 +199,13 @@ private boolean shouldRetry(Response response, Request request) {
     return false;
   }
 
-  // Calculate the back off time in milliseconds based on the retry count.
-  // This calculation is based on what the go-retryablehttp package does in its
-  // DefaultBackoff function.
-  private int calculateBackoff(int retryCount) {
+  /**
+   * Compute the "backoff" time (retry interval) in milleseconds based on the retry count.
+   * This calculation is based on the go-retryablehttp package's "DefaultBackoff()" function.
+   * @param retryCount the retry count for which we need to compute the backoff time
+   * @return the retry interval to use for retry number "retryCount"
+   */
+  protected int calculateBackoff(int retryCount) {
     // Exponential interval calculation based on the number of retries.
     double newInterval = (Math.pow(2, Double.valueOf(retryCount))) * RetryInterceptor.DEFAULT_RETRY_INTERVAL;
     if (newInterval > this.maxRetryInterval) {