agentkeepalive

When a server closes a connection during a keep-alive race, the client may throw an ECONNRESET error. agentkeepalive implements req.reusedSocket, which allows you to detect if the request was sent through a reused socket. If req.reusedSocket is true and the error is ECONNRESET, you can safely retry the request.

const http = require('http');
const HttpAgent = require('agentkeepalive').HttpAgent;
const agent = new HttpAgent();

const req = http
  .get('http://localhost:3000', { agent }, (res) => {
    // ... handle response
  })
  .on('error', (err) => {
    // If the error happened on a reused socket, it's likely a keep-alive race
    if (req.reusedSocket && err.code === 'ECONNRESET') {
      // retry the request...
    }
  });

Install the agentkeepalive package using npm to enhance Node.js http.Agent with keep-alive features, socket timeouts, and TTL.

$ npm install agentkeepalive --save

The benchmark results demonstrate that using the agentkeepalive agent significantly improves transaction rates and reduces response times compared to a normal Node.js agent.

In the provided benchmark environment (Intel(R) Core(TM)2 Duo CPU P8600 @ 2.40GHz, Node v0.8.9):

• Keep alive agent (30 seconds): Achieved a transaction rate of 2020.20 trans/sec with a response time of 0.03 secs.
• Normal agent: Achieved a transaction rate of 1289.49 trans/sec with a response time of 0.05 secs.

Key performance indicators show that the keepalive agent maintains higher concurrency and throughput by reusing sockets more effectively, resulting in fewer socket creations and lower latency distributions.

For secure connections, use HttpsAgent from the agentkeepalive module and pass it to the agent option in your https.request configuration.

const https = require('https');
const HttpsAgent = require('agentkeepalive').HttpsAgent;

const keepaliveAgent = new HttpsAgent();

const options = {
  host: 'www.google.com',
  port: 443,
  path: '/search?q=nodejs',
  method: 'GET',
  agent: keepaliveAgent,
};

const req = https.request(options, res => {
  console.log('STATUS: ' + res.statusCode);
  res.on('data', chunk => {
    console.log('BODY: ' + chunk);
  });
});

req.on('error', e => {
  console.log('problem with request: ' + e.message);
});

req.end();

To use agentkeepalive with standard HTTP requests, import HttpAgent and pass the instance to the agent property of your request options.

const http = require('http');
const HttpAgent = require('agentkeepalive').HttpAgent;

const keepaliveAgent = new HttpAgent({
  maxSockets: 100,
  maxFreeSockets: 10,
  timeout: 60000,
  freeSocketTimeout: 30000,
});

const options = {
  host: 'cnodejs.org',
  port: 80,
  path: '/',
  method: 'GET',
  agent: keepaliveAgent,
};

const req = http.request(options, res => {
  console.log('STATUS: ' + res.statusCode);
  res.on('data', chunk => {
    console.log('BODY: ' + chunk);
  });
});

req.on('error', e => {
  console.log('problem with request: ' + e.message);
});

req.end();

You can monitor the internal state of an agent using agent.getCurrentStatus(). This returns an object containing socket and request counters. You can check the agent.statusChanged getter to see if counters have changed since the last checkpoint.

// Returns an object like:
// {
//   createSocketCount: 10,
//   closeSocketCount: 5,
//   timeoutSocketCount: 0,
//   requestCount: 5,
//   freeSockets: { 'localhost:57479:': 3 },
//   sockets: { 'localhost:57479:': 5 },
//   requests: {}
// }
const status = keepaliveAgent.getCurrentStatus();

// Check if status has changed
if (keepaliveAgent.statusChanged) {
  console.log('Agent status changed:', status);
}

The following properties are deprecated and will log a warning to the console. You should migrate to the recommended options/properties:

The agentkeepalive package provides HttpAgent and HttpsAgent classes, which are enhanced versions of Node.js's built-in http.Agent and https.Agent. These agents are designed to improve performance by managing socket keep-alive more effectively.

To use the package, you can require the main export (which is HttpAgent) or access the specific classes via the named exports.

const agentkeepalive = require('agentkeepalive');

// Accessing via main export (HttpAgent)
const HttpAgent = agentkeepalive;

// Accessing via named exports
const { HttpAgent: MyHttpAgent, HttpsAgent } = agentkeepalive;

// Usage example (conceptual):
// const agent = new HttpAgent({ keepAlive: true, maxSockets: 100 });

The HttpsAgent class provides keep-alive functionality specifically for HTTPS requests. It extends the base HttpAgent and is designed to be used as the agent option in Node.js https.request() or https.get() calls. It manages a session cache for TLS sessions to optimize connection reuse.

Key configuration properties inherited or defined:

• maxCachedSessions: The maximum number of TLS sessions to cache. Defaults to 100 if not specified in the options object.

const https = require('https');
const HttpsAgent = require('agentkeepalive/https_agent');

const agent = new HttpsAgent({
  maxSockets: 10,
  maxFreeSockets: 5,
  maxCachedSessions: 50
});

const options = {
  hostname: 'example.com',
  port: 443,
  path: '/',
  method: 'GET',
  agent: agent
};

https.request(options, (res) => {
  // ...
}).end();