0
# HTTP Clients
1

2
Core HTTP client implementations providing different connection management strategies and performance characteristics. All clients extend the base `Dispatcher` class and provide specialized behavior for different use cases.
3

4
## Capabilities
5

6
### Client
7

8
Basic HTTP/1.1 client for single-origin connections with pipelining support.
9

10
```typescript { .api }
11
/**
12
 * Basic HTTP/1.1 client for single connections to an origin
13
 * Supports request pipelining for improved performance
14
 */
15
class Client extends Dispatcher {
16
  constructor(url: string | URL, options?: Client.Options);
17
  
18
  /** Current pipelining factor (number of concurrent requests) */
19
  readonly pipelining: number;
20
  
21
  /** Whether the client is closed */
22
  readonly closed: boolean;
23
  
24
  /** Whether the client is destroyed */
25
  readonly destroyed: boolean;
26
  
27
  /** Client statistics */
28
  readonly stats: Client.SocketInfo;
29
}
30

31
interface Client.Options extends Dispatcher.DispatchOptions {
32
  /** The maximum number of requests to pipeline. Default: 1 */
33
  pipelining?: number;
34
  
35
  /** Timeout for each request in milliseconds */
36
  headersTimeout?: number;
37
  
38
  /** Timeout for request body in milliseconds */
39
  bodyTimeout?: number;
40
  
41
  /** Maximum number of concurrent requests */
42
  connections?: number;
43
  
44
  /** Keep-alive timeout in milliseconds */
45
  keepAliveTimeout?: number;
46
  
47
  /** Maximum keep-alive timeout in milliseconds */
48
  keepAliveMaxTimeout?: number;
49
  
50
  /** Keep-alive timeout threshold in milliseconds */
51
  keepAliveTimeoutThreshold?: number;
52
  
53
  /** TLS/SSL connection options */
54
  tls?: {
55
    ca?: string | Buffer | Array<string | Buffer>;
56
    cert?: string | Buffer;
57
    key?: string | Buffer;
58
    rejectUnauthorized?: boolean;
59
  };
60
  
61
  /** Custom socket connector function */
62
  connect?: buildConnector.connector;
63
}
64

65
interface Client.SocketInfo {
66
  connected: number;
67
  connecting: number;
68
  pending: number;
69
  queued: number;
70
  running: number;
71
  size: number;
72
}
73
```
74

75
**Usage Examples:**
76

77
```typescript
78
import { Client } from "undici-types";
79

80
// Basic client
81
const client = new Client("https://api.example.com");
82

83
// Client with options
84
const client = new Client("https://api.example.com", {
85
  pipelining: 10,
86
  headersTimeout: 30000,
87
  bodyTimeout: 30000,
88
  keepAliveTimeout: 4000
89
});
90

91
// Make requests
92
const response = await client.request({
93
  path: "/users",
94
  method: "GET"
95
});
96

97
// Close client when done
98
await client.close();
99
```
100

101
### Pool
102

103
Connection pool managing multiple clients to a single origin for high throughput.
104

105
```typescript { .api }
106
/**
107
 * Connection pool managing multiple clients to a single origin
108
 * Automatically handles connection lifecycle and load distribution
109
 */
110
class Pool extends Dispatcher {
111
  constructor(url: string | URL, options?: Pool.Options);
112
  
113
  /** Whether the pool is closed */
114
  readonly closed: boolean;
115
  
116
  /** Whether the pool is destroyed */
117
  readonly destroyed: boolean;
118
  
119
  /** Pool statistics */
120
  readonly stats: Pool.PoolStats;
121
}
122

123
interface Pool.Options extends Client.Options {
124
  /** Maximum number of clients in the pool */
125
  connections?: number;
126
  
127
  /** Factory function for creating clients */
128
  factory?: (origin: URL, opts: object) => Dispatcher;
129
}
130

131
interface Pool.PoolStats {
132
  connected: number;
133
  free: number;
134
  pending: number;
135
  queued: number;
136
  running: number;
137
  size: number;
138
}
139
```
140

141
**Usage Examples:**
142

143
```typescript
144
import { Pool } from "undici-types";
145

146
// Basic pool
147
const pool = new Pool("https://api.example.com");
148

149
// Pool with custom configuration
150
const pool = new Pool("https://api.example.com", {
151
  connections: 50,
152
  pipelining: 10,
153
  keepAliveTimeout: 60000
154
});
155

156
// High-throughput requests
157
const promises = Array.from({ length: 100 }, (_, i) =>
158
  pool.request({
159
    path: `/data/${i}`,
160
    method: "GET"
161
  })
162
);
163

164
const responses = await Promise.all(promises);
165
```
166

167
### Agent
168

169
HTTP agent managing pools for multiple origins with automatic origin-based routing.
170

