undici 4.6.0 → 4.7.0

package/README.md

@@ -166,6 +166,33 @@ Only supported on Node 16+.
 
 This is [experimental](https://nodejs.org/api/documentation.html#documentation_stability_index) and is not yet fully compliant with the Fetch Standard. We plan to ship breaking changes to this feature until it is out of experimental.
 
+Basic usage example:
+
+```js
+    import {fetch} from 'undici';
+    
+    async function fetchJson() {
+        const res = await fetch('https://example.com')
+        const json = await res.json()
+        console.log(json);
+    }
+```
+
+#### `response.body`
+
+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';
+
+    async function fetchStream() {
+        const response = await fetch('https://example.com')
+        const readableWebStream = response.body;
+        const readableNodeStream = Readable.fromWeb(readableWebStream);
+    }
+```
+
 #### Specification Compliance
 
 This section documents parts of the [Fetch Standard](https://fetch.spec.whatwg.org) which Undici does

package/docs/api/DiagnosticsChannel.md

@@ -79,3 +79,58 @@ diagnosticsChannel.channel('undici:request:error').subscribe(({ request, error }
   // request is the same object undici:request:create
 })
 ```
+
+## `undici:client:sendHeaders`
+
+This message is published right before first byte of the request is written to the socket.
+
+*Note*: It will publish the exact headers that will be sent to the server in raw foramt. 
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:client:sendHeaders').subscribe(({ request, headers, socket }) => {
+  // request is the same object undici:request:create
+  console.log(`Full headers list ${headers.split('\r\n')}`);
+})
+```
+
+## `undici:client:beforeConnect`
+
+This message is published before creating a new connection for **any** request. 
+You can not assume that this event is related to any specific request.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:client:beforeConnect').subscribe(({ connectParams, connector }) => {
+  // const { host, hostname, protocol, port, servername } = connectParams
+  // connector is a function that creates the socket
+})
+```
+
+## `undici:client:connected`
+
+This message is published after connection established.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:client:connected').subscribe(({ socket, connectParams, connector }) => {
+  // const { host, hostname, protocol, port, servername } = connectParams
+ // connector is a function that creates the socket
+})
+```
+
+## `undici:client:connectError`
+
+This message is published if it did not succeed to create new connection
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:client:connectError').subscribe(({ error, socket, connectParams, connector }) => {
+  // const { host, hostname, protocol, port, servername } = connectParams
+  // connector is a function that creates the socket
+  console.log(`Connect failed with ${error.message}`)
+})

package/docs/api/Errors.md

@@ -20,3 +20,22 @@ import { errors } from 'undici'
 | `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`
+
+The `SocketError` has a `.socket` property which holds socket metadata:
+
+```ts
+interface SocketInfo {
+  localAddress?: string
+  localPort?: number
+  remoteAddress?: string
+  remotePort?: number
+  remoteFamily?: string
+  timeout?: number
+  bytesWritten?: number
+  bytesRead?: number
+}
+```
+
+Be aware that in some cases the `.socket` property can be `null`.

package/lib/api/api-connect.js

@@ -40,7 +40,7 @@ class ConnectHandler extends AsyncResource {
   }
 
   onHeaders () {
-    throw new SocketError('bad connect')
+    throw new SocketError('bad connect', null)
   }
 
   onUpgrade (statusCode, headers, socket) {

package/lib/api/api-upgrade.js

@@ -42,7 +42,7 @@ class UpgradeHandler extends AsyncResource {
   }
 
   onHeaders () {
-    throw new SocketError('bad upgrade')
+    throw new SocketError('bad upgrade', null)
   }
 
   onUpgrade (statusCode, headers, socket) {

package/lib/client.js

@@ -65,6 +65,21 @@ const {
   kMaxRedirections
 } = require('./core/symbols')
 
+const channels = {}
+
+try {
+  const diagnosticsChannel = require('diagnostics_channel')
+  channels.sendHeaders = diagnosticsChannel.channel('undici:client:sendHeaders')
+  channels.beforeConnect = diagnosticsChannel.channel('undici:client:beforeConnect')
+  channels.connectError = diagnosticsChannel.channel('undici:client:connectError')
+  channels.connected = diagnosticsChannel.channel('undici:client:connected')
+} catch {
+  channels.sendHeaders = { hasSubscribers: false }
+  channels.beforeConnect = { hasSubscribers: false }
+  channels.connectError = { hasSubscribers: false }
+  channels.connected = { hasSubscribers: false }
+}
+
 class Client extends Dispatcher {
   constructor (url, {
     maxHeaderSize,
@@ -764,13 +779,13 @@ class Parser {
     // TODO: More statusCode validation?
 
     if (statusCode === 100) {
-      util.destroy(socket, new SocketError('bad response'))
+      util.destroy(socket, new SocketError('bad response', util.getSocketInfo(socket)))
       return -1
     }
 
     /* istanbul ignore if: this can only happen if server is misbehaving */
     if (upgrade && !request.upgrade) {
-      util.destroy(socket, new SocketError('bad upgrade'))
+      util.destroy(socket, new SocketError('bad upgrade', util.getSocketInfo(socket)))
       return -1
     }
 
@@ -1040,7 +1055,7 @@ function onSocketEnd () {
     return
   }
 
-  util.destroy(this, new SocketError('other side closed'))
+  util.destroy(this, new SocketError('other side closed', util.getSocketInfo(this)))
 }
 
 function onSocketClose () {
@@ -1049,7 +1064,7 @@ function onSocketClose () {
   this[kParser].destroy()
   this[kParser] = null
 
-  const err = this[kError] || new SocketError('closed')
+  const err = this[kError] || new SocketError('closed', util.getSocketInfo(this))
 
   client[kSocket] = null
 
@@ -1097,6 +1112,20 @@ function connect (client) {
   }
 
   client[kConnecting] = true
+
+  if (channels.beforeConnect.hasSubscribers) {
+    channels.beforeConnect.publish({
+      connectParams: {
+        host,
+        hostname,
+        protocol,
+        port,
+        servername: client[kServerName]
+      },
+      connector: client[kConnector]
+    })
+  }
+
   client[kConnector]({
     host,
     hostname,
@@ -1107,6 +1136,20 @@ function connect (client) {
     client[kConnecting] = false
 
     if (err) {
+      if (channels.connectError.hasSubscribers) {
+        channels.connectError.publish({
+          connectParams: {
+            host,
+            hostname,
+            protocol,
+            port,
+            servername: client[kServerName]
+          },
+          connector: client[kConnector],
+          error: err
+        })
+      }
+
       if (err.code === 'ERR_TLS_CERT_ALTNAME_INVALID') {
         assert(client[kRunning] === 0)
         while (client[kPending] > 0 && client[kQueue][client[kPendingIdx]].servername === client[kServerName]) {
@@ -1136,6 +1179,20 @@ function connect (client) {
         .on('end', onSocketEnd)
         .on('close', onSocketClose)
 
+      if (channels.connected.hasSubscribers) {
+        channels.connected.publish({
+          connectParams: {
+            host,
+            hostname,
+            protocol,
+            port,
+            servername: client[kServerName]
+          },
+          connector: client[kConnector],
+          socket
+        })
+      }
+
       client.emit('connect', client[kUrl], [client])
     }
 
@@ -1412,6 +1469,10 @@ function write (client, request) {
     header += headers
   }
 
+  if (channels.sendHeaders.hasSubscribers) {
+    channels.sendHeaders.publish({ request, headers: header, socket })
+  }
+
   /* istanbul ignore else: assertion */
   if (!body) {
     if (contentLength === 0) {

package/lib/core/connect.js

@@ -29,6 +29,7 @@ function buildConnector ({ maxCachedSessions, socketPath, timeout, ...opts }) {
       const session = sessionCache.get(servername) || null
 
       socket = tls.connect({
+        highWaterMark: 16384, // TLS in node can't have bigger HWM anyway...
         ...options,
         servername,
         session,
@@ -61,6 +62,7 @@ function buildConnector ({ maxCachedSessions, socketPath, timeout, ...opts }) {
         })
     } else {
       socket = net.connect({
+        highWaterMark: 64 * 1024, // Same as nodejs fs streams.
         ...options,
         port: port || 80,
         host: hostname

package/lib/core/errors.js

@@ -147,12 +147,13 @@ class ClientClosedError extends UndiciError {
 }
 
 class SocketError extends UndiciError {
-  constructor (message) {
+  constructor (message, socket) {
     super(message)
     Error.captureStackTrace(this, SocketError)
     this.name = 'SocketError'
     this.message = message || 'Socket error'
     this.code = 'UND_ERR_SOCKET'
+    this.socket = socket
   }
 }
 

package/lib/core/util.js

@@ -245,6 +245,19 @@ function isDisturbed (body) {
   ))
 }
 
+function getSocketInfo (socket) {
+  return {
+    localAddress: socket.localAddress,
+    localPort: socket.localPort,
+    remoteAddress: socket.remoteAddress,
+    remotePort: socket.remotePort,
+    remoteFamily: socket.remoteFamily,
+    timeout: socket.timeout,
+    bytesWritten: socket.bytesWritten,
+    bytesRead: socket.bytesRead
+  }
+}
+
 const kEnumerableProperty = Object.create(null)
 kEnumerableProperty.enumerable = true
 
@@ -267,5 +280,6 @@ module.exports = {
   deepClone,
   isBuffer,
   isBlob,
-  validateHandler
+  validateHandler,
+  getSocketInfo
 }

package/lib/fetch/body.js

@@ -95,7 +95,7 @@ function extractBody (object, keepalive = false) {
           yield enc.encode(
             prefix +
               `; name="${escape(normalizeLinefeeds(name))}"` +
-              (value.filename ? `; filename="${escape(value.filename)}"` : '') +
+              (value.name ? `; filename="${escape(value.name)}"` : '') +
               '\r\n' +
               `Content-Type: ${
                 value.type || 'application/octet-stream'

package/lib/fetch/file.js

@@ -45,17 +45,17 @@ class File extends Blob {
 
     super(fileBits, { type: t })
     this[kState] = {
-      filename: n,
+      name: n,
       lastModified: d
     }
   }
 
-  get filename () {
+  get name () {
     if (!(this instanceof File)) {
       throw new TypeError('Illegal invocation')
     }
 
-    return this[kState].filename
+    return this[kState].name
   }
 
   get lastModified () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "undici",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "An HTTP/1.1 client, written from scratch for Node.js",
   "homepage": "https://undici.nodejs.org",
   "bugs": {

package/types/client.d.ts

@@ -39,4 +39,15 @@ declare namespace Client {
     /** @deprecated use the connect option instead */
     tls?: TlsOptions | null;
   }
+
+  export interface SocketInfo {
+    localAddress?: string
+    localPort?: number
+    remoteAddress?: string
+    remotePort?: number
+    remoteFamily?: string
+    timeout?: number
+    bytesWritten?: number
+    bytesRead?: number
+  }
 }

package/types/errors.d.ts

@@ -1,4 +1,5 @@
 export = Errors
+import { SocketInfo } from './client'
 
 declare namespace Errors {
   export class UndiciError extends Error { }
@@ -67,6 +68,7 @@ declare namespace Errors {
   export class SocketError extends UndiciError {
     name: 'SocketError';
     code: 'UND_ERR_SOCKET';
+    socket: SocketInfo | null
   }
 
   /** Encountered unsupported functionality. */

package/types/file.d.ts

@@ -1,13 +1,9 @@
-// based on https://unpkg.com/browse/formdata-node@4.0.1/@type/File.d.ts (MIT)
+// Based on https://github.com/octet-stream/form-data/blob/2d0f0dc371517444ce1f22cdde13f51995d0953a/lib/File.ts (MIT)
 /// <reference types="node" />
 
-import { Blob } from 'buffer'
+import { Blob, BlobOptions } from 'buffer'
 
-export interface FileOptions {
-  /**
-   * Returns the media type ([`MIME`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types)) of the file represented by a `File` object.
-   */
-  type?: string
+export interface FileOptions extends BlobOptions {
   /**
    * The last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight). Files without a known last modified date return the current date.
    */
@@ -18,21 +14,21 @@ export declare class File extends Blob {
   /**
    * Creates a new File instance.
    *
-   * @param fileBits An `Array` strings, or [`Buffer`](https://nodejs.org/dist/latest/docs/api/buffer.html#buffer_class_buffer), [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), [`ArrayBufferView`](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView), [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) objects, or a mix of any of such objects, that will be put inside the [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File).
-   * @param name The name of the file.
+   * @param fileBits An `Array` strings, or [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), [`ArrayBufferView`](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView), [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) objects, or a mix of any of such objects, that will be put inside the [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File).
+   * @param fileName The name of the file.
    * @param options An options object containing optional attributes for the file.
    */
-  constructor (fileBits: ReadonlyArray<string | NodeJS.ArrayBufferView | Blob>, name: string, options?: FileOptions)
+  constructor(fileBits: ReadonlyArray<string | NodeJS.ArrayBufferView | Blob>, fileName: string, options?: FileOptions)
+
   /**
    * Name of the file referenced by the File object.
    */
-  get name (): string
+  readonly name: string
+
   /**
    * The last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight). Files without a known last modified date return the current date.
    */
-  get lastModified (): number
-  get [Symbol.toStringTag] (): string
-  stream (): {
-    [Symbol.asyncIterator]: () => AsyncIterableIterator<Uint8Array>
-  }
+  readonly lastModified: number
+
+  readonly [Symbol.toStringTag]: string
 }

package/types/formdata.d.ts

@@ -1,4 +1,4 @@
-// based on https://unpkg.com/browse/formdata-node@4.0.1/@type/FormData.d.ts (MIT)
+// Based on https://github.com/octet-stream/form-data/blob/2d0f0dc371517444ce1f22cdde13f51995d0953a/lib/FormData.ts (MIT)
 /// <reference types="node" />
 
 import { File } from './file'
@@ -10,12 +10,8 @@ declare type FormDataEntryValue = string | File
 
 /**
  * Provides a way to easily construct a set of key/value pairs representing form fields and their values, which can then be easily sent using fetch().
- *
- * Note that this object is not a part of Node.js, so you might need to check if an HTTP client of your choice support spec-compliant FormData.
- * However, if your HTTP client does not support FormData, you can use [`form-data-encoder`](https://npmjs.com/package/form-data-encoder) package to handle "multipart/form-data" encoding.
  */
 export declare class FormData {
-  constructor ()
   /**
    * Appends a new value onto an existing key inside a FormData object,
    * or adds the key if it does not already exist.
@@ -25,9 +21,10 @@ export declare class FormData {
    * @param name The name of the field whose data is contained in `value`.
    * @param value The field's value. This can be [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
     or [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File). If none of these are specified the value is converted to a string.
-   * @param filename The filename reported to the server, when a Blob or File is passed as the second parameter. The default filename for Blob objects is "blob". The default filename for File objects is the file's filename.
+   * @param fileName The filename reported to the server, when a Blob or File is passed as the second parameter. The default filename for Blob objects is "blob". The default filename for File objects is the file's filename.
    */
-  readonly append: (name: string, value: unknown, filename?: string) => void
+  append(name: string, value: unknown, fileName?: string): void
+
   /**
    * Set a new value for an existing key inside FormData,
    * or add the new field if it does not already exist.
@@ -35,10 +32,11 @@ export declare class FormData {
    * @param name The name of the field whose data is contained in `value`.
    * @param value The field's value. This can be [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
     or [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File). If none of these are specified the value is converted to a string.
-   * @param filename The filename reported to the server, when a Blob or File is passed as the second parameter. The default filename for Blob objects is "blob". The default filename for File objects is the file's filename.
+   * @param fileName The filename reported to the server, when a Blob or File is passed as the second parameter. The default filename for Blob objects is "blob". The default filename for File objects is the file's filename.
    *
    */
-  readonly set: (name: string, value: unknown, filename?: string) => void
+  set(name: string, value: unknown, fileName?: string): void
+
   /**
    * Returns the first value associated with a given key from within a `FormData` object.
    * If you expect multiple values and want all of them, use the `getAll()` method instead.
@@ -47,7 +45,8 @@ export declare class FormData {
    *
    * @returns A `FormDataEntryValue` containing the value. If the key doesn't exist, the method returns null.
    */
-  readonly get: (name: string) => FormDataEntryValue | null
+  get(name: string): FormDataEntryValue | null
+
   /**
    * Returns all the values associated with a given key from within a `FormData` object.
    *
@@ -55,7 +54,8 @@ export declare class FormData {
    *
    * @returns An array of `FormDataEntryValue` whose key matches the value passed in the `name` parameter. If the key doesn't exist, the method returns an empty list.
    */
-  readonly getAll: (name: string) => FormDataEntryValue[]
+  getAll(name: string): FormDataEntryValue[]
+
   /**
    * Returns a boolean stating whether a `FormData` object contains a certain key.
    *
@@ -63,35 +63,42 @@ export declare class FormData {
    *
    * @return A boolean value.
    */
-  readonly has: (name: string) => boolean
+  has(name: string): boolean
+
   /**
    * Deletes a key and its value(s) from a `FormData` object.
    *
    * @param name The name of the key you want to delete.
    */
-  readonly delete: (name: string) => void
+  delete(name: string): void
+
   /**
    * Returns an [`iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) allowing to go through all keys contained in this `FormData` object.
    * Each key is a `string`.
    */
-  readonly keys: () => Generator<string>
+  keys(): Generator<string>
+
   /**
    * Returns an [`iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) allowing to go through the `FormData` key/value pairs.
    * The key of each pair is a string; the value is a [`FormDataValue`](https://developer.mozilla.org/en-US/docs/Web/API/FormDataEntryValue).
    */
-  readonly entries: () => Generator<[string, FormDataEntryValue]>
+  entries(): Generator<[string, FormDataEntryValue]>
+
   /**
    * Returns an [`iterator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) allowing to go through all values contained in this object `FormData` object.
    * Each value is a [`FormDataValue`](https://developer.mozilla.org/en-US/docs/Web/API/FormDataEntryValue).
    */
-  readonly values: () => Generator<FormDataEntryValue>
+  values(): Generator<FormDataEntryValue>
+
   /**
    * An alias for FormData#entries()
    */
-  readonly [Symbol.iterator]: () => Generator<[string, FormDataEntryValue], any, unknown>
+  [Symbol.iterator](): Generator<[string, FormDataEntryValue], void>
+
   /**
    * Executes given callback function for each field of the FormData instance
    */
-  readonly forEach: (fn: (value: FormDataEntryValue, key: string, fd: FormData) => void, ctx?: unknown) => void
-  get [Symbol.toStringTag] (): string
+  forEach(callback: (value: FormDataEntryValue, key: string, formData: FormData) => void, thisArg?: unknown): void
+
+  readonly [Symbol.toStringTag]: string
 }