0
# HTTP Messages
1

2
HTTP message implementations providing concrete `HttpRequest` and `HttpResponse` classes with cloning support, type validation, and URI handling. These classes implement the Smithy HTTP message interface with additional utility methods.
3

4
## Capabilities
5

6
### HttpRequest Class
7

8
HTTP request implementation with URI components, headers, query parameters, and body handling. Supports static cloning with proper deep/shallow copying behavior.
9

10
```typescript { .api }
11
/**
12
 * HTTP request implementation
13
 */
14
class HttpRequest implements HttpMessage, URI {
15
  method: string;
16
  protocol: string;
17
  hostname: string;
18
  port?: number;
19
  path: string;
20
  query: QueryParameterBag;
21
  headers: HeaderBag;
22
  username?: string;
23
  password?: string;
24
  fragment?: string;
25
  body?: any;
26
  
27
  constructor(options: HttpRequestOptions);
28
  static clone(request: IHttpRequest): HttpRequest;
29
  static isInstance(request: unknown): request is HttpRequest;
30
  clone(): HttpRequest; // @deprecated
31
}
32

33
type HttpRequestOptions = Partial<HttpMessage> & Partial<URI> & { 
34
  method?: string;
35
};
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import { HttpRequest, IHttpRequest } from "@smithy/protocol-http";
42

43
// Create HTTP request
44
const request = new HttpRequest({
45
  method: "POST",
46
  hostname: "api.example.com",
47
  port: 443,
48
  path: "/users",
49
  protocol: "https:",
50
  query: { limit: "10", offset: "0" },
51
  headers: { 
52
    "Content-Type": "application/json",
53
    "Authorization": "Bearer token123"
54
  },
55
  body: JSON.stringify({ name: "Alice", email: "alice@example.com" }),
56
  username: "user",
57
  password: "pass",
58
  fragment: "section1"
59
});
60

61
// Clone request (deep clone headers/query, shallow clone body)
62
const clonedRequest = HttpRequest.clone(request);
63
clonedRequest.headers["X-Custom"] = "value"; // Won't affect original
64
clonedRequest.query.page = "2"; // Won't affect original
65

66
// Type checking
67
if (HttpRequest.isInstance(someObject)) {
68
  console.log(`Method: ${someObject.method}`);
69
}
70
```
71

72
### Request Constructor
73

74
Creates a new HTTP request with default values and proper URI formatting.
75

76
```typescript { .api }
77
/**
78
 * Creates HTTP request with default values
79
 * @param options - Request configuration options
80
 */
81
constructor(options: HttpRequestOptions);
82
```
83

84
Default values:
85
- `method`: "GET"
86
- `hostname`: "localhost" 
87
- `protocol`: "https:" (auto-adds colon if missing)
88
- `path`: "/" (auto-adds leading slash if missing)
89
- `query`: {}
90
- `headers`: {}
91

92
### Static Clone Method
93

94
Clones an HTTP request with deep-cloned headers and query parameters but shallow-cloned body.
95

96
```typescript { .api }
97
/**
98
 * Note: this does not deep-clone the body.
99
 * @param request - Request to clone
100
 * @returns Cloned HttpRequest instance
101
 */
102
static clone(request: IHttpRequest): HttpRequest;
103
```
104

105
### Static Instance Check
106

107
Type guard to check if an object conforms to the HttpRequest interface.
108

109
```typescript { .api }
110
/**
111
 * This method only actually asserts that request is the interface IHttpRequest,
112
 * and not necessarily this concrete class. Left in place for API stability.
113
 * 
114
 * Do not call instance methods on the input of this function, and
115
 * do not assume it has the HttpRequest prototype.
116
 * @param request - Object to check
117
 * @returns Type guard result
118
 */
119
static isInstance(request: unknown): request is HttpRequest;
120
```
121

122
### Instance Clone Method (Deprecated)
123

124
```typescript { .api }
125
/**
126
 * @deprecated use static HttpRequest.clone(request) instead. It's not safe to call
127
 * this method because HttpRequest.isInstance incorrectly
128
 * asserts that IHttpRequest (interface) objects are of type HttpRequest (class).
129
 */
130
clone(): HttpRequest;
131
```
132

