HTTP Proxy Tunneling Agent

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... from ... not supported.

  cause Attempting to use `require()` in an ES Module context or `import` in a CommonJS context for a package that only supports the other.
  fix Ensure your file is a CommonJS module (`.js` without `"type": "module"` in `package.json` or explicitly `.cjs` extension) and use `const tunnel = require('tunnel-agent');`. If your project is ESM-only, a direct `import tunnel from 'tunnel-agent'` might work as Node.js CJS-ESM interop, but it's generally unstable for abandoned packages.

• TypeError: tunnel.httpOverHttp is not a function

  cause The `tunnel-agent` module was not correctly loaded, or `tunnel` is not the expected object.
  fix Verify that `tunnel-agent` is installed (`npm list tunnel-agent`). Ensure `const tunnel = require('tunnel-agent');` is the first interaction with the module. This error can also happen if attempting to use a default import in ESM where only named exports exist (which is not the case for this CJS module).

Warnings

• breaking This package is effectively abandoned. Its last update was over nine years ago (v0.6.0, March 2017). Using unmaintained software can lead to severe security vulnerabilities, compatibility issues with newer Node.js versions, and lack of support for modern web standards.
  Fix: Migrate to a actively maintained HTTP tunneling library like `proxy-agent`, `@fastify/http-proxy`, or `https-proxy-agent`. Ensure your chosen alternative is regularly updated and has a strong security posture.
• gotcha Older versions of `tunnel-agent` (specifically v0.4.3) have known security vulnerabilities related to 'Uninitialized Memory Exposure' when used with `request/request`. Although v0.6.0 is newer, the unmaintained status means no new vulnerabilities will be patched, posing significant risk.
  Fix: Avoid using `tunnel-agent` entirely. If migration is not immediately possible, thoroughly audit any indirect dependencies that might pull in vulnerable older versions. Scan your project with tools like Snyk or npm audit.
• gotcha As a legacy CommonJS module, `tunnel-agent` does not officially support ES Modules (ESM) `import` syntax. Attempting to use `import` without proper tooling (like Babel) or Node.js's interop features (which can be fragile for older CJS modules) will result in runtime errors.
  Fix: Always use `const tunnel = require('tunnel-agent');` when integrating `tunnel-agent` into your Node.js application. If your project is pure ESM, consider rewriting the functionality or finding an ESM-native alternative.
• gotcha The functionality of `tunnel-agent` only covers basic HTTP/HTTPS over HTTP proxies. It does not natively support advanced proxy authentication mechanisms (beyond basic `proxyAuth` string), SOCKS proxies, or more complex tunneling scenarios without external libraries or significant manual implementation.
  Fix: For SOCKS proxy support or more robust authentication, you will need to integrate additional specialized proxy agents. For modern and flexible proxying, consider libraries that offer broader protocol and authentication support out-of-the-box.

Install

• npm install tunnel-agent npm
• yarn add tunnel-agent yarn
• pnpm add tunnel-agent pnpm

Imports

• agent
  wrong:

  import tunnel from 'tunnel-agent';

  correct:

  const tunnel = require('tunnel-agent');
  const agent = tunnel.httpOverHttp({ /* options */ });

  This package is a CommonJS module. Direct ESM `import` statements are not supported without a transpiler or Node.js's native ESM interop (e.g., `import tunnel from 'tunnel-agent/index.js'`) and are generally not recommended for unmaintained CJS libraries.
• httpsOverHttp

  const tunnel = require('tunnel-agent');
  const agent = tunnel.httpsOverHttp({ proxy: { host: 'proxy.example.com', port: 8080 } });

  Used for tunneling HTTPS traffic over an HTTP proxy. Most common use case.
• httpOverHttp

  const tunnel = require('tunnel-agent');
  const agent = tunnel.httpOverHttp({ proxy: { host: 'proxy.example.com', port: 8080 } });

  Used for tunneling HTTP traffic over an HTTP proxy.

Quickstart

Demonstrates how to configure and use `tunnel-agent` to make an HTTP request through an HTTP proxy. It uses environment variables for proxy configuration for security.

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

// Configure the tunneling agent to go through an HTTP proxy
const tunnelingAgent = tunnel.httpOverHttp({
  proxy: {
    host: process.env.HTTP_PROXY_HOST ?? '127.0.0.1',
    port: parseInt(process.env.HTTP_PROXY_PORT ?? '8080', 10),
    proxyAuth: process.env.HTTP_PROXY_AUTH ?? '' // Optional: 'user:password'
  }
});

// Options for the actual HTTP request
const requestOptions = {
  host: 'example.com',
  port: 80,
  path: '/',
  agent: tunnelingAgent,
  headers: {
    'User-Agent': 'tunnel-agent-example'
  }
};

// Make the request using the tunneling agent
const req = http.request(requestOptions, (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => {
    console.log('No more data in response.');
    // console.log(data); // Uncomment to see response body
  });
});

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

req.end();