BalancedPool

A BalancedPool distributes requests across a set of <Pool> instances, each connected to a different upstream. It uses a weighted round-robin algorithm: every upstream starts with the same weight, and the weight is adjusted up on successful connections and down on connection errors, so that healthy upstreams receive a larger share of traffic.

Requests are not guaranteed to be dispatched in the order they are issued.

import { BalancedPool } from 'undici'

const pool = new BalancedPool([
  'http://localhost:3000',
  'http://localhost:3001',
  'http://localhost:3002',
])

const { statusCode, body } = await pool.request({
  path: '/',
  method: 'GET',
})
console.log('response received', statusCode)
for await (const chunk of body) {
  console.log('data', chunk.toString())
}

class BalancedPool extends Dispatcher

A pool of <Pool> instances connected to multiple upstreams.

new BalancedPool(upstreams?, options?): void

The options passed to the constructor are forwarded to every <Pool> instance that is created for an upstream.

Extends: <PoolOptions>

In addition to all <PoolOptions>, the following options are supported:

balancedPool.addUpstream(upstream): BalancedPool

Adds an upstream. If an open, non-destroyed upstream with the same origin is already present, the call is a no-op.

balancedPool.removeUpstream(upstream): BalancedPool

Removes an upstream that was previously added. If no matching upstream is found, the call is a no-op.

balancedPool.getUpstream(upstream): Pool | undefined

Returns the <Pool> instance for the given upstream origin, if it is open and not destroyed.

Implements [client.closed][].

Implements [client.destroyed][].

Returns a <PoolStats> instance aggregating the statistics of the underlying pools.

balancedPool.close(callback?): void

Implements [Dispatcher.close([callback])][].

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

Implements [Dispatcher.destroy([error, callback])][].

balancedPool.connect(options, callback?): void

See [Dispatcher.connect(options[, callback])][].

balancedPool.dispatch(options, handlers): void

Implements [Dispatcher.dispatch(options, handler)][].

balancedPool.pipeline(options, handler): void

See [Dispatcher.pipeline(options, handler)][].

balancedPool.request(options, callback?): void

See [Dispatcher.request(options[, callback])][].

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

See [Dispatcher.stream(options, factory[, callback])][].

balancedPool.upgrade(options, callback?): void

See [Dispatcher.upgrade(options[, callback])][].

See Dispatcher Event: 'connect'.

See Dispatcher Event: 'disconnect'.

See Dispatcher Event: 'drain'.

[Dispatcher.close([callback])]: Dispatcher.md#dispatcherclosecallback-promise [Dispatcher.connect(options[, callback])]: Dispatcher.md#dispatcherconnectoptions-callback [Dispatcher.destroy([error, callback])]: Dispatcher.md#dispatcherdestroyerror-callback-promise [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 [client.closed]: Client.md#clientclosed [client.destroyed]: Client.md#clientdestroyed