Configures the global
http
and
https
agents to use an upstream HTTP proxy.
Works transparently to tunnel modules that use node's default http.request()
method
as well as the popular request
module.
To make all HTTP and HTTPS connections go through an outbound HTTP proxy:
var globalTunnel = require('global-tunnel');
globalTunnel.initialize({
host: '10.0.0.10',
port: 8080,
sockets: 50 // optional pool size for each http and https
});
This will use the CONNECT
method for HTTPS requests and absolute-URIs for
HTTP requests, which is how many network proxies are configured.
Optionally, to tear-down the global agent and restore node's default global agents:
globalTunnel.end();
Any active connections will be allowed to run to completion, but new connections will use the default global agents.
The complete list of options to globalTunnel.initialize
:
- host - the hostname or IP of the HTTP proxy to use
- port - the TCP port to use on that proxy
- connect (optional) controls what protocols use the
CONNECT
method. It has three possible values (strings):- neither - don't use
CONNECT
; just use absolute URIs - https - (the default) only use
CONNECT
for HTTPS requests - both - use
CONNECT
for both HTTP and HTTPS requests
- neither - don't use
- protocol - the protocol that the proxy speaks, either
http:
orhttps:
. - sockets - (optional) maximum number of TCP sockets to use in each pool. There are two pools: one for HTTP and one for HTTPS. Uses node's default (5) if falsy.
- proxyAuth - (optional) a string to use for Basic HTTP authentication.
This gets base64-encoded then sent as part of the standard
Proxy-Authorization
header onCONNECT
requests. Typically, this is of the formusername:password
.
Here's a few interesting variations on the basic config.
Another common proxy configuration is one that expects clients to use an absolute URI for the Request-URI for all HTTP and HTTPS requests. This is common for networks that use a proxy for security scanning and access control.
What does this mean? It means that instead of ...
GET / HTTP/1.1
Host: example.com
... your proxy expects ...
GET https://example.com/ HTTP/1.1
You'll need to specify tunnel: 'neither'
if this is the case. If the proxy
speaks HTTP (i.e. the connection from node --> proxy is not encrypted):
globalTunnel.initialize({
tunnel: 'neither',
host: '10.0.0.10',
port: 3128
});
or, if the proxy speaks HTTPS to your app instead:
globalTunnel.initialize({
tunnel: 'neither',
protocol: 'https:'
host: '10.0.0.10',
port: 3129
});
If the proxy expects you to use the CONNECT
method for both HTTP and HTTPS
requests, you'll need the tunnel: 'both'
option.
What does this mean? It means that instead of ...
GET https://example.com/ HTTP/1.1
... your proxy expects ...
CONNECT example.com:443 HTTP/1.1
Be sure to set the protocol:
option based on what protocol the proxy speaks.
globalTunnel.initialize({
tunnel: 'both',
host: '10.0.0.10',
port: 3130
});
EXPERIMENTAL
If tunnelling both protocols, you can use different HTTPS client configurations for the two phases of the connection.
globalTunnel.initialize({
tunnel: 'both',
protocol: 'https:'
host: '10.0.0.10',
port: 3130,
proxyHttpsConfig: {
// use this config for app -> proxy
},
originHttpsConfig: {
// use this config for proxy -> origin
}
});
The http_proxy
environment variable will be used if the first parameter to
globalTunnel.initialize
is null or an empty object.
process.env.http_proxy = 'http://10.0.0.1:3129';
globalTunnel.initialize();
Any module that doesn't specify an explicit agent:
option to
http.request
will also work with global-tunnel.
The unit tests for this module verify that the popular request
module works with global-tunnel active.
For untested modules, it's recommended that you load and initialize
global-tunnel first. This way, any copies of http.globalAgent
will point to
the right thing.
If you'd like to contribute to or modify global-tunnel, here's a quick guide to get you started.
- node.js >= 0.10
Download via GitHub and install npm dependencies:
git clone git@github.com:goinstant/global-tunnel.git
cd global-tunnel
npm install
Testing is with the mocha framework.
Tests are located in the test/
directory.
To run the tests:
npm test
Email GoInstant Support or stop by #goinstant on freenode.
For responsible disclosures, email GoInstant Security.
To file a bug or propose a patch, please use github directly.
© 2014 GoInstant Inc., a salesforce.com company
Licensed under the BSD 3-clause license.