# global-tunnel

Configures the [global
`http`](http://nodejs.org/docs/v0.10.24/api/all.html#all_http_globalagent) and
[`https`](http://nodejs.org/docs/v0.10.24/api/all.html#all_https_globalagent)
agents to use an upstream HTTP proxy.

[![Build Status](https://travis-ci.org/goinstant/global-tunnel.png)](https://travis-ci.org/goinstant/global-tunnel)

Works transparently to tunnel modules that use node's default [`http.request()`
method](http://nodejs.org/docs/v0.10.24/api/all.html#all_http_request_options_callback)
as well as the popular [`request` module](https://npmjs.org/package/request).

# Usage

To make all HTTP and HTTPS connections go through an outbound HTTP proxy:

```js
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:

```js
globalTunnel.end();
```

Any active connections will be allowed to run to completion, but new
connections will use the default global agents.

# Advanced Usage

## Options

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
- **tunnel** _(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
- **protocol** - the protocol that the proxy speaks, either `http:` or `https:`.
- **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.

## Variations

Here's a few interesting variations on the basic config.

### Absolute URI Proxies

Another common proxy configuration is one that expects clients to use an
[absolute URI for the
Request-URI](https://tools.ietf.org/html/rfc2616#section-5.1.2) 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 ...

```http
GET / HTTP/1.1
Host: example.com
```

... your proxy expects ...

```http
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):

```js
globalTunnel.initialize({
  tunnel: 'neither',
  host: '10.0.0.10',
  port: 3128
});
```

or, if the proxy speaks HTTPS to your app instead:

```js
globalTunnel.initialize({
  tunnel: 'neither',
  protocol: 'https:'
  host: '10.0.0.10',
  port: 3129
});
```

### Always-CONNECT Proxies

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 ...

```http
GET https://example.com/ HTTP/1.1
```

... your proxy expects ...

```http
CONNECT example.com:443 HTTP/1.1
```

Be sure to set the `protocol:` option based on what protocol the proxy speaks.

```js
globalTunnel.initialize({
  tunnel: 'both',
  host: '10.0.0.10',
  port: 3130
});
```

### HTTPS configuration

_EXPERIMENTAL_

If tunnelling both protocols, you can use different HTTPS client configurations
for the two phases of the connection.

```js
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
  }
});
```

### Auto-Config

The `http_proxy` environment variable will be used if the first parameter to
`globalTunnel.initialize` is null or an empty object.

```js
process.env.http_proxy = 'http://10.0.0.1:3129';
globalTunnel.initialize();
```

# Compatibility

Any module that doesn't specify [an explicit `agent:` option to
`http.request`](http://nodejs.org/docs/v0.10.24/api/all.html#all_http_request_options_callback)
will also work with global-tunnel.

The unit tests for this module verify that the popular [`request`
module](https://npmjs.org/package/request) 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.

# Contributing

If you'd like to contribute to or modify global-tunnel, here's a quick guide
to get you started.

## Development Dependencies

- [node.js](http://nodejs.org) >= 0.10

## Set-Up

Download via GitHub and install npm dependencies:

```sh
git clone git@github.com:goinstant/global-tunnel.git
cd global-tunnel
npm install
```

## Testing

Testing is with the [mocha](https://github.com/visionmedia/mocha) framework.
Tests are located in the `test/` directory.

To run the tests:

```sh
npm test
```

# Support

Email [GoInstant Support](mailto:support@goinstant.com) or stop by [#goinstant on freenode](irc://irc.freenode.net#goinstant).

For responsible disclosures, email [GoInstant Security](mailto:security@goinstant.com).

To [file a bug](https://github.com/goinstant/global-tunnel/issues) or
[propose a patch](https://github.com/goinstant/global-tunnel/pulls),
please use github directly.

# Legal

&copy; 2014 GoInstant Inc., a salesforce.com company

Licensed under the BSD 3-clause license.
