Global HTTP & HTTPS Tunneling

Common errors

• Error: tunneling socket could not be established

  cause The proxy server rejected the CONNECT request, often due to incorrect proxy address/port, authentication failure, or network firewall rules.
  fix Verify the `host`, `port`, and `proxyAuth` options in `globalTunnel.initialize()`. Check network connectivity to the proxy. Ensure the proxy supports the `CONNECT` method for the requested protocol (HTTP/HTTPS) as configured by the `connect` option.

• TypeError: globalTunnel.initialize is not a function

  cause This typically occurs when attempting to use an ES module `import` syntax (`import globalTunnel from 'global-tunnel-ng';`) instead of the CommonJS `require` syntax (`const globalTunnel = require('global-tunnel-ng');`).
  fix Change your import statement to `const globalTunnel = require('global-tunnel-ng');` as `global-tunnel-ng` is a CommonJS module.

• Requests are not going through the configured proxy.

  cause This can happen if: 1) The Node.js version is incompatible (>=11.6.0). 2) Another module explicitly sets an `agent` option on its HTTP/HTTPS requests, bypassing the global agent. 3) The `connect` option in `initialize` is misconfigured for your proxy type. 4) The proxy configuration (host, port) is incorrect.
  fix 1) Check Node.js version; if >=11.6.0, switch to `global-agent`. 2) Ensure `global-tunnel-ng` is initialized before other modules that might manage agents. Check if affected modules allow configuring an explicit agent to `null` or `undefined` to force use of the global agent. 3) Review and adjust the `connect` option. 4) Double-check `host`, `port`, and `proxyAuth`.

Warnings

• breaking `global-tunnel-ng` is known to be broken and incompatible with Node.js versions 11.6.0 and above. It relies on internal Node.js mechanisms that changed in newer versions. For modern Node.js environments (v10+), consider using `global-agent` as an actively maintained alternative.
  Fix: For Node.js v11.6.0+, migrate to `global-agent` (e.g., `import 'global-agent/bootstrap';` and set `GLOBAL_AGENT_HTTP_PROXY` environment variable) or use a library-specific proxy configuration.
• gotcha The `connect` option within `globalTunnel.initialize()` is crucial and often misconfigured. It controls whether the `CONNECT` method is used for HTTP, HTTPS, or neither. The default is `https`, meaning `CONNECT` is only used for HTTPS. Incorrect configuration for your proxy type can lead to connection failures.
  Fix: Consult your proxy documentation. Use `connect: 'neither'` for proxies expecting absolute URIs for all requests, or `connect: 'both'` if the proxy expects `CONNECT` for both HTTP and HTTPS requests. The default `connect: 'https'` is suitable for many standard HTTP proxies.
• gotcha Modifying Node.js's global `http.globalAgent` and `https.globalAgent` can conflict with other libraries or custom code that also attempt to manage these global agents or instantiate their own specific `Agent` instances. This can lead to unexpected proxy bypasses or errors.
  Fix: Ensure `global-tunnel-ng` is initialized early in your application. If other modules explicitly define an `agent` option in their `http.request` calls, they will bypass `global-tunnel-ng`'s configuration. Consider using library-specific proxy settings or an alternative like `global-agent` which offers more explicit control and compatibility strategies.
• deprecated This package is considered for 'legacy Node.js versions' and is under `np-maintain`, indicating limited active development for new Node.js features or bug fixes. For modern applications and Node.js versions (v10 and above), the `global-agent` package is a recommended, more actively maintained alternative.
  Fix: For new projects or applications running on Node.js v10+, consider migrating to `global-agent`. It offers similar global proxying capabilities with better support for newer Node.js features and environment variable configuration.

Install

• npm install global-tunnel-ng npm
• yarn add global-tunnel-ng yarn
• pnpm add global-tunnel-ng pnpm

Imports

• globalTunnel
  wrong:

  import globalTunnel from 'global-tunnel-ng';

  correct:

  const globalTunnel = require('global-tunnel-ng');

  This package is CommonJS-only and does not support ES Modules directly. Use `require`.
• initialize

  globalTunnel.initialize({ /* options */ });

  The `initialize` method configures the global HTTP/HTTPS agents. It should be called once early in your application lifecycle.
• end

  globalTunnel.end();

  Call `end` to tear down the global agent and restore Node.js's default agents. Active connections complete first.

Quickstart

This quickstart initializes a global HTTP/HTTPS proxy using `global-tunnel-ng` and demonstrates how a standard Node.js `http.get` request automatically routes through it. It also shows how to tear down the proxy.

const globalTunnel = require('global-tunnel-ng');

// Configure a global HTTP/HTTPS proxy
globalTunnel.initialize({
  host: '10.0.0.10',
  port: 8080,
  proxyAuth: process.env.PROXY_USER_PASS ?? '', // optional authentication as 'userId:password'
  sockets: 50, // optional pool size for each http and https agent
  // For a proxy requiring absolute URIs for HTTP/HTTPS:
  // connect: 'neither',
  // For a proxy requiring CONNECT for both HTTP/HTTPS:
  // connect: 'both',
  // If the proxy itself speaks HTTPS:
  // protocol: 'https:'
});

// Example of an HTTP request that will go through the configured proxy
const http = require('http');

http.get('http://example.com/data', (res) => {
  console.log(`Status: ${res.statusCode}`);
  res.setEncoding('utf8');
  let rawData = '';
  res.on('data', (chunk) => { rawData += chunk; });
  res.on('end', () => {
    try {
      console.log('Received data:', rawData.substring(0, 100) + '...');
    } catch (e) {
      console.error(e.message);
    }
    globalTunnel.end(); // Clean up the proxy configuration
  });
}).on('error', (e) => {
  console.error(`Request error: ${e.message}`);
  globalTunnel.end();
});