undici 7.0.0-alpha.3 → 7.0.0-alpha.4

package/README.md

@@ -402,7 +402,8 @@ Refs: https://tools.ietf.org/html/rfc7231#section-5.1.1
 ### Pipelining
 
 Undici will only use pipelining if configured with a `pipelining` factor
-greater than `1`.
+greater than `1`. Also it is important to pass `blocking: false` to the
+request options to properly pipeline requests.
 
 Undici always assumes that connections are persistent and will immediately
 pipeline requests, without checking whether the connection is persistent.

package/docs/docs/api/BalancedPool.md

@@ -2,7 +2,7 @@
 
 Extends: `undici.Dispatcher`
 
-A pool of [Pool](Pool.md) instances connected to multiple upstreams.
+A pool of [Pool](/docs/docs/api/Pool.md) instances connected to multiple upstreams.
 
 Requests are not guaranteed to be dispatched in order of invocation.
 

package/docs/docs/api/CacheStore.md

@@ -2,7 +2,8 @@
 
 A Cache Store is responsible for storing and retrieving cached responses.
 It is also responsible for deciding which specific response to use based off of
-a response's `Vary` header (if present).
+a response's `Vary` header (if present). It is expected to be compliant with
+[RFC-9111](https://www.rfc-editor.org/rfc/rfc9111.html).
 
 ## Pre-built Cache Stores
 
@@ -21,27 +22,33 @@ The store must implement the following functions:
 
 ### Getter: `isFull`
 
-This tells the cache interceptor if the store is full or not. If this is true,
+Optional. This tells the cache interceptor if the store is full or not. If this is true,
 the cache interceptor will not attempt to cache the response.
 
-### Function: `createReadStream`
+### Function: `get`
 
 Parameters:
 
 * **req** `Dispatcher.RequestOptions` - Incoming request
 
-Returns: `CacheStoreReadable | Promise<CacheStoreReadable | undefined> | undefined` - If the request is cached, a readable for the body is returned. Otherwise, `undefined` is returned.
+Returns: `GetResult | Promise<GetResult | undefined> | undefined` - If the request is cached, the cached response is returned. If the request's method is anything other than HEAD, the response is also returned.
+If the request isn't cached, `undefined` is returned.
+
+Response properties:
+
+* **response** `CachedResponse` - The cached response data.
+* **body** `Readable | undefined` - The response's body.
 
 ### Function: `createWriteStream`
 
 Parameters:
 
 * **req** `Dispatcher.RequestOptions` - Incoming request
-* **value** `CacheStoreValue` - Response to store
+* **value** `CachedResponse` - Response to store
 
-Returns: `CacheStoreWriteable | undefined` - If the store is full, return `undefined`. Otherwise, return a writable so that the cache interceptor can stream the body and trailers to the store.
+Returns: `Writable | undefined` - If the store is full, return `undefined`. Otherwise, return a writable so that the cache interceptor can stream the body and trailers to the store.
 
-## `CacheStoreValue`
+## `CachedResponse`
 
 This is an interface containing the majority of a response's data (minus the body).
 
@@ -55,15 +62,11 @@ This is an interface containing the majority of a response's data (minus the bod
 
 ### Property `rawHeaders`
 
-`(Buffer | Buffer[])[]` - The response's headers.
-
-### Property `rawTrailers`
-
-`string[] | undefined` - The response's trailers.
+`Buffer[]` - The response's headers.
 
 ### Property `vary`
 
-`Record<string, string> | undefined` - The headers defined by the response's `Vary` header
+`Record<string, string | string[]> | undefined` - The headers defined by the response's `Vary` header
 and their respective values for later comparison
 
 For example, for a response like
@@ -95,22 +98,3 @@ This would be
 is either the same sa staleAt or the `max-stale` caching directive.
 
 The store must not return a response after the time defined in this property.
-
-## `CacheStoreReadable`
-
-This extends Node's [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable)
-and defines extra properties relevant to the cache interceptor.
-
-### Getter: `value`
-
-The response's [`CacheStoreValue`](#cachestorevalue)
-
-## `CacheStoreWriteable`
-
-This extends Node's [`Writable`](https://nodejs.org/api/stream.html#class-streamwritable)
-and defines extra properties relevant to the cache interceptor.
-
-### Setter: `rawTrailers`
-
-If the response has trailers, the cache interceptor will pass them to the cache
-interceptor through this method.

package/docs/docs/api/Dispatcher.md

@@ -197,7 +197,7 @@ Returns: `Boolean` - `false` if dispatcher is busy and further dispatch calls wo
 * **headers** `UndiciHeaders | string[]` (optional) - Default: `null`.
 * **query** `Record<string, any> | null` (optional) - Default: `null` - Query string params to be embedded in the request URL. Note that both keys and values of query are encoded using `encodeURIComponent`. If for some reason you need to send them unencoded, embed query params into path directly instead.
 * **idempotent** `boolean` (optional) - Default: `true` if `method` is `'HEAD'` or `'GET'` - Whether the requests can be safely retried or not. If `false` the request won't be sent until all preceding requests in the pipeline has completed.
-* **blocking** `boolean` (optional) - Default: `false` - Whether the response is expected to take a long time and would end up blocking the pipeline. When this is set to `true` further pipelining will be avoided on the same connection until headers have been received.
+* **blocking** `boolean` (optional) - Default: `method !== 'HEAD'` - Whether the response is expected to take a long time and would end up blocking the pipeline. When this is set to `true` further pipelining will be avoided on the same connection until headers have been received.
 * **upgrade** `string | null` (optional) - Default: `null` - Upgrade the request. Should be used to specify the kind of upgrade i.e. `'Websocket'`.
 * **bodyTimeout** `number | null` (optional) - The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use `0` to disable it entirely. Defaults to 300 seconds.
 * **headersTimeout** `number | null` (optional) - The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers while not sending the request. Defaults to 300 seconds.
@@ -527,6 +527,7 @@ try {
   console.log('headers', headers)
   body.setEncoding('utf8')
   body.on('data', console.log)
+  body.on('error', console.error)
   body.on('end', () => {
     console.log('trailers', trailers)
   })
@@ -630,6 +631,25 @@ try {
 }
 ```
 
+#### Example 3 - Conditionally reading the body
+
+Remember to fully consume the body even in the case when it is not read.
+
+```js
+const { body, statusCode } = await client.request({
+  path: '/',
+  method: 'GET'
+})
+
+if (statusCode === 200) {
+  return await body.arrayBuffer()
+}
+
+await body.dump()
+
+return null
+```
+
 ### `Dispatcher.stream(options, factory[, callback])`
 
 A faster version of `Dispatcher.request`. This method expects the second argument `factory` to return a [`stream.Writable`](https://nodejs.org/api/stream.html#stream_class_stream_writable) stream which the response will be written to. This improves performance by avoiding creating an intermediate [`stream.Readable`](https://nodejs.org/api/stream.html#stream_readable_streams) stream when the user expects to directly pipe the response body to a [`stream.Writable`](https://nodejs.org/api/stream.html#stream_class_stream_writable) stream.
@@ -1001,7 +1021,7 @@ The `dns` interceptor enables you to cache DNS lookups for a given duration, per
   - It can be either `'4` or `6`.
   - It will only take effect if `dualStack` is `false`.
 - `lookup: (hostname: string, options: LookupOptions, callback: (err: NodeJS.ErrnoException | null, addresses: DNSInterceptorRecord[]) => void) => void` - Custom lookup function. Default: `dns.lookup`.
-  - For more info see [dns.lookup](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback). 
+  - For more info see [dns.lookup](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback).
 - `pick: (origin: URL, records: DNSInterceptorRecords, affinity: 4 | 6) => DNSInterceptorRecord` - Custom pick function. Default: `RoundRobin`.
   - The function should return a single record from the records array.
   - By default a simplified version of Round Robin is used.

package/docs/docs/api/MockClient.md

@@ -2,7 +2,7 @@
 
 Extends: `undici.Client`
 
-A mock client class that implements the same api as [MockPool](MockPool.md).
+A mock client class that implements the same api as [MockPool](/docs/docs/api/MockPool.md).
 
 ## `new MockClient(origin, [options])`
 

package/docs/docs/api/Pool.md

@@ -2,7 +2,7 @@
 
 Extends: `undici.Dispatcher`
 
-A pool of [Client](Client.md) instances connected to the same upstream target.
+A pool of [Client](/docs/docs/api/Client.md) instances connected to the same upstream target.
 
 Requests are not guaranteed to be dispatched in order of invocation.
 

package/docs/docs/api/api-lifecycle.md

@@ -1,6 +1,6 @@
 # Client Lifecycle
 
-An Undici [Client](Client.md) can be best described as a state machine. The following list is a summary of the various state transitions the `Client` will go through in its lifecycle. This document also contains detailed breakdowns of each state.
+An Undici [Client](/docs/docs/api/Client.md) can be best described as a state machine. The following list is a summary of the various state transitions the `Client` will go through in its lifecycle. This document also contains detailed breakdowns of each state.
 
 > This diagram is not a perfect representation of the undici Client. Since the Client class is not actually implemented as a state-machine, actual execution may deviate slightly from what is described below. Consider this as a general resource for understanding the inner workings of the Undici client rather than some kind of formal specification.
 
@@ -28,7 +28,7 @@ stateDiagram-v2
   [*] --> idle
   idle --> pending : connect
   idle --> destroyed : destroy/close
-  
+
   pending --> idle : timeout
   pending --> destroyed : destroy
 

package/docs/docs/best-practices/mocking-request.md

@@ -1,6 +1,6 @@
 # Mocking Request
 
-Undici has its own mocking [utility](../api/MockAgent.md). It allow us to intercept undici HTTP requests and return mocked values instead. It can be useful for testing purposes.
+Undici has its own mocking [utility](/docs/docs/api/MockAgent.md). It allow us to intercept undici HTTP requests and return mocked values instead. It can be useful for testing purposes.
 
 Example:
 
@@ -73,7 +73,7 @@ const badRequest = await bankTransfer('1234567890', '100')
 assert.deepEqual(badRequest, { message: 'bank account not found' })
 ```
 
-Explore other MockAgent functionality [here](../api/MockAgent.md)
+Explore other MockAgent functionality [here](/docs/docs/api/MockAgent.md)
 
 ## Debug Mock Value
 

package/docs/docs/best-practices/proxy.md

@@ -2,7 +2,7 @@
 
 Connecting through a proxy is possible by:
 
-- Using [ProxyAgent](../api/ProxyAgent.md).
+- Using [ProxyAgent](/docs/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

package/index.d.ts

@@ -1,3 +1,3 @@
-export * from './types/index'
 import Undici from './types/index'
 export default Undici
+export * from './types/index'

package/index.js

@@ -136,12 +136,13 @@ const { kConstruct } = require('./lib/core/symbols')
 // 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/web/cookies')
+const { deleteCookie, getCookies, getSetCookies, setCookie, parseCookie } = require('./lib/web/cookies')
 
 module.exports.deleteCookie = deleteCookie
 module.exports.getCookies = getCookies
 module.exports.getSetCookies = getSetCookies
 module.exports.setCookie = setCookie
+module.exports.parseCookie = parseCookie
 
 const { parseMIMEType, serializeAMimeType } = require('./lib/web/fetch/data-url')
 

package/lib/api/api-request.js

@@ -153,7 +153,7 @@ class RequestHandler extends AsyncResource {
       this.res = null
       // Ensure all queued handlers are invoked before destroying res.
       queueMicrotask(() => {
-        util.destroy(res, err)
+        util.destroy(res.on('error', noop), err)
       })
     }