Node.js HTTP/HTTPS Agent with Infinite Sockets

2.0.3 · active · verified Wed Apr 22

infinity-agent is a Node.js utility package that provides custom HTTP and HTTPS agents configured with `maxSockets` set to `Infinity`. It effectively mirrors the behavior of Node.js core `http.Agent` and `https.Agent` classes but modifies them to allow an unlimited number of concurrent outgoing requests. This can be critical for high-throughput applications or services that experience `maxSockets` exhaustion with default Node.js agents. The current stable version is 2.0.3. As a wrapper around Node.js core modules, its release cadence tends to be stable, with updates driven by bug fixes or significant changes in Node.js's underlying network modules. A key differentiator is its out-of-the-box support for an unbounded connection pool, requiring minimal configuration to achieve high concurrency without the usual `maxSockets` limitations. It also includes a minor modification to the `addRequest` method that disables `keepAlive` if the agent isn't explicitly configured for it and `maxSockets` is set to `Infinity`, which is a subtle behavioral difference from the standard Node.js agent.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'globalAgent')
```
cause Attempting to access `http.globalAgent` or `https.globalAgent` on a `require`d or `import`ed object before it's fully resolved, or if the `infinity-agent` package's structure has changed.

fix Ensure `infinity-agent` is correctly imported and that you are accessing the `globalAgent` property on the `http` or `https` sub-objects. For CommonJS: `const { http, https } = require('infinity-agent'); const agent = http.globalAgent;`
```
Error: socket hang up
```
cause This generic network error can occur due to various reasons including server-side issues, network interruptions, or subtle interactions with `keepAlive` behavior when `maxSockets` is infinite.

fix While `infinity-agent` manages socket pooling, `socket hang up` often points to the remote server closing connections prematurely or network instability. Review server logs, ensure the remote service can handle sustained connections, and consider implementing robust retry mechanisms with exponential backoff in your client code.

Warnings

gotcha The package includes a minor behavioral change in its `addRequest` method: `keepAlive` functionality is disabled if the agent is not explicitly configured for it, and `maxSockets` is set to `Infinity`. Users expecting exact parity with Node.js core `Agent` behavior in all `keepAlive` scenarios should be aware of this difference.
Fix: If `keepAlive` is essential, ensure your agent instance is explicitly configured with `keepAlive: true` during instantiation, or consider managing custom agents with specific `maxSockets` values rather than relying solely on `infinity-agent` for full core parity.
gotcha While `infinity-agent` removes the `maxSockets` limit, it does not inherently prevent other forms of resource exhaustion in high-concurrency scenarios, such as excessive memory usage due to too many open sockets or file descriptors. Node.js itself has system-level limits.
Fix: Monitor system resources (memory, file descriptors) in high-load environments. Implement rate limiting or backpressure mechanisms at the application level if external services cannot handle the unbounded concurrency, or if system resources become a bottleneck.

Install

npm install infinity-agent npm
yarn add infinity-agent yarn
pnpm add infinity-agent pnpm

Imports

infinityAgent
wrong:
```
import infinityAgent from 'infinity-agent';
```
correct:
```
const infinityAgent = require('infinity-agent');
```
The package primarily targets CommonJS as shown in its usage examples. For ESM, a default import is typical, but Node.js's interoperability layers might handle `require` directly.
http.globalAgent
wrong:
```
import { globalAgent } from 'infinity-agent/http';
```
correct:
```
const { http, https } = require('infinity-agent');
const infiniteHttpAgent = http.globalAgent;
```
The agent instances are exposed as `globalAgent` properties on the `http` and `https` objects exported by the package. Direct named imports from subpaths are not supported.
https.globalAgent
wrong:
```
const infiniteHttpsAgent = require('infinity-agent').https;
```
correct:
```
const { http, https } = require('infinity-agent');
const infiniteHttpsAgent = https.globalAgent;
```
Remember to access the `globalAgent` property, as `infinityAgent.https` itself is the module's wrapper, not the agent instance.

Quickstart

This quickstart demonstrates how to use `infinity-agent` to perform multiple concurrent HTTP and HTTPS GET requests, leveraging its `maxSockets: Infinity` configuration to manage an unbounded connection pool.

const infinityAgent = require('infinity-agent');
const http = require('http');
const https = require('https');

async function makeRequests() {
  console.log('Making 5 concurrent HTTP requests with infinity-agent...');
  const httpPromises = Array.from({ length: 5 }, (_, i) => {
    return new Promise((resolve, reject) => {
      http.get('http://jsonplaceholder.typicode.com/posts/' + (i + 1), { agent: infinityAgent.http.globalAgent }, (res) => {
        let data = '';
        res.on('data', (chunk) => (data += chunk));
        res.on('end', () => {
          console.log(`HTTP Request ${i + 1} finished (Status: ${res.statusCode})`);
          resolve(JSON.parse(data).id);
        });
      }).on('error', reject);
    });
  });

  console.log('Making 5 concurrent HTTPS requests with infinity-agent...');
  const httpsPromises = Array.from({ length: 5 }, (_, i) => {
    return new Promise((resolve, reject) => {
      https.get('https://jsonplaceholder.typicode.com/comments/' + (i + 1), { agent: infinityAgent.https.globalAgent }, (res) => {
        let data = '';
        res.on('data', (chunk) => (data += chunk));
        res.on('end', () => {
          console.log(`HTTPS Request ${i + 1} finished (Status: ${res.statusCode})`);
          resolve(JSON.parse(data).id);
        });
      }).on('error', reject);
    });
  });

  try {
    const httpResults = await Promise.all(httpPromises);
    const httpsResults = await Promise.all(httpsPromises);
    console.log('\nAll HTTP requests completed successfully. IDs:', httpResults);
    console.log('All HTTPS requests completed successfully. IDs:', httpsResults);
  } catch (error) {
    console.error('\nOne or more requests failed:', error.message);
  }
}

makeRequests();

view raw JSON →