HTTP Agent (Legacy)

0.1.2 verified Thu Apr 23 auth: no javascript abandoned

This package, `http-agent`, is a deprecated and abandoned Node.js library designed to perform sequences of HTTP requests. Last published 15 years ago (July 15, 2011) at version 0.1.2, it targeted very early Node.js environments (>= 0.2.0). It was built upon the now-deprecated `request` library, leveraging it to allow for simple or complex request sequences, including an iterator pattern for dynamic control flow during web crawling. Due to its extreme age and reliance on obsolete dependencies and Node.js versions, it is not suitable for modern applications. There is no active maintenance, nor a release cadence. Modern alternatives like `axios`, `node-fetch`, or Node.js's built-in `fetch` API are highly recommended for current projects, offering better performance, security, and promise-based APIs.

Common errors

error ERR_REQUIRE_ESM: require() of ES Module ... not supported ↓

cause Attempting to use `require()` in an ES Module context or `import` in a CommonJS context when `http-agent` is purely CJS.

fix

Ensure your file is a CommonJS module (e.g., by using .cjs extension or setting "type": "commonjs" in package.json for older Node.js versions) and use const Agent = require('http-agent');. Better yet, migrate to an ESM-compatible HTTP client.

error Error: Cannot find module 'request' ↓

cause `http-agent` depends on the `request` library, which may not be installed or might have compatibility issues with your Node.js version.

fix

First, try npm install request. If the error persists, it's a strong indicator of incompatibility. Migration to a modern HTTP client is the recommended solution.

error TypeError: Agent.create is not a function ↓

cause The `http-agent` module might not be correctly imported or resolved, or the `Agent` object is not the one expected.

fix

Verify that require('http-agent') successfully returns the module. Ensure you are calling Agent.create() and not attempting to instantiate Agent with new or calling create as a top-level function.

Warnings

breaking This package relies on extremely outdated Node.js versions (>= 0.2.0) and is incompatible with modern Node.js runtimes (e.g., v12+, v14+ due to N-API changes, v16+ due to OpenSSL 3 updates). It will likely fail to run or compile. ↓

fix Migrate to a modern HTTP client library like `axios`, `node-fetch`, or Node.js's built-in `fetch` API.

breaking The core `request` library, which `http-agent` is built upon, is deprecated and no longer maintained. This means `http-agent` inherits the same end-of-life status and potential for unpatched vulnerabilities. ↓

fix Replace `http-agent` with a currently maintained and secure HTTP client.

gotcha This package is purely CommonJS (CJS). Attempting to use `import ... from 'http-agent'` in an ES Module (ESM) context will cause a `SyntaxError` or `ERR_REQUIRE_ESM`. ↓

fix Use `const Agent = require('http-agent');` in CJS files. For ESM projects, migration to a modern ESM-compatible library is necessary.

gotcha The library primarily uses an event-emitter pattern for control flow, which can be less ergonomic and more prone to callback hell compared to modern Promise-based or async/await patterns found in contemporary HTTP clients. ↓

fix Consider re-implementing request sequencing with `async/await` and modern libraries for cleaner, more readable code.

breaking Due to its abandonment, `http-agent` has not received any security updates in over a decade. It likely contains unpatched vulnerabilities that could be exploited in production environments, making it unsafe for any active project. ↓

fix Discontinue use immediately and migrate to a secure, actively maintained alternative.

Install

npm install http-agent

yarn add http-agent

pnpm add http-agent

Imports

Agent
wrong
```
import Agent from 'http-agent';
```
correct
```
const Agent = require('http-agent');
```
This package is strictly CommonJS and does not support ES Modules. Attempting to use `import` will result in an error.

create

wrong

const agent = require('http-agent').create(...);

correct

const agent = Agent.create('host', ['path1', 'path2']);

The `create` method is a static method on the exported `Agent` class/constructor.

Quickstart

Demonstrates initializing an HTTP agent, defining a sequence of requests, and handling 'next' and 'stop' events.

const Agent = require('http-agent');

// Create an agent for a specific host and a sequence of paths
const agent = Agent.create('example.com', ['/', '/about', '/contact']);

// Add a listener for the 'next' event, which fires after each request
agent.addListener('next', function (err, agent) {
  if (err) {
    console.error(`Error visiting ${agent.url}: ${err.message}`);
    // Decide whether to stop or continue on error
    // agent.stop(); 
  } else {
    console.log(`Successfully visited ${agent.url}`);
    // Access response body: agent.body
    // Access response headers: agent.headers
    // Continue to the next URL in the sequence
    agent.next();
  }
});

// Add a listener for the 'stop' event, which fires when all URLs are visited or an error occurs
agent.addListener('stop', function (err, agent) {
  if (err) {
    console.error(`Agent stopped with an unhandled error: ${err.message}`);
  } else {
    console.log('Agent finished visiting all specified URLs.');
  }
});

// Start the agent to begin the sequence of requests
agent.start();

// Example of more complex usage (showing a POST request)
/*
const complexAgent = Agent.create('example.com', [{
  method: 'POST',
  path: '/submit',
  body: 'data=someValue',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
}]);
complexAgent.addListener('next', function(err, agent) {
  console.log('Complex request done:', agent.url, agent.body);
  agent.next();
});
complexAgent.start();
*/