HTTP Keep-Alive Agent

0.6.1 · abandoned · verified Wed Apr 22

forever-agent is a Node.js module that provides an HTTP Agent designed to maintain persistent socket connections between `http.request` calls, enabling HTTP keep-alive behavior. It was originally an internal component of the widely popular, but now deprecated, `request` HTTP client library. The current stable version, 0.6.1, was last published over 11 years ago in April 2015. With the official deprecation of its progenitor `request` library in 2020, forever-agent itself is considered unmaintained and has seen no significant updates for over a decade. Its key differentiator was offering direct control over connection pooling for keep-alive outside of the `request` library, at a time when native Node.js HTTP client features were less developed regarding persistent connections.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to import `forever-agent` using ES Module `import` syntax in a JavaScript module that is treated as an ESM module (e.g., in a package with `"type": "module"` or a `.mjs` file).

fix Use CommonJS `require` syntax instead: `const ForeverAgent = require('forever-agent');`
```
TypeError: ForeverAgent is not a constructor
```
cause Attempting to call `ForeverAgent` as a function without the `new` keyword, or a bundling/transpilation issue incorrectly exporting/importing it.

fix Ensure you are instantiating it as a class: `const agent = new ForeverAgent();`
```
NPM WARN deprecated forever-agent@0.6.1: This package is very old and unmaintained.
```
cause This is a warning from `npm install` indicating that the package is no longer actively developed and may have security or compatibility issues.

fix This is a warning, not an error. The fix is to acknowledge the deprecation and plan for migration to a modern, supported alternative like `undici` or the native Node.js `http.Agent` with `keepAlive`.

Warnings

deprecated The `forever-agent` package is effectively abandoned, with its last publish over 11 years ago (April 2015). It was originally part of the `request` library, which itself was officially deprecated in 2020. Consider using built-in Node.js `http`/`https` agents with `keepAlive` options or modern, actively maintained HTTP client libraries like `axios`, `node-fetch`, or `undici` for better performance, security, and feature sets.
Fix: Migrate to `undici` (Node.js 18+) or use the native `http.Agent`/`https.Agent` with `keepAlive: true` and `maxSockets` options for connection pooling. For example: `const agent = new http.Agent({ keepAlive: true, maxSockets: 10 });`
breaking Due to its age and lack of maintenance, `forever-agent` may not be compatible with newer Node.js versions, particularly regarding internal `http` module changes, TLS/SSL updates, or event loop behavior. Unexpected errors, memory leaks, or incorrect connection handling could occur.
Fix: Update to an actively maintained HTTP client library or utilize Node.js's native `Agent` options for `keepAlive` functionality. Thoroughly test existing applications if upgrading Node.js versions while still relying on `forever-agent`.
gotcha This package has not received security updates for over a decade. It may contain unfixed vulnerabilities, especially concerning parsing HTTP headers, handling malformed responses, or TLS handshake issues, making it unsuitable for production environments where security is critical.
Fix: Immediately replace `forever-agent` with a modern, actively maintained HTTP client library or the native `http.Agent`/`https.Agent` which receive regular security patches as part of Node.js core.

Install

npm install forever-agent npm
yarn add forever-agent yarn
pnpm add forever-agent pnpm

Imports

ForeverAgent
wrong:
```
import { ForeverAgent } from 'forever-agent';
```
correct:
```
const ForeverAgent = require('forever-agent');
```
This package is a CommonJS module from an older era. ESM `import` syntax will not work directly and attempting to use it may result in `ERR_REQUIRE_ESM`.
HTTP Agent Instance
wrong:
```
const agent = ForeverAgent();
```
correct:
```
const agent = new ForeverAgent();
```
ForeverAgent is a constructor function and must be instantiated with the `new` keyword to create an agent instance.

Quickstart

This quickstart demonstrates how to instantiate `ForeverAgent` and use it with Node.js's native `http.request` to achieve persistent (keep-alive) connections across multiple requests to the same host.

const http = require('http');
const ForeverAgent = require('forever-agent');

const agent = new ForeverAgent();

// Define request options, ensuring 'Connection: keep-alive' is set.
const options = {
  hostname: 'httpbin.org', // A public service for testing HTTP requests
  port: 80,
  path: '/get',
  method: 'GET',
  agent: agent, // Crucially, assign the forever-agent instance
  headers: {
    'Connection': 'keep-alive'
  }
};

function makeKeepAliveRequest(id) {
  return new Promise((resolve, reject) => {
    console.log(`[Request ${id}] Sending request...`);
    const req = http.request(options, (res) => {
      let data = '';
      res.on('data', (chunk) => { data += chunk; });
      res.on('end', () => {
        console.log(`[Request ${id}] Status: ${res.statusCode}, Socket Local Port: ${req.socket ? req.socket.localPort : 'N/A'}`);
        resolve(res.statusCode);
      });
    });

    req.on('error', (e) => {
      console.error(`[Request ${id}] Problem with request: ${e.message}`);
      reject(e);
    });

    req.end();
  });
}

async function demonstrateKeepAlive() {
  console.log('Demonstrating HTTP keep-alive with forever-agent...');
  await makeKeepAliveRequest(1);
  await makeKeepAliveRequest(2);
  await makeKeepAliveRequest(3);
  console.log('Multiple requests sent. Check console for repeated socket local ports to confirm keep-alive.');
}

demonstrateKeepAlive();

view raw JSON →