Keep-Alive HTTP/S Agent

0.0.1 verified Thu Apr 23 auth: no javascript abandoned

This package provides a basic HTTP and HTTPS connection pooling agent for Node.js, designed to reuse sockets for improved performance by reducing the overhead of establishing new TCP connections. Originally published as version 0.0.1 in December 2012, the package appears to be abandoned, with no significant updates or active development since its initial release. Its primary differentiator was its simplicity, aiming to complement Node.js's default `Agent` rather than replace it. However, the Node.js ecosystem has evolved significantly since then, with native `http.Agent` offering `keepAlive` functionality and more feature-rich, actively maintained alternatives like `agentkeepalive` now widely available. Due to its age and lack of maintenance, it is not recommended for use in modern applications.

Common errors

error TypeError: KeepAliveAgent is not a constructor ↓

cause Attempting to use `new KeepAliveAgent()` in an environment where `require('keep-alive-agent')` returned an undefined or invalid value, often due to Node.js version incompatibility or improper module resolution.

fix

This package is unlikely to work correctly with modern Node.js. Use new http.Agent({ keepAlive: true }) or new (require('agentkeepalive').HttpAgent)() instead.

error ERR_REQUIRE_ESM ↓

cause Trying to `require()` this CommonJS package within an ES Module (ESM) context in Node.js, or attempting to `import` it with ESM syntax.

fix

This package is CommonJS-only and fundamentally too old for modern Node.js. Migrate to a modern keep-alive solution that supports ESM, such as agentkeepalive or Node.js's built-in Agent features.

error ECONNRESET ↓

cause The remote server closed the connection prematurely, or the client attempted to write to a socket that was already closed, often due to misconfigured or outdated keep-alive timeout settings.

fix

This error is common with older keep-alive implementations. Upgrade to agentkeepalive (which includes better timeout handling) or ensure your client-side keepAlive and timeout settings are less than the server's keepAliveTimeout.

Warnings

breaking This package (v0.0.1 from 2012) is severely outdated and is not compatible with modern Node.js features or best practices. It likely contains unpatched security vulnerabilities and may not function as expected or at all with current Node.js versions (e.g., Node.js 16+). ↓

fix Migrate to Node.js's built-in `http.Agent` with `keepAlive: true` or use actively maintained alternatives like `agentkeepalive` for enhanced features and stability.

gotcha Node.js versions prior to 8.0.0 had a potential Denial of Service (DoS) vulnerability (CVE-2019-5739) related to HTTP/S keep-alive connections remaining open for extended periods. This package predates these fixes and would not benefit from the default 5-second `server.keepAliveTimeout` introduced in Node.js 8.0.0. ↓

fix Do not use this package. Ensure your Node.js runtime is updated to a supported version (Node.js 16 or newer recommended) and use its native `http.Agent` with `keepAlive: true` or a modern alternative like `agentkeepalive`.

gotcha Using an unmaintained package for network operations can lead to `ECONNRESET` errors due to mismatched client/server connection timeouts. Modern `keep-alive` agents or Node.js's built-in options have better mechanisms to handle these scenarios. ↓

fix Switch to `agentkeepalive` or configure Node.js's native `http.Agent` with appropriate `keepAlive` and `timeout` settings to align client and server expectations.

gotcha There is no community support, bug fixes, or security patches for this abandoned package. Relying on it introduces significant operational risks and technical debt. ↓

fix Replace this package with a well-supported and actively maintained alternative to ensure stability, performance, and security.

Install

npm install keep-alive-agent

yarn add keep-alive-agent

pnpm add keep-alive-agent

Imports

KeepAliveAgent
wrong
```
import { KeepAliveAgent } from 'keep-alive-agent';
```
correct
```
const KeepAliveAgent = require('keep-alive-agent');
```
This package is CommonJS-only. Attempting to import it using ESM syntax will likely fail or cause runtime issues.

KeepAliveAgent.Secure

wrong

import { Secure } from 'keep-alive-agent';

correct

const KeepAliveAgent = require('keep-alive-agent');
const agent = new KeepAliveAgent.Secure();

The secure agent is a property of the main export, not a separate named export. This package is CommonJS-only.

Quickstart

Demonstrates how to initialize and use the `KeepAliveAgent` for both HTTP and HTTPS requests, reusing sockets for multiple connections.

const http = require('http');
const https = require('https');
const KeepAliveAgent = require('keep-alive-agent');

// Ensure these environment variables are set for testing
const HTTP_HOSTNAME = process.env.TEST_HOSTNAME_HTTP || 'example.com';
const HTTPS_HOSTNAME = process.env.TEST_HOSTNAME_HTTPS || 'google.com';

const httpAgent = new KeepAliveAgent({ maxSockets: 10 });
const httpsAgent = new KeepAliveAgent.Secure({ maxSockets: 10 });

// Example using HTTP keep-alive agent
const httpOptions = {
    hostname: HTTP_HOSTNAME,
    port: 80,
    path: '/',
    agent: httpAgent,
};

http.get(httpOptions, (response) => {
    console.log(`HTTP Status: ${response.statusCode}`);
    response.pipe(process.stdout);
}).on('error', (e) => {
    console.error(`HTTP request error: ${e.message}`);
});

// Example using HTTPS keep-alive agent
const httpsOptions = {
    hostname: HTTPS_HOSTNAME,
    port: 443,
    path: '/',
    agent: httpsAgent,
};

https.get(httpsOptions, (response) => {
    console.log(`HTTPS Status: ${response.statusCode}`);
    response.pipe(process.stdout);
}).on('error', (e) => {
    console.error(`HTTPS request error: ${e.message}`);
});