@dnlup/agent-11

agent-11

A simple pool manager for undici.

You might find this module useful if you use undici and need to manage connections to different hosts and you don't know them ahead of time, so you can't create static clients.

agent-11 controls undici's pool connections to different hosts. Each time you request a new one, it creates a new pool. If you don't request this connection after a certain amount of time, agent-11 will close it.

• Installation
  • Requirements
  • latest stable version
  • latest development version
• Usage
• API
  • Class: Agent11
    • Static method: Agent11.urlToObject(url)
    • Static method: Agent11.getKey(url[, options])
    • new Agent11([options])
    • agent.getConnection(url, [options])
    • agent.close()
    • agent.destroy([error])
• Contributing

Installation

Requirements

agent-11 requires that you already have installed undici in your project.

latest stable version

$ npm i @dnlup/agent-11

latest development version

$ npm i @dnlup/agent-11@next

Usage

const Agent11 = require('@dnlup/agent-11')

const agent = new Agent11({
  closeTimeout: 6e5, // inactive connections will be closed after 600000 millieconds 
  connectionOptions: {
    pipelining: 10
  }
}

const conn1 = agent.getConnection('http://localhost:3000/some/path') // use conn1 to make requests with undici API to locahost:3000

const conn2 = agent.getConnection(new URL('http://localhost:4000/some/other/path', {
  socketPath: '/tmp/agent-11.sock' // these options are merged with the default `connectionOptions` passed when creating the agent
})

const conn3 = agent.getConnection({
  protocol: 'http:',
  hostname: 'localhost',
  port: 5000
})

// close all the agent connections
agent.close().then().catch(console.error)

// destroy all the agent connections
agent.destroy(new Error('no more!')).then().catch(console.error)

API

The module directly exports a Agent11 class, which is the connections manager.

Class: Agent11

It manages undici's pool connections.

Static method: Agent11.urlToObject(url)

• url <string||URL|Object>: the url to convert.
• Returns: <Object> A url-like object with the properties protocol, hostname and port.

Static method: Agent11.getKey(url[, options])

• url <Object>: a url-like object.
• options <Object>: connection options. See undici documentation.
• Returns: <string>: the key that maps the url.

This method creates a key that maps a connection pool to a url.

new Agent11([options])

• options <Object>
  • closeTimeout <number>: the time (in milliseconds) of inactivity, after which it will close a connection. Default: 60000.
  • maxHosts <number>: the maximum number of connections to different hosts. Default: Infinity .
  • connectionOptions: the default options to use to create a new connection. See undici documentation.

agent.getConnection(url, [options])

• url <string|URL|Object>: the url to connect to.
• options <Object>: the connection options.
• Returns: Pool

The parameters are the same ones as undici. It will merge the options object with the connectionOptions specified when creating the class instance. It returns a Pool instance connected to the given url and options.

agent.close()

• Returns: <Promise>

It closes all the Pool connections gracefully.

agent.destroy([error])

• error <Error>: the error to emit when destroying the connections.
• Returns: <Promise>

It destroys all the Pool connections. It optionally takes an error parameter.

Contributing

You found a bug or want to discuss and implement a new feature? This project welcomes contributions.

The code follows the standardjs style guide.

Every contribution should pass the existing tests or implementing new ones if that's the case.

# Run tests
$ npm test

# Lint the code
$ npm lint

# Create the TOC in the README
$ npm run doc

Changelog

3.0.0 (2020-12-19)

⚠ BREAKING CHANGES

• deps: the minimu required version of undici is 3

build

• deps: bump undici to version 3 (b29efde)