diff options
Diffstat (limited to 'node_modules/global-tunnel-ng/README.md')
| -rw-r--r-- | node_modules/global-tunnel-ng/README.md | 242 |
1 files changed, 0 insertions, 242 deletions
diff --git a/node_modules/global-tunnel-ng/README.md b/node_modules/global-tunnel-ng/README.md deleted file mode 100644 index 9363824..0000000 --- a/node_modules/global-tunnel-ng/README.md +++ /dev/null @@ -1,242 +0,0 @@ -[](https://david-dm.org/np-maintain/global-tunnel) -[](https://david-dm.org/np-maintain/global-tunnel?type=dev) -[](https://travis-ci.org/np-maintain/global-tunnel) [](https://greenkeeper.io/) - -# 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. - -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). - -# Installation - -You can install this package by just executing the following: - - npm install global-tunnel-ng - -# Usage - -To make all HTTP and HTTPS connections go through an outbound HTTP proxy: - -```js -var globalTunnel = require('global-tunnel-ng'); - -globalTunnel.initialize({ - host: '10.0.0.10', - port: 8080, - proxyAuth: 'userId:password', // optional authentication - 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 -- **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 -- **protocol** - the protocol that the proxy speaks, either `http:` or `https:`. -- **proxyAuth** - _(optional)_ to authenticate `userId:password` -- **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 `connect: 'neither'` if this is the case. If the proxy -speaks HTTP (i.e. the connection from node --> proxy is not encrypted): - -```js -globalTunnel.initialize({ - connect: 'neither', - host: '10.0.0.10', - port: 3128 -}); -``` - -or, if the proxy speaks HTTPS to your app instead: - -```js -globalTunnel.initialize({ - connect: '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 `connect: '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({ - connect: '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({ - connect: 'both', - protocol: 'https:' - host: '10.0.0.10', - port: 3130, - proxyHttpsOptions: { - // use this config for app -> proxy - }, - originHttpsOptions: { - // use this config for proxy -> origin - } -}); -``` - -## Auto-Config - -If `globalTunnel.initialize` doesnt receive a configuration as its first parameter the `http_proxys` and `http_proxy` environment variables will be used. - -If these are missing the npm configurations `https-proxy`, `http-proxy`, `proxy` will be used instead. - -If no environment variables or npm configurations are found nothing will be done. - -## Retrieving proxy URL, parsed config and proxy status - -As the module does some extra job determining the proxy (including parsing the environment variables) and does some normalization (like defaulting the protocol to `http:`) it may be useful to retrieve the proxy URL used by the module. - -The property `globalTunnel.proxyUrl` is the URL-formatted (including the optional basic auth if provided) proxy config currently in use. It is `null` if the proxy is not currently enabled. - -Similarly, the `globalTunnel.proxyConfig` contains the entire parsed and normalized config. - -The property `globalTunnel.isProxying` contains the information about whether the global proxy is on or off. - -# 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:np-maintain/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 - -As this is a hard fork, you may still contact the given contacts below. - -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/np-maintain/global-tunnel/issues) or -[propose a patch](https://github.com/np-maintain/global-tunnel/pulls), -please use github directly. - -# Legal - -© 2014 GoInstant Inc., a salesforce.com company - -Licensed under the BSD 3-clause license. |