Add configurable retry with backoff for 5xx, network errors, and opt-in 429

Author: laurentpellegrino

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+- Automatic retries with exponential backoff for transient network errors and 5xx server responses, configurable via `IpregistryConfig` (`retryMaxAttempts`, `retryInterval`, `retryOnServerError`, `retryOnTooManyRequests`). Retries on 429 Too Many Requests are disabled by default and honor the `Retry-After` header when enabled.
 - `IpregistryClient` now implements `Closeable` to release the underlying HTTP connection pool.
 
 ### Fixed

README.md

@@ -140,6 +140,23 @@ InMemoryCache cache =
 
 You can also provide your own cache implementation by implementing the _IpregistryCache_ interface.
 
+## Retries
+
+Failed requests are automatically retried with an exponential backoff. By default, up to 3 retries are performed on transient network errors and 5xx server responses.
+
+Because Ipregistry does not rate limit by default (rate limiting is opt-in per API key), retries on _429 Too Many Requests_ responses are **disabled by default**. Enable them if your API key is configured with a rate limit and you want the client to wait and retry (honoring the `Retry-After` header when present):
+
+```java
+IpregistryConfig config =
+        IpregistryConfig.builder()
+                .apiKey("YOUR_API_KEY")
+                .retryMaxAttempts(3)          // 0 disables retries entirely
+                .retryInterval(1000)          // base backoff in milliseconds
+                .retryOnServerError(true)     // retry on 5xx (default: true)
+                .retryOnTooManyRequests(true) // retry on 429 (default: false)
+                .build();
+```
+
 ## Errors
 
 All Ipregistry exceptions inherit the _IpregistryException_ class.

src/main/java/co/ipregistry/api/client/IpregistryConfig.java

