undici 6.13.0 → 6.14.1

package/docs/docs/api/Client.md

@@ -23,7 +23,7 @@ Returns: `Client`
 * **headersTimeout** `number | null` (optional) - Default: `300e3` - 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.
 * **keepAliveMaxTimeout** `number | null` (optional) - Default: `600e3` - The maximum allowed `keepAliveTimeout`, in milliseconds, when overridden by *keep-alive* hints from the server. Defaults to 10 minutes.
 * **keepAliveTimeout** `number | null` (optional) - Default: `4e3` - The timeout, in milliseconds, after which a socket without active requests will time out. Monitors time between activity on a connected socket. This value may be overridden by *keep-alive* hints from the server. See [MDN: HTTP - Headers - Keep-Alive directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Keep-Alive#directives) for more details. Defaults to 4 seconds.
-* **keepAliveTimeoutThreshold** `number | null` (optional) - Default: `1e3` - A number of milliseconds subtracted from server *keep-alive* hints when overriding `keepAliveTimeout` to account for timing inaccuracies caused by e.g. transport latency. Defaults to 1 second.
+* **keepAliveTimeoutThreshold** `number | null` (optional) - Default: `2e3` - A number of milliseconds subtracted from server *keep-alive* hints when overriding `keepAliveTimeout` to account for timing inaccuracies caused by e.g. transport latency. Defaults to 2 seconds.
 * **maxHeaderSize** `number | null` (optional) - Default: `--max-http-header-size` or `16384` - The maximum length of request headers in bytes. Defaults to Node.js' --max-http-header-size or 16KiB.
 * **maxResponseSize** `number | null` (optional) - Default: `-1` - The maximum length of response body in bytes. Set to `-1` to disable.
 * **pipelining** `number | null` (optional) - Default: `1` - The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). Carefully consider your workload and environment before enabling concurrent requests as pipelining may reduce performance if used incorrectly. Pipelining is sensitive to network stack settings as well as head of line blocking caused by e.g. long running requests. Set to `0` to disable keep-alive connections.

package/docs/docs/api/EnvHttpProxyAgent.md

