undici 4.7.3 → 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/index.d.ts

@@ -1,6 +1,7 @@
 import Dispatcher = require('./types/dispatcher')
 import { setGlobalDispatcher, getGlobalDispatcher } from './types/global-dispatcher'
 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')
@@ -15,7 +16,7 @@ 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/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/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/package.json

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

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;
+}