{
  "type": "module",
  "source": "doc/api/api-roundrobinpool.md",
  "modules": [
    {
      "textRaw": "Class: RoundRobinPool",
      "name": "class:_roundrobinpool",
      "type": "module",
      "desc": "<p>Extends: <code>undici.Dispatcher</code></p>\n<p>A pool of <a href=\"/docs/docs/api/Client.html\">Client</a> instances connected to the same upstream target with round-robin client selection.</p>\n<p>Unlike <a href=\"/docs/docs/api/Pool.html\"><code>Pool</code></a>, which always selects the first available client, <code>RoundRobinPool</code> cycles through clients in a round-robin fashion. This ensures even distribution of requests across all connections, which is particularly useful when the upstream target is behind a load balancer that round-robins TCP connections across multiple backend servers (e.g., Kubernetes Services).</p>\n<p>Requests are not guaranteed to be dispatched in order of invocation.</p>",
      "signatures": [
        {
          "textRaw": "`new RoundRobinPool(url[, options])`",
          "name": "RoundRobinPool",
          "type": "ctor",
          "params": [
            {
              "name": "url"
            },
            {
              "name": "options",
              "optional": true
            }
          ],
          "desc": "<p>Arguments:</p>\n<ul>\n<li><strong>url</strong> <code>URL | string</code> - It should only include the <strong>protocol, hostname, and port</strong>.</li>\n<li><strong>options</strong> <code>RoundRobinPoolOptions</code> (optional)</li>\n</ul>",
          "modules": [
            {
              "textRaw": "Parameter: `RoundRobinPoolOptions`",
              "name": "parameter:_`roundrobinpooloptions`",
              "type": "module",
              "desc": "<p>Extends: <a href=\"/docs/docs/api/Client.html#parameter-clientoptions\"><code>ClientOptions</code></a></p>\n<ul>\n<li><strong>factory</strong> <code>(origin: URL, opts: Object) => Dispatcher</code> - Default: <code>(origin, opts) => new Client(origin, opts)</code></li>\n<li><strong>connections</strong> <code>number | null</code> (optional) - Default: <code>null</code> - The number of <code>Client</code> instances to create. When set to <code>null</code>, the <code>RoundRobinPool</code> instance will create an unlimited amount of <code>Client</code> instances.</li>\n<li><strong>clientTtl</strong> <code>number | null</code> (optional) - Default: <code>null</code> - The amount of time before a <code>Client</code> instance is removed from the <code>RoundRobinPool</code> and closed. When set to <code>null</code>, <code>Client</code> instances will not be removed or closed based on age.</li>\n</ul>",
              "displayName": "Parameter: `RoundRobinPoolOptions`"
            }
          ]
        }
      ],
      "modules": [
        {
          "textRaw": "Use Case",
          "name": "use_case",
          "type": "module",
          "desc": "<p><code>RoundRobinPool</code> is designed for scenarios where:</p>\n<ol>\n<li>You connect to a single origin (e.g., <code>http://my-service.namespace.svc</code>)</li>\n<li>That origin is backed by a load balancer distributing TCP connections across multiple servers</li>\n<li>You want requests evenly distributed across all backend servers</li>\n</ol>\n<p><strong>Example</strong>: In Kubernetes, when using a Service DNS name with multiple Pod replicas, kube-proxy load balances TCP connections. <code>RoundRobinPool</code> ensures each connection (and thus each Pod) receives an equal share of requests.</p>",
          "modules": [
            {
              "textRaw": "Important: Backend Distribution Considerations",
              "name": "important:_backend_distribution_considerations",
              "type": "module",
              "desc": "<p><code>RoundRobinPool</code> distributes <strong>HTTP requests</strong> evenly across <strong>TCP connections</strong>. Whether this translates to even backend server distribution depends on the load balancer's behavior:</p>\n<p><strong>✓ Works when the load balancer</strong>:</p>\n<ul>\n<li>Assigns different backends to different TCP connections from the same client</li>\n<li>Uses algorithms like: round-robin, random, least-connections (without client affinity)</li>\n<li>Example: Default Kubernetes Services without <code>sessionAffinity</code></li>\n</ul>\n<p><strong>✗ Does NOT work when</strong>:</p>\n<ul>\n<li>Load balancer has client/source IP affinity (all connections from one IP → same backend)</li>\n<li>Load balancer uses source-IP-hash or sticky sessions</li>\n</ul>\n<p><strong>How it works:</strong></p>\n<ol>\n<li><code>RoundRobinPool</code> creates N TCP connections to the load balancer endpoint</li>\n<li>Load balancer assigns each TCP connection to a backend (per its algorithm)</li>\n<li><code>RoundRobinPool</code> cycles HTTP requests across those N connections</li>\n<li>Result: Requests distributed proportionally to how the LB distributed the connections</li>\n</ol>\n<p>If the load balancer assigns all connections to the same backend (e.g., due to session affinity), <code>RoundRobinPool</code> cannot overcome this. In such cases, consider using <a href=\"/docs/docs/api/BalancedPool.html\"><code>BalancedPool</code></a> with direct backend addresses (e.g., individual pod IPs) instead of a load-balanced endpoint.</p>",
              "displayName": "Important: Backend Distribution Considerations"
            }
          ],
          "displayName": "Use Case"
        },
        {
          "textRaw": "Instance Properties",
          "name": "instance_properties",
          "type": "module",
          "properties": [
            {
              "textRaw": "`RoundRobinPool.closed`",
              "name": "closed",
              "type": "property",
              "desc": "<p>Implements <a href=\"/docs/docs/api/Client.html#clientclosed\">Client.closed</a></p>"
            },
            {
              "textRaw": "`RoundRobinPool.destroyed`",
              "name": "destroyed",
              "type": "property",
              "desc": "<p>Implements <a href=\"/docs/docs/api/Client.html#clientdestroyed\">Client.destroyed</a></p>"
            },
            {
              "textRaw": "`RoundRobinPool.stats`",
              "name": "stats",
              "type": "property",
              "desc": "<p>Returns <a href=\"/docs/docs/api/PoolStats.html\"><code>PoolStats</code></a> instance for this pool.</p>"
            }
          ],
          "displayName": "Instance Properties"
        },
        {
          "textRaw": "Instance Methods",
          "name": "instance_methods",
          "type": "module",
          "methods": [
            {
              "textRaw": "`RoundRobinPool.close([callback])`",
              "name": "close",
              "type": "method",
              "signatures": [
                {
                  "params": [
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>Implements <a href=\"/docs/docs/api/Dispatcher.html#dispatcherclosecallback-promise\"><code>Dispatcher.close([callback])</code></a>.</p>"
            },
            {
              "textRaw": "`RoundRobinPool.destroy([error, callback])`",
              "name": "destroy",
              "type": "method",
              "signatures": [
                {
                  "params": [
                    {
                      "name": "error",
                      "optional": true
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>Implements <a href=\"/docs/docs/api/Dispatcher.html#dispatcherdestroyerror-callback-promise\"><code>Dispatcher.destroy([error, callback])</code></a>.</p>"
            },
            {
              "textRaw": "`RoundRobinPool.connect(options[, callback])`",
              "name": "connect",
              "type": "method",
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>See <a href=\"/docs/docs/api/Dispatcher.html#dispatcherconnectoptions-callback\"><code>Dispatcher.connect(options[, callback])</code></a>.</p>"
            },
            {
              "textRaw": "`RoundRobinPool.dispatch(options, handler)`",
              "name": "dispatch",
              "type": "method",
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "handler"
                    }
                  ]
                }
              ],
              "desc": "<p>Implements <a href=\"/docs/docs/api/Dispatcher.html#dispatcherdispatchoptions-handler\"><code>Dispatcher.dispatch(options, handler)</code></a>.</p>"
            },
            {
              "textRaw": "`RoundRobinPool.pipeline(options, handler)`",
              "name": "pipeline",
              "type": "method",
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "handler"
                    }
                  ]
                }
              ],
              "desc": "<p>See <a href=\"/docs/docs/api/Dispatcher.html#dispatcherpipelineoptions-handler\"><code>Dispatcher.pipeline(options, handler)</code></a>.</p>"
            },
            {
              "textRaw": "`RoundRobinPool.request(options[, callback])`",
              "name": "request",
              "type": "method",
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>See <a href=\"/docs/docs/api/Dispatcher.html#dispatcherrequestoptions-callback\"><code>Dispatcher.request(options [, callback])</code></a>.</p>"
            },
            {
              "textRaw": "`RoundRobinPool.stream(options, factory[, callback])`",
              "name": "stream",
              "type": "method",
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "factory"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>See <a href=\"/docs/docs/api/Dispatcher.html#dispatcherstreamoptions-factory-callback\"><code>Dispatcher.stream(options, factory[, callback])</code></a>.</p>"
            },
            {
              "textRaw": "`RoundRobinPool.upgrade(options[, callback])`",
              "name": "upgrade",
              "type": "method",
              "signatures": [
                {
                  "params": [
                    {
                      "name": "options"
                    },
                    {
                      "name": "callback",
                      "optional": true
                    }
                  ]
                }
              ],
              "desc": "<p>See <a href=\"/docs/docs/api/Dispatcher.html#dispatcherupgradeoptions-callback\"><code>Dispatcher.upgrade(options[, callback])</code></a>.</p>"
            }
          ],
          "displayName": "Instance Methods"
        },
        {
          "textRaw": "Instance Events",
          "name": "instance_events",
          "type": "module",
          "events": [
            {
              "textRaw": "Event: `'connect'`",
              "name": "connect",
              "type": "event",
              "params": [],
              "desc": "<p>See <a href=\"/docs/docs/api/Dispatcher.html#event-connect\">Dispatcher Event: <code>'connect'</code></a>.</p>"
            },
            {
              "textRaw": "Event: `'disconnect'`",
              "name": "disconnect",
              "type": "event",
              "params": [],
              "desc": "<p>See <a href=\"/docs/docs/api/Dispatcher.html#event-disconnect\">Dispatcher Event: <code>'disconnect'</code></a>.</p>"
            },
            {
              "textRaw": "Event: `'drain'`",
              "name": "drain",
              "type": "event",
              "params": [],
              "desc": "<p>See <a href=\"/docs/docs/api/Dispatcher.html#event-drain\">Dispatcher Event: <code>'drain'</code></a>.</p>"
            }
          ],
          "displayName": "Instance Events"
        },
        {
          "textRaw": "Example",
          "name": "example",
          "type": "module",
          "desc": "<pre><code class=\"language-javascript\">import { RoundRobinPool } from 'undici'\n\nconst pool = new RoundRobinPool('http://my-service.default.svc.cluster.local', {\n  connections: 10\n})\n\n// Requests will be distributed evenly across all 10 connections\nfor (let i = 0; i &#x3C; 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</code></pre>",
          "displayName": "Example"
        },
        {
          "textRaw": "See Also",
          "name": "see_also",
          "type": "module",
          "desc": "<ul>\n<li><a href=\"/docs/docs/api/Pool.html\">Pool</a> - Connection pool without round-robin</li>\n<li><a href=\"/docs/docs/api/BalancedPool.html\">BalancedPool</a> - Load balancing across multiple origins</li>\n<li><a href=\"https://github.com/nodejs/undici/issues/3648\">Issue #3648</a> - Original issue describing uneven distribution</li>\n</ul>",
          "displayName": "See Also"
        }
      ],
      "displayName": "Class: RoundRobinPool"
    }
  ]
}