0
# HTTP Client Configuration
1

2
Comprehensive configuration options for the NettyNioAsyncHttpClient including connection management, timeouts, protocol selection, and advanced Netty-specific settings.
3

4
## Capabilities
5

6
### NettyNioAsyncHttpClient
7

8
The main HTTP client implementation providing asynchronous HTTP communication with AWS services.
9

10
```java { .api }
11
/**
12
 * NettyNioAsyncHttpClient provides non-blocking HTTP communication using Netty NIO.
13
 * Supports HTTP/1.1 and HTTP/2 with configurable connection pooling and timeouts.
14
 */
15
public final class NettyNioAsyncHttpClient implements SdkAsyncHttpClient {
16
    /**
17
     * Executes an asynchronous HTTP request
18
     * @param request the HTTP request to execute including headers, body, and response handler
19
     * @return CompletableFuture that completes when the response is fully processed
20
     */
21
    public CompletableFuture<Void> execute(AsyncExecuteRequest request);
22
    
23
    /**
24
     * Closes the HTTP client and releases all resources including connection pools and event loops
25
     */
26
    public void close();
27
    
28
    /**
29
     * Returns the client name identifier
30
     * @return "NettyNio" - the client identifier constant
31
     */
32
    public String clientName();
33
    
34
    /**
35
     * Creates a new builder for configuring the HTTP client
36
     * @return new Builder instance
37
     */
38
    public static Builder builder();
39
    
40
    /**
41
     * Creates an HTTP client with default configuration
42
     * @return configured SdkAsyncHttpClient instance
43
     */
44
    public static SdkAsyncHttpClient create();
45
}
46
```
47

48
**Usage Examples:**
49

50
```java
51
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
52
import software.amazon.awssdk.core.client.config.SdkClientConfiguration;
53

54
// Default configuration
55
SdkAsyncHttpClient client = NettyNioAsyncHttpClient.create();
56

57
// Custom configuration
58
SdkAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
59
    .maxConcurrency(50)
60
    .connectionTimeout(Duration.ofSeconds(10))
61
    .readTimeout(Duration.ofSeconds(30))
62
    .writeTimeout(Duration.ofSeconds(30))
63
    .protocol(Protocol.HTTP2)
64
    .build();
65

66
// Use with AWS service
67
S3AsyncClient s3 = S3AsyncClient.builder()
68
    .httpClient(client)
69
    .build();
70
```
71

72
### Builder Configuration
73

74
Comprehensive builder interface for configuring NettyNioAsyncHttpClient instances.
75

