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.14</version>
</dependency>

Gradle:

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

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:

AsyncHttpClient client = asyncHttpClient(config().setUseNativeTransport(true));

<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>

AHC decompresses Brotli, Zstd and Snappy response bodies on demand with Netty's pull-based Decompressor API, which exists since Netty 4.2.17. If you override AHC's Netty version with an older one, these codings are still decompressed, but as soon as they are read, so a suspended response does not hold them back. The same applies to Zstd if the system property io.netty.compression.defaultMaxForwardBytes is set to zero or a negative value. gzip and deflate are not affected.

Over HTTP/1.1, a compressed response body that ends in the middle of its compressed stream, for example because a body delimited by the connection was cut off, fails the request with a DecompressionException; a body without any bytes completes. Not every such end is noticed: Snappy has no end marker, so a body cut between two of its chunks looks complete, and a Zstd body of several frames completes when it is cut inside a frame that started in the same chunk as the end of the previous one. HTTP/2 response bodies are not checked, and neither are transfer codings such as Transfer-Encoding: gzip, nor Brotli, Zstd and Snappy bodies decompressed as soon as they are read, as described above.

Quick Start

Import the DSL helpers:

import static org.asynchttpclient.Dsl.*;

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

try (AsyncHttpClient client = asyncHttpClient()) {
    // Asynchronous
    client.prepareGet("https://www.example.com/")
        .execute()
        .toCompletableFuture()
        .thenApply(Response::getResponseBody)
        .thenAccept(System.out::println)
        .join();

    // Synchronous (blocking)
    Response response = 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:

AsyncHttpClient client = 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:

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

Unbound — build standalone via DSL, then execute:

This is the beginning of the README. Read the rest at the original. Read the full README ↗