@@ -47,13 +47,22 @@ public class IpregistryConfig {
      * @param connectionKeepAlive connection keep-alive timeout
      * @param connectionTimeout connection timeout
      * @param socketTimeout socket timeout
+     * @param retryMaxAttempts the maximum number of automatic retries
+     * @param retryInterval the base backoff interval, in milliseconds
+     * @param retryOnServerError whether to retry on 5xx server errors
+     * @param retryOnTooManyRequests whether to retry on 429 Too Many Requests
      */
-    public IpregistryConfig(String apiKey, String baseUrl, int connectionKeepAlive, int connectionTimeout, int socketTimeout) {
+    public IpregistryConfig(String apiKey, String baseUrl, int connectionKeepAlive, int connectionTimeout, int socketTimeout,
+                            int retryMaxAttempts, long retryInterval, boolean retryOnServerError, boolean retryOnTooManyRequests) {
         this.apiKey = apiKey;
         this.baseUrl = baseUrl;
         this.connectionKeepAlive = connectionKeepAlive;
         this.connectionTimeout = connectionTimeout;
         this.socketTimeout = socketTimeout;
+        this.retryMaxAttempts = retryMaxAttempts;
+        this.retryInterval = retryInterval;
+        this.retryOnServerError = retryOnServerError;
+        this.retryOnTooManyRequests = retryOnTooManyRequests;
     }
 
     /**
@@ -94,4 +103,34 @@ public IpregistryConfig(String apiKey, String baseUrl, int connectionKeepAlive,
     @Builder.Default
     private final int socketTimeout = 15000;
 
+    /**
+     * The maximum number of times a failed request is automatically retried (in addition to the
+     * initial attempt). Set to {@code 0} to disable retries entirely. Defaults to 3.
+     */
+    @Builder.Default
+    private final int retryMaxAttempts = 3;
+
+    /**
+     * The base backoff interval in milliseconds used between retries. Successive retries use an
+     * exponentially increasing delay ({@code retryInterval * 2^(attempt - 1)}). When a 429 response
+     * carries a {@code Retry-After} header, that value takes precedence. Defaults to 1000 milliseconds.
+     */
+    @Builder.Default
+    private final long retryInterval = 1000;
+
+    /**
+     * Whether requests failing with a 5xx server error (or a transient network error) should be
+     * retried automatically. Defaults to {@code true}.
+     */
+    @Builder.Default
+    private final boolean retryOnServerError = true;
+
+    /**
+     * Whether requests failing with a 429 Too Many Requests response should be retried automatically.
+     * Ipregistry does not rate limit by default (it is opt-in per API key), so a 429 usually reflects
+     * a deliberately configured limit; retrying is therefore disabled by default. Defaults to {@code false}.
+     */
+    @Builder.Default
+    private final boolean retryOnTooManyRequests = false;
+
 }

src/main/java/co/ipregistry/api/client/request/DefaultRequestHandler.java

@@ -89,6 +89,11 @@ public DefaultRequestHandler(final IpregistryConfig config, final ObjectMapper o
 
         this.httpClient = HttpClients.custom()
                 .setDefaultRequestConfig(requestConfig)
+                .setRetryStrategy(new IpregistryRetryStrategy(
+                        config.getRetryMaxAttempts(),
+                        config.getRetryInterval(),
+                        config.isRetryOnServerError(),
+                        config.isRetryOnTooManyRequests()))
                 .build();
     }
 

src/main/java/co/ipregistry/api/client/request/IpregistryRetryStrategy.java

@@ -0,0 +1,145 @@
+/*
+ * Copyright 2019 Ipregistry (https://ipregistry.co).
+ *
+ * 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 co.ipregistry.api.client.request;
+
+import org.apache.hc.client5.http.HttpRequestRetryStrategy;
+import org.apache.hc.core5.http.Header;
+import org.apache.hc.core5.http.HttpHeaders;
+import org.apache.hc.core5.http.HttpRequest;
+import org.apache.hc.core5.http.HttpResponse;
+import org.apache.hc.core5.http.HttpStatus;
+import org.apache.hc.core5.http.protocol.HttpContext;
+import org.apache.hc.core5.util.TimeValue;
+
+import javax.net.ssl.SSLException;
+import java.io.IOException;
+import java.io.InterruptedIOException;
+import java.net.ConnectException;
+import java.net.NoRouteToHostException;
+import java.net.UnknownHostException;
+import java.util.Arrays;
+import java.util.List;
+
+
+/**
+ * Retry strategy used by the Ipregistry HTTP client.
+ * <p>
+ * Retries are attempted, up to a configurable maximum, in the following cases:
+ * <ul>
+ *     <li>transient network failures ({@link IOException}s that are not clearly permanent);</li>
+ *     <li>5xx server error responses, when enabled;</li>
+ *     <li>429 Too Many Requests responses, when enabled.</li>
+ * </ul>
+ * Retries use an exponential backoff based on a configurable interval. For 429 responses carrying a
+ * {@code Retry-After} header expressed in seconds, that value takes precedence over the computed backoff.
+ */
+public class IpregistryRetryStrategy implements HttpRequestRetryStrategy {
+
+    /**
+     * Exceptions that are considered permanent and therefore never retried.
+     */
+    private static final List<Class<? extends IOException>> NON_RETRIABLE_EXCEPTIONS = Arrays.asList(
+            InterruptedIOException.class,
+            UnknownHostException.class,
+            ConnectException.class,
+            NoRouteToHostException.class,
+            SSLException.class);
+
+    private final int maxAttempts;
+
+    private final long intervalMillis;
+
+    private final boolean retryOnServerError;
+
+    private final boolean retryOnTooManyRequests;
+
+
+    /**
+     * Creates a new retry strategy.
+     *
+     * @param maxAttempts            the maximum number of retries (in addition to the initial attempt).
+     * @param intervalMillis         the base backoff interval, in milliseconds.
+     * @param retryOnServerError     whether to retry on 5xx server errors.
+     * @param retryOnTooManyRequests whether to retry on 429 Too Many Requests responses.
+     */
+    public IpregistryRetryStrategy(final int maxAttempts, final long intervalMillis,
+                                   final boolean retryOnServerError, final boolean retryOnTooManyRequests) {
+        this.maxAttempts = maxAttempts;
+        this.intervalMillis = intervalMillis;
+        this.retryOnServerError = retryOnServerError;
+        this.retryOnTooManyRequests = retryOnTooManyRequests;
+    }
+
+    @Override
+    public boolean retryRequest(final HttpRequest request, final IOException exception,
+                                final int execCount, final HttpContext context) {
+        if (execCount > maxAttempts) {
+            return false;
+        }
+
+        for (final Class<? extends IOException> nonRetriable : NON_RETRIABLE_EXCEPTIONS) {
+            if (nonRetriable.isInstance(exception)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    @Override
+    public boolean retryRequest(final HttpResponse response, final int execCount, final HttpContext context) {
+        if (execCount > maxAttempts) {
+            return false;
+        }
+
+        final int code = response.getCode();
+
+        if (code == HttpStatus.SC_TOO_MANY_REQUESTS) {
+            return retryOnTooManyRequests;
+        }
+
+        if (code >= 500 && code < 600) {
+            return retryOnServerError;
+        }
+
+        return false;
+    }
+
+    @Override
+    public TimeValue getRetryInterval(final HttpResponse response, final int execCount, final HttpContext context) {
+        final Header retryAfter = response.getFirstHeader(HttpHeaders.RETRY_AFTER);
+
+        if (retryAfter != null && retryAfter.getValue() != null) {
+            try {
+                final long seconds = Long.parseLong(retryAfter.getValue().trim());
+                if (seconds >= 0) {
+                    return TimeValue.ofSeconds(seconds);
+                }
+            } catch (final NumberFormatException ignored) {
+                // Retry-After expressed as an HTTP date is not honored; fall back to exponential backoff.
+            }
+        }
+
+        return exponentialBackoff(execCount);
+    }
+
+    private TimeValue exponentialBackoff(final int execCount) {
+        final int shift = Math.min(Math.max(execCount - 1, 0), 30);
+        return TimeValue.ofMilliseconds(intervalMillis * (1L << shift));
+    }
+
+}

src/test/java/co/ipregistry/api/client/request/IpregistryRetryStrategyTest.java

@@ -0,0 +1,111 @@
+/*
+ * Copyright 2019 Ipregistry (https://ipregistry.co).
+ *
+ * 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 co.ipregistry.api.client.request;
+
+import org.apache.hc.core5.http.HttpResponse;
+import org.apache.hc.core5.http.message.BasicHttpResponse;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+import javax.net.ssl.SSLException;
+import java.io.IOException;
+import java.net.ConnectException;
+import java.net.SocketTimeoutException;
+import java.net.UnknownHostException;
+
+class IpregistryRetryStrategyTest {
+
+    private static HttpResponse response(final int code) {
+        return new BasicHttpResponse(code);
+    }
+
+    @Test
+    void testRetriesOnServerErrorWhenEnabled() {
+        final IpregistryRetryStrategy strategy = new IpregistryRetryStrategy(3, 1000, true, false);
+        Assertions.assertTrue(strategy.retryRequest(response(500), 1, null));
+        Assertions.assertTrue(strategy.retryRequest(response(503), 1, null));
+        Assertions.assertTrue(strategy.retryRequest(response(599), 1, null));
+    }
+
+    @Test
+    void testDoesNotRetryServerErrorWhenDisabled() {
+        final IpregistryRetryStrategy strategy = new IpregistryRetryStrategy(3, 1000, false, false);
+        Assertions.assertFalse(strategy.retryRequest(response(500), 1, null));
+        Assertions.assertFalse(strategy.retryRequest(response(503), 1, null));
+    }
+
+    @Test
+    void testRetriesTooManyRequestsOnlyWhenEnabled() {
+        Assertions.assertFalse(new IpregistryRetryStrategy(3, 1000, true, false)
+                .retryRequest(response(429), 1, null));
+        Assertions.assertTrue(new IpregistryRetryStrategy(3, 1000, true, true)
+                .retryRequest(response(429), 1, null));
+    }
+
+    @Test
+    void testDoesNotRetryClientErrorsOrSuccess() {
+        final IpregistryRetryStrategy strategy = new IpregistryRetryStrategy(3, 1000, true, true);
+        Assertions.assertFalse(strategy.retryRequest(response(200), 1, null));
+        Assertions.assertFalse(strategy.retryRequest(response(400), 1, null));
+        Assertions.assertFalse(strategy.retryRequest(response(401), 1, null));
+        Assertions.assertFalse(strategy.retryRequest(response(404), 1, null));
+    }
+
+    @Test
+    void testStopsAfterMaxAttempts() {
+        final IpregistryRetryStrategy strategy = new IpregistryRetryStrategy(2, 1000, true, true);
+        Assertions.assertTrue(strategy.retryRequest(response(500), 1, null));
+        Assertions.assertTrue(strategy.retryRequest(response(500), 2, null));
+        Assertions.assertFalse(strategy.retryRequest(response(500), 3, null));
+    }
+
+    @Test
+    void testRetriesTransientIoExceptionButNotPermanentOnes() {
+        final IpregistryRetryStrategy strategy = new IpregistryRetryStrategy(3, 1000, true, false);
+        Assertions.assertTrue(strategy.retryRequest(null, new IOException("reset"), 1, null));
+
+        Assertions.assertFalse(strategy.retryRequest(null, new SocketTimeoutException(), 1, null));
+        Assertions.assertFalse(strategy.retryRequest(null, new UnknownHostException(), 1, null));
+        Assertions.assertFalse(strategy.retryRequest(null, new ConnectException(), 1, null));
+        Assertions.assertFalse(strategy.retryRequest(null, new SSLException("bad"), 1, null));
+
+        Assertions.assertFalse(strategy.retryRequest(null, new IOException("reset"), 4, null));
+    }
+
+    @Test
+    void testExponentialBackoff() {
+        final IpregistryRetryStrategy strategy = new IpregistryRetryStrategy(5, 1000, true, true);
+        Assertions.assertEquals(1000, strategy.getRetryInterval(response(500), 1, null).toMilliseconds());
+        Assertions.assertEquals(2000, strategy.getRetryInterval(response(500), 2, null).toMilliseconds());
+        Assertions.assertEquals(4000, strategy.getRetryInterval(response(500), 3, null).toMilliseconds());
+    }
+
+    @Test
+    void testRetryAfterHeaderTakesPrecedence() {
+        final IpregistryRetryStrategy strategy = new IpregistryRetryStrategy(5, 1000, true, true);
+
+        final HttpResponse withRetryAfter = response(429);
+        withRetryAfter.setHeader("Retry-After", "5");
+        Assertions.assertEquals(5000, strategy.getRetryInterval(withRetryAfter, 1, null).toMilliseconds());
+
+        // A non-numeric (HTTP-date) Retry-After is not honored and falls back to exponential backoff.
+        final HttpResponse httpDate = response(429);
+        httpDate.setHeader("Retry-After", "Wed, 21 Oct 2026 07:28:00 GMT");
+        Assertions.assertEquals(1000, strategy.getRetryInterval(httpDate, 1, null).toMilliseconds());
+    }
+
+}