Pool

A pool of Client instances connected to the same upstream origin. A Pool spreads requests across several connections to the same host, which allows more than one request to be in flight at a time without enabling pipelining on a single connection.

Pool extends Dispatcher. Each Client in the pool is created lazily through a configurable factory and shares the same options. Requests are not guaranteed to be dispatched in the order in which they are invoked.

import { Pool } from 'undici'

const pool = new Pool('http://localhost:3000', { connections: 10 })
const { statusCode, body } = await pool.request({ path: '/', method: 'GET' })
console.log(statusCode, await body.text())
await pool.close()

class Pool extends Dispatcher

new Pool(url, options?): void

Creates a new Pool against url. If connections is provided it must be a finite, non-negative number, otherwise an InvalidArgumentError is thrown. The factory must be a function, and connect (inherited from <ClientOptions>) must be a function or an object when provided.

The connection-related <ClientOptions> (connect, connectTimeout, tls, maxCachedSessions, socketPath, autoSelectFamily, autoSelectFamilyAttemptTimeout, allowH2, and useH2c) are used to build the connector shared by every pooled client.

import { Pool } from 'undici'

const pool = new Pool('http://localhost:3000', {
  connections: 128,
  pipelining: 1
})

true after [pool.close()][] has been called.

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

Aggregate statistics for the pool. See PoolStats.

pool.close(callback?): void

Implements [dispatcher.close([callback])][]. Gracefully closes the pool and all of its clients, waiting for in-flight requests to complete. Resolves once every pooled client has closed.

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

Implements [dispatcher.destroy([error[, callback]])][]. Forcefully destroys the pool and all of its clients, aborting any in-flight requests with error.

pool.connect(options, callback?): void

See [dispatcher.connect(options[, callback])][]. Performs an HTTP CONNECT request through one of the pooled clients.

pool.dispatch(options, handler): void

Implements [dispatcher.dispatch(options, handler)][]. Selects an available client - creating a new one through factory when none is free and the connections limit has not been reached - and dispatches the request to it.

pool.pipeline(options, handler): void

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

pool.request(options, callback?): void

See [dispatcher.request(options[, callback])][]. Performs a request through one of the pooled clients.

import { Pool } from 'undici'

const pool = new Pool('http://localhost:3000', { connections: 10 })
const { statusCode, headers, body } = await pool.request({
  path: '/',
  method: 'GET'
})
console.log(statusCode, headers)
console.log(await body.text())
await pool.close()

pool.stream(options, factory, callback?): void

See [dispatcher.stream(options, factory[, callback])][]. Performs a request and writes the response body into the <Writable> stream returned by factory.

pool.upgrade(options, callback?): void

See [dispatcher.upgrade(options[, callback])][]. Upgrades a connection (for example to a WebSocket) through one of the pooled clients.

Emitted by a pooled client when a socket has connected. See Dispatcher Event: 'connect'. When clientTtl is set, the connecting client's time-to-live timer starts on this event.

Emitted by a pooled client when a socket has disconnected. See Dispatcher Event: 'disconnect'.

Emitted when a pooled client is no longer busy and can accept more requests. See Dispatcher Event: 'drain'.

[dispatcher.close([callback])]: Dispatcher.md#dispatcherclosecallback [dispatcher.connect(options[, callback])]: 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 [pool.close()]: #poolclosecallback [pool.destroy()]: #pooldestroyerror-callback