171
```typescript { .api }
172
/**
173
 * HTTP agent managing multiple origin pools
174
 * Automatically routes requests to appropriate pools based on origin
175
 */
176
class Agent extends Dispatcher {
177
  constructor(options?: Agent.Options);
178
  
179
  /** Whether the agent is closed */
180
  readonly closed: boolean;
181
  
182
  /** Whether the agent is destroyed */
183
  readonly destroyed: boolean;
184
  
185
  /** Dispatch method for making requests */
186
  dispatch(options: Agent.DispatchOptions, handler: Dispatcher.DispatchHandler): boolean;
187
  
188
  /** Per-origin statistics */
189
  readonly stats: Record<string, Pool.PoolStats>;
190
}
191

192
interface Agent.Options extends Pool.Options {
193
  /** Factory function for creating pools */
194
  factory?: (origin: URL, opts: object) => Dispatcher;
195
  
196
  /** Maximum number of queued requests per origin */
197
  maxRedirections?: number;
198
}
199

200
interface Agent.DispatchOptions extends Dispatcher.DispatchOptions {
201
  /** Origin for the request (required) */
202
  origin?: string | URL;
203
}
204
```
205

206
**Usage Examples:**
207

208
```typescript
209
import { Agent, setGlobalDispatcher } from "undici-types";
210

211
// Create and set global agent
212
const agent = new Agent({
213
  connections: 100,
214
  pipelining: 10
215
});
216
setGlobalDispatcher(agent);
217

218
// Agent automatically handles multiple origins
219
const [response1, response2] = await Promise.all([
220
  agent.request({
221
    origin: "https://api1.example.com",
222
    path: "/users",
223
    method: "GET"
224
  }),
225
  agent.request({
226
    origin: "https://api2.example.com", 
227
    path: "/posts",
228
    method: "GET"
229
  })
230
]);
231
```
232

233
### BalancedPool
234

235
Load-balancing pool distributing requests across multiple upstream servers.
236

237
```typescript { .api }
238
/**
239
 * Load-balancing pool distributing requests across multiple upstreams
240
 * Provides high availability and load distribution
241
 */
242
class BalancedPool extends Dispatcher {
243
  constructor(url: string | URL | string[], options?: Pool.Options);
244
  
245
  /** Add an upstream server to the pool */
246
  addUpstream(upstream: string | URL): BalancedPool;
247
  
248
  /** Remove an upstream server from the pool */
249
  removeUpstream(upstream: string | URL): BalancedPool;
250
  
251
  /** Get list of upstream servers */
252
  upstreams: string[];
253
  
254
  /** Whether the pool is closed */
255
  readonly closed: boolean;
256
  
257
  /** Whether the pool is destroyed */
258
  readonly destroyed: boolean;
259
}
260
```
261

262
**Usage Examples:**
263

264
```typescript
265
import { BalancedPool } from "undici-types";
266

267
// Create balanced pool with multiple upstreams
268
const pool = new BalancedPool([
269
  "https://server1.example.com",
270
  "https://server2.example.com",
271
  "https://server3.example.com"
272
]);
273

274
// Dynamically manage upstreams
275
pool.addUpstream("https://server4.example.com");
276
pool.removeUpstream("https://server1.example.com");
277

278
// Requests are automatically load balanced
279
const response = await pool.request({
280
  path: "/api/data",
281
  method: "GET"
282
});
283
```
284

285
### H2CClient  
286

287
HTTP/2 cleartext client for HTTP/2 connections without TLS.
288

289
```typescript { .api }
290
/**
291
 * HTTP/2 cleartext client for unencrypted HTTP/2 connections
292
 * Supports HTTP/2 features like multiplexing and server push
293
 */
294
class H2CClient extends Client {
295
  constructor(url: string | URL, options?: H2CClient.Options);
296
}
297

298
interface H2CClient.Options extends Client.Options {
299
  /** HTTP/2 settings */
300
  settings?: {
301
    headerTableSize?: number;
302
    enablePush?: boolean;
303
    maxConcurrentStreams?: number;
304
    initialWindowSize?: number;
305
    maxFrameSize?: number;
306
    maxHeaderListSize?: number;
307
  };
308
}
309
```
310

311
**Usage Examples:**
312

313
```typescript
314
import { H2CClient } from "undici-types";
315

316
// HTTP/2 cleartext client
317
const client = new H2CClient("http://http2.example.com", {
318
  settings: {
319
    enablePush: true,
320
    maxConcurrentStreams: 100
321
  }
322
});
323

324
// Use HTTP/2 multiplexing
325
const [response1, response2] = await Promise.all([
326
  client.request({ path: "/api/users", method: "GET" }),
327
  client.request({ path: "/api/posts", method: "GET" })
328
]);
329
```
330

331
## Types
332

333
### Base Dispatcher Options
334

335
```typescript { .api }
336
interface Dispatcher.DispatchOptions {
337
  origin?: string | URL;
338
  path: string;
339
  method?: HttpMethod;
340
  body?: BodyInit;
341
  headers?: HeadersInit;
342
  query?: Record<string, any>;
343
  idempotent?: boolean;
344
  upgrade?: string;
345
  headersTimeout?: number;
346
  bodyTimeout?: number;
347
  reset?: boolean;
348
  throwOnError?: boolean;
349
  expectContinue?: boolean;
350
}
351

352
type HttpMethod = 
353
  | "GET" | "HEAD" | "POST" | "PUT" | "DELETE" 
354
  | "CONNECT" | "OPTIONS" | "TRACE" | "PATCH";
355

356
type BodyInit = 
357
  | ArrayBuffer | ArrayBufferView | NodeJS.ReadableStream 
358
  | string | URLSearchParams | FormData | Blob | null;
359

360
type HeadersInit = 
361
  | Headers | Record<string, string | string[]> 
362
  | Iterable<readonly [string, string]> | string[][];
363
```