0
# Extension Configuration
1

2
Internal extension configuration system for HTTP handler customization. Provides runtime configuration management and helper functions for integrating HTTP handlers into Smithy client runtime configurations.
3

4
## Capabilities
5

6
### HttpHandlerExtensionConfiguration Interface
7

8
Core interface for HTTP handler extension configuration providing lifecycle management methods.
9

10
```typescript { .api }
11
/**
12
 * @internal
13
 * Extension configuration interface for HTTP handler management
14
 */
15
interface HttpHandlerExtensionConfiguration<HandlerConfig extends object = {}> {
16
  setHttpHandler(handler: HttpHandler<HandlerConfig>): void;
17
  httpHandler(): HttpHandler<HandlerConfig>;
18
  updateHttpClientConfig(key: keyof HandlerConfig, value: HandlerConfig[typeof key]): void;
19
  httpHandlerConfigs(): HandlerConfig;
20
}
21
```
22

23
### Set HTTP Handler
24

25
Sets the HTTP handler instance for the extension configuration.
26

27
```typescript { .api }
28
/**
29
 * Set the HTTP handler instance
30
 * @param handler - HttpHandler instance to set
31
 */
32
setHttpHandler(handler: HttpHandler<HandlerConfig>): void;
33
```
34

35
### Get HTTP Handler
36

37
Retrieves the current HTTP handler instance.
38

39
```typescript { .api }
40
/**
41
 * Get the current HTTP handler instance  
42
 * @returns Current HttpHandler instance
43
 */
44
httpHandler(): HttpHandler<HandlerConfig>;
45
```
46

47
### Update HTTP Client Config
48

49
Updates HTTP client configuration through the handler.
50

51
```typescript { .api }
52
/**
53
 * Update HTTP client configuration via the handler
54
 * @param key - Configuration key to update
55
 * @param value - New value for the configuration key
56
 */
57
updateHttpClientConfig(key: keyof HandlerConfig, value: HandlerConfig[typeof key]): void;
58
```
59

60
### Get HTTP Handler Configs
61

62
Retrieves HTTP handler configuration object.
63

64
```typescript { .api }
65
/**
66
 * Get HTTP handler configuration object
67
 * @returns Handler configuration object
68
 */
69
httpHandlerConfigs(): HandlerConfig;
70
```
71

72
### HttpHandlerExtensionConfigType
73

74
Type representing partial extension configuration with optional HTTP handler.
75

76
```typescript { .api }
77
/**
78
 * @internal
79
 * Partial extension configuration type
80
 */
81
type HttpHandlerExtensionConfigType<HandlerConfig extends object = {}> = Partial<{
82
  httpHandler: HttpHandler<HandlerConfig>;
83
}>;
84
```
85

86
### getHttpHandlerExtensionConfiguration Function
87

88
Helper function to resolve default extension configuration from runtime config. Creates extension configuration implementation from runtime configuration.
89

90
```typescript { .api }
91
/**
92
 * @internal
93
 * Helper function to resolve default extension configuration from runtime config
94
 * @param runtimeConfig - Runtime configuration object
95
 * @returns Extension configuration implementation
96
 */
97
function getHttpHandlerExtensionConfiguration<HandlerConfig extends object = {}>(
98
  runtimeConfig: HttpHandlerExtensionConfigType<HandlerConfig>
99
): HttpHandlerExtensionConfiguration<HandlerConfig>;
100
```
101

102
**Usage Example:**
103

104
```typescript
105
// Internal usage in Smithy client configuration
106
const runtimeConfig = {
107
  httpHandler: myHttpHandler
108
};
109

110
const extensionConfig = getHttpHandlerExtensionConfiguration(runtimeConfig);
111

112
// Extension config provides handler management methods
113
extensionConfig.setHttpHandler(newHandler);
114
const currentHandler = extensionConfig.httpHandler();
115
extensionConfig.updateHttpClientConfig('timeout', 5000);
116
const configs = extensionConfig.httpHandlerConfigs();
117
```
118

119
### resolveHttpHandlerRuntimeConfig Function
120

121
Helper function to resolve runtime config from extension configuration. Extracts runtime configuration from extension configuration for client initialization.
122

123
```typescript { .api }
124
/**
125
 * @internal
126
 * Helper function to resolve runtime config from default extension configuration
127
 * @param httpHandlerExtensionConfiguration - Extension configuration instance
128
 * @returns Runtime configuration object
129
 */
130
function resolveHttpHandlerRuntimeConfig<HandlerConfig extends object = {}>(
131
  httpHandlerExtensionConfiguration: HttpHandlerExtensionConfiguration<HandlerConfig>
132
): HttpHandlerExtensionConfigType<HandlerConfig>;
133
```
134

135
**Usage Example:**
136

137
```typescript
138
// Internal usage in Smithy client initialization
139
const extensionConfig: HttpHandlerExtensionConfiguration = {
140
  setHttpHandler: (handler) => { /* implementation */ },
141
  httpHandler: () => myHandler,
142
  updateHttpClientConfig: (key, value) => { /* implementation */ },
143
  httpHandlerConfigs: () => ({ /* config */ })
144
};
145

146
const runtimeConfig = resolveHttpHandlerRuntimeConfig(extensionConfig);
147
// runtimeConfig = { httpHandler: myHandler }
148
```
149

150
## Implementation Details
151

152
The extension configuration system works through a bidirectional conversion pattern:
153

154
1. **Runtime → Extension**: `getHttpHandlerExtensionConfiguration()` converts runtime config to extension interface
155
2. **Extension → Runtime**: `resolveHttpHandlerRuntimeConfig()` extracts runtime config from extension interface
156

157
This design enables:
158
- **Consistent Interface**: All Smithy clients use the same extension configuration interface
159
- **Handler Swapping**: Runtime replacement of HTTP handlers without recreating clients  
160
- **Configuration Updates**: Dynamic HTTP client configuration changes
161
- **Type Safety**: Generic type parameter ensures configuration type consistency
162

163
## Configuration Flow
164

165
```typescript
166
// 1. Initial runtime config
167
const initialConfig = { httpHandler: defaultHandler };
168

169
// 2. Create extension config
170
const extensionConfig = getHttpHandlerExtensionConfiguration(initialConfig);
171

172
// 3. Runtime handler updates
173
extensionConfig.setHttpHandler(newHandler);
174
extensionConfig.updateHttpClientConfig('timeout', 10000);
175

176
// 4. Extract updated runtime config
177
const updatedConfig = resolveHttpHandlerRuntimeConfig(extensionConfig);
178
```
179

180
This pattern enables Smithy clients to maintain flexible HTTP handler configuration while providing a consistent internal interface for configuration management.