undici 4.7.0 → 4.8.0

package/docs/api/BalancedPool.md

@@ -0,0 +1,98 @@
+# Class: BalancedPool
+
+Extends: `undici.Dispatcher`
+
+A pool of [Pool](docs/api/Pool.md) instances connected to multiple upstreams.
+
+Requests are not guaranteed to be dispatched in order of invocation.
+
+## `new BalancedPool(upstreams [, options])`
+
+Arguments:
+
+* **upstreams** `URL | string | string[]` - It should only include the **protocol, hostname, and port**.
+* **options** `PoolOptions` (optional)
+
+### Parameter: `PoolOptions`
+
+The `PoolOptions` are passed to each of the `Pool` instances being created.
+
+See: [`PoolOptions`](docs/api/Pool.md#parameter-pooloptions)
+
+## Instance Properties
+
+### `BalancedPool.upstreams`
+
+Returns an array of upstreams that were previously added.
+
+### `BalancedPool.busy`
+
+Implements [Client.busy](docs/api/Client.md#clientbusy)
+
+### `BalancedPool.closed`
+
+Implements [Client.closed](docs/api/Client.md#clientclosed)
+
+### `BalancedPool.destroyed`
+
+Implements [Client.destroyed](docs/api/Client.md#clientdestroyed)
+
+## Instance Methods
+
+### `BalancedPool.addUpstream(upstream)`
+
+Add an upstream.
+
+Arguments:
+
+* **upstream** `string` - It should only include the **protocol, hostname, and port**.
+
+### `BalancedPool.removeUpstream(upstream)`
+
+Removes an upstream that was previously addded.
+
+### `BalancedPool.close([callback])`
+
+Implements [`Dispatcher.close([callback])`](docs/api/Dispatcher.md#clientclose-callback-).
+
+### `BalancedPool.destroy([error, callback])`
+
+Implements [`Dispatcher.destroy([error, callback])`](docs/api/Dispatcher.md#dispatcher-callback-).
+
+### `BalancedPool.connect(options[, callback])`
+
+See [`Dispatcher.connect(options[, callback])`](docs/api/Dispatcher.md#clientconnectoptions--callback).
+
+### `BalancedPool.dispatch(options, handlers)`
+
+Implements [`Dispatcher.dispatch(options, handlers)`](docs/api/Dispatcher.md#clientdispatchoptions-handlers).
+
+### `BalancedPool.pipeline(options, handler)`
+
+See [`Dispatcher.pipeline(options, handler)`](docs/api/Dispatcher.md#clientpipelineoptions-handler).
+
+### `BalancedPool.request(options[, callback])`
+
+See [`Dispatcher.request(options [, callback])`](docs/api/Dispatcher.md#clientrequestoptions--callback).
+
+### `BalancedPool.stream(options, factory[, callback])`
+
+See [`Dispatcher.stream(options, factory[, callback])`](docs/api/Dispatcher.md#clientstreamoptions-factory--callback).
+
+### `BalancedPool.upgrade(options[, callback])`
+
+See [`Dispatcher.upgrade(options[, callback])`](docs/api/Dispatcher.md#clientupgradeoptions-callback).
+
+## Instance Events
+
+### Event: `'connect'`
+
+See [Dispatcher Event: `'connect'`](docs/api/Dispatcher.md#event-connect).
+
+### Event: `'disconnect'`
+
+See [Dispatcher Event: `'disconnect'`](docs/api/Dispatcher.md#event-connect).
+
+### Event: `'drain'`
+
+See [Dispatcher Event: `'drain'`](docs/api/Dispatcher.md#event-connect).

package/docs/api/DiagnosticsChannel.md

@@ -2,8 +2,8 @@
 
 Stability: Experimental.
 
-Undici support the [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html) (currently available only on Node.js v16+).
-It is the preferred way to instrument Undici and retrieve internal informations.
+Undici supports the [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html) (currently available only on Node.js v16+).
+It is the preferred way to instrument Undici and retrieve internal information.
 
 The channels available are the following.
 
@@ -15,6 +15,7 @@ This message is published when a new outgoing request is created.
 import diagnosticsChannel from 'diagnostics_channel'
 
 diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
+  console.log('origin', request.origin)
   console.log('completed', request.completed)
   console.log('method', request.method)
   console.log('path', request.path)
@@ -39,7 +40,7 @@ diagnosticsChannel.channel('undici:request:bodySent').subscribe(({ request }) =>
 
 ## `undici:request:headers`
 
-This message is published after the response headers have been received, i.e. the reponse has been completed.
+This message is published after the response headers have been received, i.e. the response has been completed.
 
 ```js
 import diagnosticsChannel from 'diagnostics_channel'
@@ -55,7 +56,7 @@ diagnosticsChannel.channel('undici:request:headers').subscribe(({ request, respo
 
 ## `undici:request:trailers`
 
-This message is published after the response body and trailers have been received, i.e. the reponse has been completed.
+This message is published after the response body and trailers have been received, i.e. the response has been completed.
 
 ```js
 import diagnosticsChannel from 'diagnostics_channel'
@@ -82,9 +83,9 @@ diagnosticsChannel.channel('undici:request:error').subscribe(({ request, error }
 
 ## `undici:client:sendHeaders`
 
-This message is published right before first byte of the request is written to the socket.
+This message is published right before the 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. 
+*Note*: It will publish the exact headers that will be sent to the server in raw format.
 
 ```js
 import diagnosticsChannel from 'diagnostics_channel'
@@ -97,7 +98,7 @@ diagnosticsChannel.channel('undici:client:sendHeaders').subscribe(({ request, he
 
 ## `undici:client:beforeConnect`
 
-This message is published before creating a new connection for **any** request. 
+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
@@ -111,7 +112,7 @@ diagnosticsChannel.channel('undici:client:beforeConnect').subscribe(({ connectPa
 
 ## `undici:client:connected`
 
-This message is published after connection established.
+This message is published after a connection is established.
 
 ```js
 import diagnosticsChannel from 'diagnostics_channel'

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

@@ -0,0 +1,101 @@
+# Mocking Request
+
+Undici have its own mocking [utility](docs/api/MockAgent.md). It allow us to intercept undici HTTP request and return mocked value instead. It can be useful for testing purposes.
+
+Example:
+
+```js
+// index.mjs
+import { request } from 'undici'
+
+export async function bankTransfer(recepient, ammount) {
+  const { body } = await request('http://localhost:3000/bank-transfer', 
+    {
+      method: 'POST',
+      headers: {
+        'X-TOKEN-SECRET': 'SuperSecretToken',
+      },
+      body: JSON.stringify({ recepient })
+    }
+  )
+  return await body.json()
+}
+```
+
+And this is what the test file looks like:
+
+```js
+// index.test.mjs
+import { strict as assert } from 'assert'
+import { MockAgent, setGlobalDispatcher, } from 'undici'
+import { bankTransfer } from './undici.mjs'
+
+const mockAgent = new MockAgent();
+
+setGlobalDispatcher(mockAgent);
+
+// Provide the base url to the request
+const mockPool = mockAgent.get('http://localhost:3000');
+
+// intercept the request
+mockPool.intercept({
+  path: '/bank-transfer',
+  method: 'POST',
+  headers: {
+    'X-TOKEN-SECRET': 'SuperSecretToken',
+  },
+  body: JSON.stringify({
+    recepient: '1234567890',
+    ammount: '100'
+  })
+}).reply(200, {
+  message: 'transaction processed'
+})
+
+const success = await bankTransfer('1234567890', '100')
+
+assert.deepEqual(success, { message: 'transaction processed' })
+
+// if you dont want to check whether the body or the headers contain the same value
+// just remove it from interceptor
+mockPool.intercept({
+  path: '/bank-transfer',
+  method: 'POST',
+}).reply(400, {
+  message: 'bank account not found'
+})
+
+const badRequest = await bankTransfer('1234567890', '100')
+
+assert.deepEqual(badRequest, { message: 'bank account not found' })
+```
+
+Explore other MockAgent functionality [here](docs/api/MockAgent.md)
+
+## Debug Mock Value
+
+When the interceptor we wrote are not the same undici will automatically call real HTTP request. To debug our mock value use `mockAgent.disableNetConnect()`
+
+```js
+const mockAgent = new MockAgent();
+
+setGlobalDispatcher(mockAgent);
+mockAgent.disableNetConnect()
+
+// Provide the base url to the request
+const mockPool = mockAgent.get('http://localhost:3000');
+
+mockPool.intercept({
+  path: '/bank-tanfer',
+  method: 'POST',
+}).reply(200, {
+  message: 'transaction processed'
+})
+
+const badRequest = await bankTransfer('1234567890', '100')
+// Will throw an error
+// MockNotMatchedError: Mock dispatch not matched for path '/bank-transfer': 
+// subsequent request to origin http://localhost:3000 was not allowed (net.connect disabled)
+```
+
+

package/index.d.ts

@@ -1,21 +1,22 @@
-import Dispatcher from './types/dispatcher'
+import Dispatcher = require('./types/dispatcher')
 import { setGlobalDispatcher, getGlobalDispatcher } from './types/global-dispatcher'
-import Pool from './types/pool'
-import Client from './types/client'
-import buildConnector from './types/connector'
-import errors from './types/errors'
-import Agent from './types/agent'
-import MockClient from './types/mock-client'
-import MockPool from './types/mock-pool'
-import MockAgent from './types/mock-agent'
-import mockErrors from './types/mock-errors'
+import Pool = require('./types/pool')
+import BalancedPool = require('./types/balanced-pool')
+import Client = require('./types/client')
+import buildConnector = require('./types/connector')
+import errors = require('./types/errors')
+import Agent = require('./types/agent')
+import MockClient = require('./types/mock-client')
+import MockPool = require('./types/mock-pool')
+import MockAgent = require('./types/mock-agent')
+import mockErrors = require('./types/mock-errors')
 import { request, pipeline, stream, connect, upgrade } from './types/api'
 
 export * from './types/fetch'
 export * from './types/file'
 export * from './types/formdata'
 
-export { Dispatcher, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, MockClient, MockPool, MockAgent, mockErrors }
+export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, MockClient, MockPool, MockAgent, mockErrors }
 export default Undici
 
 declare function Undici(url: string, opts: Pool.Options): Pool
@@ -23,6 +24,7 @@ declare function Undici(url: string, opts: Pool.Options): Pool
 declare namespace Undici {
   var Dispatcher: typeof import('./types/dispatcher')
   var Pool: typeof import('./types/pool');
+  var BalancedPool: typeof import('./types/balanced-pool');
   var Client: typeof import('./types/client');
   var buildConnector: typeof import('./types/connector');
   var errors: typeof import('./types/errors');

package/index.js

@@ -4,6 +4,7 @@ const Client = require('./lib/client')
 const Dispatcher = require('./lib/dispatcher')
 const errors = require('./lib/core/errors')
 const Pool = require('./lib/pool')
+const BalancedPool = require('./lib/balanced-pool')
 const Agent = require('./lib/agent')
 const util = require('./lib/core/util')
 const { InvalidArgumentError } = errors
@@ -23,6 +24,7 @@ Object.assign(Dispatcher.prototype, api)
 module.exports.Dispatcher = Dispatcher
 module.exports.Client = Client
 module.exports.Pool = Pool
+module.exports.BalancedPool = BalancedPool
 module.exports.Agent = Agent
 
 module.exports.buildConnector = buildConnector

package/lib/api/readable.js

@@ -18,7 +18,11 @@ const kContentType = Symbol('kContentType')
 
 module.exports = class BodyReadable extends Readable {
   constructor (resume, abort, contentType = '') {
-    super({ autoDestroy: true, read: resume })
+    super({
+      autoDestroy: true,
+      read: resume,
+      highWaterMark: 64 * 1024 // Same as nodejs fs streams.
+    })
 
     this._readableState.dataEmitted = false
 

package/lib/balanced-pool.js

@@ -0,0 +1,119 @@
+'use strict'
+
+const { BalancedPoolMissingUpstreamError } = require('./core/errors')
+const Dispatcher = require('./dispatcher')
+const Pool = require('./pool')
+
+const kPools = Symbol('kPools')
+const kPoolOpts = Symbol('kPoolOpts')
+const kUpstream = Symbol('kUpstream')
+const kNeedDrain = Symbol('kNeedDrain')
+
+class BalancedPool extends Dispatcher {
+  constructor (upstreams = [], opts = {}) {
+    super()
+
+    this[kPools] = []
+    this[kPoolOpts] = opts
+    this[kNeedDrain] = false
+
+    if (!Array.isArray(upstreams)) {
+      upstreams = [upstreams]
+    }
+
+    for (const upstream of upstreams) {
+      this.addUpstream(upstream)
+    }
+  }
+
+  addUpstream (upstream) {
+    if (this[kPools].find((pool) => pool[kUpstream] === upstream)) {
+      return this
+    }
+
+    const pool = new Pool(upstream, Object.assign({}, this[kPoolOpts]))
+
+    pool[kUpstream] = upstream
+
+    pool.on('connect', (...args) => {
+      this.emit('connect', ...args)
+    })
+
+    pool.on('disconnect', (...args) => {
+      this.emit('disconnect', ...args)
+    })
+
+    pool.on('drain', (...args) => {
+      if (this[kNeedDrain]) {
+        this[kNeedDrain] = false
+        this.emit('drain', ...args)
+      }
+    })
+
+    this[kPools].push(pool)
+    return this
+  }
+
+  dispatch (opts, handler) {
+    // We validate that pools is greater than 0,
+    // otherwise we would have to wait until an upstream
+    // is added, which might never happen.
+    if (this[kPools].length === 0) {
+      throw new BalancedPoolMissingUpstreamError()
+    }
+
+    let pool = this[kPools].shift()
+    this[kPools].push(pool)
+    if (pool.busy) {
+      pool = this[kPools].find(pool => !pool.busy) || pool
+    }
+    this[kNeedDrain] = !pool.dispatch(opts, handler)
+    return !this[kNeedDrain]
+  }
+
+  removeUpstream (upstream) {
+    const pool = this[kPools].find((pool) => pool[kUpstream] === upstream)
+    const idx = this[kPools].indexOf(pool)
+    this[kPools].splice(idx, 1)
+    pool.close()
+    return this
+  }
+
+  get upstreams () {
+    return this[kPools].map((p) => p[kUpstream])
+  }
+
+  get destroyed () {
+    return this[kPools].reduce((acc, pool) => acc && pool.destroyed, true)
+  }
+
+  get busy () {
+    return this[kPools].reduce((acc, pool) => acc && pool.busy, true) || false
+  }
+
+  get closed () {
+    return this[kPools].reduce((acc, pool) => acc && pool.closed, true)
+  }
+
+  close (cb) {
+    const p = Promise.all(this[kPools].map((p) => p.close()))
+
+    if (!cb) {
+      return p
+    }
+
+    p.then(() => process.nextTick(cb), (err) => process.nextTick(cb, err))
+  }
+
+  destroy (err, cb) {
+    const p = Promise.all(this[kPools].map((p) => p.destroy(err)))
+
+    if (!cb) {
+      return p
+    }
+
+    p.then(() => process.nextTick(cb))
+  }
+}
+
+module.exports = BalancedPool

package/lib/client.js

@@ -282,7 +282,9 @@ class Client extends Dispatcher {
         handler = new RedirectHandler(this, maxRedirections, opts, handler)
       }
 
-      const request = new Request(opts, handler)
+      const origin = opts.origin || this[kUrl].origin
+
+      const request = new Request(origin, opts, handler)
 
       this[kQueue].push(request)
       if (this[kResuming]) {

package/lib/core/errors.js

@@ -167,6 +167,16 @@ class NotSupportedError extends UndiciError {
   }
 }
 
+class BalancedPoolMissingUpstreamError extends UndiciError {
+  constructor (message) {
+    super(message)
+    Error.captureStackTrace(this, NotSupportedError)
+    this.name = 'MissingUpstreamError'
+    this.message = message || 'No upstream has been added to the BalancedPool'
+    this.code = 'UND_ERR_BPL_MISSING_UPSTREAM'
+  }
+}
+
 class HTTPParserError extends Error {
   constructor (message, code, data) {
     super(message)
@@ -195,5 +205,6 @@ module.exports = {
   InformationalError,
   SocketError,
   NotSupportedError,
-  ResponseContentLengthMismatchError
+  ResponseContentLengthMismatchError,
+  BalancedPoolMissingUpstreamError
 }

package/lib/core/request.js

@@ -27,7 +27,7 @@ try {
 }
 
 class Request {
-  constructor ({
+  constructor (origin, {
     path,
     method,
     body,
@@ -93,6 +93,8 @@ class Request {
 
     this.path = path
 
+    this.origin = origin
+
     this.idempotent = idempotent == null
       ? method === 'HEAD' || method === 'GET'
       : idempotent

package/lib/fetch/index.js

@@ -1685,6 +1685,7 @@ function httpNetworkFetch (
           if (decoders.length > 1) {
             if (compose) {
               this.decoder = compose(...decoders)
+              iterator = this.decoder[Symbol.asyncIterator]()
             } else {
               this.decoder = new PassThrough()
               iterator = pipeline(this.decoder, ...decoders, () => {})[

package/package.json

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

package/types/agent.d.ts

@@ -1,6 +1,6 @@
 import { URL } from 'url'
-import Dispatcher from './dispatcher'
-import Pool from './pool'
+import Dispatcher = require('./dispatcher')
+import Pool = require('./pool')
 
 export = Agent
 

package/types/api.d.ts

@@ -1,6 +1,6 @@
 import { URL, UrlObject } from 'url'
 import { Duplex } from 'stream'
-import Dispatcher from './dispatcher'
+import Dispatcher = require('./dispatcher')
 
 export {
   request,

package/types/balanced-pool.d.ts

@@ -0,0 +1,19 @@
+import Client = require('./client')
+import Pool = require('./pool')
+import Dispatcher = require('./dispatcher')
+import { URL } from 'url'
+
+export = BalancedPool
+
+declare class BalancedPool extends Dispatcher {
+  constructor(url: string | URL | string[], options?: Pool.Options);
+
+  addUpstream(upstream: string): BalancedPool;
+  removeUpstream(upstream: string): BalancedPool;
+  upstreams: Array<string>;
+
+  /** `true` after `pool.close()` has been called. */
+  closed: boolean;
+  /** `true` after `pool.destroyed()` has been called or `pool.close()` has been called and the pool shutdown has completed. */
+  destroyed: boolean;
+}

package/types/client.d.ts

@@ -1,7 +1,8 @@
 import { URL } from 'url'
 import { TlsOptions } from 'tls'
-import Dispatcher, { DispatchOptions, RequestOptions } from './dispatcher'
-import buildConnector from './connector'
+import Dispatcher = require('./dispatcher')
+import { DispatchOptions, RequestOptions } from './dispatcher'
+import buildConnector = require('./connector')
 
 export = Client
 

package/types/global-dispatcher.d.ts

@@ -1,4 +1,4 @@
-import Dispatcher from "./dispatcher";
+import Dispatcher = require("./dispatcher");
 
 export {
   getGlobalDispatcher,

package/types/mock-agent.d.ts

@@ -1,5 +1,5 @@
-import Agent from './agent'
-import Dispatcher from './dispatcher'
+import Agent = require('./agent')
+import Dispatcher = require('./dispatcher')
 import { Interceptable } from './mock-interceptor'
 
 export = MockAgent

package/types/mock-client.d.ts

@@ -1,6 +1,6 @@
-import Client from './client'
-import Dispatcher from './dispatcher'
-import MockAgent from './mock-agent'
+import Client = require('./client')
+import Dispatcher = require('./dispatcher')
+import MockAgent = require('./mock-agent')
 import { MockInterceptor, Interceptable } from './mock-interceptor'
 
 export = MockClient

package/types/mock-pool.d.ts

@@ -1,7 +1,7 @@
-import Pool from './pool'
-import MockAgent from './mock-agent'
+import Pool = require('./pool')
+import MockAgent = require('./mock-agent')
 import { Interceptable, MockInterceptor } from './mock-interceptor'
-import Dispatcher from './dispatcher'
+import Dispatcher = require('./dispatcher')
 
 export = MockPool
 

package/types/pool.d.ts

@@ -1,5 +1,5 @@
-import Client from './client'
-import Dispatcher from './dispatcher'
+import Client = require('./client')
+import Dispatcher = require('./dispatcher')
 import { URL } from 'url'
 
 export = Pool