{ "type": "module", "source": "doc/api/api-roundrobinpool.md", "modules": [ { "textRaw": "RoundRobinPool", "name": "roundrobinpool", "introduced_in": "v7.17.0", "type": "module", "stability": 2, "stabilityText": "Stable", "desc": "

A pool of Client instances connected to the same upstream target that\nselects clients in a round-robin fashion.

\n

Unlike Pool, which always reuses the first available client,\nRoundRobinPool cycles through its clients so that requests are distributed\nevenly across every open connection. This is useful when the upstream target is\nfronted by a load balancer that distributes TCP connections across multiple\nbackend servers (for example, a Kubernetes Service): each connection is pinned\nto a backend by the load balancer, and RoundRobinPool spreads requests across\nthose connections so every backend receives a comparable share of traffic.

\n

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

\n
import { RoundRobinPool } from 'undici'\n\nconst pool = new RoundRobinPool('http://localhost:3000', { connections: 10 })\n
\n

RoundRobinPool distributes HTTP requests evenly across TCP connections, not\nacross backend servers directly. Even backend distribution therefore depends on\nthe load balancer assigning different connections to different backends (for\nexample, round-robin, random, or least-connections without client affinity). If\nthe load balancer pins all connections from one source to the same backend (for\nexample, source-IP affinity or sticky sessions), consider BalancedPool\nwith the individual backend addresses instead.

", "classes": [ { "textRaw": "Class: `RoundRobinPool`", "name": "RoundRobinPool", "type": "class", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "desc": "", "signatures": [ { "textRaw": "`new RoundRobinPool(url[, options])`", "name": "RoundRobinPool", "type": "ctor", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "params": [ { "textRaw": "`url` {URL|string} The upstream target. It should only include the **protocol, hostname, and port**.", "name": "url", "type": "URL|string", "desc": "The upstream target. It should only include the **protocol, hostname, and port**." }, { "textRaw": "`options` {RoundRobinPoolOptions} (optional)", "name": "options", "type": "RoundRobinPoolOptions", "desc": "(optional)", "optional": true } ], "modules": [ { "textRaw": "Parameter: `RoundRobinPoolOptions`", "name": "parameter:_`roundrobinpooloptions`", "type": "module", "desc": "

Extends: <ClientOptions>

\n\n

RoundRobinPool inherits all Client options. A Client instance is\ncreated lazily on the first dispatch and additional instances are created on\ndemand, up to connections, when every existing client is busy.

", "displayName": "Parameter: `RoundRobinPoolOptions`" } ] } ], "properties": [ { "textRaw": "Type: {boolean}", "name": "closed", "type": "boolean", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "desc": "

true after roundRobinPool.close() has been called.

" }, { "textRaw": "Type: {boolean}", "name": "destroyed", "type": "boolean", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "desc": "

true after roundRobinPool.destroy() has been called, or after\nroundRobinPool.close() has been called and the pool shutdown has completed.

" }, { "textRaw": "Type: {PoolStats}", "name": "stats", "type": "PoolStats", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "desc": "

Aggregate connection statistics for the pool. See PoolStats.

" } ], "methods": [ { "textRaw": "`roundRobinPool.close([callback])`", "name": "close", "type": "method", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "signatures": [ { "params": [ { "name": "callback", "optional": true } ] } ], "desc": "

Closes the pool and gracefully waits for enqueued requests to complete before\nresolving. Implements [dispatcher.close([callback])][].

" }, { "textRaw": "`roundRobinPool.destroy([error[, callback]])`", "name": "destroy", "type": "method", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "signatures": [ { "params": [ { "name": "error", "optional": true }, { "name": "callback", "optional": true } ] } ], "desc": "

Destroys the pool abruptly. All pending and running requests are aborted with\nthe given error. Implements [dispatcher.destroy([error[, callback]])][].

" }, { "textRaw": "`roundRobinPool.connect(options[, callback])`", "name": "connect", "type": "method", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "signatures": [ { "params": [ { "name": "options" }, { "name": "callback", "optional": true } ] } ], "desc": "

Starts two-way communications with the requested resource using\nHTTP CONNECT. See [dispatcher.connect(options[, callback])][].

" }, { "textRaw": "`roundRobinPool.dispatch(options, handler)`", "name": "dispatch", "type": "method", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "signatures": [ { "params": [ { "name": "options" }, { "name": "handler" } ] } ], "desc": "

Dispatches a request through the next client selected in round-robin order.\nImplements [dispatcher.dispatch(options, handler)][].

" }, { "textRaw": "`roundRobinPool.pipeline(options, handler)`", "name": "pipeline", "type": "method", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "signatures": [ { "params": [ { "name": "options" }, { "name": "handler" } ] } ], "desc": "

For easy use with [stream.pipeline][]. See\n[dispatcher.pipeline(options, handler)][].

" }, { "textRaw": "`roundRobinPool.request(options[, callback])`", "name": "request", "type": "method", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "signatures": [ { "params": [ { "name": "options" }, { "name": "callback", "optional": true } ] } ], "desc": "

Performs an HTTP request. See [dispatcher.request(options[, callback])][].

" }, { "textRaw": "`roundRobinPool.stream(options, factory[, callback])`", "name": "stream", "type": "method", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "signatures": [ { "params": [ { "name": "options" }, { "name": "factory" }, { "name": "callback", "optional": true } ] } ], "desc": "

A faster version of [roundRobinPool.request()][]. See\n[dispatcher.stream(options, factory[, callback])][].

" }, { "textRaw": "`roundRobinPool.upgrade(options[, callback])`", "name": "upgrade", "type": "method", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "signatures": [ { "params": [ { "name": "options" }, { "name": "callback", "optional": true } ] } ], "desc": "

Upgrades a connection to a different protocol. See\n[dispatcher.upgrade(options[, callback])][].

" } ], "events": [ { "textRaw": "Event: `'connect'`", "name": "connect", "type": "event", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "params": [], "desc": "

See [Dispatcher Event: 'connect'][].

" }, { "textRaw": "Event: `'disconnect'`", "name": "disconnect", "type": "event", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "params": [], "desc": "

See [Dispatcher Event: 'disconnect'][].

" }, { "textRaw": "Event: `'drain'`", "name": "drain", "type": "event", "meta": { "added": [ "v7.17.0" ], "changes": [] }, "params": [], "desc": "

See [Dispatcher Event: 'drain'][].

" } ] } ], "modules": [ { "textRaw": "Example", "name": "example", "type": "module", "desc": "
import { RoundRobinPool } from 'undici'\n\nconst pool = new RoundRobinPool('http://localhost:3000', {\n  connections: 10\n})\n\n// Requests are distributed evenly across all 10 connections.\nfor (let i = 0; i < 100; i++) {\n  const { body } = await pool.request({\n    path: '/api/data',\n    method: 'GET'\n  })\n  console.log(await body.json())\n}\n\nawait pool.close()\n
\n

[dispatcher.close([callback])]: Dispatcher.md#dispatcherclosecallback-promise\n[dispatcher.connect(options[, callback])]: Dispatcher.md#dispatcherconnectoptions-callback\n[dispatcher.destroy([error[, callback]])]: Dispatcher.md#dispatcherdestroyerror-callback-promise\n[dispatcher.dispatch(options, handler)]: Dispatcher.md#dispatcherdispatchoptions-handler\n[dispatcher.pipeline(options, handler)]: Dispatcher.md#dispatcherpipelineoptions-handler\n[dispatcher.request(options[, callback])]: Dispatcher.md#dispatcherrequestoptions-callback\n[dispatcher.stream(options, factory[, callback])]: Dispatcher.md#dispatcherstreamoptions-factory-callback\n[dispatcher.upgrade(options[, callback])]: Dispatcher.md#dispatcherupgradeoptions-callback\n[roundRobinPool.request()]: #roundrobinpoolrequestoptions-callback\n[stream.pipeline]: https://nodejs.org/api/stream.html#streampipelinesource-transforms-destination-callback\n[Dispatcher Event: 'connect']: Dispatcher.md#event-connect\n[Dispatcher Event: 'disconnect']: Dispatcher.md#event-disconnect\n[Dispatcher Event: 'drain']: Dispatcher.md#event-drain

", "displayName": "Example" } ] } ] }