undici 5.2.0 → 5.5.0

package/README.md

@@ -185,20 +185,19 @@ Help us improve the test coverage by following instructions at [nodejs/undici/#9
 Basic usage example:
 
 ```js
-    import {fetch} from 'undici';
+import { fetch } from 'undici';
 
-    async function fetchJson() {
-        const res = await fetch('https://example.com')
-        const json = await res.json()
-        console.log(json);
-    }
+
+const res = await fetch('https://example.com')
+const json = await res.json()
+console.log(json);
 ```
 
 You can pass an optional dispatcher to `fetch` as:
 
 ```js
 import { fetch, Agent } from 'undici'
-  
+
 const res = await fetch('https://example.com', {
   // Mocks are also supported
   dispatcher: new Agent({
@@ -235,9 +234,7 @@ const data = {
   },
 };
 
-(async () => {
-  await fetch("https://example.com", { body: data, method: 'POST' });
-})();
+await fetch("https://example.com", { body: data, method: 'POST' });
 ```
 
 #### `response.body`
@@ -245,14 +242,12 @@ const data = {
 Nodejs has two kinds of streams: [web streams](https://nodejs.org/dist/latest-v16.x/docs/api/webstreams.html), which follow the API of the WHATWG web standard found in browsers, and an older Node-specific [streams API](https://nodejs.org/api/stream.html). `response.body` returns a readable web stream. If you would prefer to work with a Node stream you can convert a web stream using `.fromWeb()`.
 
 ```js
-    import {fetch} from 'undici';
-    import {Readable} from 'node:stream';
+import { fetch } from 'undici';
+import { Readable } from 'node:stream';
 
-    async function fetchStream() {
-        const response = await fetch('https://example.com')
-        const readableWebStream = response.body;
-        const readableNodeStream = Readable.fromWeb(readableWebStream);
-    }
+const response = await fetch('https://example.com')
+const readableWebStream = response.body;
+const readableNodeStream = Readable.fromWeb(readableWebStream);
 ```
 
 #### Specification Compliance
@@ -288,6 +283,15 @@ const headers = await fetch(url)
   .then(res => res.headers)
 ```
 
+##### Forbidden and Safelisted Header Names
+
+* https://fetch.spec.whatwg.org/#cors-safelisted-response-header-name
+* https://fetch.spec.whatwg.org/#forbidden-header-name
+* https://fetch.spec.whatwg.org/#forbidden-response-header-name
+* https://github.com/wintercg/fetch/issues/6
+
+The [Fetch Standard](https://fetch.spec.whatwg.org) requires implementations to exclude certain headers from requests and responses. In browser environments, some headers are forbidden so the user agent remains in full control over them. In Undici, these constraints are removed to give more control to the user.
+
 ### `undici.upgrade([url, options]): Promise`
 
 Upgrade to a different protocol. See [MDN - HTTP - Protocol upgrade mechanism](https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism) for more details.
@@ -375,6 +379,7 @@ Refs: https://fetch.spec.whatwg.org/#atomic-http-redirect-handling
 * [__Daniele Belardi__](https://github.com/dnlup), <https://www.npmjs.com/~dnlup>
 * [__Ethan Arrowood__](https://github.com/ethan-arrowood), <https://www.npmjs.com/~ethan_arrowood>
 * [__Matteo Collina__](https://github.com/mcollina), <https://www.npmjs.com/~matteo.collina>
+* [__Matthew Aitken__](https://github.com/KhafraDev), <https://www.npmjs.com/~khaf>
 * [__Robert Nagy__](https://github.com/ronag), <https://www.npmjs.com/~ronag>
 * [__Szymon Marczak__](https://github.com/szmarczak), <https://www.npmjs.com/~szmarczak>
 * [__Tomas Della Vedova__](https://github.com/delvedor), <https://www.npmjs.com/~delvedor>

package/docs/api/Dispatcher.md

@@ -194,18 +194,20 @@ Returns: `Boolean` - `false` if dispatcher is busy and further dispatch calls wo
 * **method** `string`
 * **body** `string | Buffer | Uint8Array | stream.Readable | Iterable | AsyncIterable | null` (optional) - Default: `null`
 * **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.
 * **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 30 seconds.
 * **headersTimeout** `number | null` (optional) - The amount of time the parser will wait to receive the complete HTTP headers. Defaults to 30 seconds.
+* **throwOnError** `boolean` (optional) - Default: `false` - Whether Undici should throw an error upon receiving a 4xx or 5xx response from the server.
 
 #### Parameter: `DispatchHandler`
 
 * **onConnect** `(abort: () => void, context: object) => void` - Invoked before request is dispatched on socket. May be invoked multiple times when a request is retried when the request at the head of the pipeline fails.
 * **onError** `(error: Error) => void` - Invoked when an error has occurred. May not throw.
 * **onUpgrade** `(statusCode: number, headers: Buffer[], socket: Duplex) => void` (optional) - Invoked when request is upgraded. Required if `DispatchOptions.upgrade` is defined or `DispatchOptions.method === 'CONNECT'`.
-* **onHeaders** `(statusCode: number, headers: Buffer[], resume: () => void) => boolean` - Invoked when statusCode and headers have been received. May be invoked multiple times due to 1xx informational headers. Not required for `upgrade` requests.
+* **onHeaders** `(statusCode: number, headers: Buffer[], resume: () => void, statusText: string) => boolean` - Invoked when statusCode and headers have been received. May be invoked multiple times due to 1xx informational headers. Not required for `upgrade` requests.
 * **onData** `(chunk: Buffer) => boolean` - Invoked when response payload data is received. Not required for `upgrade` requests.
 * **onComplete** `(trailers: Buffer[]) => void` - Invoked when response payload and trailers have been received and the request has completed. Not required for `upgrade` requests.
 * **onBodySent** `(chunk: string | Buffer | Uint8Array) => void` - Invoked when a body chunk is sent to the server. Not required. For a stream or iterable body this will be invoked for every chunk. For other body types, it will be invoked once after the body is sent.

package/docs/api/MockPool.md

@@ -57,6 +57,7 @@ Returns: `MockInterceptor` corresponding to the input options.
 * **method** `string | RegExp | (method: string) => boolean` - a matcher for the HTTP request method.
 * **body** `string | RegExp | (body: string) => boolean` - (optional) - a matcher for the HTTP request body.
 * **headers** `Record<string, string | RegExp | (body: string) => boolean`> - (optional) - a matcher for the HTTP request headers. To be intercepted, a request must match all defined headers. Extra headers not defined here may (or may not) be included in the request and do not affect the interception in any way.
+* **query** `Record<string, any> | null` - (optional) - a matcher for the HTTP request query string params.
 
 ### Return: `MockInterceptor`
 

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

@@ -101,4 +101,36 @@ const badRequest = await bankTransfer('1234567890', '100')
 // subsequent request to origin http://localhost:3000 was not allowed (net.connect disabled)
 ```
 
+## Reply with data based on request
 
+If the mocked response needs to be dynamically derived from the request parameters, you can provide a function instead of an object to `reply`
+
+```js
+mockPool.intercept({
+  path: '/bank-transfer',
+  method: 'POST',
+  headers: {
+    'X-TOKEN-SECRET': 'SuperSecretToken',
+  },
+  body: JSON.stringify({
+    recepient: '1234567890',
+    amount: '100'
+  })
+}).reply(200, (opts) => {
+  // do something with opts
+
+  return { message: 'transaction processed' }
+})
+```
+
+in this case opts will be
+
+```
+{
+  method: 'POST',
+  headers: { 'X-TOKEN-SECRET': 'SuperSecretToken' },
+  body: '{"recepient":"1234567890","amount":"100"}',
+  origin: 'http://localhost:3000',
+  path: '/bank-transfer'
+}
+```

package/index.d.ts

@@ -16,6 +16,7 @@ import { request, pipeline, stream, connect, upgrade } from './types/api'
 export * from './types/fetch'
 export * from './types/file'
 export * from './types/formdata'
+export * from './types/diagnostics-channel'
 export { Interceptable } from './types/mock-interceptor'
 
 export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, MockClient, MockPool, MockAgent, mockErrors, ProxyAgent }

package/lib/api/api-request.js

@@ -3,7 +3,8 @@
 const Readable = require('./readable')
 const {
   InvalidArgumentError,
-  RequestAbortedError
+  RequestAbortedError,
+  ResponseStatusCodeError
 } = require('../core/errors')
 const util = require('../core/util')
 const { AsyncResource } = require('async_hooks')
@@ -15,7 +16,7 @@ class RequestHandler extends AsyncResource {
       throw new InvalidArgumentError('invalid opts')
     }
 
-    const { signal, method, opaque, body, onInfo, responseHeaders } = opts
+    const { signal, method, opaque, body, onInfo, responseHeaders, throwOnError } = opts
 
     try {
       if (typeof callback !== 'function') {
@@ -51,6 +52,7 @@ class RequestHandler extends AsyncResource {
     this.trailers = {}
     this.context = null
     this.onInfo = onInfo || null
+    this.throwOnError = throwOnError
 
     if (util.isStream(body)) {
       body.on('error', (err) => {
@@ -70,7 +72,7 @@ class RequestHandler extends AsyncResource {
     this.context = context
   }
 
-  onHeaders (statusCode, rawHeaders, resume) {
+  onHeaders (statusCode, rawHeaders, resume, statusMessage) {
     const { callback, opaque, abort, context } = this
 
     if (statusCode < 200) {
@@ -89,6 +91,13 @@ class RequestHandler extends AsyncResource {
     const headers = this.responseHeaders === 'raw' ? util.parseRawHeaders(rawHeaders) : util.parseHeaders(rawHeaders)
 
     if (callback !== null) {
+      if (this.throwOnError && statusCode >= 400) {
+        this.runInAsyncScope(callback, null,
+          new ResponseStatusCodeError(`Response status code ${statusCode}${statusMessage ? `: ${statusMessage}` : ''}`, statusCode, headers)
+        )
+        return
+      }
+
       this.runInAsyncScope(callback, null, null, {
         statusCode,
         headers,

package/lib/client.js

@@ -873,6 +873,11 @@ class Parser {
       // have been queued since then.
       util.destroy(socket, new InformationalError('reset'))
       return constants.ERROR.PAUSED
+    } else if (client[kPipelining] === 1) {
+      // We must wait a full event loop cycle to reuse this socket to make sure
+      // that non-spec compliant servers are not closing the connection even if they
+      // said they won't.
+      setImmediate(resume, client)
     } else {
       resume(client)
     }

package/lib/core/errors.js

@@ -56,6 +56,19 @@ class BodyTimeoutError extends UndiciError {
   }
 }
 
+class ResponseStatusCodeError extends UndiciError {
+  constructor (message, statusCode, headers) {
+    super(message)
+    Error.captureStackTrace(this, ResponseStatusCodeError)
+    this.name = 'ResponseStatusCodeError'
+    this.message = message || 'Response Status Code Error'
+    this.code = 'UND_ERR_RESPONSE_STATUS_CODE'
+    this.status = statusCode
+    this.statusCode = statusCode
+    this.headers = headers
+  }
+}
+
 class InvalidArgumentError extends UndiciError {
   constructor (message) {
     super(message)
@@ -186,6 +199,7 @@ module.exports = {
   BodyTimeoutError,
   RequestContentLengthMismatchError,
   ConnectTimeoutError,
+  ResponseStatusCodeError,
   InvalidArgumentError,
   InvalidReturnValueError,
   RequestAbortedError,

package/lib/core/request.js

@@ -4,8 +4,8 @@ const {
   InvalidArgumentError,
   NotSupportedError
 } = require('./errors')
-const util = require('./util')
 const assert = require('assert')
+const util = require('./util')
 
 const kHandler = Symbol('handler')
 
@@ -38,11 +38,13 @@ class Request {
     method,
     body,
     headers,
+    query,
     idempotent,
     blocking,
     upgrade,
     headersTimeout,
-    bodyTimeout
+    bodyTimeout,
+    throwOnError
   }, handler) {
     if (typeof path !== 'string') {
       throw new InvalidArgumentError('path must be a string')
@@ -70,19 +72,20 @@ class Request {
 
     this.bodyTimeout = bodyTimeout
 
+    this.throwOnError = throwOnError === true
+
     this.method = method
 
     if (body == null) {
       this.body = null
     } else if (util.isStream(body)) {
       this.body = body
-    } else if (body instanceof DataView) {
-      // TODO: Why is DataView special?
-      this.body = body.buffer.byteLength ? Buffer.from(body.buffer) : null
-    } else if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) {
-      this.body = body.byteLength ? Buffer.from(body) : null
     } else if (util.isBuffer(body)) {
       this.body = body.byteLength ? body : null
+    } else if (ArrayBuffer.isView(body)) {
+      this.body = body.buffer.byteLength ? Buffer.from(body.buffer, body.byteOffset, body.byteLength) : null
+    } else if (body instanceof ArrayBuffer) {
+      this.body = body.byteLength ? Buffer.from(body) : null
     } else if (typeof body === 'string') {
       this.body = body.length ? Buffer.from(body) : null
     } else if (util.isFormDataLike(body) || util.isIterable(body) || util.isBlobLike(body)) {
@@ -97,7 +100,7 @@ class Request {
 
     this.upgrade = upgrade || null
 
-    this.path = path
+    this.path = query ? util.buildURL(path, query) : path
 
     this.origin = origin
 

package/lib/core/util.js

@@ -26,6 +26,51 @@ function isBlobLike (object) {
   )
 }
 
+function isObject (val) {
+  return val !== null && typeof val === 'object'
+}
+
+// this escapes all non-uri friendly characters
+function encode (val) {
+  return encodeURIComponent(val)
+}
+
+// based on https://github.com/axios/axios/blob/63e559fa609c40a0a460ae5d5a18c3470ffc6c9e/lib/helpers/buildURL.js (MIT license)
+function buildURL (url, queryParams) {
+  if (url.includes('?') || url.includes('#')) {
+    throw new Error('Query params cannot be passed when url already contains "?" or "#".')
+  }
+  if (!isObject(queryParams)) {
+    throw new Error('Query params must be an object')
+  }
+
+  const parts = []
+  for (let [key, val] of Object.entries(queryParams)) {
+    if (val === null || typeof val === 'undefined') {
+      continue
+    }
+
+    if (!Array.isArray(val)) {
+      val = [val]
+    }
+
+    for (const v of val) {
+      if (isObject(v)) {
+        throw new Error('Passing object as a query param is not supported, please serialize to string up-front')
+      }
+      parts.push(encode(key) + '=' + encode(v))
+    }
+  }
+
+  const serializedParams = parts.join('&')
+
+  if (serializedParams) {
+    url += '?' + serializedParams
+  }
+
+  return url
+}
+
 function parseURL (url) {
   if (typeof url === 'string') {
     url = new URL(url)
@@ -357,5 +402,6 @@ module.exports = {
   isBuffer,
   validateHandler,
   getSocketInfo,
-  isFormDataLike
+  isFormDataLike,
+  buildURL
 }

package/lib/fetch/body.js

@@ -9,7 +9,7 @@ const { kBodyUsed } = require('../core/symbols')
 const assert = require('assert')
 const { NotSupportedError } = require('../core/errors')
 const { isErrored } = require('../core/util')
-const { isUint8Array } = require('util/types')
+const { isUint8Array, isArrayBuffer } = require('util/types')
 
 let ReadableStream
 
@@ -61,7 +61,7 @@ function extractBody (object, keepalive = false) {
 
     // Set Content-Type to `application/x-www-form-urlencoded;charset=UTF-8`.
     contentType = 'application/x-www-form-urlencoded;charset=UTF-8'
-  } else if (object instanceof ArrayBuffer || ArrayBuffer.isView(object)) {
+  } else if (isArrayBuffer(object) || ArrayBuffer.isView(object)) {
     // BufferSource
 
     if (object instanceof DataView) {

package/lib/fetch/constants.js

@@ -1,28 +1,5 @@
 'use strict'
 
-const forbiddenHeaderNames = [
-  'accept-charset',
-  'accept-encoding',
-  'access-control-request-headers',
-  'access-control-request-method',
-  'connection',
-  'content-length',
-  'cookie',
-  'cookie2',
-  'date',
-  'dnt',
-  'expect',
-  'host',
-  'keep-alive',
-  'origin',
-  'referer',
-  'te',
-  'trailer',
-  'transfer-encoding',
-  'upgrade',
-  'via'
-]
-
 const corsSafeListedMethods = ['GET', 'HEAD', 'POST']
 
 const nullBodyStatus = [101, 204, 205, 304]
@@ -58,9 +35,6 @@ const requestCache = [
   'only-if-cached'
 ]
 
-// https://fetch.spec.whatwg.org/#forbidden-response-header-name
-const forbiddenResponseHeaderNames = ['set-cookie', 'set-cookie2']
-
 const requestBodyHeader = [
   'content-encoding',
   'content-language',
@@ -86,12 +60,8 @@ const subresource = [
   ''
 ]
 
-const corsSafeListedResponseHeaderNames = [] // TODO
-
 module.exports = {
   subresource,
-  forbiddenResponseHeaderNames,
-  corsSafeListedResponseHeaderNames,
   forbiddenMethods,
   requestBodyHeader,
   referrerPolicy,
@@ -99,7 +69,6 @@ module.exports = {
   requestMode,
   requestCredentials,
   requestCache,
-  forbiddenHeaderNames,
   redirectStatus,
   corsSafeListedMethods,
   nullBodyStatus,

package/lib/fetch/file.js

@@ -69,10 +69,6 @@ class File extends Blob {
   }
 
   get [Symbol.toStringTag] () {
-    if (!(this instanceof File)) {
-      throw new TypeError('Illegal invocation')
-    }
-
     return this.constructor.name
   }
 }
@@ -190,10 +186,6 @@ class FileLike {
   }
 
   get [Symbol.toStringTag] () {
-    if (!(this instanceof FileLike)) {
-      throw new TypeError('Illegal invocation')
-    }
-
     return 'File'
   }
 }

package/lib/fetch/formdata.js

@@ -1,11 +1,13 @@
 'use strict'
 
-const { isBlobLike, isFileLike, toUSVString } = require('./util')
+const { isBlobLike, isFileLike, toUSVString, makeIterator } = require('./util')
 const { kState } = require('./symbols')
 const { File, FileLike } = require('./file')
 const { Blob } = require('buffer')
 
 class FormData {
+  static name = 'FormData'
+
   constructor (...args) {
     if (args.length > 0 && !(args[0]?.constructor?.name === 'HTMLFormElement')) {
       throw new TypeError(
@@ -182,52 +184,71 @@ class FormData {
   }
 
   get [Symbol.toStringTag] () {
+    return this.constructor.name
+  }
+
+  entries () {
     if (!(this instanceof FormData)) {
       throw new TypeError('Illegal invocation')
     }
 
-    return this.constructor.name
+    return makeIterator(
+      makeIterable(this[kState], 'entries'),
+      'FormData'
+    )
   }
 
-  * entries () {
+  keys () {
     if (!(this instanceof FormData)) {
       throw new TypeError('Illegal invocation')
     }
 
-    for (const pair of this) {
-      yield pair
-    }
+    return makeIterator(
+      makeIterable(this[kState], 'keys'),
+      'FormData'
+    )
   }
 
-  * keys () {
+  values () {
     if (!(this instanceof FormData)) {
       throw new TypeError('Illegal invocation')
     }
 
-    for (const [key] of this) {
-      yield key
-    }
+    return makeIterator(
+      makeIterable(this[kState], 'values'),
+      'FormData'
+    )
   }
 
-  * values () {
+  /**
+   * @param {(value: string, key: string, self: FormData) => void} callbackFn
+   * @param {unknown} thisArg
+   */
+  forEach (callbackFn, thisArg = globalThis) {
     if (!(this instanceof FormData)) {
       throw new TypeError('Illegal invocation')
     }
 
-    for (const [, value] of this) {
-      yield value
+    if (arguments.length < 1) {
+      throw new TypeError(
+        `Failed to execute 'forEach' on 'FormData': 1 argument required, but only ${arguments.length} present.`
+      )
     }
-  }
 
-  * [Symbol.iterator] () {
-    // The value pairs to iterate over are this’s entry list’s entries with
-    // the key being the name and the value being the value.
-    for (const { name, value } of this[kState]) {
-      yield [name, value]
+    if (typeof callbackFn !== 'function') {
+      throw new TypeError(
+        "Failed to execute 'forEach' on 'FormData': parameter 1 is not of type 'Function'."
+      )
+    }
+
+    for (const [key, value] of this) {
+      callbackFn.apply(thisArg, [value, key, this])
     }
   }
 }
 
+FormData.prototype[Symbol.iterator] = FormData.prototype.entries
+
 function makeEntry (name, value, filename) {
   // To create an entry for name, value, and optionally a filename, run these
   // steps:
@@ -245,8 +266,8 @@ function makeEntry (name, value, filename) {
   // object, representing the same bytes, whose name attribute value is "blob".
   if (isBlobLike(value) && !isFileLike(value)) {
     value = value instanceof Blob
-      ? new File([value], 'blob')
-      : new FileLike(value, 'blob')
+      ? new File([value], 'blob', value)
+      : new FileLike(value, 'blob', value)
   }
 
   // 4. If value is (now) a File object and filename is given, then set value to a
@@ -258,8 +279,8 @@ function makeEntry (name, value, filename) {
   // creating one more File instance doesn't make much sense....
   if (isFileLike(value) && filename != null) {
     value = value instanceof File
-      ? new File([value], filename)
-      : new FileLike(value, filename)
+      ? new File([value], filename, value)
+      : new FileLike(value, filename, value)
   }
 
   // 5. Set entry’s value to value.
@@ -269,4 +290,18 @@ function makeEntry (name, value, filename) {
   return entry
 }
 
-module.exports = { FormData: globalThis.FormData ?? FormData }
+function * makeIterable (entries, type) {
+  // The value pairs to iterate over are this’s entry list’s entries
+  // with the key being the name and the value being the value.
+  for (const { name, value } of entries) {
+    if (type === 'entries') {
+      yield [name, value]
+    } else if (type === 'values') {
+      yield value
+    } else {
+      yield name
+    }
+  }
+}
+
+module.exports = { FormData }