Async Http Client

AsyncHttpClient (AHC) is a high-performance, asynchronous HTTP client for Java built on top of Netty. It supports HTTP/1.1, HTTP/2, and WebSocket protocols.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Configuration
• HTTP Requests
• Handling Responses
• HTTP/2
• WebSocket
• Authentication
• Proxy Support
• Community
• License

Features

• HTTP/2 with multiplexing — enabled by default over TLS via ALPN, with connection multiplexing and GOAWAY handling
• HTTP/1.1 and HTTP/1.0 — connection pooling and keep-alive
• WebSocket — text, binary, and ping/pong frame support
• Asynchronous API — non-blocking I/O with ListenableFuture and CompletableFuture
• Compression — automatic gzip, deflate, Brotli, and Zstd decompression
• Authentication — Basic, Digest, NTLM, SPNEGO/Kerberos, and SCRAM-SHA-256
• Proxy — HTTP, SOCKS4, and SOCKS5 with CONNECT tunneling
• Native transports — optional Epoll, KQueue, and io_uring
• Request/response filters — intercept and transform at each stage
• Cookie management — RFC 6265-compliant cookie store
• Multipart uploads — file, byte array, input stream, and string parts
• Resumable downloads — built-in ResumableIOExceptionFilter

Requirements

Java 11+

Installation

Maven:

<dependency>
<groupId>org.asynchttpclient</groupId>
<artifactId>async-http-client</artifactId>
<version>3.0.12</version>
</dependency>

Gradle:

implementation 'org.asynchttpclient:async-http-client:3.0.12'

Optional: Native Transport

For lower-latency I/O on Linux, add a native transport dependency:

<!-- Epoll (Linux) -->
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-transport-native-epoll</artifactId>
<classifier>linux-x86_64</classifier>
</dependency>
<!-- io_uring (Linux) -->
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-transport-native-io_uring</artifactId>
<classifier>linux-x86_64</classifier>
</dependency>

Then enable in config:

AsyncHttpClientclient = asyncHttpClient(config().setUseNativeTransport(true));

Optional: Brotli / Zstd Compression

<dependency>
<groupId>com.aayushatharva.brotli4j</groupId>
<artifactId>brotli4j</artifactId>
<version>1.20.0</version>
</dependency>
<dependency>
<groupId>com.github.luben</groupId>
<artifactId>zstd-jni</artifactId>
<version>1.5.7-7</version>
</dependency>

Quick Start

Import the DSL helpers:

importstaticorg.asynchttpclient.Dsl.*;

Create a client, execute a request, and read the response:

try (AsyncHttpClientclient = asyncHttpClient()) {
// Asynchronousclient.prepareGet("https://www.example.com/")
.execute()
.toCompletableFuture()
.thenApply(Response::getResponseBody)
.thenAccept(System.out::println)
.join();
// Synchronous (blocking)Responseresponse = client.prepareGet("https://www.example.com/")
.execute()
.get();
}

Note:AsyncHttpClient instances are long-lived, shared resources. Always close them when done. Creating a new client per request will degrade performance due to repeated thread pool and connection pool creation.

Configuration

Use config() to build an AsyncHttpClientConfig:

AsyncHttpClientclient = asyncHttpClient(config()
.setConnectTimeout(Duration.ofSeconds(5))
.setRequestTimeout(Duration.ofSeconds(30))
.setMaxConnections(500)
.setMaxConnectionsPerHost(100)
.setFollowRedirect(true)
.setMaxRedirects(5)
.setCompressionEnforced(true));

HTTP Requests

Sending Requests

Bound — build directly from the client:

Responseresponse = client
.prepareGet("https://api.example.com/users")
.addHeader("Accept", "application/json")
.addQueryParam("page", "1")
.execute()
.get();

Unbound — build standalone via DSL, then execute:

Requestrequest = get("https://api.example.com/users")
.addHeader("Accept", "application/json")
.addQueryParam("page", "1")
.build();
Responseresponse = client.executeRequest(request).get();

Methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE.

Request Bodies

Use setBody to attach a body. Supported types:

Type	Description
String	Text content
byte[]	Raw bytes
ByteBuffer	NIO buffer
InputStream	Streaming input
File	File content
Publisher<ByteBuf>	Reactive stream
BodyGenerator	Custom body generation

Responseresponse = client
.preparePost("https://api.example.com/data")
.setHeader("Content-Type", "application/json")
.setBody("{\"name\": \"value\"}")
.execute()
.get();

For streaming bodies, see FeedableBodyGenerator which lets you push chunks asynchronously.

Multipart Uploads

Responseresponse = client
.preparePost("https://api.example.com/upload")
.addBodyPart(newFilePart("file", newFile("report.pdf"), "application/pdf"))
.addBodyPart(newStringPart("description", "Monthly report"))
.execute()
.get();

