0
# Smithy Node HTTP Handler
1
2
The Smithy Node HTTP Handler provides HTTP request handling functionality for Node.js environments in the Smithy TypeScript ecosystem. It implements default request handlers using Node.js built-in HTTP modules to enable HTTP client communication for Smithy-generated SDK clients.
3
4
## Package Information
5
6
- **Package Name**: @smithy/node-http-handler
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @smithy/node-http-handler`
10
- **Minimum Node.js**: 18.0.0
11
12
## Core Imports
13
14
```typescript
15
import { NodeHttpHandler, NodeHttp2Handler, streamCollector } from "@smithy/node-http-handler";
16
```
17
18
For CommonJS:
19
20
```javascript
21
const { NodeHttpHandler, NodeHttp2Handler, streamCollector } = require("@smithy/node-http-handler");
22
```
23
24
## Basic Usage
25
26
```typescript
27
import { NodeHttpHandler, NodeHttp2Handler } from "@smithy/node-http-handler";
28
import { HttpRequest } from "@smithy/protocol-http";
29
30
// HTTP/1.1 handler
31
const httpHandler = new NodeHttpHandler({
32
requestTimeout: 30000,
33
connectionTimeout: 5000
34
});
35
36
// HTTP/2 handler
37
const http2Handler = new NodeHttp2Handler({
38
requestTimeout: 30000,
39
sessionTimeout: 300000
40
});
41
42
// Handle a request
43
const request = new HttpRequest({
44
method: "GET",
45
hostname: "example.com",
46
path: "/api/data",
47
headers: {
48
"Content-Type": "application/json"
49
}
50
});
51
52
const { response } = await httpHandler.handle(request);
53
```
54
55
## Architecture
56
57
The package is built around several key components:
58
59
- **HTTP/1.1 Handler**: `NodeHttpHandler` using Node.js `http` and `https` modules
60
- **HTTP/2 Handler**: `NodeHttp2Handler` using Node.js `http2` module
61
- **Connection Management**: HTTP/2 connection pooling and session management
62
- **Stream Processing**: Utilities for collecting response body streams
63
- **Timeout Management**: Comprehensive timeout handling for connections and requests
64
65
## Capabilities
66
67
### HTTP/1.1 Request Handler
68
69
Primary request handler using Node.js http and https modules with connection pooling, timeout management, and socket configuration.
70
71
```typescript { .api }
72
class NodeHttpHandler implements HttpHandler<NodeHttpHandlerOptions> {
73
constructor(options?: NodeHttpHandlerOptions | Provider<NodeHttpHandlerOptions | void>);
74
75
static create(
76
instanceOrOptions?: HttpHandler<any> | NodeHttpHandlerOptions | Provider<NodeHttpHandlerOptions | void>
77
): NodeHttpHandler;
78
79
static checkSocketUsage(agent: Agent, socketWarningTimestamp: number, logger?: Logger): number;
80
81
handle(request: HttpRequest, options?: HttpHandlerOptions): Promise<{ response: HttpResponse }>;
82
destroy(): void;
83
updateHttpClientConfig(key: keyof NodeHttpHandlerOptions, value: NodeHttpHandlerOptions[typeof key]): void;
84
httpHandlerConfigs(): NodeHttpHandlerOptions;
85
86
readonly metadata: { handlerProtocol: "http/1.1" };
87
}
88
89
const DEFAULT_REQUEST_TIMEOUT: number;
90
```
91
92
[HTTP/1.1 Handler](./http-handler.md)
93
94
### HTTP/2 Request Handler
95
96
Request handler using Node.js http2 module with session pooling, stream management, and concurrent request support.
97
98
```typescript { .api }
99
class NodeHttp2Handler implements HttpHandler<NodeHttp2HandlerOptions> {
100
constructor(options?: NodeHttp2HandlerOptions | Provider<NodeHttp2HandlerOptions | void>);
101
102
static create(
103
instanceOrOptions?: HttpHandler<any> | NodeHttp2HandlerOptions | Provider<NodeHttp2HandlerOptions | void>
104
): NodeHttp2Handler;
105
106
handle(request: HttpRequest, options?: HttpHandlerOptions): Promise<{ response: HttpResponse }>;
107
destroy(): void;
108
updateHttpClientConfig(key: keyof NodeHttp2HandlerOptions, value: NodeHttp2HandlerOptions[typeof key]): void;
109
httpHandlerConfigs(): NodeHttp2HandlerOptions;
110
111
readonly metadata: { handlerProtocol: "h2" };
112
}
113
114
interface NodeHttp2HandlerOptions {
115
requestTimeout?: number;
116
sessionTimeout?: number;
117
disableConcurrentStreams?: boolean;
118
maxConcurrentStreams?: number;
119
}
120
```
121
122
[HTTP/2 Handler](./http2-handler.md)
123
124
### Stream Collection
125
126
Utilities for converting Node.js streams and Web API ReadableStreams to byte arrays for response body processing.
127
128
```typescript { .api }
129
const streamCollector: StreamCollector;
130
131
type StreamCollector = (stream: Readable | ReadableStream): Promise<Uint8Array>;
132
133
class Collector extends Writable {
134
constructor(options?: WritableOptions);
135
bufferedBytes: Buffer[];
136
_write(chunk: Buffer, encoding: string, callback: (err?: Error) => void): void;
137
}
138
```
139
140
[Stream Collection](./stream-collector.md)
141
142
## Types
143
144
```typescript { .api }
145
// Re-exported from @smithy/types
146
interface NodeHttpHandlerOptions {
147
requestTimeout?: number;
148
connectionTimeout?: number;
149
socketTimeout?: number;
150
httpAgent?: Agent;
151
httpsAgent?: Agent;
152
// ... other options from @smithy/types
153
}
154
155
// From @smithy/protocol-http
156
interface HttpRequest {
157
method: string;
158
hostname?: string;
159
port?: number;
160
path?: string;
161
headers?: Record<string, string>;
162
body?: any;
163
// ... other properties
164
}
165
166
interface HttpResponse {
167
statusCode: number;
168
headers: Record<string, string>;
169
body?: any;
170
// ... other properties
171
}
172
173
interface HttpHandler<T> {
174
handle(request: HttpRequest, options?: HttpHandlerOptions): Promise<{ response: HttpResponse }>;
175
}
176
177
interface HttpHandlerOptions {
178
abortSignal?: AbortSignal;
179
}
180
181
// From @smithy/types
182
type Provider<T> = T | (() => T) | (() => Promise<T>);
183
184
// From Node.js http/https modules
185
interface Agent {
186
destroy(): void;
187
// ... other Agent properties
188
}
189
190
// From @smithy/types
191
interface Logger {
192
warn?(message: string): void;
193
// ... other Logger methods
194
}
195
196
// From Node.js stream module
197
interface Readable {
198
pipe<T extends Writable>(destination: T): T;
199
on(event: string, listener: Function): this;
200
// ... other Readable properties
201
}
202
203
// From Node.js stream module
204
interface WritableOptions {
205
highWaterMark?: number;
206
objectMode?: boolean;
207
// ... other Writable options
208
}
209
210
// From stream/web (Node.js 16.5.0+)
211
interface ReadableStream<R = any> {
212
getReader(): ReadableStreamDefaultReader<R>;
213
// ... other ReadableStream properties
214
}
215
```
216
217
## Error Handling
218
219
The handlers provide comprehensive error handling for various network conditions:
220
221
- Connection timeouts and socket errors
222
- HTTP/2 stream errors and session management
223
- Request cancellation via AbortSignal
224
- Node.js specific timeout error handling for network interruptions