0
# HTTP Requests
1

2
Core functionality for creating HTTP requests with Node.js API compatibility. Provides both simple URL-based requests and comprehensive options-based configuration.
3

4
## Capabilities
5

6
### HTTP Request Function
7

8
Creates a new HTTP request with full Node.js API compatibility.
9

10
```javascript { .api }
11
/**
12
 * Creates a new HTTP request
13
 * @param opts - URL string or options object containing request configuration
14
 * @param cb - Optional callback function that will be called with the response
15
 * @returns ClientRequest instance for the outgoing request
16
 */
17
function request(opts, cb);
18
```
19

20
**Parameters:**
21

22
- `opts` (string | object): Either a URL string or options object
23
  - If string: URL to request
24
  - If object: Request configuration (see RequestOptions below)
25
- `cb` (function, optional): Callback function called with `(response)` when response headers are received
26

27
**Returns:** `ClientRequest` instance
28

29
**Usage Examples:**
30

31
```javascript
32
const http = require('stream-http');
33

34
// Simple string URL
35
const req = http.request('https://api.example.com/data', function(res) {
36
  console.log('Status:', res.statusCode);
37
});
38
req.end();
39

40
// Options object
41
const req = http.request({
42
  hostname: 'api.example.com',
43
  port: 443,
44
  path: '/users',
45
  method: 'POST',
46
  headers: {
47
    'Content-Type': 'application/json',
48
    'Authorization': 'Bearer token123'
49
  }
50
}, function(res) {
51
  res.on('data', function(chunk) {
52
    console.log('Data:', chunk.toString());
53
  });
54
});
55

56
req.write(JSON.stringify({ name: 'Alice' }));
57
req.end();
58
```
59

60
### HTTP GET Function
61

62
Convenience method for GET requests that automatically calls `end()` on the request.
63

64
```javascript { .api }
65
/**
66
 * Convenience method for GET requests
67
 * @param opts - URL string or options object
68
 * @param cb - Optional callback for 'response' event
69
 * @returns ClientRequest instance with end() already called
70
 */
71
function get(opts, cb);
72
```
73

74
**Parameters:**
75
- `opts` (string | object): URL string or options object (same as `request()`)
76
- `cb` (function, optional): Response callback (same as `request()`)
77

78
**Returns:** `ClientRequest` instance (already ended)
79

80
**Usage Examples:**
81

82
```javascript
83
// Simple GET request
84
http.get('https://api.example.com/users', function(res) {
85
  let data = '';
86
  res.on('data', function(chunk) {
87
    data += chunk;
88
  });
89
  res.on('end', function() {
90
    console.log('Users:', JSON.parse(data));
91
  });
92
});
93

94
// GET with headers
95
http.get({
96
  hostname: 'api.example.com',
97
  path: '/protected',
98
  headers: {
99
    'Authorization': 'Bearer token123'
100
  }
101
}, function(res) {
102
  console.log('Protected data status:', res.statusCode);
103
});
104
```
105

106
## Request Options
107

108
### Standard Node.js Options
109

110
```javascript { .api }
111
interface StandardRequestOptions {
112
  /** Protocol (http: or https:) */
113
  protocol?: string;
114
  /** Server hostname */
115
  hostname?: string;
116
  /** Server host (alternative to hostname) */
117
  host?: string;
118
  /** Server port number */
119
  port?: number;
120
  /** Request path including query string */
121
  path?: string;
122
  /** HTTP method (default: 'GET') */
123
  method?: string;
124
  /** Request headers object */
125
  headers?: object;
126
  /** Basic authentication string ('user:pass') */
127
  auth?: string;
128
}
129
```
130

131
### Browser-Specific Options
132

133
```javascript { .api }
134
interface BrowserRequestOptions {
135
  /** Send cookies/credentials with CORS requests (default: false) */
136
  withCredentials?: boolean;
137
  /** Request mode affecting streaming behavior */
138
  mode?: 'default' | 'allow-wrong-content-type' | 'prefer-streaming' | 'disable-fetch' | 'prefer-fast';
139
  /** Request timeout in milliseconds */
140
  requestTimeout?: number;
141
  /** Socket timeout in milliseconds (Node.js compatibility) */
142
  timeout?: number;
143
}
144
```
145

146
### Complete Request Options
147

148
```javascript { .api }
149
interface RequestOptions extends StandardRequestOptions, BrowserRequestOptions {
150
  // All properties from both interfaces above
151
}
152
```
153

154
## Request Modes
155

156
The `mode` option controls how stream-http handles streaming and data correctness:
157

158
- **'default'** (or falsy): Balanced performance and correctness
159
- **'allow-wrong-content-type'**: More streaming but may affect content-type header
160
- **'prefer-streaming'**: Maximum streaming, may corrupt binary data
161
- **'disable-fetch'**: Force XHR usage for full compatibility
162
- **'prefer-fast'**: Deprecated, same as 'default'
163

164
## URL Construction
165

166
Stream-http automatically constructs URLs from options:
167

168
```javascript
169
// These are equivalent:
170
http.request('https://example.com:8080/path?query=value');
171

172
http.request({
173
  protocol: 'https:',
174
  hostname: 'example.com',
175
  port: 8080,
176
  path: '/path?query=value'
177
});
178
```
179

180
Protocol defaults to current page protocol if not specified (except for file: protocol which defaults to 'http:').