0
# HTTP/2 Handler
1

2
The NodeHttp2Handler provides HTTP/2 request handling using Node.js http2 module with session pooling, concurrent stream management, and comprehensive configuration options.
3

4
## Capabilities
5

6
### NodeHttp2Handler Class
7

8
HTTP/2 request handler implementing the HttpHandler interface with advanced session and stream management.
9

10
```typescript { .api }
11
/**
12
 * A request handler using the node:http2 package.
13
 */
14
class NodeHttp2Handler implements HttpHandler<NodeHttp2HandlerOptions> {
15
  /**
16
   * Create a new HTTP/2 handler instance
17
   * @param options - Handler configuration options or provider function
18
   */
19
  constructor(options?: NodeHttp2HandlerOptions | Provider<NodeHttp2HandlerOptions | void>);
20
  
21
  /**
22
   * Factory method to create handler instance or return existing HttpHandler
23
   * @param instanceOrOptions - Existing handler, options, or provider function
24
   * @returns NodeHttp2Handler instance
25
   */
26
  static create(
27
    instanceOrOptions?: HttpHandler<any> | NodeHttp2HandlerOptions | Provider<NodeHttp2HandlerOptions | void>
28
  ): NodeHttp2Handler;
29
  
30
  /**
31
   * Handle HTTP/2 request and return response
32
   * @param request - HTTP request object  
33
   * @param options - Request-specific options including abort signal
34
   * @returns Promise resolving to response object
35
   */
36
  handle(request: HttpRequest, options?: HttpHandlerOptions): Promise<{ response: HttpResponse }>;
37
  
38
  /**
39
   * Clean up handler resources and close all HTTP/2 sessions
40
   */
41
  destroy(): void;
42
  
43
  /**
44
   * Update a specific configuration option
45
   * @param key - Configuration key to update
46
   * @param value - New value for the configuration key
47
   */
48
  updateHttpClientConfig(key: keyof NodeHttp2HandlerOptions, value: NodeHttp2HandlerOptions[typeof key]): void;
49
  
50
  /**
51
   * Get current handler configuration
52
   * @returns Current NodeHttp2HandlerOptions configuration
53
   */
54
  httpHandlerConfigs(): NodeHttp2HandlerOptions;
55
  
56
  /**
57
   * Handler metadata indicating protocol version
58
   */
59
  readonly metadata: { handlerProtocol: "h2" };
60
}
61
```
62

63
**Usage Examples:**
64

65
```typescript
66
import { NodeHttp2Handler } from "@smithy/node-http-handler";
67
import { HttpRequest } from "@smithy/protocol-http";
68

69
// Basic HTTP/2 handler with defaults
70
const handler = new NodeHttp2Handler();
71

72
// Handler with custom configuration
73
const configuredHandler = new NodeHttp2Handler({
74
  requestTimeout: 30000,
75
  sessionTimeout: 300000,     // 5 minutes
76
  maxConcurrentStreams: 100,
77
  disableConcurrentStreams: false
78
});
79

80
// Using factory method
81
const factoryHandler = NodeHttp2Handler.create({
82
  requestTimeout: 60000,
83
  sessionTimeout: 600000      // 10 minutes
84
});
85

86
// Handle multiple concurrent requests (default behavior)
87
const request1 = new HttpRequest({
88
  method: "GET",
89
  hostname: "http2.example.com",
90
  path: "/api/users",
91
  headers: { "Authorization": "Bearer token123" }
92
});
93

94
const request2 = new HttpRequest({
95
  method: "GET", 
96
  hostname: "http2.example.com",
97
  path: "/api/posts",
98
  headers: { "Authorization": "Bearer token123" }
99
});
100

101
// Both requests can use the same HTTP/2 session concurrently
102
const [response1, response2] = await Promise.all([
103
  handler.handle(request1),
104
  handler.handle(request2)
105
]);
106

107
// Handle request with timeout
108
const timeoutRequest = new HttpRequest({
109
  method: "POST",
110
  hostname: "http2.example.com",
111
  path: "/api/data",
112
  headers: { "Content-Type": "application/json" },
113
  body: JSON.stringify({ key: "value" })
114
});
115

116
const { response } = await handler.handle(timeoutRequest, {
117
  abortSignal: AbortSignal.timeout(10000) // 10 second timeout
118
});
119

120
// Update configuration after creation
121
handler.updateHttpClientConfig("maxConcurrentStreams", 200);
122
handler.updateHttpClientConfig("requestTimeout", 45000);
123

124
// Clean up when done
125
handler.destroy();
126
```
127

128
### NodeHttp2Handler Configuration
129

130
Configuration interface for HTTP/2 handler options.
131

132
```typescript { .api }
133
/**
134
 * Represents the http2 options that can be passed to a node http2 client.
135
 */
136
interface NodeHttp2HandlerOptions {
137
  /**
138
   * The maximum time in milliseconds that a stream may remain idle before it
139
   * is closed.
140
   */
141
  requestTimeout?: number;
142

143
  /**
144
   * The maximum time in milliseconds that a session or socket may remain idle
145
   * before it is closed.
146
   * https://nodejs.org/docs/latest-v12.x/api/http2.html#http2_http2session_and_sockets
147
   */
148
  sessionTimeout?: number;
149

150
  /**
151
   * Disables processing concurrent streams on a ClientHttp2Session instance. When set
152
   * to true, a new session instance is created for each request to a URL.
153
   * Default: false.
154
   * https://nodejs.org/api/http2.html#http2_class_clienthttp2session
155
   */
156
  disableConcurrentStreams?: boolean;
157

158
  /**
159
   * Maximum number of concurrent Http2Stream instances per ClientHttp2Session. Each session
160
   * may have up to 2^31-1 Http2Stream instances over its lifetime.
161
   * This value must be greater than or equal to 0.
162
   * https://nodejs.org/api/http2.html#class-http2stream
163
   */
164
  maxConcurrentStreams?: number;
165
}
166
```
167

168
## Connection Management
169

170
The HTTP/2 handler automatically manages session pooling and connection lifecycle internally. Sessions are reused for multiple requests to the same origin when concurrent streams are enabled, and properly cleaned up when the handler is destroyed.
171

172
The handler automatically manages HTTP/2 sessions, multiplexing multiple requests over single connections, stream lifecycle, server push support, and comprehensive error handling for HTTP/2-specific scenarios.