Client

A basic HTTP/1.1 client mapped on top of a single TCP/TLS connection. When the server supports HTTP/2 and selects it during ALPN negotiation, the same connection is used for HTTP/2. Pipelining is disabled by default.

Client extends Dispatcher and is the lowest-level dispatcher in undici: it manages exactly one origin over one connection. For pooling across multiple connections use Pool, and for routing across multiple origins use Agent. Requests are not guaranteed to be dispatched in the order in which they are invoked.

import { Client } from 'undici'

const client = new Client('http://localhost:3000')
const { statusCode, body } = await client.request({ path: '/', method: 'GET' })

class Client extends Dispatcher

new Client(url, options?): Client

Instantiating a Client does not open a connection; the connection is established lazily once a request is queued. Call client.connect() to connect eagerly.

Notes about HTTP/2:

• Pseudo headers (:path, :method, :scheme, :authority) are attached automatically and overwrite any user-provided values.
• The server must support HTTP/2 and select it during ALPN negotiation, and must not give HTTP/1.1 a higher priority than HTTP/2.
• PUSH frames are not supported.

import { Client } from 'undici'

const client = new Client('http://localhost:3000')

When a connector function is provided, undici wraps it to automatically inject socketPath and allowH2 into the options argument when those values are set on the client. See Connector for details on building custom connectors.

client.close(callback?): void

Implements [dispatcher.close([callback])][]. Closes the client gracefully, waiting for enqueued requests to complete before resolving.

client.destroy(error?, callback?): void

Implements [dispatcher.destroy([error[, callback]])][]. Destroys the client abruptly, aborting all pending and running requests, and waits until the socket is closed before invoking callback (or resolving the returned promise).

client.connect(options, callback?): Promise | void

Starts a connection to the client's origin and tunnels a connection through it, as defined by [dispatcher.connect()][].

client.dispatch(options, handlers): void

Implements [dispatcher.dispatch(options, handler)][]. This is the lowest-level API used by all other request methods; prefer client.request() for most use cases.

client.pipeline(options, handler): void

See [dispatcher.pipeline(options, handler)][]. Sends a request and returns a <Duplex> stream that the request body is written to and the response body is read from.

client.request(options, callback?): Promise | void

See [dispatcher.request(options[, callback])][]. Performs an HTTP request and returns its status code, headers, trailers, and a readable body stream.

import { Client } from 'undici'

const client = new Client('http://localhost:3000')
const { statusCode, headers, body } = await client.request({
  path: '/',
  method: 'GET'
})

console.log(statusCode)
for await (const chunk of body) {
  console.log(chunk.toString())
}

client.stream(options, factory, callback?): Promise | void

See [dispatcher.stream(options, factory[, callback])][]. A faster alternative to client.request() when the destination of the response body is known in advance.

client.upgrade(options, callback?): Promise | void

See [dispatcher.upgrade(options[, callback])][]. Upgrades a connection to a different protocol, such as for WebSocket or HTTP CONNECT.

true after client.close() has been called.

true after client.destroy() has been called, or after client.close() has been called and the client shutdown has completed.

The pipelining factor. This property can be read and written to adjust the number of concurrent requests sent over the connection. Only enable pipelining with trusted remote servers.

Aggregate statistics for the client. See ClientStats.

Emitted when a socket has been created and connected. The client connects once client.size > 0. See Dispatcher Event: 'connect'.

import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'

const server = createServer((request, response) => {
  response.end('Hello, World!')
}).listen()

await once(server, 'listening')

const client = new Client(`http://localhost:${server.address().port}`)

client.on('connect', (origin) => {
  console.log(`Connected to ${origin}`)
})

const { body } = await client.request({ path: '/', method: 'GET' })
body.setEncoding('utf8')
body.on('data', console.log)

client.close()
server.close()

Emitted when a socket has disconnected. The error argument is the error that caused the disconnection. The client reconnects if or once client.size > 0. See Dispatcher Event: 'disconnect'.

import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'

const server = createServer((request, response) => {
  response.destroy()
}).listen()

await once(server, 'listening')

const client = new Client(`http://localhost:${server.address().port}`)

client.on('disconnect', (origin) => {
  console.log(`Disconnected from ${origin}`)
})

try {
  await client.request({ path: '/', method: 'GET' })
} catch (error) {
  console.error(error.message)
} finally {
  client.close()
  server.close()
}

Emitted when the pipeline is no longer busy. See Dispatcher Event: 'drain'.

import { createServer } from 'node:http'
import { Client } from 'undici'
import { once } from 'node:events'

const server = createServer((request, response) => {
  response.end('Hello, World!')
}).listen()

await once(server, 'listening')

const client = new Client(`http://localhost:${server.address().port}`)

client.on('drain', () => {
  console.log('drain event')
  client.close()
  server.close()
})

await Promise.all([
  client.request({ path: '/', method: 'GET' }),
  client.request({ path: '/', method: 'GET' }),
  client.request({ path: '/', method: 'GET' })
])

Emitted for user errors, such as throwing inside an onResponseError handler.

[dispatcher.close([callback])]: Dispatcher.md#dispatcherclosecallback [dispatcher.connect()]: Dispatcher.md#dispatcherconnectoptions-callback [dispatcher.destroy([error[, callback]])]: Dispatcher.md#dispatcherdestroyerror-callback [dispatcher.dispatch(options, handler)]: Dispatcher.md#dispatcherdispatchoptions-handler [dispatcher.pipeline(options, handler)]: Dispatcher.md#dispatcherpipelineoptions-handler [dispatcher.request(options[, callback])]: Dispatcher.md#dispatcherrequestoptions-callback [dispatcher.stream(options, factory[, callback])]: Dispatcher.md#dispatcherstreamoptions-factory-callback [dispatcher.upgrade(options[, callback])]: Dispatcher.md#dispatcherupgradeoptions-callback [tls.connect()]: https://nodejs.org/api/tls.html#tlsconnectoptions-callback