0
# HTTP/1.1 Handler
1

2
The NodeHttpHandler provides HTTP/1.1 request handling using Node.js built-in http and https modules with comprehensive configuration options for timeouts, connection management, and socket settings.
3

4
## Capabilities
5

6
### NodeHttpHandler Class
7

8
Primary HTTP/1.1 request handler implementing the HttpHandler interface from @smithy/protocol-http.
9

10
```typescript { .api }
11
/**
12
 * A request handler that uses the Node.js http and https modules.
13
 */
14
class NodeHttpHandler implements HttpHandler<NodeHttpHandlerOptions> {
15
  /**
16
   * Create a new HTTP handler instance
17
   * @param options - Handler configuration options or provider function
18
   */
19
  constructor(options?: NodeHttpHandlerOptions | Provider<NodeHttpHandlerOptions | 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 NodeHttpHandler instance
25
   */
26
  static create(
27
    instanceOrOptions?: HttpHandler<any> | NodeHttpHandlerOptions | Provider<NodeHttpHandlerOptions | void>
28
  ): NodeHttpHandler;
29
  
30
  /**
31
   * Handle HTTP 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 connection pools
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 NodeHttpHandlerOptions, value: NodeHttpHandlerOptions[typeof key]): void;
49
  
50
  /**
51
   * Get current handler configuration
52
   * @returns Current NodeHttpHandlerOptions configuration
53
   */
54
  httpHandlerConfigs(): NodeHttpHandlerOptions;
55
  
56
  /**
57
   * Handler metadata indicating protocol version
58
   */
59
  readonly metadata: { handlerProtocol: "http/1.1" };
60
  
61
  /**
62
   * Static utility method to check socket usage and log warnings
63
   * @param agent - HTTP or HTTPS agent instance
64
   * @param socketWarningTimestamp - Timestamp for rate limiting warnings
65
   * @param logger - Optional logger instance
66
   * @returns Updated warning timestamp
67
   */
68
  static checkSocketUsage(agent: Agent, socketWarningTimestamp: number, logger?: Logger): number;
69
}
70
```
71

72
**Usage Examples:**
73

74
```typescript
75
import { NodeHttpHandler } from "@smithy/node-http-handler";
76
import { HttpRequest } from "@smithy/protocol-http";
77
import { Agent } from "https";
78

79
// Basic handler with default options
80
const handler = new NodeHttpHandler();
81

82
// Handler with custom configuration
83
const configuredHandler = new NodeHttpHandler({
84
  requestTimeout: 30000,
85
  connectionTimeout: 5000,
86
  socketTimeout: 10000,
87
  httpsAgent: new Agent({
88
    keepAlive: true,
89
    maxSockets: 50
90
  })
91
});
92

93
// Using factory method
94
const factoryHandler = NodeHttpHandler.create({
95
  requestTimeout: 60000
96
});
97

98
// Handle a GET request
99
const getRequest = new HttpRequest({
100
  method: "GET",
101
  hostname: "api.example.com",
102
  path: "/users",
103
  headers: {
104
    "Authorization": "Bearer token123",
105
    "Content-Type": "application/json"
106
  }
107
});
108

109
const { response } = await handler.handle(getRequest);
110
console.log(response.statusCode); // 200
111
console.log(response.headers); // Response headers object
112

113
// Handle a POST request with body
114
const postRequest = new HttpRequest({
115
  method: "POST",
116
  hostname: "api.example.com", 
117
  path: "/users",
118
  headers: {
119
    "Content-Type": "application/json"
120
  },
121
  body: JSON.stringify({ name: "John", email: "john@example.com" })
122
});
123

124
const { response: postResponse } = await handler.handle(postRequest, {
125
  abortSignal: AbortSignal.timeout(5000) // 5 second timeout
126
});
127

128
// Update configuration dynamically
129
handler.updateHttpClientConfig("requestTimeout", 45000);
130

131
// Clean up when done
132
handler.destroy();
133
```
134

135
### Default Request Timeout
136

137
Default timeout value used when no specific timeout is configured.
138

139
```typescript { .api }
140
/**
141
 * A default of 0 means no timeout.
142
 */
143
const DEFAULT_REQUEST_TIMEOUT: number;
144
```
145

146
## Configuration Types
147

148
```typescript { .api }
149
// Re-exported from @smithy/types
150
interface NodeHttpHandlerOptions {
151
  /**
152
   * The maximum time in milliseconds that a socket may remain idle before it
153
   * is closed.
154
   */
155
  requestTimeout?: number;
156
  
157
  /**
158
   * The maximum time in milliseconds that a socket may wait for a connection to be established.
159
   */
160
  connectionTimeout?: number;
161
  
162
  /**
163
   * The maximum time in milliseconds that a socket may remain idle.
164
   */
165
  socketTimeout?: number;
166
  
167
  /**
168
   * The HTTP agent to use for http requests.
169
   */
170
  httpAgent?: Agent;
171
  
172
  /**
173
   * The HTTPS agent to use for https requests.
174
   */
175
  httpsAgent?: Agent;
176
  
177
  /**
178
   * The amount of time in milliseconds to wait before warning about socket usage saturation.
179
   */
180
  socketAcquisitionWarningTimeout?: number;
181
}
182
```
183

184
The handler automatically manages HTTP and HTTPS agents, connection pooling, socket timeouts, and request lifecycle. It supports abort signals for request cancellation and provides comprehensive error handling for network-related issues.