Node.js HTTP/HTTPS Tunneling Agent

Common errors

• TypeError: tunnelingAgent.addRequest is not a function

  cause This error occurs because internal APIs of Node.js's `http.Agent` and `https.Agent` classes changed significantly after the versions supported by the `tunnel` package (<=0.7.x). Modern Node.js versions do not expose or expect the `addRequest` method in the same way.
  fix This package is incompatible with modern Node.js. Use an alternative like `https-proxy-agent` which is actively maintained and designed for current Node.js versions.

• Error: Cannot find module 'tunnel'

  cause This typically indicates the package is not installed, or npm failed to install it correctly due to compatibility issues with your Node.js version, or the package entry on the registry might be broken for older versions.
  fix First, ensure `npm install tunnel` completes successfully. If not, it reinforces that the package is too old or broken. The recommended fix is to abandon this package and use a modern, actively maintained proxy agent library.

Warnings

• breaking The `tunnel` package is abandoned and last updated in 2014. It explicitly targets Node.js versions `<=0.7.x` and is incompatible with all modern Node.js versions (>=1.0.0), leading to runtime errors.
  Fix: Do not use this package. Migrate to actively maintained alternatives such as `https-proxy-agent` or `socks-proxy-agent`.
• breaking Due to its abandonment, this package has not received any security updates. It may contain unpatched vulnerabilities related to network communication, proxy handling, or certificate validation, posing significant security risks.
  Fix: Immediately cease use of this package in production. Replace it with a well-maintained, modern proxy agent library.
• gotcha The API for `http.Agent` and `https.Agent` has evolved significantly since Node.js 0.7.x. Attempting to use `tunnel` with newer Node.js versions will result in `TypeError`s or unexpected behavior due to incompatible method signatures and internal changes.
  Fix: This package cannot be made compatible with modern Node.js. Use contemporary libraries designed for current Node.js APIs.

Install

• npm install tunnel npm
• yarn add tunnel yarn
• pnpm add tunnel pnpm

Imports

• tunnel
  wrong:

  import tunnel from 'tunnel';

  correct:

  const tunnel = require('tunnel');

  This package exclusively uses CommonJS `require` syntax as it predates widespread Node.js ESM adoption. The `tunnel` variable will hold an object containing the agent creation functions.
• httpsOverHttp
  wrong:

  import { httpsOverHttp } from 'tunnel';

  correct:

  const { httpsOverHttp } = require('tunnel');

  While CommonJS, direct destructuring of properties like `httpsOverHttp` might not have been a common or reliable pattern in Node.js versions targeted by this package. It's safer to access via `tunnel.httpsOverHttp`.

Quickstart

This example demonstrates how to create an `httpsOverHttp` tunneling agent and use it with `https.request` to make a secure HTTP request through an HTTP proxy. It highlights the basic configuration for the proxy settings and includes error handling.

const tunnel = require('tunnel');
const https = require('https');

const tunnelingAgent = tunnel.httpsOverHttp({
  proxy: {
    host: 'localhost',
    port: 3128,
    proxyAuth: process.env.PROXY_AUTH ?? '', // Example: 'user:password'
    headers: {
      'User-Agent': 'Node.js Tunnel Example'
    }
  }
});

const options = {
  host: 'example.com',
  port: 443,
  agent: tunnelingAgent,
  path: '/',
  method: 'GET'
};

const req = https.request(options, (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    console.log(`BODY: ${chunk}`);
  });
  res.on('end', () => {
    console.log('No more data in response.');
  });
});

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

req.end();