0
# HTTP Handler Configuration
1

2
HTTP handler interfaces and user input types for configurable request handling. Provides abstractions for pluggable HTTP client implementations with configuration management capabilities.
3

4
## Capabilities
5

6
### HttpHandler Interface
7

8
Generic HTTP handler interface extending RequestHandler with configuration management methods. Enables pluggable HTTP client implementations.
9

10
```typescript { .api }
11
/**
12
 * @internal
13
 * HTTP handler interface with configuration management
14
 */
15
type HttpHandler<HttpHandlerConfig extends object = {}> = RequestHandler<
16
  HttpRequest,
17
  HttpResponse,
18
  HttpHandlerOptions
19
> & {
20
  updateHttpClientConfig(key: keyof HttpHandlerConfig, value: HttpHandlerConfig[typeof key]): void;
21
  httpHandlerConfigs(): HttpHandlerConfig;
22
};
23
```
24

25
The `HttpHandler` type combines:
26
- `RequestHandler<HttpRequest, HttpResponse, HttpHandlerOptions>` - Core request handling capability
27
- Configuration management methods for runtime HTTP client updates
28

29
### Update HTTP Client Config
30

31
Updates HTTP client configuration at runtime for a specific configuration key.
32

33
```typescript { .api }
34
/**
35
 * @internal
36
 * Update HTTP client configuration
37
 * @param key - Configuration key to update
38
 * @param value - New value for the configuration key
39
 */
40
updateHttpClientConfig(key: keyof HttpHandlerConfig, value: HttpHandlerConfig[typeof key]): void;
41
```
42

43
### Get HTTP Handler Configs  
44

45
Retrieves the current HTTP handler configuration object.
46

47
```typescript { .api }
48
/**
49
 * @internal
50
 * Get current HTTP handler configuration
51
 * @returns Current handler configuration object
52
 */
53
httpHandlerConfigs(): HttpHandlerConfig;
54
```
55

56
### HttpHandlerUserInput Type
57

58
Union type representing accepted user inputs for the `requestHandler` field of client constructors. Provides flexibility in how users configure HTTP handling.
59

60
```typescript { .api }
61
/**
62
 * @public
63
 * 
64
 * A type representing the accepted user inputs for the `requestHandler` field
65
 * of a client's constructor object.
66
 * 
67
 * You may provide an instance of an HttpHandler, or alternatively
68
 * provide the constructor arguments as an object which will be passed
69
 * to the constructor of the default request handler.
70
 * 
71
 * The default class constructor to which your arguments will be passed
72
 * varies. The Node.js default is the NodeHttpHandler and the browser/react-native
73
 * default is the FetchHttpHandler. In rarer cases specific clients may be
74
 * configured to use other default implementations such as Websocket or HTTP2.
75
 * 
76
 * The fallback type Record<string, unknown> is part of the union to allow
77
 * passing constructor params to an unknown requestHandler type.
78
 */
79
type HttpHandlerUserInput =
80
  | HttpHandler
81
  | NodeHttpHandlerOptions
82
  | FetchHttpHandlerOptions
83
  | Record<string, unknown>;
84
```
85

86
**Usage Examples:**
87

88
```typescript
89
import { HttpHandlerUserInput } from "@smithy/protocol-http";
90

91
// Option 1: Provide HttpHandler instance
92
const customHandler: HttpHandler = {
93
  handle: (request) => Promise.resolve(/* response */),
94
  updateHttpClientConfig: (key, value) => { /* update logic */ },
95
  httpHandlerConfigs: () => ({ /* config */ })
96
};
97

98
// Option 2: Provide Node.js handler options
99
const nodeOptions: NodeHttpHandlerOptions = {
100
  connectionTimeout: 5000,
101
  socketTimeout: 10000,
102
  httpAgent: new HttpAgent({ keepAlive: true })
103
};
104

105
// Option 3: Provide Fetch handler options  
106
const fetchOptions: FetchHttpHandlerOptions = {
107
  requestTimeout: 8000,
108
  keepAlive: true
109
};
110

111
// Option 4: Provide custom configuration
112
const customConfig = {
113
  timeout: 5000,
114
  retries: 3,
115
  customProperty: "value"
116
};
117

118
// All are valid HttpHandlerUserInput
119
const inputs: HttpHandlerUserInput[] = [
120
  customHandler,
121
  nodeOptions, 
122
  fetchOptions,
123
  customConfig
124
];
125
```
126

127
## Handler Input Types
128

129
The `HttpHandlerUserInput` union accommodates different runtime environments:
130

131
### HttpHandler Instance
132
Direct HttpHandler implementation with full control over request handling and configuration.
133

134
### NodeHttpHandlerOptions  
135
Configuration options for Node.js HTTP handler in server environments:
136
- Connection and socket timeouts
137
- HTTP agent configuration  
138
- Certificate and proxy settings
139
- Keep-alive behavior
140

141
### FetchHttpHandlerOptions
142
Configuration options for Fetch-based handler in browser/React Native environments:
143
- Request timeout settings
144
- Keep-alive configuration
145
- Fetch API specific options
146

147
### Generic Configuration
148
Fallback `Record<string, unknown>` type allows custom configuration objects for specialized HTTP handler implementations like WebSocket or HTTP2.
149

150
## Platform-Specific Defaults
151

152
The actual HttpHandler implementation varies by platform:
153

154
- **Node.js**: Defaults to `NodeHttpHandler` with Node.js native HTTP modules
155
- **Browser/React Native**: Defaults to `FetchHttpHandler` using the Fetch API  
156
- **Specialized Clients**: May use WebSocket handlers, HTTP2 handlers, or other protocol-specific implementations
157

158
This design allows clients to accept handler configuration without tightly coupling to specific HTTP implementation details.