undici 6.6.2 → 6.7.1

package/README.md

@@ -17,24 +17,42 @@ npm i undici
 
 ## Benchmarks
 
-The benchmark is a simple `hello world` [example](benchmarks/benchmark.js) using a
+The benchmark is a simple getting data [example](benchmarks/benchmark.js) using a
 50 TCP connections with a pipelining depth of 10 running on Node 20.10.0.
 
-```
-│ Tests               │ Samples │          Result │ Tolerance │ Difference with slowest │
-|─────────────────────|─────────|─────────────────|───────────|─────────────────────────|
-│ got                 │      45 │ 1661.71 req/sec │  ± 2.93 % │                       - │
-│ node-fetch          │      20 │ 2164.81 req/sec │  ± 2.63 % │               + 30.28 % │
-│ undici - fetch      │      35 │ 2274.27 req/sec │  ± 2.70 % │               + 36.86 % │
-│ http - no keepalive │      15 │ 2376.04 req/sec │  ± 2.99 % │               + 42.99 % │
-│ axios               │      25 │ 2612.93 req/sec │  ± 2.89 % │               + 57.24 % │
-│ request             │      40 │ 2712.19 req/sec │  ± 2.92 % │               + 63.22 % │
-│ http - keepalive    │      45 │ 4393.25 req/sec │  ± 2.86 % │              + 164.38 % │
-│ undici - pipeline   │      45 │ 5484.69 req/sec │  ± 2.87 % │              + 230.06 % │
-│ undici - request    │      55 │ 7773.98 req/sec │  ± 2.93 % │              + 367.83 % │
-│ undici - stream     │      70 │ 8425.96 req/sec │  ± 2.91 % │              + 407.07 % │
-│ undici - dispatch   │      50 │ 9488.99 req/sec │  ± 2.85 % │              + 471.04 % │
-```
+|       _Tests_       | _Samples_ |     _Result_     | _Tolerance_ | _Difference with slowest_ |
+| :-----------------: | :-------: | :--------------: | :---------: | :-----------------------: |
+|   undici - fetch    |    30     | 3704.43 req/sec  |  ± 2.95 %   |             -             |
+| http - no keepalive |    20     | 4275.30 req/sec  |  ± 2.60 %   |         + 15.41 %         |
+|     node-fetch      |    10     | 4759.42 req/sec  |  ± 0.87 %   |         + 28.48 %         |
+|       request       |    40     | 4803.37 req/sec  |  ± 2.77 %   |         + 29.67 %         |
+|        axios        |    45     | 4951.97 req/sec  |  ± 2.88 %   |         + 33.68 %         |
+|         got         |    10     | 5969.67 req/sec  |  ± 2.64 %   |         + 61.15 %         |
+|     superagent      |    10     | 9471.48 req/sec  |  ± 1.50 %   |        + 155.68 %         |
+|  http - keepalive   |    25     | 10327.49 req/sec |  ± 2.95 %   |        + 178.79 %         |
+|  undici - pipeline  |    10     | 15053.41 req/sec |  ± 1.63 %   |        + 306.36 %         |
+|  undici - request   |    10     | 19264.24 req/sec |  ± 1.74 %   |        + 420.03 %         |
+|   undici - stream   |    15     | 20317.29 req/sec |  ± 2.13 %   |        + 448.46 %         |
+|  undici - dispatch  |    10     | 24883.28 req/sec |  ± 1.54 %   |        + 571.72 %         |
+
+The benchmark is a simple sending data [example](benchmarks/post-benchmark.js) using a
+50 TCP connections with a pipelining depth of 10 running on Node 20.10.0.
+
+|       _Tests_       | _Samples_ |    _Result_     | _Tolerance_ | _Difference with slowest_ |
+| :-----------------: | :-------: | :-------------: | :---------: | :-----------------------: |
+|   undici - fetch    |    20     | 1968.42 req/sec |  ± 2.63 %   |             -             |
+| http - no keepalive |    25     | 2330.30 req/sec |  ± 2.99 %   |         + 18.38 %         |
+|     node-fetch      |    20     | 2485.36 req/sec |  ± 2.70 %   |         + 26.26 %         |
+|         got         |    15     | 2787.68 req/sec |  ± 2.56 %   |         + 41.62 %         |
+|       request       |    30     | 2805.10 req/sec |  ± 2.59 %   |         + 42.50 %         |
+|        axios        |    10     | 3040.45 req/sec |  ± 1.72 %   |         + 54.46 %         |
+|     superagent      |    20     | 3358.29 req/sec |  ± 2.51 %   |         + 70.61 %         |
+|  http - keepalive   |    20     | 3477.94 req/sec |  ± 2.51 %   |         + 76.69 %         |
+|  undici - pipeline  |    25     | 3812.61 req/sec |  ± 2.80 %   |         + 93.69 %         |
+|  undici - request   |    10     | 6067.00 req/sec |  ± 0.94 %   |        + 208.22 %         |
+|   undici - stream   |    10     | 6391.61 req/sec |  ± 1.98 %   |        + 224.71 %         |
+|  undici - dispatch  |    10     | 6397.00 req/sec |  ± 1.48 %   |        + 224.98 %         |
+
 
 ## Quick Start
 
