Support caller-provided HTTP client with caller-owned lifecycle

Author: laurentpellegrino

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+- Support for a caller-provided `CloseableHttpClient` via new `IpregistryClient` and `DefaultRequestHandler` constructors, allowing full control over connection pooling, proxying, TLS, and metrics. An injected client is not closed by the Ipregistry client (the caller retains ownership).
 - Typed error codes: `ApiException#getErrorCode()` (and `Error#getErrorCode()`) now return a strongly typed `ErrorCode` enum in addition to the raw string `code`, allowing callers to branch on error conditions without string matching. Unrecognized codes return `null` while the raw code remains available.
 - 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.

README.md

@@ -157,6 +157,24 @@ IpregistryConfig config =
                 .build();
 ```
 
+## Custom HTTP client
+
+By default, the client manages its own Apache HttpClient 5 instance (connection pool, timeouts, retries). To take full control — connection pool sizing, a proxy, custom TLS, or metrics — provide your own `CloseableHttpClient`:
+
+```java
+CloseableHttpClient httpClient = HttpClients.custom()
+        // ... your connection manager, proxy, TLS, retry strategy, etc.
+        .build();
+
+IpregistryConfig config =
+        IpregistryConfig.builder().apiKey("YOUR_API_KEY").build();
+
+IpregistryClient ipregistry =
+        new IpregistryClient(config, NoCache.getInstance(), httpClient);
+```
+
+When you supply your own client, you own its lifecycle: it is **not** closed when the Ipregistry client is closed, and the timeout/retry settings from `IpregistryConfig` are ignored in favor of your client's own configuration.
+
 ## Errors
 
 All Ipregistry exceptions inherit the _IpregistryException_ class.

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

@@ -24,6 +24,7 @@
 import co.ipregistry.api.client.model.*;
 import co.ipregistry.api.client.options.IpregistryOption;
 import co.ipregistry.api.client.request.DefaultRequestHandler;
+import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
 
 import java.io.Closeable;
 import java.io.IOException;
@@ -70,6 +71,20 @@ public IpregistryClient(final IpregistryConfig config, final IpregistryCache cac
         this(config, cache, new DefaultRequestHandler(config));
     }
 
+    /**
+     * Creates a new client instance using a caller-provided {@link CloseableHttpClient}.
+     * <p>
+     * The caller keeps ownership of the supplied HTTP client: it is <em>not</em> closed when this
+     * client is closed. Use this to fully control connection pooling, proxying, TLS, or metrics.
+     *
+     * @param config     the configuration instance to use.
+     * @param cache      the cache instance to use.
+     * @param httpClient the HTTP client to use for dispatching requests.
+     */
+    public IpregistryClient(final IpregistryConfig config, final IpregistryCache cache, final CloseableHttpClient httpClient) {
+        this(config, cache, new DefaultRequestHandler(config, httpClient));
+    }
+
     /**
      * Creates a new client instance using the specified {@code config}, {@code cache}, and {@code requestHandler} instances.
      *

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

@@ -58,6 +58,8 @@ public class DefaultRequestHandler implements IpregistryRequestHandler {
 
     private final CloseableHttpClient httpClient;
 
+    private final boolean ownsHttpClient;
+
     private final ObjectMapper objectMapper;
 
 
@@ -67,7 +69,7 @@ public class DefaultRequestHandler implements IpregistryRequestHandler {
      * @param config the configuration instance to use.
      */
     public DefaultRequestHandler(final IpregistryConfig config) {
-        this(config, new ObjectMapper().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false));
+        this(config, defaultObjectMapper());
     }
 
     /**
@@ -77,17 +79,61 @@ public DefaultRequestHandler(final IpregistryConfig config) {
      * @param objectMapper the object mapper instance used for unmarshalling responses.
      */
     public DefaultRequestHandler(final IpregistryConfig config, final ObjectMapper objectMapper) {
+        this(config, objectMapper, buildDefaultHttpClient(config), true);
+    }
+
+    /**
+     * Creates a {@code DefaultRequestHandler} using a caller-provided {@link CloseableHttpClient}.
+     * <p>
+     * The caller keeps ownership of the supplied client: it is <em>not</em> closed when this handler
+     * (or the enclosing {@link co.ipregistry.api.client.IpregistryClient}) is closed. The client's own
+     * request configuration and retry strategy are used; the timeout and retry settings from
+     * {@code config} are ignored.
+     *
+     * @param config     the configuration instance (used for the API key and base URL).
+     * @param httpClient the HTTP client to use for dispatching requests.
+     */
+    public DefaultRequestHandler(final IpregistryConfig config, final CloseableHttpClient httpClient) {
+        this(config, defaultObjectMapper(), httpClient, false);
+    }
+
+    /**
+     * Creates a {@code DefaultRequestHandler} using a caller-provided {@link CloseableHttpClient} and
+     * {@link ObjectMapper}.
+     * <p>
+     * The caller keeps ownership of the supplied client: it is <em>not</em> closed when this handler
+     * (or the enclosing {@link co.ipregistry.api.client.IpregistryClient}) is closed.
+     *
+     * @param config       the configuration instance (used for the API key and base URL).
+     * @param objectMapper the object mapper instance used for unmarshalling responses.
+     * @param httpClient   the HTTP client to use for dispatching requests.
+     */
+    public DefaultRequestHandler(final IpregistryConfig config, final ObjectMapper objectMapper,
+                                 final CloseableHttpClient httpClient) {
+        this(config, objectMapper, httpClient, false);
+    }
+
+    private DefaultRequestHandler(final IpregistryConfig config, final ObjectMapper objectMapper,
+                                  final CloseableHttpClient httpClient, final boolean ownsHttpClient) {
         this.config = config;
         this.objectMapper = objectMapper;
+        this.httpClient = httpClient;
+        this.ownsHttpClient = ownsHttpClient;
+    }
+
+    private static ObjectMapper defaultObjectMapper() {
+        return new ObjectMapper().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
+    }
 
+    private static CloseableHttpClient buildDefaultHttpClient(final IpregistryConfig config) {
         final RequestConfig requestConfig =
                 RequestConfig.custom()
                         .setConnectionKeepAlive(TimeValue.ofMilliseconds(config.getConnectionKeepAlive()))
                         .setConnectionRequestTimeout(config.getConnectionTimeout(), TimeUnit.MILLISECONDS)
                         .setResponseTimeout(config.getSocketTimeout(), TimeUnit.MILLISECONDS)
                         .build();
 
-        this.httpClient = HttpClients.custom()
+        return HttpClients.custom()
                 .setDefaultRequestConfig(requestConfig)
                 .setRetryStrategy(new IpregistryRetryStrategy(
                         config.getRetryMaxAttempts(),
@@ -257,7 +303,11 @@ String toJsonList(final Iterable<String> values) throws JsonProcessingException
 
     @Override
     public void close() throws IOException {
-        httpClient.close();
+        // Only close the HTTP client if this handler created it; a caller-provided client
+        // remains under the caller's ownership.
+        if (ownsHttpClient) {
+            httpClient.close();
+        }
     }
 
 }

src/test/java/co/ipregistry/api/client/IpregistryClientTest.java

@@ -42,6 +42,7 @@
 import co.ipregistry.api.client.request.DefaultRequestHandler;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
+import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
 import org.mockito.Mockito;
 
 import java.io.Closeable;
@@ -202,4 +203,19 @@ void testCloseClosesRequestHandler() throws Exception {
         Mockito.verify(requestHandler).close();
     }
 
+    @Test
+    void testInjectedHttpClientNotClosedByClientClose() throws Exception {
+        final IpregistryConfig config =
+                IpregistryConfig.builder().apiKey("test").build();
+        final CloseableHttpClient httpClient = Mockito.mock(CloseableHttpClient.class);
+
+        final IpregistryClient client =
+                new IpregistryClient(config, NoCache.getInstance(), httpClient);
+
+        client.close();
+
+        // The caller owns the injected client; closing the Ipregistry client must not close it.
+        Mockito.verify(httpClient, Mockito.never()).close();
+    }
+
 }

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

@@ -19,8 +19,10 @@
 import co.ipregistry.api.client.IpregistryConfig;
 import co.ipregistry.api.client.options.IpregistryOption;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
 
 import java.util.Arrays;
 
@@ -60,4 +62,17 @@ void testToJsonListEscapesSpecialCharacters() throws Exception {
         Assertions.assertArrayEquals(values, parsed);
     }
 
+    @Test
+    void testInjectedHttpClientIsNotClosed() throws Exception {
+        final IpregistryConfig config =
+                IpregistryConfig.builder().apiKey("test").build();
+        final CloseableHttpClient httpClient = Mockito.mock(CloseableHttpClient.class);
+
+        final DefaultRequestHandler requestHandler = new DefaultRequestHandler(config, httpClient);
+        requestHandler.close();
+
+        // A caller-provided client remains owned by the caller and must not be closed by the handler.
+        Mockito.verify(httpClient, Mockito.never()).close();
+    }
+
 }