undici 5.1.0 → 5.3.0

package/README.md

@@ -194,6 +194,21 @@ Basic usage example:
     }
 ```
 
+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({
+    keepAliveTimeout: 10,
+    keepAliveMaxTimeout: 10
+  })
+})
+const json = await res.json()
+console.log(json)
+```
 
 #### `request.body`
 
@@ -360,6 +375,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/Errors.md

@@ -19,7 +19,6 @@ import { errors } from 'undici'
 | `RequestContentLengthMismatchError`  | `UND_ERR_REQ_CONTENT_LENGTH_MISMATCH` | request body does not match content-length header  |
 | `ResponseContentLengthMismatchError` | `UND_ERR_RES_CONTENT_LENGTH_MISMATCH` | response body does not match content-length header |
 | `InformationalError`                 | `UND_ERR_INFO`                        | expected error with reason                         |
-| `TrailerMismatchError`               | `UND_ERR_TRAILER_MISMATCH`            | trailers did not match specification               |
 
 ### `SocketError`
 

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-fetch.js

@@ -0,0 +1,13 @@
+'use strict'
+
+const { getGlobalDispatcher } = require('./lib/global')
+const fetchImpl = require('./lib/fetch')
+
+module.exports.fetch = async function fetch (resource) {
+  const dispatcher = (arguments[1] && arguments[1].dispatcher) || getGlobalDispatcher()
+  return fetchImpl.apply(dispatcher, arguments)
+}
+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

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/index.js

@@ -15,6 +15,7 @@ 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 { getGlobalDispatcher, setGlobalDispatcher } = require('./lib/global')
 
 const nodeVersion = process.versions.node.split('.')
 const nodeMajor = Number(nodeVersion[0])
@@ -32,19 +33,6 @@ module.exports.ProxyAgent = ProxyAgent
 module.exports.buildConnector = buildConnector
 module.exports.errors = errors
 
-let globalDispatcher = new Agent()
-
-function setGlobalDispatcher (agent) {
-  if (!agent || typeof agent.dispatch !== 'function') {
-    throw new InvalidArgumentError('Argument agent must implement Agent')
-  }
-  globalDispatcher = agent
-}
-
-function getGlobalDispatcher () {
-  return globalDispatcher
-}
-
 function makeDispatcher (fn) {
   return (url, opts, handler) => {
     if (typeof opts === 'function') {
@@ -98,7 +86,7 @@ if (nodeMajor > 16 || (nodeMajor === 16 && nodeMinor >= 5)) {
     if (!fetchImpl) {
       fetchImpl = require('./lib/fetch')
     }
-    const dispatcher = getGlobalDispatcher()
+    const dispatcher = (arguments[1] && arguments[1].dispatcher) || getGlobalDispatcher()
     return fetchImpl.apply(dispatcher, arguments)
   }
   module.exports.Headers = require('./lib/fetch/headers').Headers

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

@@ -11,7 +11,6 @@ const RedirectHandler = require('./handler/redirect')
 const {
   RequestContentLengthMismatchError,
   ResponseContentLengthMismatchError,
-  TrailerMismatchError,
   InvalidArgumentError,
   RequestAbortedError,
   HeadersTimeoutError,
@@ -425,7 +424,6 @@ class Parser {
 
     this.bytesRead = 0
 
-    this.trailer = ''
     this.keepAlive = ''
     this.contentLength = ''
   }
@@ -615,8 +613,6 @@ class Parser {
     const key = this.headers[len - 2]
     if (key.length === 10 && key.toString().toLowerCase() === 'keep-alive') {
       this.keepAlive += buf.toString()
-    } else if (key.length === 7 && key.toString().toLowerCase() === 'trailer') {
-      this.trailer += buf.toString()
     } else if (key.length === 14 && key.toString().toLowerCase() === 'content-length') {
       this.contentLength += buf.toString()
     }
@@ -819,7 +815,7 @@ class Parser {
   }
 
   onMessageComplete () {
-    const { client, socket, statusCode, upgrade, trailer, headers, contentLength, bytesRead, shouldKeepAlive } = this
+    const { client, socket, statusCode, upgrade, headers, contentLength, bytesRead, shouldKeepAlive } = this
 
     if (socket.destroyed && (!statusCode || shouldKeepAlive)) {
       return -1
@@ -838,7 +834,6 @@ class Parser {
     this.statusText = ''
     this.bytesRead = 0
     this.contentLength = ''
-    this.trailer = ''
     this.keepAlive = ''
 
     assert(this.headers.length % 2 === 0)
@@ -849,23 +844,6 @@ class Parser {
       return
     }
 
-    const trailers = trailer ? trailer.split(/,\s*/) : []
-    for (let i = 0; i < trailers.length; i++) {
-      const trailer = trailers[i]
-      let found = false
-      for (let n = 0; n < headers.length; n += 2) {
-        const key = headers[n]
-        if (key.length === trailer.length && key.toString().toLowerCase() === trailer.toLowerCase()) {
-          found = true
-          break
-        }
-      }
-      if (!found) {
-        util.destroy(socket, new TrailerMismatchError())
-        return -1
-      }
-    }
-
     /* istanbul ignore next: should be handled by llhttp? */
     if (request.method !== 'HEAD' && contentLength && bytesRead !== parseInt(contentLength, 10)) {
       util.destroy(socket, new ResponseContentLengthMismatchError())

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)
@@ -116,16 +129,6 @@ class ResponseContentLengthMismatchError extends UndiciError {
   }
 }
 
-class TrailerMismatchError extends UndiciError {
-  constructor (message) {
-    super(message)
-    Error.captureStackTrace(this, TrailerMismatchError)
-    this.name = 'TrailerMismatchError'
-    this.message = message || 'Trailers does not match trailer header'
-    this.code = 'UND_ERR_TRAILER_MISMATCH'
-  }
-}
-
 class ClientDestroyedError extends UndiciError {
   constructor (message) {
     super(message)
@@ -196,7 +199,7 @@ module.exports = {
   BodyTimeoutError,
   RequestContentLengthMismatchError,
   ConnectTimeoutError,
-  TrailerMismatchError,
+  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,6 +72,8 @@ class Request {
 
     this.bodyTimeout = bodyTimeout
 
+    this.throwOnError = throwOnError === true
+
     this.method = method
 
     if (body == null) {
@@ -97,7 +101,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/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

@@ -6,6 +6,8 @@ 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,10 +184,6 @@ class FormData {
   }
 
   get [Symbol.toStringTag] () {
-    if (!(this instanceof FormData)) {
-      throw new TypeError('Illegal invocation')
-    }
-
     return this.constructor.name
   }
 
@@ -269,4 +267,4 @@ function makeEntry (name, value, filename) {
   return entry
 }
 
-module.exports = { FormData: globalThis.FormData ?? FormData }
+module.exports = { FormData }