@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 and unknown hosts.

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

2.0.0 (2020-12-09)

⚠ BREAKING CHANGES

• some error messages have changed.

Features

• add full url support (34a54e1)