# global-tunnel

> Global HTTP & HTTPS tunneling

Latest version **1.2.0** (published 2014-01-09) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install global-tunnel
pnpm add global-tunnel
yarn add global-tunnel
bun add global-tunnel
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2014-01-09 |
| First published | 2014-01-06 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | none |
| Module format | CommonJS |
| Node | 0.10.x |
| Dependencies | 2 |
| Known vulnerabilities | 0 (+5 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 48 |
| Author | GoInstant Inc., a salesforce.com company |
| Maintainers | goinstant |
| Keywords | http, https, tunnel, global |

## Links

- npm: https://www.npmjs.com/package/global-tunnel
- Repository: https://github.com/goinstant/global-tunnel
- Issues: https://github.com/goinstant/global-tunnel/issues
- npm.io page: https://npm.io/package/global-tunnel

## Dependencies (2)

- [lodash](https://npm.io/package/lodash.md) 1.3.1
- [tunnel](https://npm.io/package/tunnel.md) 0.0.2

## Recent versions

- 1.2.0 (latest) — 2014-01-09
- 1.1.0 — 2014-01-07
- 1.0.1 — 2014-01-06

## README

# 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

© 2014 GoInstant Inc., a salesforce.com company

Licensed under the BSD 3-clause license.

---
_Source: https://npm.io/package/global-tunnel · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._