undici 4.7.2 → 4.8.2

package/docs/api/BalancedPool.md

@@ -0,0 +1,98 @@
+# Class: BalancedPool
+
+Extends: `undici.Dispatcher`
+
+A pool of [Pool](docs/api/Pool.md) instances connected to multiple upstreams.
+
+Requests are not guaranteed to be dispatched in order of invocation.
+
+## `new BalancedPool(upstreams [, options])`
+
+Arguments:
+
+* **upstreams** `URL | string | string[]` - It should only include the **protocol, hostname, and port**.
+* **options** `PoolOptions` (optional)
+
+### Parameter: `PoolOptions`
+
+The `PoolOptions` are passed to each of the `Pool` instances being created.
+
+See: [`PoolOptions`](docs/api/Pool.md#parameter-pooloptions)
+
+## Instance Properties
+
+### `BalancedPool.upstreams`
+
+Returns an array of upstreams that were previously added.
+
+### `BalancedPool.busy`
+
+Implements [Client.busy](docs/api/Client.md#clientbusy)
+
+### `BalancedPool.closed`
+
+Implements [Client.closed](docs/api/Client.md#clientclosed)
+
+### `BalancedPool.destroyed`
+
+Implements [Client.destroyed](docs/api/Client.md#clientdestroyed)
+
+## Instance Methods
+
+### `BalancedPool.addUpstream(upstream)`
+
+Add an upstream.
+
+Arguments:
+
+* **upstream** `string` - It should only include the **protocol, hostname, and port**.
+
+### `BalancedPool.removeUpstream(upstream)`
+
+Removes an upstream that was previously addded.
+
+### `BalancedPool.close([callback])`
+
+Implements [`Dispatcher.close([callback])`](docs/api/Dispatcher.md#clientclose-callback-).
+
+### `BalancedPool.destroy([error, callback])`
+
+Implements [`Dispatcher.destroy([error, callback])`](docs/api/Dispatcher.md#dispatcher-callback-).
+
+### `BalancedPool.connect(options[, callback])`
+
+See [`Dispatcher.connect(options[, callback])`](docs/api/Dispatcher.md#clientconnectoptions--callback).
+
+### `BalancedPool.dispatch(options, handlers)`
+
+Implements [`Dispatcher.dispatch(options, handlers)`](docs/api/Dispatcher.md#clientdispatchoptions-handlers).
+
+### `BalancedPool.pipeline(options, handler)`
+
+See [`Dispatcher.pipeline(options, handler)`](docs/api/Dispatcher.md#clientpipelineoptions-handler).
+
+### `BalancedPool.request(options[, callback])`
+
+See [`Dispatcher.request(options [, callback])`](docs/api/Dispatcher.md#clientrequestoptions--callback).
+
+### `BalancedPool.stream(options, factory[, callback])`
+
+See [`Dispatcher.stream(options, factory[, callback])`](docs/api/Dispatcher.md#clientstreamoptions-factory--callback).
+
+### `BalancedPool.upgrade(options[, callback])`
+
+See [`Dispatcher.upgrade(options[, callback])`](docs/api/Dispatcher.md#clientupgradeoptions-callback).
+
+## Instance Events
+
+### Event: `'connect'`
+
+See [Dispatcher Event: `'connect'`](docs/api/Dispatcher.md#event-connect).
+
+### Event: `'disconnect'`
+
+See [Dispatcher Event: `'disconnect'`](docs/api/Dispatcher.md#event-connect).
+
+### Event: `'drain'`
+
+See [Dispatcher Event: `'drain'`](docs/api/Dispatcher.md#event-connect).

package/docs/api/ProxyAgent.md

@@ -0,0 +1,100 @@
+# Class: ProxyAgent
+
+Extends: `undici.Dispatcher`
+
+A Proxy Agent class that implements the Agent API. It allows the connection through proxy in a simple way.
+
+## `new ProxyAgent([options])`
+
+Arguments:
+
+* **options** `ProxyAgentOptions` (required) - It extends the `Agent` options.
+
+Returns: `ProxyAgent`
+
+### Parameter: `ProxyAgentOptions`
+
+Extends: [`AgentOptions`](docs/api/Agent.md#parameter-agentoptions)
+
+* **uri** `string` (required) - It can be passed either by a string or a object containing `uri` as string.
+
+Examples:
+
+```js
+import { ProxyAgent } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+// or
+const proxyAgent = new ProxyAgent({ uri: 'my.proxy.server' })
+```
+
+#### Example - Basic ProxyAgent instantiation
+
+This will instantiate the ProxyAgent. It will not do anything until registered as the agent to use with requests.
+
+```js
+import { ProxyAgent } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+```
+
+#### Example - Basic Proxy Request with global agent dispatcher
+
+```js
+import { setGlobalDispatcher, request, ProxyAgent } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+setGlobalDispatcher(proxyAgent)
+
+const { statusCode, body } = await request('http://localhost:3000/foo')
+
+console.log('response received', statusCode) // response received 200
+
+for await (const data of body) {
+  console.log('data', data.toString('utf8')) // data foo
+}
+```
+
+#### Example - Basic Proxy Request with local agent dispatcher
+
+```js
+import { ProxyAgent, request } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+
+const {
+  statusCode,
+  body
+} = await request('http://localhost:3000/foo', { dispatcher: proxyAgent })
+
+console.log('response received', statusCode) // response received 200
+
+for await (const data of body) {
+  console.log('data', data.toString('utf8')) // data foo
+}
+```
+
+### `ProxyAgent.close()`
+
+Closes the proxy agent and waits for registered pools and clients to also close before resolving.
+
+Returns: `Promise<void>`
+
+#### Example - clean up after tests are complete
+
+```js
+import { ProxyAgent, setGlobalDispatcher } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+setGlobalDispatcher(proxyAgent)
+
+await proxyAgent.close()
+```
+
+### `ProxyAgent.dispatch(options, handlers)`
+
+Implements [`Agent.dispatch(options, handlers)`](docs/api/Agent.md#parameter-agentdispatchoptions).
+
+### `ProxyAgent.request(options[, callback])`
+
+See [`Dispatcher.request(options [, callback])`](docs/api/Dispatcher.md#clientrequestoptions--callback).

package/docs/best-practices/proxy.md

@@ -1,6 +1,9 @@
 # Connecting through a proxy
 
-Connecting through a proxy is possible by properly configuring the `Client` or `Pool` constructor and request.
+Connecting through a proxy is possible by:
+
+- Using [AgentProxy](docs/api/ProxyAgent.md).
+- Configuring `Client` or `Pool` constructor.
 
 The proxy url should be passed to the `Client` or `Pool` constructor, while the upstream server url
 should be added to every request call in the `path`.

package/index.d.ts

@@ -1,6 +1,7 @@
 import Dispatcher = require('./types/dispatcher')
 import { setGlobalDispatcher, getGlobalDispatcher } from './types/global-dispatcher'
 import Pool = require('./types/pool')
+import BalancedPool = require('./types/balanced-pool')
 import Client = require('./types/client')
 import buildConnector = require('./types/connector')
 import errors = require('./types/errors')
@@ -9,13 +10,14 @@ import MockClient = require('./types/mock-client')
 import MockPool = require('./types/mock-pool')
 import MockAgent = require('./types/mock-agent')
 import mockErrors = require('./types/mock-errors')
+import ProxyAgent from './types/proxy-agent'
 import { request, pipeline, stream, connect, upgrade } from './types/api'
 
 export * from './types/fetch'
 export * from './types/file'
 export * from './types/formdata'
 
-export { Dispatcher, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, MockClient, MockPool, MockAgent, mockErrors }
+export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, MockClient, MockPool, MockAgent, mockErrors, ProxyAgent }
 export default Undici
 
 declare function Undici(url: string, opts: Pool.Options): Pool
@@ -23,6 +25,7 @@ declare function Undici(url: string, opts: Pool.Options): Pool
 declare namespace Undici {
   var Dispatcher: typeof import('./types/dispatcher')
   var Pool: typeof import('./types/pool');
+  var BalancedPool: typeof import('./types/balanced-pool');
   var Client: typeof import('./types/client');
   var buildConnector: typeof import('./types/connector');
   var errors: typeof import('./types/errors');

package/index.js

@@ -4,6 +4,7 @@ const Client = require('./lib/client')
 const Dispatcher = require('./lib/dispatcher')
 const errors = require('./lib/core/errors')
 const Pool = require('./lib/pool')
+const BalancedPool = require('./lib/balanced-pool')
 const Agent = require('./lib/agent')
 const util = require('./lib/core/util')
 const { InvalidArgumentError } = errors
@@ -13,6 +14,7 @@ const MockClient = require('./lib/mock/mock-client')
 const MockAgent = require('./lib/mock/mock-agent')
 const MockPool = require('./lib/mock/mock-pool')
 const mockErrors = require('./lib/mock/mock-errors')
+const ProxyAgent = require('./lib/proxy-agent')
 
 const nodeVersion = process.versions.node.split('.')
 const nodeMajor = Number(nodeVersion[0])
@@ -23,7 +25,9 @@ Object.assign(Dispatcher.prototype, api)
 module.exports.Dispatcher = Dispatcher
 module.exports.Client = Client
 module.exports.Pool = Pool
+module.exports.BalancedPool = BalancedPool
 module.exports.Agent = Agent
+module.exports.ProxyAgent = ProxyAgent
 
 module.exports.buildConnector = buildConnector
 module.exports.errors = errors
@@ -89,8 +93,11 @@ module.exports.setGlobalDispatcher = setGlobalDispatcher
 module.exports.getGlobalDispatcher = getGlobalDispatcher
 
 if (nodeMajor > 16 || (nodeMajor === 16 && nodeMinor >= 5)) {
-  const fetchImpl = require('./lib/fetch')
+  let fetchImpl = null
   module.exports.fetch = async function fetch (resource, init) {
+    if (!fetchImpl) {
+      fetchImpl = require('./lib/fetch')
+    }
     const dispatcher = getGlobalDispatcher()
     return fetchImpl.call(dispatcher, resource, init)
   }

package/lib/balanced-pool.js

@@ -0,0 +1,119 @@
+'use strict'
+
+const { BalancedPoolMissingUpstreamError } = require('./core/errors')
+const Dispatcher = require('./dispatcher')
+const Pool = require('./pool')
+
+const kPools = Symbol('kPools')
+const kPoolOpts = Symbol('kPoolOpts')
+const kUpstream = Symbol('kUpstream')
+const kNeedDrain = Symbol('kNeedDrain')
+
+class BalancedPool extends Dispatcher {
+  constructor (upstreams = [], opts = {}) {
+    super()
+
+    this[kPools] = []
+    this[kPoolOpts] = opts
+    this[kNeedDrain] = false
+
+    if (!Array.isArray(upstreams)) {
+      upstreams = [upstreams]
+    }
+
+    for (const upstream of upstreams) {
+      this.addUpstream(upstream)
+    }
+  }
+
+  addUpstream (upstream) {
+    if (this[kPools].find((pool) => pool[kUpstream] === upstream)) {
+      return this
+    }
+
+    const pool = new Pool(upstream, Object.assign({}, this[kPoolOpts]))
+
+    pool[kUpstream] = upstream
+
+    pool.on('connect', (...args) => {
+      this.emit('connect', ...args)
+    })
+
+    pool.on('disconnect', (...args) => {
+      this.emit('disconnect', ...args)
+    })
+
+    pool.on('drain', (...args) => {
+      if (this[kNeedDrain]) {
+        this[kNeedDrain] = false
+        this.emit('drain', ...args)
+      }
+    })
+
+    this[kPools].push(pool)
+    return this
+  }
+
+  dispatch (opts, handler) {
+    // We validate that pools is greater than 0,
+    // otherwise we would have to wait until an upstream
+    // is added, which might never happen.
+    if (this[kPools].length === 0) {
+      throw new BalancedPoolMissingUpstreamError()
+    }
+
+    let pool = this[kPools].shift()
+    this[kPools].push(pool)
+    if (pool.busy) {
+      pool = this[kPools].find(pool => !pool.busy) || pool
+    }
+    this[kNeedDrain] = !pool.dispatch(opts, handler)
+    return !this[kNeedDrain]
+  }
+
+  removeUpstream (upstream) {
+    const pool = this[kPools].find((pool) => pool[kUpstream] === upstream)
+    const idx = this[kPools].indexOf(pool)
+    this[kPools].splice(idx, 1)
+    pool.close()
+    return this
+  }
+
+  get upstreams () {
+    return this[kPools].map((p) => p[kUpstream])
+  }
+
+  get destroyed () {
+    return this[kPools].reduce((acc, pool) => acc && pool.destroyed, true)
+  }
+
+  get busy () {
+    return this[kPools].reduce((acc, pool) => acc && pool.busy, true) || false
+  }
+
+  get closed () {
+    return this[kPools].reduce((acc, pool) => acc && pool.closed, true)
+  }
+
+  close (cb) {
+    const p = Promise.all(this[kPools].map((p) => p.close()))
+
+    if (!cb) {
+      return p
+    }
+
+    p.then(() => process.nextTick(cb), (err) => process.nextTick(cb, err))
+  }
+
+  destroy (err, cb) {
+    const p = Promise.all(this[kPools].map((p) => p.destroy(err)))
+
+    if (!cb) {
+      return p
+    }
+
+    p.then(() => process.nextTick(cb))
+  }
+}
+
+module.exports = BalancedPool

package/lib/client.js

@@ -397,76 +397,77 @@ class Client extends Dispatcher {
   }
 }
 
-const { resolve } = require('path')
-const { readFileSync } = require('fs')
 const constants = require('./llhttp/constants')
 const EMPTY_BUF = Buffer.alloc(0)
 
+let llhttpPromise
 let llhttpInstance
-function lazyllhttp () {
-  if (!llhttpInstance) {
-    let mod
-    try {
-      mod = new WebAssembly.Module(readFileSync(resolve(__dirname, './llhttp/llhttp_simd.wasm')))
-    } catch (e) {
-      /* istanbul ignore next */
+async function lazyllhttp () {
+  const { resolve } = require('path')
+  const { readFile } = require('fs').promises
 
-      // We could check if the error was caused by the simd option not
-      // being enabled, but the occurring of this other error
-      // * https://github.com/emscripten-core/emscripten/issues/11495
-      // got me to remove that check to avoid breaking Node 12.
-      mod = new WebAssembly.Module(readFileSync(resolve(__dirname, './llhttp/llhttp.wasm')))
-    }
+  let mod
+  try {
+    mod = await WebAssembly.compile(await readFile(resolve(__dirname, './llhttp/llhttp_simd.wasm')))
+  } catch (e) {
+    /* istanbul ignore next */
 
-    llhttpInstance = new WebAssembly.Instance(mod, {
-      env: {
-        /* eslint-disable camelcase */
+    // We could check if the error was caused by the simd option not
+    // being enabled, but the occurring of this other error
+    // * https://github.com/emscripten-core/emscripten/issues/11495
+    // got me to remove that check to avoid breaking Node 12.
+    mod = await WebAssembly.compile(await readFile(resolve(__dirname, './llhttp/llhttp.wasm')))
+  }
 
-        wasm_on_url: (p, at, len) => {
-          /* istanbul ignore next */
-          return 0
-        },
-        wasm_on_status: (p, at, len) => {
-          assert.strictEqual(currentParser.ptr, p)
-          const start = at - currentBufferPtr
-          const end = start + len
-          return currentParser.onStatus(currentBufferRef.slice(start, end)) || 0
-        },
-        wasm_on_message_begin: (p) => {
-          assert.strictEqual(currentParser.ptr, p)
-          return currentParser.onMessageBegin() || 0
-        },
-        wasm_on_header_field: (p, at, len) => {
-          assert.strictEqual(currentParser.ptr, p)
-          const start = at - currentBufferPtr
-          const end = start + len
-          return currentParser.onHeaderField(currentBufferRef.slice(start, end)) || 0
-        },
-        wasm_on_header_value: (p, at, len) => {
-          assert.strictEqual(currentParser.ptr, p)
-          const start = at - currentBufferPtr
-          const end = start + len
-          return currentParser.onHeaderValue(currentBufferRef.slice(start, end)) || 0
-        },
-        wasm_on_headers_complete: (p, statusCode, upgrade, shouldKeepAlive) => {
-          assert.strictEqual(currentParser.ptr, p)
-          return currentParser.onHeadersComplete(statusCode, Boolean(upgrade), Boolean(shouldKeepAlive)) || 0
-        },
-        wasm_on_body: (p, at, len) => {
-          assert.strictEqual(currentParser.ptr, p)
-          const start = at - currentBufferPtr
-          const end = start + len
-          return currentParser.onBody(currentBufferRef.slice(start, end)) || 0
-        },
-        wasm_on_message_complete: (p) => {
-          assert.strictEqual(currentParser.ptr, p)
-          return currentParser.onMessageComplete() || 0
-        }
+  llhttpInstance = new WebAssembly.Instance(mod, {
+    env: {
+      /* eslint-disable camelcase */
 
-        /* eslint-enable camelcase */
+      wasm_on_url: (p, at, len) => {
+        /* istanbul ignore next */
+        return 0
+      },
+      wasm_on_status: (p, at, len) => {
+        assert.strictEqual(currentParser.ptr, p)
+        const start = at - currentBufferPtr
+        const end = start + len
+        return currentParser.onStatus(currentBufferRef.slice(start, end)) || 0
+      },
+      wasm_on_message_begin: (p) => {
+        assert.strictEqual(currentParser.ptr, p)
+        return currentParser.onMessageBegin() || 0
+      },
+      wasm_on_header_field: (p, at, len) => {
+        assert.strictEqual(currentParser.ptr, p)
+        const start = at - currentBufferPtr
+        const end = start + len
+        return currentParser.onHeaderField(currentBufferRef.slice(start, end)) || 0
+      },
+      wasm_on_header_value: (p, at, len) => {
+        assert.strictEqual(currentParser.ptr, p)
+        const start = at - currentBufferPtr
+        const end = start + len
+        return currentParser.onHeaderValue(currentBufferRef.slice(start, end)) || 0
+      },
+      wasm_on_headers_complete: (p, statusCode, upgrade, shouldKeepAlive) => {
+        assert.strictEqual(currentParser.ptr, p)
+        return currentParser.onHeadersComplete(statusCode, Boolean(upgrade), Boolean(shouldKeepAlive)) || 0
+      },
+      wasm_on_body: (p, at, len) => {
+        assert.strictEqual(currentParser.ptr, p)
+        const start = at - currentBufferPtr
+        const end = start + len
+        return currentParser.onBody(currentBufferRef.slice(start, end)) || 0
+      },
+      wasm_on_message_complete: (p) => {
+        assert.strictEqual(currentParser.ptr, p)
+        return currentParser.onMessageComplete() || 0
       }
-    })
-  }
+
+      /* eslint-enable camelcase */
+    }
+  })
+
   return llhttpInstance
 }
 
@@ -480,10 +481,10 @@ const TIMEOUT_BODY = 2
 const TIMEOUT_IDLE = 3
 
 class Parser {
-  constructor (client, socket) {
+  constructor (client, socket, { exports }) {
     assert(Number.isFinite(client[kMaxHeadersSize]) && client[kMaxHeadersSize] > 0)
 
-    this.llhttp = lazyllhttp().exports
+    this.llhttp = exports
     this.ptr = this.llhttp.llhttp_alloc(constants.TYPE.RESPONSE)
     this.client = client
     this.socket = socket
@@ -1096,7 +1097,7 @@ function onSocketClose () {
   resume(client)
 }
 
-function connect (client) {
+async function connect (client) {
   assert(!client[kConnecting])
   assert(!client[kSocket])
 
@@ -1128,78 +1129,97 @@ function connect (client) {
     })
   }
 
-  client[kConnector]({
-    host,
-    hostname,
-    protocol,
-    port,
-    servername: client[kServerName]
-  }, function (err, socket) {
-    client[kConnecting] = false
-
-    if (err) {
-      if (channels.connectError.hasSubscribers) {
-        channels.connectError.publish({
-          connectParams: {
-            host,
-            hostname,
-            protocol,
-            port,
-            servername: client[kServerName]
-          },
-          connector: client[kConnector],
-          error: err
-        })
+  try {
+    if (!llhttpInstance) {
+      if (!llhttpPromise) {
+        llhttpPromise = lazyllhttp()
       }
+      await llhttpPromise
+      assert(llhttpInstance)
+      llhttpPromise = null
+    }
 
-      if (err.code === 'ERR_TLS_CERT_ALTNAME_INVALID') {
-        assert(client[kRunning] === 0)
-        while (client[kPending] > 0 && client[kQueue][client[kPendingIdx]].servername === client[kServerName]) {
-          const request = client[kQueue][client[kPendingIdx]++]
-          errorRequest(client, request, err)
+    const socket = await new Promise((resolve, reject) => {
+      client[kConnector]({
+        host,
+        hostname,
+        protocol,
+        port,
+        servername: client[kServerName]
+      }, (err, socket) => {
+        if (err) {
+          reject(err)
+        } else {
+          resolve(socket)
         }
-      } else {
-        onError(client, err)
-      }
+      })
+    })
 
-      client.emit('connectionError', client[kUrl], [client], err)
-    } else {
-      assert(socket)
+    client[kConnecting] = false
 
-      client[kSocket] = socket
+    assert(socket)
 
-      socket[kNoRef] = false
-      socket[kWriting] = false
-      socket[kReset] = false
-      socket[kBlocking] = false
-      socket[kError] = null
-      socket[kParser] = new Parser(client, socket)
-      socket[kClient] = client
-      socket
-        .on('error', onSocketError)
-        .on('readable', onSocketReadable)
-        .on('end', onSocketEnd)
-        .on('close', onSocketClose)
-
-      if (channels.connected.hasSubscribers) {
-        channels.connected.publish({
-          connectParams: {
-            host,
-            hostname,
-            protocol,
-            port,
-            servername: client[kServerName]
-          },
-          connector: client[kConnector],
-          socket
-        })
-      }
+    client[kSocket] = socket
+
+    socket[kNoRef] = false
+    socket[kWriting] = false
+    socket[kReset] = false
+    socket[kBlocking] = false
+    socket[kError] = null
+    socket[kParser] = new Parser(client, socket, llhttpInstance)
+    socket[kClient] = client
+    socket
+      .on('error', onSocketError)
+      .on('readable', onSocketReadable)
+      .on('end', onSocketEnd)
+      .on('close', onSocketClose)
+
+    if (channels.connected.hasSubscribers) {
+      channels.connected.publish({
+        connectParams: {
+          host,
+          hostname,
+          protocol,
+          port,
+          servername: client[kServerName]
+        },
+        connector: client[kConnector],
+        socket
+      })
+    }
 
-      client.emit('connect', client[kUrl], [client])
+    client.emit('connect', client[kUrl], [client])
+  } catch (err) {
+    client[kConnecting] = false
+
+    if (channels.connectError.hasSubscribers) {
+      channels.connectError.publish({
+        connectParams: {
+          host,
+          hostname,
+          protocol,
+          port,
+          servername: client[kServerName]
+        },
+        connector: client[kConnector],
+        error: err
+      })
     }
 
-    resume(client)
-  })
+    if (err.code === 'ERR_TLS_CERT_ALTNAME_INVALID') {
+      assert(client[kRunning] === 0)
+      while (client[kPending] > 0 && client[kQueue][client[kPendingIdx]].servername === client[kServerName]) {
+        const request = client[kQueue][client[kPendingIdx]++]
+        errorRequest(client, request, err)
+      }
+    } else {
+      onError(client, err)
+    }
+
+    client.emit('connectionError', client[kUrl], [client], err)
+  }
+
+  resume(client)
 }
 
 function emitDrain (client) {

package/lib/core/errors.js

@@ -167,6 +167,16 @@ class NotSupportedError extends UndiciError {
   }
 }
 
+class BalancedPoolMissingUpstreamError extends UndiciError {
+  constructor (message) {
+    super(message)
+    Error.captureStackTrace(this, NotSupportedError)
+    this.name = 'MissingUpstreamError'
+    this.message = message || 'No upstream has been added to the BalancedPool'
+    this.code = 'UND_ERR_BPL_MISSING_UPSTREAM'
+  }
+}
+
 class HTTPParserError extends Error {
   constructor (message, code, data) {
     super(message)
@@ -195,5 +205,6 @@ module.exports = {
   InformationalError,
   SocketError,
   NotSupportedError,
-  ResponseContentLengthMismatchError
+  ResponseContentLengthMismatchError,
+  BalancedPoolMissingUpstreamError
 }

package/lib/core/symbols.js

@@ -40,5 +40,6 @@ module.exports = {
   kHostHeader: Symbol('host header'),
   kConnector: Symbol('connector'),
   kStrictContentLength: Symbol('strict content length'),
-  kMaxRedirections: Symbol('maxRedirections')
+  kMaxRedirections: Symbol('maxRedirections'),
+  kProxy: Symbol('proxy agent options')
 }

package/lib/proxy-agent.js

@@ -0,0 +1,59 @@
+'use strict'
+
+const { kClients, kProxy } = require('./core/symbols')
+const url = require('url')
+const Agent = require('./agent')
+const Dispatcher = require('./dispatcher')
+const { InvalidArgumentError } = require('./core/errors')
+
+const kAgent = Symbol('proxy agent')
+
+class ProxyAgent extends Dispatcher {
+  constructor (opts) {
+    super(opts)
+    this[kProxy] = buildProxyOptions(opts)
+
+    const agent = new Agent(opts)
+    this[kAgent] = agent
+
+    this[kClients] = agent[kClients]
+  }
+
+  dispatch (opts, handler) {
+    const { host } = url.parse(opts.origin)
+    return this[kAgent].dispatch(
+      {
+        ...opts,
+        origin: this[kProxy].uri,
+        path: opts.origin + opts.path,
+        headers: {
+          ...opts.headers,
+          host
+        },
+      },
+      handler
+    )
+  }
+
+  async close () {
+    await this[kAgent].close()
+    this[kClients].clear()
+  }
+}
+
+function buildProxyOptions(opts) {
+  if (typeof opts === 'string') {
+    opts = { uri: opts }
+  }
+
+  if (!opts || !opts.uri) {
+    throw new InvalidArgumentError('Proxy opts.uri is mandatory')
+  }
+
+  return {
+    uri: opts.uri,
+    protocol: opts.protocol || 'https'
+  }
+}
+
+module.exports = ProxyAgent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "undici",
-  "version": "4.7.2",
+  "version": "4.8.2",
   "description": "An HTTP/1.1 client, written from scratch for Node.js",
   "homepage": "https://undici.nodejs.org",
   "bugs": {

package/types/balanced-pool.d.ts

@@ -0,0 +1,19 @@
+import Client = require('./client')
+import Pool = require('./pool')
+import Dispatcher = require('./dispatcher')
+import { URL } from 'url'
+
+export = BalancedPool
+
+declare class BalancedPool extends Dispatcher {
+  constructor(url: string | URL | string[], options?: Pool.Options);
+
+  addUpstream(upstream: string): BalancedPool;
+  removeUpstream(upstream: string): BalancedPool;
+  upstreams: Array<string>;
+
+  /** `true` after `pool.close()` has been called. */
+  closed: boolean;
+  /** `true` after `pool.destroyed()` has been called or `pool.close()` has been called and the pool shutdown has completed. */
+  destroyed: boolean;
+}

package/types/proxy-agent.d.ts

@@ -0,0 +1,17 @@
+import Agent = require('./agent')
+import Dispatcher = require('./dispatcher')
+
+export = ProxyAgent
+
+declare class ProxyAgent extends Dispatcher {
+  constructor(options: ProxyAgent.Options | string)
+
+  dispatch(options: Agent.DispatchOptions, handler: Dispatcher.DispatchHandlers): void;
+  close(): Promise<void>;
+}
+
+declare namespace ProxyAgent {
+  export interface Options extends Agent.Options {
+    uri: string;
+  }
+}