Add CompletableFuture async API backed by a virtual-thread executor

Author: laurentpellegrino

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+- Asynchronous API: `lookupAsync`/`parseAsync` methods on `IpregistryClient` return a `CompletableFuture` and are backed by a virtual-thread-per-task executor by default. The executor is configurable via `IpregistryConfig#executor` (a caller-provided executor is not shut down by the client).
 - 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.

README.md

@@ -175,6 +175,35 @@ IpregistryClient ipregistry =
 
 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.
 
+## Asynchronous API
+
+Every lookup and parse method has an asynchronous variant returning a `CompletableFuture`, suitable for composing non-blocking pipelines:
+
+```java
+IpregistryClient ipregistry = new IpregistryClient("YOUR_API_KEY");
+
+ipregistry.lookupAsync("8.8.8.8")
+        .thenAccept(info -> System.out.println(info.getLocation().getCountry().getName()))
+        .exceptionally(error -> {
+            error.getCause().printStackTrace(); // ApiException or ClientException
+            return null;
+        });
+```
+
+The futures are backed by a virtual-thread-per-task executor (Java 21+), so thousands of concurrent lookups are cheap. A failed request completes the future exceptionally with the same `ApiException`/`ClientException` thrown by the synchronous API (wrapped in a `CompletionException`, so unwrap via `getCause()`).
+
+To use your own executor, set it on the configuration. You then own its lifecycle: it is not shut down when the client is closed.
+
+```java
+IpregistryConfig config =
+        IpregistryConfig.builder()
+                .apiKey("YOUR_API_KEY")
+                .executor(myExecutorService)
+                .build();
+```
+
+Reactive users can bridge these futures directly, for example with `Mono.fromFuture(...)` (Reactor) or `Single.fromCompletionStage(...)` (RxJava).
+
 ## Errors
 
 All Ipregistry exceptions inherit the _IpregistryException_ class.

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