@@ -60,10 +78,14 @@ console.log('trailers', trailers)
 
 The `body` mixins are the most common way to format the request/response body. Mixins include:
 
-- [`.formData()`](https://fetch.spec.whatwg.org/#dom-body-formdata)
+- [`.arrayBuffer()`](https://fetch.spec.whatwg.org/#dom-body-arraybuffer)
+- [`.blob()`](https://fetch.spec.whatwg.org/#dom-body-blob)
 - [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json)
 - [`.text()`](https://fetch.spec.whatwg.org/#dom-body-text)
 
+> [!NOTE]
+> The body returned from `undici.request` does not implement `.formData()`.
+
 Example usage:
 
 ```js
@@ -123,14 +145,14 @@ Returns a promise with the result of the `Dispatcher.stream` method.
 
 Calls `options.dispatcher.stream(options, factory)`.
 
-See [Dispatcher.stream](docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback) for more details.
+See [Dispatcher.stream](./docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback) for more details.
 
 ### `undici.pipeline([url, options, ]handler): Duplex`
 
 Arguments:
 
 * **url** `string | URL | UrlObject`
-* **options** [`PipelineOptions`](docs/api/Dispatcher.md#parameter-pipelineoptions)
+* **options** [`PipelineOptions`](./docs/api/Dispatcher.md#parameter-pipelineoptions)
   * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)
   * **method** `String` - Default: `PUT` if `options.body`, otherwise `GET`
   * **maxRedirections** `Integer` - Default: `0`
@@ -140,7 +162,7 @@ Returns: `stream.Duplex`
 
 Calls `options.dispatch.pipeline(options, handler)`.
 
-See [Dispatcher.pipeline](docs/api/Dispatcher.md#dispatcherpipelineoptions-handler) for more details.
+See [Dispatcher.pipeline](./docs/api/Dispatcher.md#dispatcherpipelineoptions-handler) for more details.
 
 ### `undici.connect([url, options]): Promise`
 
@@ -149,7 +171,7 @@ Starts two-way communications with the requested resource using [HTTP CONNECT](h
 Arguments:
 
 * **url** `string | URL | UrlObject`
-* **options** [`ConnectOptions`](docs/api/Dispatcher.md#parameter-connectoptions)
+* **options** [`ConnectOptions`](./docs/api/Dispatcher.md#parameter-connectoptions)
   * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)
   * **maxRedirections** `Integer` - Default: `0`
 * **callback** `(err: Error | null, data: ConnectData | null) => void` (optional)
@@ -158,7 +180,7 @@ Returns a promise with the result of the `Dispatcher.connect` method.
 
 Calls `options.dispatch.connect(options)`.
 
-See [Dispatcher.connect](docs/api/Dispatcher.md#dispatcherconnectoptions-callback) for more details.
+See [Dispatcher.connect](./docs/api/Dispatcher.md#dispatcherconnectoptions-callback) for more details.
 
 ### `undici.fetch(input[, init]): Promise`
 
@@ -226,7 +248,7 @@ await fetch('https://example.com', { body: data, method: 'POST', duplex: 'half'
 
 - half
 
-In this implementation of fetch, `request.duplex` must be set if `request.body` is `ReadableStream` or `Async Iterables`. And fetch requests are currently always be full duplex. More detail refer to [Fetch Standard.](https://fetch.spec.whatwg.org/#dom-requestinit-duplex)
+In this implementation of fetch, `request.duplex` must be set if `request.body` is `ReadableStream` or `Async Iterables`, however, fetch requests are currently always full duplex. For more detail refer to the [Fetch Standard.](https://fetch.spec.whatwg.org/#dom-requestinit-duplex).
 
 #### `response.body`
 
@@ -297,7 +319,7 @@ Upgrade to a different protocol. See [MDN - HTTP - Protocol upgrade mechanism](h
 Arguments:
 
 * **url** `string | URL | UrlObject`
-* **options** [`UpgradeOptions`](docs/api/Dispatcher.md#parameter-upgradeoptions)
+* **options** [`UpgradeOptions`](./docs/api/Dispatcher.md#parameter-upgradeoptions)
   * **dispatcher** `Dispatcher` - Default: [getGlobalDispatcher](#undicigetglobaldispatcher)
   * **maxRedirections** `Integer` - Default: `0`
 * **callback** `(error: Error | null, data: UpgradeData) => void` (optional)
@@ -306,7 +328,7 @@ Returns a promise with the result of the `Dispatcher.upgrade` method.
 
 Calls `options.dispatcher.upgrade(options)`.
 
-See [Dispatcher.upgrade](docs/api/Dispatcher.md#dispatcherupgradeoptions-callback) for more details.
+See [Dispatcher.upgrade](./docs/api/Dispatcher.md#dispatcherupgradeoptions-callback) for more details.
 
 ### `undici.setGlobalDispatcher(dispatcher)`
 
@@ -400,9 +422,9 @@ Refs: https://fetch.spec.whatwg.org/#atomic-http-redirect-handling
 
 If you experience problem when connecting to a remote server that is resolved by your DNS servers to a IPv6 (AAAA record)
 first, there are chances that your local router or ISP might have problem connecting to IPv6 networks. In that case
-undici will throw an error with code `UND_ERR_CONNECT_TIMEOUT`. 
+undici will throw an error with code `UND_ERR_CONNECT_TIMEOUT`.
 
-If the target server resolves to both a IPv6 and IPv4 (A records) address and you are using a compatible Node version 
+If the target server resolves to both a IPv6 and IPv4 (A records) address and you are using a compatible Node version
 (18.3.0 and above), you can fix the problem by providing the `autoSelectFamily` option (support by both `undici.request`
 and `undici.Agent`) which will enable the family autoselection algorithm when establishing the connection.
 

package/docs/{api → docs/api}/DiagnosticsChannel.md

@@ -19,9 +19,9 @@ diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
   console.log('completed', request.completed)
   console.log('method', request.method)
   console.log('path', request.path)
-  console.log('headers') // raw text, e.g: 'bar: bar\r\n'
+  console.log('headers') // array of strings, e.g: ['foo', 'bar']
   request.addHeader('hello', 'world')
-  console.log('headers', request.headers) // e.g. 'bar: bar\r\nhello: world\r\n'
+  console.log('headers', request.headers) // e.g. ['foo', 'bar', 'hello', 'world']
 })
 ```
 

package/docs/{api → docs/api}/Dispatcher.md

@@ -855,10 +855,12 @@ Emitted when dispatcher is no longer busy.
 
 ## Parameter: `UndiciHeaders`
 
-* `Record<string, string | string[] | undefined> | string[] | null`
-
-Header arguments such as `options.headers` in [`Client.dispatch`](Client.md#clientdispatchoptions-handlers) can be specified in two forms; either as an object specified by the `Record<string, string | string[] | undefined>` (`IncomingHttpHeaders`) type, or an array of strings. An array representation of a header list must have an even length or an `InvalidArgumentError` will be thrown.
+* `Record<string, string | string[] | undefined> | string[] | Iterable<[string, string | string[] | undefined]> | null`
 
+Header arguments such as `options.headers` in [`Client.dispatch`](Client.md#clientdispatchoptions-handlers) can be specified in three forms:
+* As an object specified by the `Record<string, string | string[] | undefined>` (`IncomingHttpHeaders`) type.
+* As an array of strings. An array representation of a header list must have an even length, or an `InvalidArgumentError` will be thrown.
+* As an iterable that can encompass `Headers`, `Map`, or a custom iterator returning key-value pairs.
 Keys are lowercase and values are not modified.
 
 Response headers will derive a `host` from the `url` of the [Client](Client.md#class-client) instance if no `host` header was previously specified.
@@ -886,3 +888,37 @@ Response headers will derive a `host` from the `url` of the [Client](Client.md#c
   'accept', '*/*'
 ]
 ```
+
+### Example 3 - Iterable
+
+```js
+new Headers({
+  'content-length': '123',
+  'content-type': 'text/plain',
+  connection: 'keep-alive',
+  host: 'mysite.com',
+  accept: '*/*'
+})
+```
+or
+```js
+new Map([
+  ['content-length', '123'],
+  ['content-type', 'text/plain'],
+  ['connection', 'keep-alive'],
+  ['host', 'mysite.com'],
+  ['accept', '*/*']
+])
+```
+or
+```js
+{
+  *[Symbol.iterator] () {
+    yield ['content-length', '123']
+    yield ['content-type', 'text/plain']
+    yield ['connection', 'keep-alive']
+    yield ['host', 'mysite.com']
+    yield ['accept', '*/*']
+  }
+}
+```

package/docs/docs/api/Fetch.md

@@ -0,0 +1,57 @@
+# Fetch
+
+Undici exposes a fetch() method starts the process of fetching a resource from the network.
+
+Documentation and examples can be found on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/fetch).
+
+## File
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/File)
+
+In Node versions v18.13.0 and above and v19.2.0 and above, undici will default to using Node's [File](https://nodejs.org/api/buffer.html#class-file) class. In versions where it's not available, it will default to the undici one.
+
+## FormData
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/FormData).
+
+If any parameters are passed to the FormData constructor other than `undefined`, an error will be thrown. Other parameters are ignored.
+
+## Response
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Response)
+
+## Request
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Request)
+
+## Header
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
+
+# Body Mixins
+
+`Response` and `Request` body inherit body mixin methods. These methods include:
+
+- [`.arrayBuffer()`](https://fetch.spec.whatwg.org/#dom-body-arraybuffer)
+- [`.blob()`](https://fetch.spec.whatwg.org/#dom-body-blob)
+- [`.formData()`](https://fetch.spec.whatwg.org/#dom-body-formdata)
+- [`.json()`](https://fetch.spec.whatwg.org/#dom-body-json)
+- [`.text()`](https://fetch.spec.whatwg.org/#dom-body-text)
+
+There is an ongoing discussion regarding `.formData()` and its usefulness and performance in server environments. It is recommended to use a dedicated library for parsing `multipart/form-data` bodies, such as [Busboy](https://www.npmjs.com/package/busboy) or [@fastify/busboy](https://www.npmjs.com/package/@fastify/busboy).
+
+These libraries can be interfaced with fetch with the following example code:
+
+```mjs
+import { Busboy } from '@fastify/busboy'
+import { Readable } from 'node:stream'
+
+const response = await fetch('...')
+const busboy = new Busboy({
+  headers: {
+    'content-type': response.headers.get('content-type')
+  }
+})
+
+Readable.fromWeb(response.body).pipe(busboy)
+```

package/docs/{api → docs/api}/ProxyAgent.md

@@ -16,7 +16,9 @@ Returns: `ProxyAgent`
 
 Extends: [`AgentOptions`](Agent.md#parameter-agentoptions)
 
-* **uri** `string` (required) - It can be passed either by a string or a object containing `uri` as string.
+* **uri** `string | URL` (required) - The URI of the proxy server.  This can be provided as a string, as an instance of the URL class, or as an object with a `uri` property of type string.
+If the `uri` is provided as a string or `uri` is an object with an `uri` property of type string, then it will be parsed into a `URL` object according to the [WHATWG URL Specification](https://url.spec.whatwg.org).
+For detailed information on the parsing process and potential validation errors, please refer to the ["Writing" section](https://url.spec.whatwg.org/#writing) of the WHATWG URL Specification.
 * **token** `string` (optional) - It can be passed by a string of token for authentication.
 * **auth** `string` (**deprecated**) - Use token.
 * **clientFactory** `(origin: URL, opts: Object) => Dispatcher` (optional) - Default: `(origin, opts) => new Pool(origin, opts)`
@@ -30,6 +32,8 @@ import { ProxyAgent } from 'undici'
 
 const proxyAgent = new ProxyAgent('my.proxy.server')
 // or
+const proxyAgent = new ProxyAgent(new URL('my.proxy.server'))
+// or
 const proxyAgent = new ProxyAgent({ uri: 'my.proxy.server' })
 ```
 

package/docs/docs/api/RetryAgent.md

@@ -0,0 +1,45 @@
+# Class: RetryAgent
+
+Extends: `undici.Dispatcher`
+
+A `undici.Dispatcher` that allows to automatically retry a request.
+Wraps a `undici.RetryHandler`.
+
+## `new RetryAgent(dispatcher, [options])`
+
+Arguments:
+
+* **dispatcher** `undici.Dispatcher` (required) - the dispatcher to wrap
+* **options** `RetryHandlerOptions` (optional) - the options
+
+Returns: `ProxyAgent`
+
+### Parameter: `RetryHandlerOptions`
+
+- **retry** `(err: Error, context: RetryContext, callback: (err?: Error | null) => void) => void` (optional) - Function to be called after every retry. It should pass error if no more retries should be performed.
+- **maxRetries** `number` (optional) - Maximum number of retries. Default: `5`
+- **maxTimeout** `number` (optional) - Maximum number of milliseconds to wait before retrying. Default: `30000` (30 seconds)
+- **minTimeout** `number` (optional) - Minimum number of milliseconds to wait before retrying. Default: `500` (half a second)
+- **timeoutFactor** `number` (optional) - Factor to multiply the timeout by for each retry attempt. Default: `2`
+- **retryAfter** `boolean` (optional) - It enables automatic retry after the `Retry-After` header is received. Default: `true`
+-
+- **methods** `string[]` (optional) - Array of HTTP methods to retry. Default: `['GET', 'PUT', 'HEAD', 'OPTIONS', 'DELETE']`
+- **statusCodes** `number[]` (optional) - Array of HTTP status codes to retry. Default: `[429, 500, 502, 503, 504]`
+- **errorCodes** `string[]` (optional) - Array of Error codes to retry. Default: `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN','ENETUNREACH', 'EHOSTDOWN', 'UND_ERR_SOCKET']`
+
+**`RetryContext`**
+
+- `state`: `RetryState` - Current retry state. It can be mutated.
+- `opts`: `Dispatch.DispatchOptions & RetryOptions` - Options passed to the retry handler.
+
+Example:
+
+```js
+import { Agent, RetryAgent } from 'undici'
+
+const agent = new RetryAgent(new Agent())
+
+const res = await agent.request('http://example.com')
+console.log(res.statuCode)
+console.log(await res.body.text())
+```

package/docs/{api → docs/api}/RetryHandler.md

@@ -28,7 +28,7 @@ Extends: [`Dispatch.DispatchOptions`](Dispatcher.md#parameter-dispatchoptions).
 -
 - **methods** `string[]` (optional) - Array of HTTP methods to retry. Default: `['GET', 'PUT', 'HEAD', 'OPTIONS', 'DELETE']`
 - **statusCodes** `number[]` (optional) - Array of HTTP status codes to retry. Default: `[429, 500, 502, 503, 504]`
-- **errorCodes** `string[]` (optional) - Array of Error codes to retry. Default: `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN','ENETUNREACH', 'EHOSTDOWN',
+- **errorCodes** `string[]` (optional) - Array of Error codes to retry. Default: `['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN','ENETUNREACH', 'EHOSTDOWN', 'UND_ERR_SOCKET']`
 
 **`RetryContext`**
 

package/docs/{api → docs/api}/api-lifecycle.md

@@ -21,10 +21,39 @@ An Undici [Client](Client.md) can be best described as a state machine. The foll
   * At any point in time, the *destroy* event will transition the `Client` from the **processing** state to the **destroyed** state, destroying any queued requests.
 * The **destroyed** state is a final state and the `Client` is no longer functional.
 
-![A state diagram representing an Undici Client instance](../assets/lifecycle-diagram.png)
-
-> The diagram was generated using Mermaid.js Live Editor. Modify the state diagram [here](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic3RhdGVEaWFncmFtLXYyXG4gICAgWypdIC0tPiBpZGxlXG4gICAgaWRsZSAtLT4gcGVuZGluZyA6IGNvbm5lY3RcbiAgICBpZGxlIC0tPiBkZXN0cm95ZWQgOiBkZXN0cm95L2Nsb3NlXG4gICAgXG4gICAgcGVuZGluZyAtLT4gaWRsZSA6IHRpbWVvdXRcbiAgICBwZW5kaW5nIC0tPiBkZXN0cm95ZWQgOiBkZXN0cm95XG5cbiAgICBzdGF0ZSBjbG9zZV9mb3JrIDw8Zm9yaz4-XG4gICAgcGVuZGluZyAtLT4gY2xvc2VfZm9yayA6IGNsb3NlXG4gICAgY2xvc2VfZm9yayAtLT4gcHJvY2Vzc2luZ1xuICAgIGNsb3NlX2ZvcmsgLS0-IGRlc3Ryb3llZFxuXG4gICAgcGVuZGluZyAtLT4gcHJvY2Vzc2luZyA6IHByb2Nlc3NcblxuICAgIHByb2Nlc3NpbmcgLS0-IHBlbmRpbmcgOiBrZWVwYWxpdmVcbiAgICBwcm9jZXNzaW5nIC0tPiBkZXN0cm95ZWQgOiBkb25lXG4gICAgcHJvY2Vzc2luZyAtLT4gZGVzdHJveWVkIDogZGVzdHJveVxuXG4gICAgc3RhdGUgcHJvY2Vzc2luZyB7XG4gICAgICAgIHJ1bm5pbmcgLS0-IGJ1c3kgOiBuZWVkRHJhaW5cbiAgICAgICAgYnVzeSAtLT4gcnVubmluZyA6IGRyYWluQ29tcGxldGVcbiAgICAgICAgcnVubmluZyAtLT4gWypdIDoga2VlcGFsaXZlXG4gICAgICAgIHJ1bm5pbmcgLS0-IGNsb3NpbmcgOiBjbG9zZVxuICAgICAgICBjbG9zaW5nIC0tPiBbKl0gOiBkb25lXG4gICAgICAgIFsqXSAtLT4gcnVubmluZ1xuICAgIH1cbiAgICAiLCJtZXJtYWlkIjp7InRoZW1lIjoiYmFzZSJ9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)
-
+A state diagram representing an Undici Client instance:
+
+```mermaid
+stateDiagram-v2
+  [*] --> idle
+  idle --> pending : connect
+  idle --> destroyed : destroy/close
+  
+  pending --> idle : timeout
+  pending --> destroyed : destroy
+
+  state close_fork <<fork>>
+  pending --> close_fork : close
+  close_fork --> processing
+  close_fork --> destroyed
+
+  pending --> processing : process
+
+  processing --> pending : keepalive
+  processing --> destroyed : done
+  processing --> destroyed : destroy
+
+  destroyed --> [*]
+
+  state processing {
+      [*] --> running
+      running --> closing : close
+      running --> busy : needDrain
+      busy --> running : drainComplete
+      running --> [*] : keepalive
+      closing --> [*] : done
+  }
+```
 ## State details
 
 ### idle

package/docs/{best-practices → docs/best-practices}/proxy.md

@@ -17,7 +17,7 @@ If you proxy requires basic authentication, you can send it via the `proxy-autho
 ```js
 import { Client } from 'undici'
 import { createServer } from 'http'
-import proxy from 'proxy'
+import { createProxy } from 'proxy'
 
 const server = await buildServer()
 const proxyServer = await buildProxy()
@@ -59,7 +59,7 @@ function buildServer () {
 
 function buildProxy () {
   return new Promise((resolve, reject) => {
-    const server = proxy(createServer())
+    const server = createProxy(createServer())
     server.listen(0, () => resolve(server))
   })
 }
@@ -70,7 +70,7 @@ function buildProxy () {
 ```js
 import { Client } from 'undici'
 import { createServer } from 'http'
-import proxy from 'proxy'
+import { createProxy } from 'proxy'
 
 const server = await buildServer()
 const proxyServer = await buildProxy()
@@ -78,8 +78,8 @@ const proxyServer = await buildProxy()
 const serverUrl = `http://localhost:${server.address().port}`
 const proxyUrl = `http://localhost:${proxyServer.address().port}`
 
-proxyServer.authenticate = function (req, fn) {
-  fn(null, req.headers['proxy-authorization'] === `Basic ${Buffer.from('user:pass').toString('base64')}`)
+proxyServer.authenticate = function (req) {
+  return req.headers['proxy-authorization'] === `Basic ${Buffer.from('user:pass').toString('base64')}`
 }
 
 server.on('request', (req, res) => {
@@ -119,7 +119,7 @@ function buildServer () {
 
 function buildProxy () {
   return new Promise((resolve, reject) => {
-    const server = proxy(createServer())
+    const server = createProxy(createServer())
     server.listen(0, () => resolve(server))
   })
 }

package/index-fetch.js

@@ -1,20 +1,21 @@
 'use strict'
 
-const fetchImpl = require('./lib/fetch').fetch
+const fetchImpl = require('./lib/web/fetch').fetch
 
 module.exports.fetch = function fetch (resource, init = undefined) {
   return fetchImpl(resource, init).catch((err) => {
-    if (typeof err === 'object') {
+    if (err && typeof err === 'object') {
       Error.captureStackTrace(err, this)
     }
     throw err
   })
 }
-module.exports.FormData = require('./lib/fetch/formdata').FormData
-module.exports.Headers = require('./lib/fetch/headers').Headers
-module.exports.Response = require('./lib/fetch/response').Response
-module.exports.Request = require('./lib/fetch/request').Request
+module.exports.FormData = require('./lib/web/fetch/formdata').FormData
+module.exports.Headers = require('./lib/web/fetch/headers').Headers
+module.exports.Response = require('./lib/web/fetch/response').Response
+module.exports.Request = require('./lib/web/fetch/request').Request
 
-module.exports.WebSocket = require('./lib/websocket/websocket').WebSocket
+module.exports.WebSocket = require('./lib/web/websocket/websocket').WebSocket
+module.exports.MessageEvent = require('./lib/web/websocket/events').MessageEvent
 
-module.exports.EventSource = require('./lib/eventsource/eventsource').EventSource
+module.exports.EventSource = require('./lib/web/eventsource/eventsource').EventSource

package/index.js

@@ -1,11 +1,13 @@
 'use strict'
 
-const Client = require('./lib/client')
-const Dispatcher = require('./lib/dispatcher')
+const Client = require('./lib/dispatcher/client')
+const Dispatcher = require('./lib/dispatcher/dispatcher')
+const Pool = require('./lib/dispatcher/pool')
+const BalancedPool = require('./lib/dispatcher/balanced-pool')
+const Agent = require('./lib/dispatcher/agent')
+const ProxyAgent = require('./lib/dispatcher/proxy-agent')
+const RetryAgent = require('./lib/dispatcher/retry-agent')
 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
 const api = require('./lib/api')
@@ -14,12 +16,11 @@ 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 RetryHandler = require('./lib/handler/RetryHandler')
+const RetryHandler = require('./lib/handler/retry-handler')
 const { getGlobalDispatcher, setGlobalDispatcher } = require('./lib/global')
-const DecoratorHandler = require('./lib/handler/DecoratorHandler')
-const RedirectHandler = require('./lib/handler/RedirectHandler')
-const createRedirectInterceptor = require('./lib/interceptor/redirectInterceptor')
+const DecoratorHandler = require('./lib/handler/decorator-handler')
+const RedirectHandler = require('./lib/handler/redirect-handler')
+const createRedirectInterceptor = require('./lib/interceptor/redirect-interceptor')
 
 Object.assign(Dispatcher.prototype, api)
 
@@ -29,6 +30,7 @@ module.exports.Pool = Pool
 module.exports.BalancedPool = BalancedPool
 module.exports.Agent = Agent
 module.exports.ProxyAgent = ProxyAgent
+module.exports.RetryAgent = RetryAgent
 module.exports.RetryHandler = RetryHandler
 
 module.exports.DecoratorHandler = DecoratorHandler
@@ -94,50 +96,54 @@ function makeDispatcher (fn) {
 module.exports.setGlobalDispatcher = setGlobalDispatcher
 module.exports.getGlobalDispatcher = getGlobalDispatcher
 
-const fetchImpl = require('./lib/fetch').fetch
+const fetchImpl = require('./lib/web/fetch').fetch
 module.exports.fetch = async function fetch (init, options = undefined) {
   try {
     return await fetchImpl(init, options)
   } catch (err) {
-    if (typeof err === 'object') {
+    if (err && typeof err === 'object') {
       Error.captureStackTrace(err, this)
     }
 
     throw err
   }
 }
-module.exports.Headers = require('./lib/fetch/headers').Headers
-module.exports.Response = require('./lib/fetch/response').Response
-module.exports.Request = require('./lib/fetch/request').Request
-module.exports.FormData = require('./lib/fetch/formdata').FormData
-module.exports.File = require('./lib/fetch/file').File
-module.exports.FileReader = require('./lib/fileapi/filereader').FileReader
+module.exports.Headers = require('./lib/web/fetch/headers').Headers
+module.exports.Response = require('./lib/web/fetch/response').Response
+module.exports.Request = require('./lib/web/fetch/request').Request
+module.exports.FormData = require('./lib/web/fetch/formdata').FormData
+module.exports.File = require('./lib/web/fetch/file').File
+module.exports.FileReader = require('./lib/web/fileapi/filereader').FileReader
 
-const { setGlobalOrigin, getGlobalOrigin } = require('./lib/fetch/global')
+const { setGlobalOrigin, getGlobalOrigin } = require('./lib/web/fetch/global')
 
 module.exports.setGlobalOrigin = setGlobalOrigin
 module.exports.getGlobalOrigin = getGlobalOrigin
 
-const { CacheStorage } = require('./lib/cache/cachestorage')
-const { kConstruct } = require('./lib/cache/symbols')
+const { CacheStorage } = require('./lib/web/cache/cachestorage')
+const { kConstruct } = require('./lib/web/cache/symbols')
 
 // Cache & CacheStorage are tightly coupled with fetch. Even if it may run
 // in an older version of Node, it doesn't have any use without fetch.
 module.exports.caches = new CacheStorage(kConstruct)
 
-const { deleteCookie, getCookies, getSetCookies, setCookie } = require('./lib/cookies')
+const { deleteCookie, getCookies, getSetCookies, setCookie } = require('./lib/web/cookies')
 
 module.exports.deleteCookie = deleteCookie
 module.exports.getCookies = getCookies
 module.exports.getSetCookies = getSetCookies
 module.exports.setCookie = setCookie
 
-const { parseMIMEType, serializeAMimeType } = require('./lib/fetch/dataURL')
+const { parseMIMEType, serializeAMimeType } = require('./lib/web/fetch/data-url')
 
 module.exports.parseMIMEType = parseMIMEType
 module.exports.serializeAMimeType = serializeAMimeType
 
-module.exports.WebSocket = require('./lib/websocket/websocket').WebSocket
+const { CloseEvent, ErrorEvent, MessageEvent } = require('./lib/web/websocket/events')
+module.exports.WebSocket = require('./lib/web/websocket/websocket').WebSocket
+module.exports.CloseEvent = CloseEvent
+module.exports.ErrorEvent = ErrorEvent
+module.exports.MessageEvent = MessageEvent
 
 module.exports.request = makeDispatcher(api.request)
 module.exports.stream = makeDispatcher(api.stream)
@@ -150,6 +156,6 @@ module.exports.MockPool = MockPool
 module.exports.MockAgent = MockAgent
 module.exports.mockErrors = mockErrors
 
-const { EventSource } = require('./lib/eventsource/eventsource')
+const { EventSource } = require('./lib/web/eventsource/eventsource')
 
 module.exports.EventSource = EventSource

package/lib/api/api-request.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const Readable = require('./readable')
+const { Readable } = require('./readable')
 const {
   InvalidArgumentError,
   RequestAbortedError