undici 7.0.0-alpha.2 → 7.0.0-alpha.4

package/README.md

@@ -132,7 +132,7 @@ Returns a promise with the result of the `Dispatcher.request` method.
 
 Calls `options.dispatcher.request(options)`.
 
-See [Dispatcher.request](./docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback) for more details, and [request examples](./examples/README.md) for examples.
+See [Dispatcher.request](./docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback) for more details, and [request examples](./docs/examples/README.md) for examples.
 
 ### `undici.stream([url, options, ]factory): Promise`
 
@@ -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

@@ -0,0 +1,100 @@
+# Cache Store
+
+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). It is expected to be compliant with
+[RFC-9111](https://www.rfc-editor.org/rfc/rfc9111.html).
+
+## Pre-built Cache Stores
+
+### `MemoryCacheStore`
+
+The `MemoryCacheStore` stores the responses in-memory.
+
+**Options**
+
+- `maxEntries` - The maximum amount of responses to store. Default `Infinity`.
+- `maxEntrySize` - The maximum size in bytes that a response's body can be. If a response's body is greater than or equal to this, the response will not be cached.
+
+## Defining a Custom Cache Store
+
+The store must implement the following functions:
+
+### Getter: `isFull`
+
+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: `get`
+
+Parameters:
+
+* **req** `Dispatcher.RequestOptions` - Incoming request
+
+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** `CachedResponse` - Response to 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.
+
+## `CachedResponse`
+
+This is an interface containing the majority of a response's data (minus the body).
+
+### Property `statusCode`
+
+`number` - The response's HTTP status code.
+
+### Property `statusMessage`
+
+`string` - The response's HTTP status message.
+
+### Property `rawHeaders`
+
+`Buffer[]` - The response's headers.
+
+### Property `vary`
+
+`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
+```
+Vary: content-encoding, accepts
+content-encoding: utf8
+accepts: application/json
+```
+
+This would be
+```js
+{
+  'content-encoding': 'utf8',
+  accepts: 'application/json'
+}
+```
+
+### Property `cachedAt`
+
+`number` - Time in millis that this value was cached.
+
+### Property `staleAt`
+
+`number` - Time in millis that this value is considered stale.
+
+### Property `deleteAt`
+
+`number` - Time in millis that this value is to be deleted from the cache. This
+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.

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.
@@ -1233,6 +1253,16 @@ test('should not error if request status code is not in the specified error code
 
 The Response Error Interceptor provides a robust mechanism for handling HTTP response errors by capturing detailed error information and propagating it through a structured `ResponseError` class. This enhancement improves error handling and debugging capabilities in applications using the interceptor.
 
+##### `Cache Interceptor`
+
+The `cache` interceptor implements client-side response caching as described in
+[RFC9111](https://www.rfc-editor.org/rfc/rfc9111.html).
+
+**Options**
+
+- `store` - The [`CacheStore`](./CacheStore.md) to store and retrieve responses from. Default is [`MemoryCacheStore`](./CacheStore.md#memorycachestore).
+- `methods` - The [**safe** HTTP methods](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1) to cache the response of.
+
 ## Instance Events
 
 ### Event: `'connect'`

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

@@ -40,7 +40,12 @@ module.exports.interceptors = {
   redirect: require('./lib/interceptor/redirect'),
   retry: require('./lib/interceptor/retry'),
   dump: require('./lib/interceptor/dump'),
-  dns: require('./lib/interceptor/dns')
+  dns: require('./lib/interceptor/dns'),
+  cache: require('./lib/interceptor/cache')
+}
+
+module.exports.cacheStores = {
+  MemoryCacheStore: require('./lib/cache/memory-cache-store')
 }
 
 module.exports.buildConnector = buildConnector
@@ -131,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

@@ -65,7 +65,7 @@ class RequestHandler extends AsyncResource {
       this.removeAbortListener = util.addAbortListener(signal, () => {
         this.reason = signal.reason ?? new RequestAbortedError()
         if (this.res) {
-          util.destroy(this.res, this.reason)
+          util.destroy(this.res.on('error', noop), this.reason)
         } else if (this.abort) {
           this.abort(this.reason)
         }
@@ -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)
       })
     }
 

package/lib/api/readable.js

@@ -164,7 +164,7 @@ class BodyReadable extends Readable {
    * @see https://fetch.spec.whatwg.org/#dom-body-text
    * @returns {Promise<string>}
    */
-  async text () {
+  text () {
     return consume(this, 'text')
   }
 
@@ -174,7 +174,7 @@ class BodyReadable extends Readable {
    * @see https://fetch.spec.whatwg.org/#dom-body-json
    * @returns {Promise<unknown>}
    */
-  async json () {
+  json () {
     return consume(this, 'json')
   }
 
@@ -184,7 +184,7 @@ class BodyReadable extends Readable {
    * @see https://fetch.spec.whatwg.org/#dom-body-blob
    * @returns {Promise<Blob>}
    */
-  async blob () {
+  blob () {
     return consume(this, 'blob')
   }
 
@@ -194,7 +194,7 @@ class BodyReadable extends Readable {
    * @see https://fetch.spec.whatwg.org/#dom-body-bytes
    * @returns {Promise<Uint8Array>}
    */
-  async bytes () {
+  bytes () {
     return consume(this, 'bytes')
   }
 
@@ -204,7 +204,7 @@ class BodyReadable extends Readable {
    * @see https://fetch.spec.whatwg.org/#dom-body-arraybuffer
    * @returns {Promise<ArrayBuffer>}
    */
-  async arrayBuffer () {
+  arrayBuffer () {
     return consume(this, 'arrayBuffer')
   }
 
@@ -355,7 +355,7 @@ function isUnusable (bodyReadable) {
  * @param {string} type
  * @returns {Promise<any>}
  */
-async function consume (stream, type) {
+function consume (stream, type) {
   assert(!stream[kConsume])
 
   return new Promise((resolve, reject) => {