76
```java { .api }
77
/**
78
 * Builder interface for configuring NettyNioAsyncHttpClient instances
79
 */
80
public interface Builder extends SdkAsyncHttpClient.Builder<Builder> {
81
    /**
82
     * Sets the maximum number of concurrent connections/requests
83
     * @param maxConcurrency maximum concurrency (default: 50)
84
     * @return this builder for method chaining
85
     */
86
    Builder maxConcurrency(Integer maxConcurrency);
87
    
88
    /**
89
     * Sets the maximum number of pending connection acquisitions from the pool
90
     * @param maxPendingConnectionAcquires maximum pending acquisitions (default: 10000)
91
     * @return this builder for method chaining
92
     */
93
    Builder maxPendingConnectionAcquires(Integer maxPendingConnectionAcquires);
94
    
95
    /**
96
     * Sets the socket read timeout duration
97
     * @param readTimeout read timeout (default: 30 seconds)
98
     * @return this builder for method chaining
99
     */
100
    Builder readTimeout(Duration readTimeout);
101
    
102
    /**
103
     * Sets the socket write timeout duration
104
     * @param writeTimeout write timeout (default: 30 seconds)
105
     * @return this builder for method chaining
106
     */
107
    Builder writeTimeout(Duration writeTimeout);
108
    
109
    /**
110
     * Sets the connection establishment timeout
111
     * @param connectionTimeout connection timeout (default: 10 seconds)
112
     * @return this builder for method chaining
113
     */
114
    Builder connectionTimeout(Duration connectionTimeout);
115
    
116
    /**
117
     * Sets the connection pool acquisition timeout
118
     * @param connectionAcquisitionTimeout acquisition timeout (default: 10 seconds)
119
     * @return this builder for method chaining
120
     */
121
    Builder connectionAcquisitionTimeout(Duration connectionAcquisitionTimeout);
122
    
123
    /**
124
     * Sets the maximum connection lifetime (time-to-live)
125
     * @param connectionTimeToLive connection TTL (default: infinite)
126
     * @return this builder for method chaining
127
     */
128
    Builder connectionTimeToLive(Duration connectionTimeToLive);
129
    
130
    /**
131
     * Sets the maximum connection idle time before closure
132
     * @param connectionMaxIdleTime max idle time (default: 60 seconds)
133
     * @return this builder for method chaining
134
     */
135
    Builder connectionMaxIdleTime(Duration connectionMaxIdleTime);
136
    
137
    /**
138
     * Sets the TLS handshake timeout duration
139
     * @param tlsNegotiationTimeout TLS timeout (default: 10 seconds)
140
     * @return this builder for method chaining
141
     */
142
    Builder tlsNegotiationTimeout(Duration tlsNegotiationTimeout);
143
    
144
    /**
145
     * Enables or disables idle connection cleanup
146
     * @param useIdleConnectionReaper true to enable reaper (default: true)
147
     * @return this builder for method chaining
148
     */
149
    Builder useIdleConnectionReaper(Boolean useIdleConnectionReaper);
150
    
151
    /**
152
     * Sets custom event loop group (caller manages lifecycle)
153
     * @param eventLoopGroup custom event loop group
154
     * @return this builder for method chaining
155
     */
156
    Builder eventLoopGroup(SdkEventLoopGroup eventLoopGroup);
157
    
158
    /**
159
     * Sets event loop group builder (SDK manages lifecycle)
160
     * @param eventLoopGroupBuilder event loop builder
161
     * @return this builder for method chaining
162
     */
163
    Builder eventLoopGroupBuilder(SdkEventLoopGroup.Builder eventLoopGroupBuilder);
164
    
165
    /**
166
     * Sets the HTTP protocol version
167
     * @param protocol HTTP/1.1 or HTTP/2 (default: HTTP/1.1)
168
     * @return this builder for method chaining
169
     */
170
    Builder protocol(Protocol protocol);
171
    
172
    /**
173
     * Sets the protocol negotiation strategy
174
     * @param protocolNegotiation ALPN or ASSUME_PROTOCOL (default: ALPN for HTTPS)
175
     * @return this builder for method chaining
176
     */
177
    Builder protocolNegotiation(ProtocolNegotiation protocolNegotiation);
178
    
179
    /**
180
     * Enables or disables TCP keep-alive
181
     * @param tcpKeepAlive true to enable keep-alive (default: false)
182
     * @return this builder for method chaining
183
     */
184
    Builder tcpKeepAlive(Boolean tcpKeepAlive);
185
    
186
    /**
187
     * Adds a custom Netty channel option
188
     * @param channelOption the channel option to set
189
     * @param value the value for the option
190
     * @return this builder for method chaining
191
     */
192
    Builder putChannelOption(ChannelOption channelOption, Object value);
193
    
194
    /**
195
     * Sets the maximum number of concurrent HTTP/2 streams per connection
196
     * @param maxHttp2Streams maximum concurrent HTTP/2 streams
197
     * @return this builder for method chaining
198
     * @deprecated Use http2Configuration(Http2Configuration) with Http2Configuration.Builder.maxStreams(Long) instead
199
     */
200
    @Deprecated
201
    Builder maxHttp2Streams(Integer maxHttp2Streams);
202
    
203
    /**
204
     * Sets the SSL provider implementation
205
     * @param sslProvider JDK, OPENSSL, or OPENSSL_REFCNT (default: OPENSSL if available)
206
     * @return this builder for method chaining
207
     */
208
    Builder sslProvider(SslProvider sslProvider);
209
    
210
    /**
211
     * Sets proxy configuration
212
     * @param proxyConfiguration proxy settings
213
     * @return this builder for method chaining
214
     */
215
    Builder proxyConfiguration(ProxyConfiguration proxyConfiguration);
216
    
217
    /**
218
     * Sets TLS key managers provider for client certificates
219
     * @param tlsKeyManagersProvider key manager provider
220
     * @return this builder for method chaining
221
     */
222
    Builder tlsKeyManagersProvider(TlsKeyManagersProvider tlsKeyManagersProvider);
223
    
224
    /**
225
     * Sets TLS trust managers provider for server certificate validation
226
     * @param tlsTrustManagersProvider trust manager provider
227
     * @return this builder for method chaining
228
     */
229
    Builder tlsTrustManagersProvider(TlsTrustManagersProvider tlsTrustManagersProvider);
230
    
231
    /**
232
     * Sets HTTP/2 specific configuration
233
     * @param http2Configuration HTTP/2 settings
234
     * @return this builder for method chaining
235
     */
236
    Builder http2Configuration(Http2Configuration http2Configuration);
237
    
238
    /**
239
     * Sets HTTP/2 configuration via consumer
240
     * @param http2ConfigurationBuilder consumer to configure HTTP/2 settings
241
     * @return this builder for method chaining
242
     */
243
    Builder http2Configuration(Consumer<Http2Configuration.Builder> http2ConfigurationBuilder);
244
    
245
    /**
246
     * Enables or disables non-blocking DNS resolution
247
     * @param useNonBlockingDnsResolver true to enable non-blocking DNS (default: true)
248
     * @return this builder for method chaining
249
     */
250
    Builder useNonBlockingDnsResolver(Boolean useNonBlockingDnsResolver);
251
    
252
    /**
253
     * Builds the configured NettyNioAsyncHttpClient
254
     * @return configured HTTP client instance
255
     */
256
    NettyNioAsyncHttpClient build();
257
}
258
```
259

