@dnlup/agent-11
v3.0.0
Published
A simple undici pool manager
Downloads
8
Readme
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
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 propertiesprotocol
,hostname
andport
.
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