@@ -31,6 +31,10 @@
 import java.net.InetAddress;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
 
 
 /**
@@ -42,6 +46,10 @@ public class IpregistryClient implements Closeable {
 
     private final DefaultRequestHandler requestHandler;
 
+    private final ExecutorService executor;
+
+    private final boolean ownsExecutor;
+
 
     /**
      * Creates a new client instance using the specified {@code apiKey}.
@@ -95,6 +103,14 @@ public IpregistryClient(final IpregistryConfig config, final IpregistryCache cac
     public IpregistryClient(final IpregistryConfig config, final IpregistryCache cache, final DefaultRequestHandler requestHandler) {
         this.cache = cache;
         this.requestHandler = requestHandler;
+
+        if (config.getExecutor() != null) {
+            this.executor = config.getExecutor();
+            this.ownsExecutor = false;
+        } else {
+            this.executor = Executors.newVirtualThreadPerTaskExecutor();
+            this.ownsExecutor = true;
+        }
     }
 
     /**
@@ -246,8 +262,89 @@ public UserAgentList parse(final String... userAgents) throws ApiException, Clie
     }
 
     /**
-     * Releases the resources held by this client, notably the underlying HTTP connection pool.
-     * Once closed, the client must no longer be used.
+     * Asynchronous variant of {@link #lookup(IpregistryOption...)}.
+     *
+     * @param options the options to use when dispatching the request.
+     * @return a future completing with the data found for the origin IP address, or completing
+     * exceptionally with an {@link ApiException} or {@link ClientException}.
+     */
+    public CompletableFuture<RequesterIpInfo> lookupAsync(final IpregistryOption... options) {
+        return supplyAsync(() -> lookup(options));
+    }
+
+    /**
+     * Asynchronous variant of {@link #lookup(String, IpregistryOption...)}.
+     *
+     * @param ip      the IP address to lookup.
+     * @param options the options to use when dispatching the request.
+     * @return a future completing with the data found for the IP address, or completing
+     * exceptionally with an {@link ApiException} or {@link ClientException}.
+     */
+    public CompletableFuture<IpInfo> lookupAsync(final String ip, final IpregistryOption... options) {
+        return supplyAsync(() -> lookup(ip, options));
+    }
+
+    /**
+     * Asynchronous variant of {@link #lookup(InetAddress, IpregistryOption...)}.
+     *
+     * @param ip      the IP address to lookup.
+     * @param options the options to use when dispatching the request.
+     * @return a future completing with the data found for the IP address, or completing
+     * exceptionally with an {@link ApiException} or {@link ClientException}.
+     */
+    public CompletableFuture<IpInfo> lookupAsync(final InetAddress ip, final IpregistryOption... options) {
+        return supplyAsync(() -> lookup(ip, options));
+    }
+
+    /**
+     * Asynchronous variant of {@link #lookup(List, IpregistryOption...)}.
+     *
+     * @param ips     the IP addresses to lookup.
+     * @param options the options to use when dispatching the request.
+     * @return a future completing with the data found for the IP addresses, or completing
+     * exceptionally with an {@link ApiException} or {@link ClientException}.
+     */
+    public CompletableFuture<IpInfoList> lookupAsync(final List<String> ips, final IpregistryOption... options) {
+        return supplyAsync(() -> lookup(ips, options));
+    }
+
+    /**
+     * Asynchronous variant of {@link #parse(String...)}.
+     *
+     * @param userAgents the raw user-agent values.
+     * @return a future completing with the parsed user-agent data, or completing exceptionally with
+     * an {@link ApiException} or {@link ClientException}.
+     */
+    public CompletableFuture<UserAgentList> parseAsync(final String... userAgents) {
+        return supplyAsync(() -> parse(userAgents));
+    }
+
+    private <T> CompletableFuture<T> supplyAsync(final IpregistrySupplier<T> supplier) {
+        return CompletableFuture.supplyAsync(() -> {
+            try {
+                return supplier.get();
+            } catch (final IpregistryException e) {
+                throw new CompletionException(e);
+            }
+        }, executor);
+    }
+
+    /**
+     * A supplier whose computation may fail with an {@link IpregistryException}.
+     *
+     * @param <T> the type of the supplied result.
+     */
+    @FunctionalInterface
+    private interface IpregistrySupplier<T> {
+
+        T get() throws IpregistryException;
+
+    }
+
+    /**
+     * Releases the resources held by this client: the underlying HTTP connection pool and, when the
+     * client created it, the executor backing the asynchronous API. Once closed, the client must no
+     * longer be used.
      *
      * @throws IOException if closing the underlying request handler fails.
      */
@@ -259,6 +356,10 @@ public void close() throws IOException {
             throw e;
         } catch (final Exception e) {
             throw new IOException(e);
+        } finally {
+            if (ownsExecutor) {
+                executor.close();
+            }
         }
     }
 

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

@@ -20,6 +20,8 @@
 import lombok.Getter;
 import lombok.NonNull;
 
+import java.util.concurrent.ExecutorService;
+
 
 /**
  * Configuration settings for the Ipregistry API client.
@@ -51,9 +53,11 @@ public class IpregistryConfig {
      * @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
+     * @param executor the executor backing the asynchronous API, or {@code null} to use a per-client default
      */
     public IpregistryConfig(String apiKey, String baseUrl, int connectionKeepAlive, int connectionTimeout, int socketTimeout,
-                            int retryMaxAttempts, long retryInterval, boolean retryOnServerError, boolean retryOnTooManyRequests) {
+                            int retryMaxAttempts, long retryInterval, boolean retryOnServerError, boolean retryOnTooManyRequests,
+                            ExecutorService executor) {
         this.apiKey = apiKey;
         this.baseUrl = baseUrl;
         this.connectionKeepAlive = connectionKeepAlive;
@@ -63,6 +67,7 @@ public IpregistryConfig(String apiKey, String baseUrl, int connectionKeepAlive,
         this.retryInterval = retryInterval;
         this.retryOnServerError = retryOnServerError;
         this.retryOnTooManyRequests = retryOnTooManyRequests;
+        this.executor = executor;
     }
 
     /**
@@ -133,4 +138,12 @@ public IpregistryConfig(String apiKey, String baseUrl, int connectionKeepAlive,
     @Builder.Default
     private final boolean retryOnTooManyRequests = false;
 
+    /**
+     * The executor backing the asynchronous {@code lookupAsync}/{@code parseAsync} methods. When left
+     * {@code null} (the default), each {@link IpregistryClient} creates and owns a virtual-thread-per-task
+     * executor that is shut down when the client is closed. When a custom executor is supplied, the caller
+     * retains ownership and it is not shut down by the client.
+     */
+    private final ExecutorService executor;
+
 }

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