133
### HttpResponse Class
134

135
HTTP response implementation with status code, headers, and body handling.
136

137
```typescript { .api }
138
/**
139
 * HTTP response implementation
140
 */
141
class HttpResponse {
142
  statusCode: number;
143
  reason?: string;
144
  headers: HeaderBag;
145
  body?: any;
146
  
147
  constructor(options: HttpResponseOptions);
148
  static isInstance(response: unknown): response is HttpResponse;
149
}
150

151
type HttpResponseOptions = Partial<HttpMessage> & {
152
  statusCode: number;
153
  reason?: string;
154
};
155
```
156

157
**Usage Examples:**
158

159
```typescript
160
import { HttpResponse } from "@smithy/protocol-http";
161

162
// Create HTTP response
163
const response = new HttpResponse({
164
  statusCode: 200,
165
  reason: "OK",
166
  headers: {
167
    "Content-Type": "application/json",
168
    "Cache-Control": "no-cache"
169
  },
170
  body: JSON.stringify({ 
171
    success: true, 
172
    data: { id: 123, name: "Alice" }
173
  })
174
});
175

176
// Error response
177
const errorResponse = new HttpResponse({
178
  statusCode: 400,
179
  reason: "Bad Request",
180
  headers: { "Content-Type": "application/json" },
181
  body: JSON.stringify({ 
182
    error: "Invalid input", 
183
    code: "VALIDATION_ERROR" 
184
  })
185
});
186

187
// Type checking
188
if (HttpResponse.isInstance(someObject)) {
189
  console.log(`Status: ${someObject.statusCode}`);
190
}
191
```
192

193
### Response Constructor
194

195
Creates a new HTTP response with required status code and optional headers/body.
196

197
```typescript { .api }
198
/**
199
 * Creates HTTP response
200
 * @param options - Response configuration options
201
 */
202
constructor(options: HttpResponseOptions);
203
```
204

205
### Response Instance Check
206

207
Type guard to validate if an object conforms to the HttpResponse interface.
208

209
```typescript { .api }
210
/**
211
 * Determine if response is a valid HttpResponse
212
 * @param response - Object to check
213
 * @returns Type guard result
214
 */
215
static isInstance(response: unknown): response is HttpResponse;
216
```
217

218
## Types
219

220
```typescript { .api }
221
type HttpRequestOptions = Partial<HttpMessage> & Partial<URI> & { 
222
  method?: string;
223
};
224

225
type HttpResponseOptions = Partial<HttpMessage> & {
226
  statusCode: number;
227
  reason?: string;
228
};
229

230
interface IHttpRequest extends HttpMessage, URI {
231
  method: string;
232
  protocol: string;
233
  hostname: string;
234
  port?: number;
235
  path: string;
236
  query: QueryParameterBag;
237
  headers: HeaderBag;
238
  username?: string;
239
  password?: string;
240
  fragment?: string;
241
  body?: any;
242
}
243
```
244

245
## Hostname Validation
246

247
Utility function for validating hostname format using regex pattern matching.
248

249
```typescript { .api }
250
/**
251
 * Validates hostname format
252
 * @param hostname - Hostname string to validate
253
 * @returns True if hostname format is valid
254
 */
255
function isValidHostname(hostname: string): boolean;
256
```
257

258
**Usage Examples:**
259

260
```typescript
261
import { isValidHostname } from "@smithy/protocol-http";
262

263
// Valid hostnames
264
console.log(isValidHostname("example.com")); // true
265
console.log(isValidHostname("api.example.com")); // true
266
console.log(isValidHostname("sub-domain.example.co.uk")); // true
267

268
// Invalid hostnames  
269
console.log(isValidHostname("")); // false
270
console.log(isValidHostname("example.")); // false
271
console.log(isValidHostname(".example.com")); // false
272
```
273

274
The validation uses the pattern: `/^[a-z0-9][a-z0-9\.\-]*[a-z0-9]$/`