0
# HTTP/2 Configuration
1

2
HTTP/2 protocol-specific configuration options for stream management, window sizes, and connection health monitoring in the NettyNioAsyncHttpClient.
3

4
## Capabilities
5

6
### Http2Configuration
7

8
Configuration class for HTTP/2 specific settings including stream limits, window sizes, and health check parameters.
9

10
```java { .api }
11
/**
12
 * Http2Configuration provides HTTP/2 protocol-specific settings for NettyNioAsyncHttpClient.
13
 * Configures stream concurrency, flow control, and connection health monitoring.
14
 */
15
public final class Http2Configuration implements ToCopyableBuilder<Http2Configuration.Builder, Http2Configuration> {
16
    /**
17
     * Returns the maximum number of concurrent streams per HTTP/2 connection
18
     * @return maximum concurrent streams (default: Long.MAX_VALUE)
19
     */
20
    public Long maxStreams();
21
    
22
    /**
23
     * Returns the initial window size for HTTP/2 streams in bytes
24
     * @return initial window size (default: 65535 bytes per RFC 7540)
25
     */
26
    public Integer initialWindowSize();
27
    
28
    /**
29
     * Returns the period for sending health check PING frames
30
     * @return health check ping period (default: null - no health checks)
31
     */
32
    public Duration healthCheckPingPeriod();
33
    
34
    /**
35
     * Creates a new builder from this configuration
36
     * @return builder initialized with current values
37
     */
38
    public Builder toBuilder();
39
    
40
    /**
41
     * Creates a new builder instance
42
     * @return new Builder for HTTP/2 configuration
43
     */
44
    public static Builder builder();
45
    
46
    /**
47
     * Standard equals implementation
48
     */
49
    public boolean equals(Object obj);
50
    
51
    /**
52
     * Standard hashCode implementation
53
     */
54
    public int hashCode();
55
}
56
```
57

58
**Usage Examples:**
59

60
```java
61
import software.amazon.awssdk.http.nio.netty.Http2Configuration;
62
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
63

64
// Basic HTTP/2 configuration
65
Http2Configuration http2Config = Http2Configuration.builder()
66
    .maxStreams(100L)
67
    .initialWindowSize(1024 * 1024)  // 1MB
68
    .healthCheckPingPeriod(Duration.ofSeconds(30))
69
    .build();
70

71
// Use with HTTP client
72
NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
73
    .protocol(Protocol.HTTP2)
74
    .http2Configuration(http2Config)
75
    .build();
76

77
// Consumer-based configuration
78
NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
79
    .protocol(Protocol.HTTP2)
80
    .http2Configuration(builder -> builder
81
        .maxStreams(50L)
82
        .initialWindowSize(512 * 1024)
83
        .healthCheckPingPeriod(Duration.ofMinutes(1)))
84
    .build();
85
```
86

87
### Http2Configuration Builder
88

89
Builder interface for configuring HTTP/2 specific parameters.
90

91
```java { .api }
92
/**
93
 * Builder for configuring HTTP/2 specific parameters
94
 */
95
public interface Builder extends CopyableBuilder<Builder, Http2Configuration> {
96
    /**
97
     * Sets the maximum number of concurrent streams per HTTP/2 connection.
98
     * This limits how many requests can be multiplexed over a single connection.
99
     * 
100
     * @param maxStreams maximum concurrent streams (must be positive, default: Long.MAX_VALUE)
101
     * @return this builder for method chaining
102
     */
103
    Builder maxStreams(Long maxStreams);
104
    
105
    /**
106
     * Sets the initial window size for HTTP/2 stream flow control in bytes.
107
     * This controls the initial amount of data that can be sent without flow control.
108
     * Must comply with RFC 7540 requirements (between 65535 and 2^31-1).
109
     * 
110
     * @param initialWindowSize initial window size in bytes (default: 65535)
111
     * @return this builder for method chaining
112
     */
113
    Builder initialWindowSize(Integer initialWindowSize);
114
    
115
    /**
116
     * Sets the period for sending HTTP/2 PING frames for connection health monitoring.
117
     * When set, the client will periodically send PING frames to detect connection issues.
118
     * 
119
     * @param healthCheckPingPeriod ping period duration (null disables health checks)
120
     * @return this builder for method chaining
121
     */
122
    Builder healthCheckPingPeriod(Duration healthCheckPingPeriod);
123
    
124
    /**
125
     * Builds the HTTP/2 configuration instance
126
     * @return configured Http2Configuration
127
     */
128
    Http2Configuration build();
129
}
130
```
131

132
**Configuration Examples:**
133

134
```java
135
// High-throughput configuration
136
Http2Configuration highThroughput = Http2Configuration.builder()
137
    .maxStreams(200L)                          // Allow 200 concurrent streams
138
    .initialWindowSize(2 * 1024 * 1024)        // 2MB initial window
139
    .healthCheckPingPeriod(Duration.ofSeconds(15))  // Ping every 15 seconds
140
    .build();
141

142
// Conservative configuration for unreliable networks
143
Http2Configuration conservative = Http2Configuration.builder()
144
    .maxStreams(10L)                           // Limit to 10 concurrent streams
145
    .initialWindowSize(64 * 1024)              // 64KB initial window
146
    .healthCheckPingPeriod(Duration.ofSeconds(5))   // Frequent health checks
147
    .build();
148

149
// Disable health checks
150
Http2Configuration noHealthChecks = Http2Configuration.builder()
151
    .maxStreams(100L)
152
    .initialWindowSize(1024 * 1024)
153
    .healthCheckPingPeriod(null)               // No health check pings
154
    .build();
155

156
// Copy and modify existing configuration
157
Http2Configuration modified = existingConfig.toBuilder()
158
    .maxStreams(150L)                          // Change only max streams
159
    .build();
160
```
161

