0
# @smithy/protocol-http
1

2
Protocol HTTP utilities for Smithy TypeScript clients and servers, providing HTTP request/response handling, field management, hostname validation, and extension configuration for HTTP-based protocol implementations.
3

4
## Package Information
5

6
- **Package Name**: @smithy/protocol-http
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install @smithy/protocol-http`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  Field, 
16
  Fields, 
17
  HttpRequest, 
18
  HttpResponse, 
19
  isValidHostname,
20
  HttpHandler,
21
  HttpHandlerUserInput
22
} from "@smithy/protocol-http";
23
```
24

25
For CommonJS:
26

27
```javascript
28
const { 
29
  Field, 
30
  Fields, 
31
  HttpRequest, 
32
  HttpResponse, 
33
  isValidHostname 
34
} = require("@smithy/protocol-http");
35
```
36

37
## Basic Usage
38

39
```typescript
40
import { Field, Fields, HttpRequest, HttpResponse, isValidHostname } from "@smithy/protocol-http";
41
import { FieldPosition } from "@smithy/types";
42

43
// Create HTTP fields (headers/trailers)
44
const headerField = new Field({
45
  name: "Content-Type",
46
  kind: FieldPosition.HEADER,
47
  values: ["application/json"]
48
});
49

50
// Manage field collections
51
const fields = new Fields({ fields: [headerField] });
52
const contentType = fields.getField("content-type"); // Case insensitive
53

54
// Create HTTP requests
55
const request = new HttpRequest({
56
  method: "POST",
57
  hostname: "api.example.com", 
58
  path: "/users",
59
  headers: { "Content-Type": "application/json" },
60
  body: JSON.stringify({ name: "Alice" })
61
});
62

63
// Create HTTP responses
64
const response = new HttpResponse({
65
  statusCode: 200,
66
  headers: { "Content-Type": "application/json" },
67
  body: JSON.stringify({ id: 123, name: "Alice" })
68
});
69

70
// Validate hostnames
71
if (isValidHostname("api.example.com")) {
72
  console.log("Valid hostname");
73
}
74
```
75

76
## Architecture
77

78
@smithy/protocol-http is built around several key components:
79

80
- **Field System**: `Field` and `Fields` classes for managing HTTP metadata (headers, trailers) with case-insensitive access
81
- **Message Types**: `HttpRequest` and `HttpResponse` classes providing concrete implementations with cloning capabilities  
82
- **Handler Interface**: `HttpHandler` type and configuration for pluggable HTTP client implementations
83
- **Validation Utilities**: Hostname validation and type guards for runtime safety
84
- **Extension System**: Configuration hooks for protocol-specific HTTP handler customization
85
- **Type Compatibility**: Deprecated type re-exports maintaining backward compatibility with existing code
86

87
## Capabilities
88

89
### HTTP Field Management
90

91
HTTP field handling for headers and trailers with case-insensitive operations and value management.
92

93
```typescript { .api }
94
class Field {
95
  constructor(options: { name: string; kind?: FieldPosition; values?: string[] });
96
  add(value: string): void;
97
  set(values: string[]): void;
98
  remove(value: string): void;
99
  toString(): string;
100
  get(): string[];
101
}
102

103
class Fields {
104
  constructor(options: { fields?: Field[]; encoding?: string });
105
  setField(field: Field): void;
106
  getField(name: string): Field | undefined;
107
  removeField(name: string): void;
108
  getByType(kind: FieldPosition): Field[];
109
}
110
```
111

112
[Field Management](./field-management.md)
113

114
### HTTP Request and Response
115

116
HTTP message implementations with cloning support and type validation.
117

118
```typescript { .api }
119
class HttpRequest {
120
  constructor(options: HttpRequestOptions);
121
  static clone(request: IHttpRequest): HttpRequest;
122
  static isInstance(request: unknown): request is HttpRequest;
123
  clone(): HttpRequest; // @deprecated
124
}
125

126
class HttpResponse {
127
  constructor(options: { statusCode: number; reason?: string; headers?: HeaderBag; body?: any });
128
  static isInstance(response: unknown): response is HttpResponse;
129
}
130
```
131

132
[HTTP Messages](./http-messages.md)
133

134
### HTTP Handler Configuration
135

136
HTTP handler interfaces and user input types for configurable request handling.
137

138
```typescript { .api }
139
/**
140
 * @internal
141
 */
142
type HttpHandler<HttpHandlerConfig extends object = {}> = RequestHandler<
143
  HttpRequest,
144
  HttpResponse,
145
  HttpHandlerOptions
146
> & {
147
  updateHttpClientConfig(key: keyof HttpHandlerConfig, value: HttpHandlerConfig[typeof key]): void;
148
  httpHandlerConfigs(): HttpHandlerConfig;
149
};
150

151
type HttpHandlerUserInput =
152
  | HttpHandler
153
  | NodeHttpHandlerOptions
154
  | FetchHttpHandlerOptions
155
  | Record<string, unknown>;
156
```
157

158
[Handler Configuration](./handler-configuration.md)
159

160
### Hostname Validation
161

162
Hostname format validation utility for URL construction and validation.
163

164
```typescript { .api }
165
function isValidHostname(hostname: string): boolean;
166
```
167

168
### Extension System
169

170
Internal extension configuration system for HTTP handler customization.
171

172
```typescript { .api }
173
interface HttpHandlerExtensionConfiguration<HandlerConfig extends object = {}> {
174
  setHttpHandler(handler: HttpHandler<HandlerConfig>): void;
175
  httpHandler(): HttpHandler<HandlerConfig>;
176
  updateHttpClientConfig(key: keyof HandlerConfig, value: HandlerConfig[typeof key]): void;
177
  httpHandlerConfigs(): HandlerConfig;
178
}
179
```
180

181
[Extension Configuration](./extension-configuration.md)
182

183
### Deprecated Type Re-exports
184

185
Type aliases maintaining backward compatibility with existing code. These types are deprecated and users should migrate to @smithy/types.
186

187
```typescript { .api }
188
/** @deprecated Use FieldOptions from @smithy/types instead */
189
type FieldOptions = __FieldOptions;
190

191
/** @deprecated Use FieldPosition from @smithy/types instead */
192
type FieldPosition = __FieldPosition;
193

194
/** @deprecated Use HeaderBag from @smithy/types instead */
195
type HeaderBag = __HeaderBag;
196

197
/** @deprecated Use HttpMessage from @smithy/types instead */
198
type HttpMessage = __HttpMessage;
199

200
/** @deprecated Use HttpHandlerOptions from @smithy/types instead */
201
type HttpHandlerOptions = __HttpHandlerOptions;
202
```