Part types: FilePart, ByteArrayPart, InputStreamPart, StringPart.

Handling Responses

Blocking

Responseresponse = client.prepareGet("https://www.example.com/").execute().get();

Useful for debugging, but defeats the purpose of an async client in production.

ListenableFuture

execute() returns a ListenableFuture that supports completion listeners:

ListenableFuture<Response> future = client
.prepareGet("https://www.example.com/")
.execute();
future.addListener(() -> {
Responseresponse = future.get();
System.out.println(response.getStatusCode());
}, executor);

If executor is null, the callback runs on the Netty I/O thread. Never block inside I/O thread callbacks.

CompletableFuture

client.prepareGet("https://www.example.com/")
.execute()
.toCompletableFuture()
.thenApply(Response::getResponseBody)
.thenAccept(System.out::println)
.join();

AsyncCompletionHandler

For most async use cases, extend AsyncCompletionHandler — it buffers the full response and gives you a single onCompleted(Response) callback:

client.prepareGet("https://www.example.com/")
.execute(newAsyncCompletionHandler<String>() {
@OverridepublicStringonCompleted(Responseresponse) {
returnresponse.getResponseBody();
}
});

AsyncHandler

For fine-grained control, implement AsyncHandler directly. This lets you inspect status, headers, and body chunks as they arrive and abort early:

Future<Integer> future = client
.prepareGet("https://www.example.com/")
.execute(newAsyncHandler<>() {
privateintstatus;
@OverridepublicStateonStatusReceived(HttpResponseStatuss) {
status = s.getStatusCode();
returnState.CONTINUE;
}
@OverridepublicStateonHeadersReceived(HttpHeadersheaders) {
returnState.CONTINUE;
}
@OverridepublicStateonBodyPartReceived(HttpResponseBodyPartpart) {
returnState.ABORT; // stop early — we only needed the status
}
@OverridepublicIntegeronCompleted() {
returnstatus;
}
@OverridepublicvoidonThrowable(Throwablet) {
t.printStackTrace();
}
});

HTTP/2

HTTP/2 is enabled by default for HTTPS connections via ALPN negotiation. The client uses HTTP/2 when the server supports it and falls back to HTTP/1.1 otherwise. No additional configuration is required.

• Connection multiplexing — concurrent streams over a single TCP connection
• GOAWAY handling — graceful connection draining on server shutdown
• PING keepalive — configurable ping frames to keep connections alive

HTTP/2 Configuration

AsyncHttpClientclient = asyncHttpClient(config()
.setHttp2MaxConcurrentStreams(100)
.setHttp2InitialWindowSize(65_535)
.setHttp2MaxFrameSize(16_384)
.setHttp2MaxHeaderListSize(8_192)
.setHttp2PingInterval(Duration.ofSeconds(30)) // keepalive pings
.setHttp2CleartextEnabled(true)); // h2c prior knowledge

To force HTTP/1.1, disable HTTP/2:

AsyncHttpClientclient = asyncHttpClient(config().setHttp2Enabled(false));

WebSocket

WebSocketws = client
.prepareGet("wss://echo.example.com/")
.execute(newWebSocketUpgradeHandler.Builder()
.addWebSocketListener(newWebSocketListener() {
@OverridepublicvoidonOpen(WebSocketws) {
ws.sendTextFrame("Hello!");
}
@OverridepublicvoidonTextFrame(Stringpayload, booleanfinalFragment, intrsv) {
System.out.println(payload);
}
@OverridepublicvoidonClose(WebSocketws, intcode, Stringreason) {}
@OverridepublicvoidonError(Throwablet) { t.printStackTrace(); }
})
.build())
.get();

Authentication

// Client-wide Basic authAsyncHttpClientclient = asyncHttpClient(config()
.setRealm(basicAuthRealm("user", "password")));
// Per-request Digest authResponseresponse = client
.prepareGet("https://api.example.com/protected")
.setRealm(digestAuthRealm("user", "password").build())
.execute()
.get();
// SCRAM-SHA-256 (RFC 7804)Responseresponse = client
.prepareGet("https://api.example.com/protected")
.setRealm(scramSha256AuthRealm("user", "password").build())
.execute()
.get();

Supported schemes: Basic, Digest, NTLM, SPNEGO/Kerberos, SCRAM-SHA-256.

Proxy Support

// HTTP proxyAsyncHttpClientclient = asyncHttpClient(config()
.setProxyServer(proxyServer("proxy.example.com", 8080)));
// Authenticated proxyAsyncHttpClientclient = asyncHttpClient(config()
.setProxyServer(proxyServer("proxy.example.com", 8080)
.setRealm(basicAuthRealm("proxyUser", "proxyPassword"))));

SOCKS4 and SOCKS5 proxies are also supported.

Community

• GitHub Discussions — questions, ideas, and general discussion
• Issue Tracker — bug reports and feature requests

License

Apache License 2.0