Registry / http-networking / global-tunnel-ng

global-tunnel-ng

JSON →
library2.7.1jsnpmunverified

global-tunnel-ng is a utility that globally configures Node.js's built-in `http` and `https` agents to route all outgoing network traffic through an upstream HTTP proxy. It works transparently for modules that utilize Node's default `http.request()` method and popular libraries like `request`. The current stable version is 2.7.1, published in November 2018. The package focuses on transparent global proxying, allowing developers to set a proxy once for an entire application without modifying individual HTTP client calls. It supports both `CONNECT` tunneling for HTTPS (and optionally HTTP) and absolute-URI request methods, accommodating various proxy configurations. Its primary differentiator is its low-level global interception of Node.js's native networking stack. For modern Node.js versions (v10+), `global-agent` is often recommended as a more actively maintained alternative.

npm install global-tunnel-ng
INSTALL
IMPORT
SIG · GLOBAL-TUNNEL-NG
G
global-tunnel-ng
http-networkingjavascriptv2.7.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

globalTunnel
const globalTunnel = require('global-tunnel-ng');
import globalTunnel from '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.

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(); });
Debug
Known issues
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.
affects: >=11.6.0
gotchaThe `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.
affects: >=2.0.0
gotchaModifying 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.
affects: >=2.0.0
deprecatedThis 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.
affects: All versions
Errors
Common errors & fixes
Error: tunneling socket could not be established
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
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.
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`.
Upgrade
Version history
2.7.1latest on npm
Audit
Dependencies
tunnel-agentrequiredCore dependency for managing HTTP proxy tunneling agents; internal to global-tunnel-ng's operation.
Agent activity
4 hits · last 30 days
node
4
Resources
global-tunnel-ng — npm install global-tunnel-ng · libregistry