260
**Configuration Examples:**
261

262
```java
263
// High-throughput configuration
264
NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
265
    .maxConcurrency(200)
266
    .maxPendingConnectionAcquires(1000)
267
    .connectionTimeout(Duration.ofSeconds(5))
268
    .readTimeout(Duration.ofMinutes(2))
269
    .writeTimeout(Duration.ofMinutes(2))
270
    .connectionMaxIdleTime(Duration.ofMinutes(1))
271
    .useIdleConnectionReaper(true)
272
    .protocol(Protocol.HTTP2)
273
    .tcpKeepAlive(true)
274
    .build();
275

276
// Custom event loop configuration
277
SdkEventLoopGroup eventLoopGroup = SdkEventLoopGroup.builder()
278
    .numberOfThreads(8)
279
    .build();
280
    
281
NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
282
    .eventLoopGroup(eventLoopGroup)
283
    .build();
284

285
// SSL/TLS configuration
286
NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
287
    .sslProvider(SslProvider.OPENSSL)
288
    .tlsNegotiationTimeout(Duration.ofSeconds(15))
289
    .tlsKeyManagersProvider(myKeyManagersProvider)
290
    .tlsTrustManagersProvider(myTrustManagersProvider)
291
    .build();
292
```
293

294
## Types
295

296
### Core HTTP Types
297

298
```java { .api }
299
interface SdkAsyncHttpClient extends SdkHttpClient {
300
    CompletableFuture<Void> execute(AsyncExecuteRequest request);
301
    void close();
302
    String clientName();
303
}
304

305
interface AsyncExecuteRequest {
306
    SdkHttpRequest request();
307
    AsyncRequestBody requestBody();
308
    ResponseHandler responseHandler();
309
}
310

311
enum Protocol {
312
    HTTP1_1,  // HTTP/1.1 protocol
313
    HTTP2     // HTTP/2 protocol
314
}
315

316
enum ProtocolNegotiation {
317
    ALPN,              // Application Layer Protocol Negotiation
318
    ASSUME_PROTOCOL    // Assume configured protocol without negotiation
319
}
320

321
enum SslProvider {
322
    JDK,               // Use JDK's SSL implementation
323
    OPENSSL,           // Use OpenSSL implementation
324
    OPENSSL_REFCNT     // Use OpenSSL with reference counting
325
}
326
```
327

328
### Netty Channel Configuration
329

330
```java { .api }
331
// Common Netty channel options that can be used with putChannelOption()
332
class ChannelOption<T> {
333
    static final ChannelOption<Boolean> SO_KEEPALIVE;
334
    static final ChannelOption<Boolean> TCP_NODELAY;
335
    static final ChannelOption<Integer> SO_TIMEOUT;
336
    static final ChannelOption<Integer> CONNECT_TIMEOUT_MILLIS;
337
}
338
```