Add httpClient() method to WebServiceClient.Builder

This allows users to provide a custom HttpClient for full control over
client configuration. When a custom HttpClient is provided, the builder
validates that conflicting parameters (connectTimeout, proxy) are not
also set, ensuring clear configuration ownership.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: horgh

CHANGELOG.md

@@ -1,6 +1,12 @@
 CHANGELOG
 =========
 
+4.4.0
+------------------
+
+* `WebServiceClient.Builder` now has an `httpClient()` method to allow
+  passing in a custom `HttpClient`.
+
 4.3.1 (2025-05-28)
 ------------------
 

src/main/java/com/maxmind/geoip2/WebServiceClient.java

@@ -140,10 +140,16 @@ private WebServiceClient(Builder builder) {
             .build();
 
         requestTimeout = builder.requestTimeout;
-        httpClient = HttpClient.newBuilder()
-            .connectTimeout(builder.connectTimeout)
-            .proxy(builder.proxy)
-            .build();
+
+        // Use custom HttpClient if provided, otherwise create a default one
+        if (builder.httpClient != null) {
+            httpClient = builder.httpClient;
+        } else {
+            httpClient = HttpClient.newBuilder()
+                .connectTimeout(builder.connectTimeout)
+                .proxy(builder.proxy)
+                .build();
+        }
     }
 
     /**
@@ -176,6 +182,7 @@ public static final class Builder {
 
         List<String> locales = Collections.singletonList("en");
         private ProxySelector proxy = ProxySelector.getDefault();
+        private HttpClient httpClient = null;
 
         /**
          * @param accountId  Your MaxMind account ID.
@@ -296,11 +303,38 @@ public Builder proxy(ProxySelector val) {
             return this;
         }
 
+        /**
+         * @param val the custom HttpClient to use for requests. When providing a
+         *            custom HttpClient, you cannot also set connectTimeout or proxy
+         *            parameters as these should be configured on the provided client.
+         * @return Builder object
+         */
+        public Builder httpClient(HttpClient val) {
+            this.httpClient = val;
+            return this;
+        }
+
         /**
          * @return an instance of {@code WebServiceClient} created from the
          * fields set on this builder.
+         * @throws IllegalArgumentException if httpClient is provided along with
+         *                                  connectTimeout or proxy settings
          */
         public WebServiceClient build() {
+            if (httpClient != null) {
+                // Check if connectTimeout was changed from default
+                if (!connectTimeout.equals(Duration.ofSeconds(3))) {
+                    throw new IllegalArgumentException(
+                        "Cannot set both httpClient and connectTimeout. "
+                        + "Configure timeout on the provided HttpClient instead.");
+                }
+                // Check if proxy was changed from default
+                if (proxy != ProxySelector.getDefault()) {
+                    throw new IllegalArgumentException(
+                        "Cannot set both httpClient and proxy. "
+                        + "Configure proxy on the provided HttpClient instead.");
+                }
+            }
             return new WebServiceClient(this);
         }
     }

src/test/java/com/maxmind/geoip2/WebServiceClientTest.java

@@ -36,7 +36,11 @@
 import com.maxmind.geoip2.record.Traits;
 import java.io.UnsupportedEncodingException;
 import java.net.InetAddress;
+import java.net.InetSocketAddress;
+import java.net.ProxySelector;
+import java.net.http.HttpClient;
 import java.nio.charset.StandardCharsets;
+import java.time.Duration;
 import java.util.List;
 import org.hamcrest.CoreMatchers;
 import org.junit.jupiter.api.Test;
@@ -407,4 +411,53 @@ private WebServiceClient createClient(String service, String ip, int status, Str
             .disableHttps()
             .build();
     }
+
+    @Test
+    public void testHttpClientWithConnectTimeoutThrowsException() {
+        HttpClient customClient = HttpClient.newBuilder()
+            .connectTimeout(Duration.ofSeconds(10))
+            .build();
+
+        WebServiceClient.Builder builder = new WebServiceClient.Builder(6, "0123456789")
+            .httpClient(customClient)
+            .connectTimeout(Duration.ofSeconds(5));
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, builder::build);
+        assertEquals("Cannot set both httpClient and connectTimeout. Configure timeout on the provided HttpClient instead.",
+            ex.getMessage());
+    }
+
+    @Test
+    public void testHttpClientWithProxyThrowsException() {
+        HttpClient customClient = HttpClient.newBuilder()
+            .connectTimeout(Duration.ofSeconds(10))
+            .build();
+
+        ProxySelector proxySelector = ProxySelector.of(new InetSocketAddress("proxy.example.com", 8080));
+        WebServiceClient.Builder builder = new WebServiceClient.Builder(6, "0123456789")
+            .httpClient(customClient)
+            .proxy(proxySelector);
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, builder::build);
+        assertEquals("Cannot set both httpClient and proxy. Configure proxy on the provided HttpClient instead.",
+            ex.getMessage());
+    }
+
+    @Test
+    public void testHttpClientWithDefaultSettingsDoesNotThrow() throws Exception {
+        HttpClient customClient = HttpClient.newBuilder()
+            .connectTimeout(Duration.ofSeconds(10))
+            .build();
+
+        // Should not throw because we're not setting connectTimeout or proxy
+        WebServiceClient client = new WebServiceClient.Builder(6, "0123456789")
+            .host("localhost")
+            .port(8080)
+            .disableHttps()
+            .httpClient(customClient)
+            .build();
+
+        assertNotNull(client);
+    }
+
 }