162
## HTTP/2 Performance Tuning
163

164
### Stream Concurrency
165

166
The `maxStreams` setting controls how many HTTP requests can be multiplexed over a single HTTP/2 connection:
167

168
```java
169
// For high-throughput scenarios
170
Http2Configuration.builder()
171
    .maxStreams(500L)  // Allow many concurrent streams
172
    .build();
173

174
// For memory-constrained environments
175
Http2Configuration.builder()
176
    .maxStreams(20L)   // Limit concurrent streams
177
    .build();
178
```
179

180
### Flow Control Window Size
181

182
The `initialWindowSize` affects throughput and memory usage:
183

184
```java
185
// Large window for high-bandwidth connections
186
Http2Configuration.builder()
187
    .initialWindowSize(4 * 1024 * 1024)  // 4MB - higher throughput, more memory
188
    .build();
189

190
// Small window for bandwidth-limited connections
191
Http2Configuration.builder()
192
    .initialWindowSize(64 * 1024)        // 64KB - lower memory, may limit throughput
193
    .build();
194
```
195

196
### Connection Health Monitoring
197

198
Health check pings help detect broken connections:
199

200
```java
201
// Aggressive health checking for critical applications
202
Http2Configuration.builder()
203
    .healthCheckPingPeriod(Duration.ofSeconds(10))
204
    .build();
205

206
// Conservative health checking to reduce overhead
207
Http2Configuration.builder()
208
    .healthCheckPingPeriod(Duration.ofMinutes(2))
209
    .build();
210

211
// Disable health checking (rely on other mechanisms)
212
Http2Configuration.builder()
213
    .healthCheckPingPeriod(null)
214
    .build();
215
```
216

217
## Integration with HTTP Client
218

219
### Protocol Selection
220

221
HTTP/2 configuration only applies when HTTP/2 protocol is selected:
222

223
```java
224
NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
225
    .protocol(Protocol.HTTP2)              // Must specify HTTP/2
226
    .protocolNegotiation(ProtocolNegotiation.ALPN)  // Use ALPN negotiation
227
    .http2Configuration(Http2Configuration.builder()
228
        .maxStreams(100L)
229
        .initialWindowSize(1024 * 1024)
230
        .build())
231
    .build();
232
```
233

234
### ALPN vs Prior Knowledge
235

236
Protocol negotiation affects how HTTP/2 is established:
237

238
```java
239
// ALPN negotiation (recommended for HTTPS)
240
NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
241
    .protocol(Protocol.HTTP2)
242
    .protocolNegotiation(ProtocolNegotiation.ALPN)  // Negotiate during TLS handshake
243
    .http2Configuration(http2Config)
244
    .build();
245

246
// Prior knowledge (for known HTTP/2 servers)
247
NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
248
    .protocol(Protocol.HTTP2)
249
    .protocolNegotiation(ProtocolNegotiation.ASSUME_PROTOCOL)  // Assume HTTP/2
250
    .http2Configuration(http2Config)
251
    .build();
252
```
253

254
## Types
255

256
### HTTP/2 Protocol Types
257

258
```java { .api }
259
enum Protocol {
260
    HTTP1_1,  // HTTP/1.1 protocol
261
    HTTP2     // HTTP/2 protocol
262
}
263

264
enum ProtocolNegotiation {
265
    ALPN,              // Application Layer Protocol Negotiation (RFC 7301)
266
    ASSUME_PROTOCOL    // Assume configured protocol without negotiation
267
}
268
```
269

270
### Builder Pattern Types
271

272
```java { .api }
273
interface ToCopyableBuilder<B extends CopyableBuilder<B, T>, T> {
274
    B toBuilder();
275
}
276

277
interface CopyableBuilder<B extends CopyableBuilder<B, T>, T> {
278
    T build();
279
}
280
```
281

282
### Duration Type
283

284
```java { .api }
285
// Standard Java duration type for time-based configurations
286
class Duration {
287
    static Duration ofSeconds(long seconds);
288
    static Duration ofMillis(long millis);
289
    static Duration ofMinutes(long minutes);
290
    static Duration ofHours(long hours);
291
    
292
    long toSeconds();
293
    long toMillis();
294
}
295
```
296

297
## HTTP/2 Specification Compliance
298

299
The Http2Configuration follows RFC 7540 (HTTP/2) specifications:
300

301
- **Initial Window Size**: Must be between 65,535 bytes (default) and 2^31-1 bytes
302
- **Stream Concurrency**: Controlled by SETTINGS_MAX_CONCURRENT_STREAMS
303
- **Flow Control**: Implements HTTP/2 flow control mechanisms
304
- **Health Checks**: Uses HTTP/2 PING frames for connection validation