@@ -35,6 +35,7 @@
 import co.ipregistry.api.client.cache.InMemoryCache;
 import co.ipregistry.api.client.cache.NoCache;
 import co.ipregistry.api.client.cache.IpregistryCache;
+import co.ipregistry.api.client.exceptions.ApiException;
 import co.ipregistry.api.client.exceptions.IpregistryException;
 import co.ipregistry.api.client.model.IpInfo;
 import co.ipregistry.api.client.model.IpInfoList;
@@ -48,6 +49,11 @@
 import java.io.Closeable;
 import java.util.Arrays;
 import java.util.List;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.RejectedExecutionException;
 
 class IpregistryClientTest {
 
@@ -218,4 +224,67 @@ void testInjectedHttpClientNotClosedByClientClose() throws Exception {
         Mockito.verify(httpClient, Mockito.never()).close();
     }
 
+    @Test
+    void testLookupAsyncReturnsValue() throws Exception {
+        final IpregistryConfig config =
+                IpregistryConfig.builder().apiKey("test").build();
+        final IpregistryCache cache = Mockito.spy(new InMemoryCache());
+        final DefaultRequestHandler requestHandler = Mockito.spy(new DefaultRequestHandler(config));
+
+        final IpInfo ipdata = new IpInfo();
+        Mockito.doReturn(ipdata).when(requestHandler).lookup("8.8.8.8");
+
+        try (IpregistryClient client = new IpregistryClient(config, cache, requestHandler)) {
+            final CompletableFuture<IpInfo> future = client.lookupAsync("8.8.8.8");
+            Assertions.assertSame(ipdata, future.get());
+        }
+    }
+
+    @Test
+    void testLookupAsyncCompletesExceptionallyWithApiException() throws Exception {
+        final IpregistryConfig config =
+                IpregistryConfig.builder().apiKey("test").build();
+        final IpregistryCache cache = Mockito.spy(new InMemoryCache());
+        final DefaultRequestHandler requestHandler = Mockito.spy(new DefaultRequestHandler(config));
+
+        Mockito.doThrow(new ApiException("INVALID_API_KEY", "bad key", "fix it"))
+                .when(requestHandler).lookup("8.8.8.8");
+
+        try (IpregistryClient client = new IpregistryClient(config, cache, requestHandler)) {
+            final CompletableFuture<IpInfo> future = client.lookupAsync("8.8.8.8");
+            final ExecutionException ex = Assertions.assertThrows(ExecutionException.class, future::get);
+            Assertions.assertInstanceOf(ApiException.class, ex.getCause());
+        }
+    }
+
+    @Test
+    void testInjectedExecutorNotClosedByClientClose() throws Exception {
+        final ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
+        final IpregistryConfig config =
+                IpregistryConfig.builder().apiKey("test").executor(executor).build();
+        final DefaultRequestHandler requestHandler = Mockito.mock(DefaultRequestHandler.class);
+
+        final IpregistryClient client =
+                new IpregistryClient(config, NoCache.getInstance(), requestHandler);
+        client.close();
+
+        // A caller-provided executor remains owned by the caller and must not be shut down.
+        Assertions.assertFalse(executor.isShutdown());
+        executor.close();
+    }
+
+    @Test
+    void testOwnedExecutorShutDownOnClientClose() throws Exception {
+        final IpregistryConfig config =
+                IpregistryConfig.builder().apiKey("test").build();
+        final DefaultRequestHandler requestHandler = Mockito.mock(DefaultRequestHandler.class);
+
+        final IpregistryClient client =
+                new IpregistryClient(config, NoCache.getInstance(), requestHandler);
+        client.close();
+
+        // The default per-client executor is shut down on close, so further async calls are rejected.
+        Assertions.assertThrows(RejectedExecutionException.class, () -> client.lookupAsync("8.8.8.8"));
+    }
+
 }