1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
[](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.
|
