undici 7.0.0-alpha.1 → 7.0.0-alpha.2

package/lib/api/readable.js

@@ -19,7 +19,20 @@ const kBytesRead = Symbol('kBytesRead')
 
 const noop = () => {}
 
+/**
+ * @class
+ * @extends {Readable}
+ * @see https://fetch.spec.whatwg.org/#body
+ */
 class BodyReadable extends Readable {
+  /**
+   * @param {object} opts
+   * @param {(this: Readable, size: number) => void} opts.resume
+   * @param {() => (void | null)} opts.abort
+   * @param {string} [opts.contentType = '']
+   * @param {number} [opts.contentLength]
+   * @param {number} [opts.highWaterMark = 64 * 1024]
+   */
   constructor ({
     resume,
     abort,
@@ -36,8 +49,15 @@ class BodyReadable extends Readable {
     this._readableState.dataEmitted = false
 
     this[kAbort] = abort
+
+    /**
+     * @type {Consume | null}
+     */
     this[kConsume] = null
     this[kBytesRead] = 0
+    /**
+     * @type {ReadableStream|null}
+     */
     this[kBody] = null
     this[kUsed] = false
     this[kContentType] = contentType
@@ -50,6 +70,11 @@ class BodyReadable extends Readable {
     this[kReading] = false
   }
 
+  /**
+   * @param {Error|null} err
+   * @param {(error:(Error|null)) => void} callback
+   * @returns {void}
+   */
   _destroy (err, callback) {
     if (!err && !this._readableState.endEmitted) {
       err = new RequestAbortedError()
@@ -61,7 +86,7 @@ class BodyReadable extends Readable {
 
     // Workaround for Node "bug". If the stream is destroyed in same
     // tick as it is created, then a user who is waiting for a
-    // promise (i.e micro tick) for installing a 'error' listener will
+    // promise (i.e micro tick) for installing an 'error' listener will
     // never get a chance and will always encounter an unhandled exception.
     if (!this[kUsed]) {
       setImmediate(() => {
@@ -72,21 +97,36 @@ class BodyReadable extends Readable {
     }
   }
 
-  on (ev, ...args) {
-    if (ev === 'data' || ev === 'readable') {
+  /**
+   * @param {string} event
+   * @param {(...args: any[]) => void} listener
+   * @returns {this}
+   */
+  on (event, listener) {
+    if (event === 'data' || event === 'readable') {
       this[kReading] = true
       this[kUsed] = true
     }
-    return super.on(ev, ...args)
+    return super.on(event, listener)
   }
 
-  addListener (ev, ...args) {
-    return this.on(ev, ...args)
+  /**
+   * @param {string} event
+   * @param {(...args: any[]) => void} listener
+   * @returns {this}
+   */
+  addListener (event, listener) {
+    return this.on(event, listener)
   }
 
-  off (ev, ...args) {
-    const ret = super.off(ev, ...args)
-    if (ev === 'data' || ev === 'readable') {
+  /**
+   * @param {string|symbol} event
+   * @param {(...args: any[]) => void} listener
+   * @returns {this}
+   */
+  off (event, listener) {
+    const ret = super.off(event, listener)
+    if (event === 'data' || event === 'readable') {
       this[kReading] = (
         this.listenerCount('data') > 0 ||
         this.listenerCount('readable') > 0
@@ -95,10 +135,19 @@ class BodyReadable extends Readable {
     return ret
   }
 
-  removeListener (ev, ...args) {
-    return this.off(ev, ...args)
+  /**
+   * @param {string|symbol} event
+   * @param {(...args: any[]) => void} listener
+   * @returns {this}
+   */
+  removeListener (event, listener) {
+    return this.off(event, listener)
   }
 
+  /**
+   * @param {Buffer|null} chunk
+   * @returns {boolean}
+   */
   push (chunk) {
     this[kBytesRead] += chunk ? chunk.length : 0
 
@@ -109,43 +158,84 @@ class BodyReadable extends Readable {
     return super.push(chunk)
   }
 
-  // https://fetch.spec.whatwg.org/#dom-body-text
+  /**
+   * Consumes and returns the body as a string.
+   *
+   * @see https://fetch.spec.whatwg.org/#dom-body-text
+   * @returns {Promise<string>}
+   */
   async text () {
     return consume(this, 'text')
   }
 
-  // https://fetch.spec.whatwg.org/#dom-body-json
+  /**
+   * Consumes and returns the body as a JavaScript Object.
+   *
+   * @see https://fetch.spec.whatwg.org/#dom-body-json
+   * @returns {Promise<unknown>}
+   */
   async json () {
     return consume(this, 'json')
   }
 
-  // https://fetch.spec.whatwg.org/#dom-body-blob
+  /**
+   * Consumes and returns the body as a Blob
+   *
+   * @see https://fetch.spec.whatwg.org/#dom-body-blob
+   * @returns {Promise<Blob>}
+   */
   async blob () {
     return consume(this, 'blob')
   }
 
-  // https://fetch.spec.whatwg.org/#dom-body-bytes
+  /**
+   * Consumes and returns the body as an Uint8Array.
+   *
+   * @see https://fetch.spec.whatwg.org/#dom-body-bytes
+   * @returns {Promise<Uint8Array>}
+   */
   async bytes () {
     return consume(this, 'bytes')
   }
 
-  // https://fetch.spec.whatwg.org/#dom-body-arraybuffer
+  /**
+   * Consumes and returns the body as an ArrayBuffer.
+   *
+   * @see https://fetch.spec.whatwg.org/#dom-body-arraybuffer
+   * @returns {Promise<ArrayBuffer>}
+   */
   async arrayBuffer () {
     return consume(this, 'arrayBuffer')
   }
 
-  // https://fetch.spec.whatwg.org/#dom-body-formdata
+  /**
+   * Not implemented
+   *
+   * @see https://fetch.spec.whatwg.org/#dom-body-formdata
+   * @throws {NotSupportedError}
+   */
   async formData () {
     // TODO: Implement.
     throw new NotSupportedError()
   }
 
-  // https://fetch.spec.whatwg.org/#dom-body-bodyused
+  /**
+   * Returns true if the body is not null and the body has been consumed.
+   * Otherwise, returns false.
+   *
+   * @see https://fetch.spec.whatwg.org/#dom-body-bodyused
+   * @readonly
+   * @returns {boolean}
+   */
   get bodyUsed () {
     return util.isDisturbed(this)
   }
 
-  // https://fetch.spec.whatwg.org/#dom-body-body
+  /**
+   * @see https://fetch.spec.whatwg.org/#dom-body-body
+   * @readonly
+   * @returns {ReadableStream}
+   */
   get body () {
     if (!this[kBody]) {
       this[kBody] = ReadableStreamFrom(this)
@@ -158,6 +248,13 @@ class BodyReadable extends Readable {
     return this[kBody]
   }
 
+  /**
+   * Dumps the response body by reading `limit` number of bytes.
+   * @param {object} opts
+   * @param {number} [opts.limit = 131072] Number of bytes to read.
+   * @param {AbortSignal} [opts.signal] An AbortSignal to cancel the dump.
+   * @returns {Promise<null>}
+   */
   async dump (opts) {
     const signal = opts?.signal
 
@@ -165,7 +262,9 @@ class BodyReadable extends Readable {
       throw new InvalidArgumentError('signal must be an AbortSignal')
     }
 
-    const limit = Number.isFinite(opts?.limit) ? opts.limit : 128 * 1024
+    const limit = opts?.limit && Number.isFinite(opts.limit)
+      ? opts.limit
+      : 128 * 1024
 
     signal?.throwIfAborted()
 
@@ -174,26 +273,34 @@ class BodyReadable extends Readable {
     }
 
     return await new Promise((resolve, reject) => {
-      if (this[kContentLength] > limit || this[kBytesRead] > limit) {
+      if (
+        (this[kContentLength] && (this[kContentLength] > limit)) ||
+        this[kBytesRead] > limit
+      ) {
         this.destroy(new AbortError())
       }
 
-      const onAbort = () => {
-        this.destroy(signal.reason ?? new AbortError())
+      if (signal) {
+        const onAbort = () => {
+          this.destroy(signal.reason ?? new AbortError())
+        }
+        signal.addEventListener('abort', onAbort)
+        this
+          .on('close', function () {
+            signal.removeEventListener('abort', onAbort)
+            if (signal.aborted) {
+              reject(signal.reason ?? new AbortError())
+            } else {
+              resolve(null)
+            }
+          })
+      } else {
+        this.on('close', resolve)
       }
-      signal?.addEventListener('abort', onAbort)
 
       this
-        .on('close', function () {
-          signal?.removeEventListener('abort', onAbort)
-          if (signal?.aborted) {
-            reject(signal.reason ?? new AbortError())
-          } else {
-            resolve(null)
-          }
-        })
         .on('error', noop)
-        .on('data', function (chunk) {
+        .on('data', () => {
           if (this[kBytesRead] > limit) {
             this.destroy()
           }
@@ -204,7 +311,7 @@ class BodyReadable extends Readable {
 
   /**
    * @param {BufferEncoding} encoding
-   * @returns {BodyReadable}
+   * @returns {this}
    */
   setEncoding (encoding) {
     if (Buffer.isEncoding(encoding)) {
@@ -214,17 +321,40 @@ class BodyReadable extends Readable {
   }
 }
 
-// https://streams.spec.whatwg.org/#readablestream-locked
-function isLocked (self) {
+/**
+ * @see https://streams.spec.whatwg.org/#readablestream-locked
+ * @param {BodyReadable} bodyReadable
+ * @returns {boolean}
+ */
+function isLocked (bodyReadable) {
   // Consume is an implicit lock.
-  return (self[kBody] && self[kBody].locked === true) || self[kConsume]
+  return bodyReadable[kBody]?.locked === true || bodyReadable[kConsume] !== null
 }
 
-// https://fetch.spec.whatwg.org/#body-unusable
-function isUnusable (self) {
-  return util.isDisturbed(self) || isLocked(self)
+/**
+ * @see https://fetch.spec.whatwg.org/#body-unusable
+ * @param {BodyReadable} bodyReadable
+ * @returns {boolean}
+ */
+function isUnusable (bodyReadable) {
+  return util.isDisturbed(bodyReadable) || isLocked(bodyReadable)
 }
 
+/**
+ * @typedef {object} Consume
+ * @property {string} type
+ * @property {BodyReadable} stream
+ * @property {((value?: any) => void)} resolve
+ * @property {((err: Error) => void)} reject
+ * @property {number} length
+ * @property {Buffer[]} body
+ */
+
+/**
+ * @param {BodyReadable} stream
+ * @param {string} type
+ * @returns {Promise<any>}
+ */
 async function consume (stream, type) {
   assert(!stream[kConsume])
 
@@ -269,6 +399,10 @@ async function consume (stream, type) {
   })
 }
 
+/**
+ * @param {Consume} consume
+ * @returns {void}
+ */
 function consumeStart (consume) {
   if (consume.body === null) {
     return
@@ -356,6 +490,11 @@ function chunksConcat (chunks, length) {
   return buffer
 }
 
+/**
+ * @param {Consume} consume
+ * @param {BufferEncoding} encoding
+ * @returns {void}
+ */
 function consumeEnd (consume, encoding) {
   const { type, body, resolve, stream, length } = consume
 
@@ -378,11 +517,21 @@ function consumeEnd (consume, encoding) {
   }
 }
 
+/**
+ * @param {Consume} consume
+ * @param {Buffer} chunk
+ * @returns {void}
+ */
 function consumePush (consume, chunk) {
   consume.length += chunk.length
   consume.body.push(chunk)
 }
 
+/**
+ * @param {Consume} consume
+ * @param {Error} [err]
+ * @returns {void}
+ */
 function consumeFinish (consume, err) {
   if (consume.body === null) {
     return
@@ -394,6 +543,7 @@ function consumeFinish (consume, err) {
     consume.resolve()
   }
 
+  // Reset the consume object to allow for garbage collection.
   consume.type = null
   consume.stream = null
   consume.resolve = null
@@ -402,4 +552,7 @@ function consumeFinish (consume, err) {
   consume.body = null
 }
 
-module.exports = { Readable: BodyReadable, chunksDecode }
+module.exports = {
+  Readable: BodyReadable,
+  chunksDecode
+}

package/lib/api/util.js

@@ -1,3 +1,5 @@
+'use strict'
+
 const assert = require('node:assert')
 const {
   ResponseStatusCodeError

package/lib/core/connect.js

@@ -6,6 +6,8 @@ const util = require('./util')
 const { InvalidArgumentError, ConnectTimeoutError } = require('./errors')
 const timers = require('../util/timers')
 
+function noop () {}
+
 let tls // include tls conditionally since it is not always available
 
 // TODO: session re-use does not wait for the first
@@ -92,9 +94,11 @@ function buildConnector ({ allowH2, maxCachedSessions, socketPath, timeout, sess
       servername = servername || options.servername || util.getServerName(host) || null
 
       const sessionKey = servername || hostname
+      assert(sessionKey)
+
       const session = customSession || sessionCache.get(sessionKey) || null
 
-      assert(sessionKey)
+      port = port || 443
 
       socket = tls.connect({
         highWaterMark: 16384, // TLS in node can't have bigger HWM anyway...
@@ -105,7 +109,7 @@ function buildConnector ({ allowH2, maxCachedSessions, socketPath, timeout, sess
         // TODO(HTTP/2): Add support for h2c
         ALPNProtocols: allowH2 ? ['http/1.1', 'h2'] : ['http/1.1'],
         socket: httpSocket, // upgrade socket connection
-        port: port || 443,
+        port,
         host: hostname
       })
 
@@ -116,11 +120,14 @@ function buildConnector ({ allowH2, maxCachedSessions, socketPath, timeout, sess
         })
     } else {
       assert(!httpSocket, 'httpSocket can only be sent on TLS update')
+
+      port = port || 80
+
       socket = net.connect({
         highWaterMark: 64 * 1024, // Same as nodejs fs streams.
         ...options,
         localAddress,
-        port: port || 80,
+        port,
         host: hostname
       })
     }
@@ -131,12 +138,12 @@ function buildConnector ({ allowH2, maxCachedSessions, socketPath, timeout, sess
       socket.setKeepAlive(true, keepAliveInitialDelay)
     }
 
-    const cancelConnectTimeout = setupConnectTimeout(new WeakRef(socket), timeout)
+    const clearConnectTimeout = setupConnectTimeout(new WeakRef(socket), { timeout, hostname, port })
 
     socket
       .setNoDelay(true)
       .once(protocol === 'https:' ? 'secureConnect' : 'connect', function () {
-        cancelConnectTimeout()
+        queueMicrotask(clearConnectTimeout)
 
         if (callback) {
           const cb = callback
@@ -145,7 +152,7 @@ function buildConnector ({ allowH2, maxCachedSessions, socketPath, timeout, sess
         }
       })
       .on('error', function (err) {
-        cancelConnectTimeout()
+        queueMicrotask(clearConnectTimeout)
 
         if (callback) {
           const cb = callback
@@ -158,50 +165,70 @@ function buildConnector ({ allowH2, maxCachedSessions, socketPath, timeout, sess
   }
 }
 
+/**
+ * @param {WeakRef<net.Socket>} socketWeakRef
+ * @param {object} opts
+ * @param {number} opts.timeout
+ * @param {string} opts.hostname
+ * @param {number} opts.port
+ * @returns {() => void}
+ */
 const setupConnectTimeout = process.platform === 'win32'
-  ? (socket, timeout) => {
-      if (!timeout) {
-        return () => { }
+  ? (socketWeakRef, opts) => {
+      if (!opts.timeout) {
+        return noop
       }
 
       let s1 = null
       let s2 = null
-      const timer = timers.setTimeout(() => {
+      const fastTimer = timers.setFastTimeout(() => {
       // setImmediate is added to make sure that we prioritize socket error events over timeouts
         s1 = setImmediate(() => {
         // Windows needs an extra setImmediate probably due to implementation differences in the socket logic
-          s2 = setImmediate(() => onConnectTimeout(socket.deref()))
+          s2 = setImmediate(() => onConnectTimeout(socketWeakRef.deref(), opts))
         })
-      }, timeout)
+      }, opts.timeout)
       return () => {
-        timers.clearTimeout(timer)
+        timers.clearFastTimeout(fastTimer)
         clearImmediate(s1)
         clearImmediate(s2)
       }
     }
-  : (socket, timeout) => {
-      if (!timeout) {
-        return () => { }
+  : (socketWeakRef, opts) => {
+      if (!opts.timeout) {
+        return noop
       }
 
       let s1 = null
-      const timer = timers.setTimeout(() => {
+      const fastTimer = timers.setFastTimeout(() => {
       // setImmediate is added to make sure that we prioritize socket error events over timeouts
         s1 = setImmediate(() => {
-          onConnectTimeout(socket.deref())
+          onConnectTimeout(socketWeakRef.deref(), opts)
         })
-      }, timeout)
+      }, opts.timeout)
       return () => {
-        timers.clearTimeout(timer)
+        timers.clearFastTimeout(fastTimer)
         clearImmediate(s1)
       }
     }
 
-function onConnectTimeout (socket) {
+/**
+ * @param {net.Socket} socket
+ * @param {object} opts
+ * @param {number} opts.timeout
+ * @param {string} opts.hostname
+ * @param {number} opts.port
+ */
+function onConnectTimeout (socket, opts) {
   let message = 'Connect Timeout Error'
   if (Array.isArray(socket.autoSelectFamilyAttemptedAddresses)) {
-    message += ` (attempted addresses: ${socket.autoSelectFamilyAttemptedAddresses.join(', ')})`
+    message += ` (attempted addresses: ${socket.autoSelectFamilyAttemptedAddresses.join(', ')},`
+  } else {
+    message += ` (attempted address: ${opts.hostname}:${opts.port},`
   }
+
+  message += ` timeout: ${opts.timeout}ms)`
+
   util.destroy(socket, new ConnectTimeoutError(message))
 }
 

package/lib/core/constants.js

@@ -1,10 +1,9 @@
 'use strict'
 
-/** @type {Record<string, string | undefined>} */
-const headerNameLowerCasedRecord = {}
-
-// https://developer.mozilla.org/docs/Web/HTTP/Headers
-const wellknownHeaderNames = [
+/**
+ * @see https://developer.mozilla.org/docs/Web/HTTP/Headers
+ */
+const wellknownHeaderNames = /** @type {const} */ ([
   'Accept',
   'Accept-Encoding',
   'Accept-Language',
@@ -100,7 +99,13 @@ const wellknownHeaderNames = [
   'X-Powered-By',
   'X-Requested-With',
   'X-XSS-Protection'
-]
+])
+
+/** @type {Record<typeof wellknownHeaderNames[number]|Lowercase<typeof wellknownHeaderNames[number]>, string>} */
+const headerNameLowerCasedRecord = {}
+
+// Note: object prototypes should not be able to be referenced. e.g. `Object#hasOwnProperty`.
+Object.setPrototypeOf(headerNameLowerCasedRecord, null)
 
 for (let i = 0; i < wellknownHeaderNames.length; ++i) {
   const key = wellknownHeaderNames[i]
@@ -109,9 +114,6 @@ for (let i = 0; i < wellknownHeaderNames.length; ++i) {
     lowerCasedKey
 }
 
-// Note: object prototypes should not be able to be referenced. e.g. `Object#hasOwnProperty`.
-Object.setPrototypeOf(headerNameLowerCasedRecord, null)
-
 module.exports = {
   wellknownHeaderNames,
   headerNameLowerCasedRecord