@@ -0,0 +1,162 @@
+# Class: EnvHttpProxyAgent
+
+Stability: Experimental.
+
+Extends: `undici.Dispatcher`
+
+EnvHttpProxyAgent automatically reads the proxy configuration from the environment variables `http_proxy`, `https_proxy`, and `no_proxy` and sets up the proxy agents accordingly. When `http_proxy` and `https_proxy` are set, `http_proxy` is used for HTTP requests and `https_proxy` is used for HTTPS requests. If only `http_proxy` is set, `http_proxy` is used for both HTTP and HTTPS requests. If only `https_proxy` is set, it is only used for HTTPS requests.
+
+`no_proxy` is a comma or space-separated list of hostnames that should not be proxied. The list may contain leading wildcard characters (`*`). If `no_proxy` is set, the EnvHttpProxyAgent will bypass the proxy for requests to hosts that match the list. If `no_proxy` is set to `"*"`, the EnvHttpProxyAgent will bypass the proxy for all requests.
+
+Uppercase environment variables are also supported: `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`. However, if both the lowercase and uppercase environment variables are set, the uppercase environment variables will be ignored.
+
+## `new EnvHttpProxyAgent([options])`
+
+Arguments:
+
+* **options** `EnvHttpProxyAgentOptions` (optional) - extends the `Agent` options.
+
+Returns: `EnvHttpProxyAgent`
+
+### Parameter: `EnvHttpProxyAgentOptions`
+
+Extends: [`AgentOptions`](Agent.md#parameter-agentoptions)
+
+* **httpProxy** `string` (optional) - When set, it will override the `HTTP_PROXY` environment variable.
+* **httpsProxy** `string` (optional) - When set, it will override the `HTTPS_PROXY` environment variable.
+* **noProxy** `string` (optional) - When set, it will override the `NO_PROXY` environment variable.
+
+Examples:
+
+```js
+import { EnvHttpProxyAgent } from 'undici'
+
+const envHttpProxyAgent = new EnvHttpProxyAgent()
+// or
+const envHttpProxyAgent = new EnvHttpProxyAgent({ httpProxy: 'my.proxy.server:8080', httpsProxy: 'my.proxy.server:8443', noProxy: 'localhost' })
+```
+
+#### Example - EnvHttpProxyAgent instantiation
+
+This will instantiate the EnvHttpProxyAgent. It will not do anything until registered as the agent to use with requests.
+
+```js
+import { EnvHttpProxyAgent } from 'undici'
+
+const envHttpProxyAgent = new EnvHttpProxyAgent()
+```
+
+#### Example - Basic Proxy Fetch with global agent dispatcher
+
+```js
+import { setGlobalDispatcher, fetch, EnvHttpProxyAgent } from 'undici'
+
+const envHttpProxyAgent = new EnvHttpProxyAgent()
+setGlobalDispatcher(envHttpProxyAgent)
+
+const { status, json } = await fetch('http://localhost:3000/foo')
+
+console.log('response received', status) // response received 200
+
+const data = await json() // data { foo: "bar" }
+```
+
+#### Example - Basic Proxy Request with global agent dispatcher
+
+```js
+import { setGlobalDispatcher, request, EnvHttpProxyAgent } from 'undici'
+
+const envHttpProxyAgent = new EnvHttpProxyAgent()
+setGlobalDispatcher(envHttpProxyAgent)
+
+const { statusCode, body } = await request('http://localhost:3000/foo')
+
+console.log('response received', statusCode) // response received 200
+
+for await (const data of body) {
+  console.log('data', data.toString('utf8')) // data foo
+}
+```
+
+#### Example - Basic Proxy Request with local agent dispatcher
+
+```js
+import { EnvHttpProxyAgent, request } from 'undici'
+
+const envHttpProxyAgent = new EnvHttpProxyAgent()
+
+const {
+  statusCode,
+  body
+} = await request('http://localhost:3000/foo', { dispatcher: envHttpProxyAgent })
+
+console.log('response received', statusCode) // response received 200
+
+for await (const data of body) {
+  console.log('data', data.toString('utf8')) // data foo
+}
+```
+
+#### Example - Basic Proxy Fetch with local agent dispatcher
+
+```js
+import { EnvHttpProxyAgent, fetch } from 'undici'
+
+const envHttpProxyAgent = new EnvHttpProxyAgent()
+
+const {
+  status,
+  json
+} = await fetch('http://localhost:3000/foo', { dispatcher: envHttpProxyAgent })
+
+console.log('response received', status) // response received 200
+
+const data = await json() // data { foo: "bar" }
+```
+
+## Instance Methods
+
+### `EnvHttpProxyAgent.close([callback])`
+
+Implements [`Dispatcher.close([callback])`](Dispatcher.md#dispatcherclosecallback-promise).
+
+### `EnvHttpProxyAgent.destroy([error, callback])`
+
+Implements [`Dispatcher.destroy([error, callback])`](Dispatcher.md#dispatcherdestroyerror-callback-promise).
+
+### `EnvHttpProxyAgent.dispatch(options, handler: AgentDispatchOptions)`
+
+Implements [`Dispatcher.dispatch(options, handler)`](Dispatcher.md#dispatcherdispatchoptions-handler).
+
+#### Parameter: `AgentDispatchOptions`
+
+Extends: [`DispatchOptions`](Dispatcher.md#parameter-dispatchoptions)
+
+* **origin** `string | URL`
+* **maxRedirections** `Integer`.
+
+Implements [`Dispatcher.destroy([error, callback])`](Dispatcher.md#dispatcherdestroyerror-callback-promise).
+
+### `EnvHttpProxyAgent.connect(options[, callback])`
+
+See [`Dispatcher.connect(options[, callback])`](Dispatcher.md#dispatcherconnectoptions-callback).
+
+### `EnvHttpProxyAgent.dispatch(options, handler)`
+
+Implements [`Dispatcher.dispatch(options, handler)`](Dispatcher.md#dispatcherdispatchoptions-handler).
+
+### `EnvHttpProxyAgent.pipeline(options, handler)`
+
+See [`Dispatcher.pipeline(options, handler)`](Dispatcher.md#dispatcherpipelineoptions-handler).
+
+### `EnvHttpProxyAgent.request(options[, callback])`
+
+See [`Dispatcher.request(options [, callback])`](Dispatcher.md#dispatcherrequestoptions-callback).
+
+### `EnvHttpProxyAgent.stream(options, factory[, callback])`
+
+See [`Dispatcher.stream(options, factory[, callback])`](Dispatcher.md#dispatcherstreamoptions-factory-callback).
+
+### `EnvHttpProxyAgent.upgrade(options[, callback])`
+
+See [`Dispatcher.upgrade(options[, callback])`](Dispatcher.md#dispatcherupgradeoptions-callback).

package/docs/docs/api/EventSource.md

@@ -1,5 +1,7 @@
 # EventSource
 
+> ⚠️ Warning: the EventSource API is experimental.
+
 Undici exposes a WHATWG spec-compliant implementation of [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource)
 for [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events).
 
@@ -11,11 +13,33 @@ follows:
 ```mjs
 import { EventSource } from 'undici'
 
-const evenSource = new EventSource('http://localhost:3000')
-evenSource.onmessage = (event) => {
+const eventSource = new EventSource('http://localhost:3000')
+eventSource.onmessage = (event) => {
   console.log(event.data)
 }
 ```
 
+## Using a custom Dispatcher
+
+undici allows you to set your own Dispatcher in the EventSource constructor.
+
+An example which allows you to modify the request headers is:
+
+```mjs
+import { EventSource, Agent } from 'undici'
+
+class CustomHeaderAgent extends Agent {
+  dispatch (opts) {
+    opts.headers['x-custom-header'] = 'hello world'
+    return super.dispatch(...arguments)
+  }
+}
+
+const eventSource = new EventSource('http://localhost:3000', {
+  dispatcher: new CustomHeaderAgent()
+})
+
+```
+
 More information about the EventSource API can be found on
-[MDN](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).
+[MDN](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).

package/docs/docs/api/Fetch.md

@@ -4,12 +4,6 @@ Undici exposes a fetch() method starts the process of fetching a resource from t
 
 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).

package/index.js

@@ -6,6 +6,7 @@ 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 EnvHttpProxyAgent = require('./lib/dispatcher/env-http-proxy-agent')
 const RetryAgent = require('./lib/dispatcher/retry-agent')
 const errors = require('./lib/core/errors')
 const util = require('./lib/core/util')
@@ -30,6 +31,7 @@ module.exports.Pool = Pool
 module.exports.BalancedPool = BalancedPool
 module.exports.Agent = Agent
 module.exports.ProxyAgent = ProxyAgent
+module.exports.EnvHttpProxyAgent = EnvHttpProxyAgent
 module.exports.RetryAgent = RetryAgent
 module.exports.RetryHandler = RetryHandler
 
@@ -116,7 +118,7 @@ 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.File = globalThis.File ?? require('node:buffer').File
 module.exports.FileReader = require('./lib/web/fileapi/filereader').FileReader
 
 const { setGlobalOrigin, getGlobalOrigin } = require('./lib/web/fetch/global')

package/lib/api/util.js

@@ -12,18 +12,25 @@ async function getResolveErrorBodyCallback ({ callback, body, contentType, statu
   let chunks = []
   let length = 0
 
-  for await (const chunk of body) {
-    chunks.push(chunk)
-    length += chunk.length
-    if (length > CHUNK_LIMIT) {
-      chunks = null
-      break
+  try {
+    for await (const chunk of body) {
+      chunks.push(chunk)
+      length += chunk.length
+      if (length > CHUNK_LIMIT) {
+        chunks = []
+        length = 0
+        break
+      }
     }
+  } catch {
+    chunks = []
+    length = 0
+    // Do nothing....
   }
 
   const message = `Response status code ${statusCode}${statusMessage ? `: ${statusMessage}` : ''}`
 
-  if (statusCode === 204 || !contentType || !chunks) {
+  if (statusCode === 204 || !contentType || !length) {
     queueMicrotask(() => callback(new ResponseStatusCodeError(message, statusCode, headers)))
     return
   }

package/lib/core/request.js

@@ -7,7 +7,7 @@ const {
 const assert = require('node:assert')
 const {
   isValidHTTPToken,
-  isValidHeaderChar,
+  isValidHeaderValue,
   isStream,
   destroy,
   isBuffer,
@@ -336,7 +336,7 @@ function processHeader (request, key, val) {
     const arr = []
     for (let i = 0; i < val.length; i++) {
       if (typeof val[i] === 'string') {
-        if (!isValidHeaderChar(val[i])) {
+        if (!isValidHeaderValue(val[i])) {
           throw new InvalidArgumentError(`invalid ${key} header`)
         }
         arr.push(val[i])
@@ -350,13 +350,11 @@ function processHeader (request, key, val) {
     }
     val = arr
   } else if (typeof val === 'string') {
-    if (!isValidHeaderChar(val)) {
+    if (!isValidHeaderValue(val)) {
       throw new InvalidArgumentError(`invalid ${key} header`)
     }
   } else if (val === null) {
     val = ''
-  } else if (typeof val === 'object') {
-    throw new InvalidArgumentError(`invalid ${key} header`)
   } else {
     val = `${val}`
   }

package/lib/core/symbols.js

@@ -60,5 +60,8 @@ module.exports = {
   kConstruct: Symbol('constructable'),
   kListeners: Symbol('listeners'),
   kHTTPContext: Symbol('http context'),
-  kMaxConcurrentStreams: Symbol('max concurrent streams')
+  kMaxConcurrentStreams: Symbol('max concurrent streams'),
+  kNoProxyAgent: Symbol('no proxy agent'),
+  kHttpProxyAgent: Symbol('http proxy agent'),
+  kHttpsProxyAgent: Symbol('https proxy agent')
 }

package/lib/core/util.js

@@ -52,11 +52,37 @@ function buildURL (url, queryParams) {
   return url
 }
 
+function isValidPort (port) {
+  const value = parseInt(port, 10)
+  return (
+    value === Number(port) &&
+    value >= 0 &&
+    value <= 65535
+  )
+}
+
+function isHttpOrHttpsPrefixed (value) {
+  return (
+    value != null &&
+    value[0] === 'h' &&
+    value[1] === 't' &&
+    value[2] === 't' &&
+    value[3] === 'p' &&
+    (
+      value[4] === ':' ||
+      (
+        value[4] === 's' &&
+        value[5] === ':'
+      )
+    )
+  )
+}
+
 function parseURL (url) {
   if (typeof url === 'string') {
     url = new URL(url)
 
-    if (!/^https?:/.test(url.origin || url.protocol)) {
+    if (!isHttpOrHttpsPrefixed(url.origin || url.protocol)) {
       throw new InvalidArgumentError('Invalid URL protocol: the URL must start with `http:` or `https:`.')
     }
 
@@ -67,12 +93,8 @@ function parseURL (url) {
     throw new InvalidArgumentError('Invalid URL: The URL argument must be a non-null object.')
   }
 
-  if (!/^https?:/.test(url.origin || url.protocol)) {
-    throw new InvalidArgumentError('Invalid URL protocol: the URL must start with `http:` or `https:`.')
-  }
-
   if (!(url instanceof URL)) {
-    if (url.port != null && url.port !== '' && !Number.isFinite(parseInt(url.port))) {
+    if (url.port != null && url.port !== '' && isValidPort(url.port) === false) {
       throw new InvalidArgumentError('Invalid URL: port must be a valid integer or a string representation of an integer.')
     }
 
@@ -92,28 +114,36 @@ function parseURL (url) {
       throw new InvalidArgumentError('Invalid URL origin: the origin must be a string or null/undefined.')
     }
 
+    if (!isHttpOrHttpsPrefixed(url.origin || url.protocol)) {
+      throw new InvalidArgumentError('Invalid URL protocol: the URL must start with `http:` or `https:`.')
+    }
+
     const port = url.port != null
       ? url.port
       : (url.protocol === 'https:' ? 443 : 80)
     let origin = url.origin != null
       ? url.origin
-      : `${url.protocol}//${url.hostname}:${port}`
+      : `${url.protocol || ''}//${url.hostname || ''}:${port}`
     let path = url.path != null
       ? url.path
       : `${url.pathname || ''}${url.search || ''}`
 
-    if (origin.endsWith('/')) {
-      origin = origin.substring(0, origin.length - 1)
+    if (origin[origin.length - 1] === '/') {
+      origin = origin.slice(0, origin.length - 1)
     }
 
-    if (path && !path.startsWith('/')) {
+    if (path && path[0] !== '/') {
       path = `/${path}`
     }
     // new URL(path, origin) is unsafe when `path` contains an absolute URL
     // From https://developer.mozilla.org/en-US/docs/Web/API/URL/URL:
     // If first parameter is a relative URL, second param is required, and will be used as the base URL.
     // If first parameter is an absolute URL, a given second param will be ignored.
-    url = new URL(origin + path)
+    return new URL(`${origin}${path}`)
+  }
+
+  if (!isHttpOrHttpsPrefixed(url.origin || url.protocol)) {
+    throw new InvalidArgumentError('Invalid URL protocol: the URL must start with `http:` or `https:`.')
   }
 
   return url
@@ -193,11 +223,6 @@ function isDestroyed (body) {
   return body && !!(body.destroyed || body[kDestroyed] || (stream.isDestroyed?.(body)))
 }
 
-function isReadableAborted (stream) {
-  const state = stream?._readableState
-  return isDestroyed(stream) && state && !state.endEmitted
-}
-
 function destroy (stream, err) {
   if (stream == null || !isStream(stream) || isDestroyed(stream)) {
     return
@@ -522,7 +547,7 @@ const headerCharRegex = /[^\t\x20-\x7e\x80-\xff]/
 /**
  * @param {string} characters
  */
-function isValidHeaderChar (characters) {
+function isValidHeaderValue (characters) {
   return !headerCharRegex.test(characters)
 }
 
@@ -575,7 +600,6 @@ module.exports = {
   isReadable,
   toUSVString,
   isUSVString,
-  isReadableAborted,
   isBlobLike,
   parseOrigin,
   parseURL,
@@ -603,11 +627,12 @@ module.exports = {
   buildURL,
   addAbortListener,
   isValidHTTPToken,
-  isValidHeaderChar,
+  isValidHeaderValue,
   isTokenCharCode,
   parseRangeHeader,
+  isValidPort,
+  isHttpOrHttpsPrefixed,
   nodeMajor,
   nodeMinor,
-  nodeHasAutoSelectFamily: nodeMajor > 18 || (nodeMajor === 18 && nodeMinor >= 13),
   safeHTTPMethods: ['GET', 'HEAD', 'OPTIONS', 'TRACE']
 }

package/lib/dispatcher/client-h2.js

@@ -208,10 +208,9 @@ function onHttp2SessionEnd () {
  * This is the root cause of #3011
  * We need to handle GOAWAY frames properly, and trigger the session close
  * along with the socket right away
- * Find a way to trigger the close cycle from here on.
  */
 function onHTTP2GoAway (code) {
-  const err = new InformationalError(`HTTP/2: "GOAWAY" frame received with code ${code}`)
+  const err = new RequestAbortedError(`HTTP/2: "GOAWAY" frame received with code ${code}`)
 
   // We need to trigger the close cycle right away
   // We need to destroy the session and the socket
@@ -220,8 +219,7 @@ function onHTTP2GoAway (code) {
   this[kClient][kOnError](err)
 
   this.unref()
-  // We send the GOAWAY frame response as no error
-  this.destroy()
+
   util.destroy(this[kSocket], err)
 }
 

package/lib/dispatcher/client.js

@@ -203,7 +203,7 @@ class Client extends DispatcherBase {
         allowH2,
         socketPath,
         timeout: connectTimeout,
-        ...(util.nodeHasAutoSelectFamily && autoSelectFamily ? { autoSelectFamily, autoSelectFamilyAttemptTimeout } : undefined),
+        ...(autoSelectFamily ? { autoSelectFamily, autoSelectFamilyAttemptTimeout } : undefined),
         ...connect
       })
     }
@@ -226,7 +226,7 @@ class Client extends DispatcherBase {
     this[kMaxHeadersSize] = maxHeaderSize || http.maxHeaderSize
     this[kKeepAliveDefaultTimeout] = keepAliveTimeout == null ? 4e3 : keepAliveTimeout
     this[kKeepAliveMaxTimeout] = keepAliveMaxTimeout == null ? 600e3 : keepAliveMaxTimeout
-    this[kKeepAliveTimeoutThreshold] = keepAliveTimeoutThreshold == null ? 1e3 : keepAliveTimeoutThreshold
+    this[kKeepAliveTimeoutThreshold] = keepAliveTimeoutThreshold == null ? 2e3 : keepAliveTimeoutThreshold
     this[kKeepAliveTimeoutValue] = this[kKeepAliveDefaultTimeout]
     this[kServerName] = null
     this[kLocalAddress] = localAddress != null ? localAddress : null
@@ -376,6 +376,7 @@ function onError (client, err) {
     assert(client[kPendingIdx] === client[kRunningIdx])
 
     const requests = client[kQueue].splice(client[kRunningIdx])
+
     for (let i = 0; i < requests.length; i++) {
       const request = requests[i]
       util.errorRequest(client, request, err)

package/lib/dispatcher/dispatcher-base.js

@@ -6,10 +6,8 @@ const {
   ClientClosedError,
   InvalidArgumentError
 } = require('../core/errors')
-const { kDestroy, kClose, kDispatch, kInterceptors } = require('../core/symbols')
+const { kDestroy, kClose, kClosed, kDestroyed, kDispatch, kInterceptors } = require('../core/symbols')
 
-const kDestroyed = Symbol('destroyed')
-const kClosed = Symbol('closed')
 const kOnDestroyed = Symbol('onDestroyed')
 const kOnClosed = Symbol('onClosed')
 const kInterceptedDispatch = Symbol('Intercepted Dispatch')