1 | # proxy-from-env
|
---|
2 |
|
---|
3 | [![Build Status](https://travis-ci.org/Rob--W/proxy-from-env.svg?branch=master)](https://travis-ci.org/Rob--W/proxy-from-env)
|
---|
4 | [![Coverage Status](https://coveralls.io/repos/github/Rob--W/proxy-from-env/badge.svg?branch=master)](https://coveralls.io/github/Rob--W/proxy-from-env?branch=master)
|
---|
5 |
|
---|
6 | `proxy-from-env` is a Node.js package that exports a function (`getProxyForUrl`)
|
---|
7 | that takes an input URL (a string or
|
---|
8 | [`url.parse`](https://nodejs.org/docs/latest/api/url.html#url_url_parsing)'s
|
---|
9 | return value) and returns the desired proxy URL (also a string) based on
|
---|
10 | standard proxy environment variables. If no proxy is set, an empty string is
|
---|
11 | returned.
|
---|
12 |
|
---|
13 | It is your responsibility to actually proxy the request using the given URL.
|
---|
14 |
|
---|
15 | Installation:
|
---|
16 |
|
---|
17 | ```sh
|
---|
18 | npm install proxy-from-env
|
---|
19 | ```
|
---|
20 |
|
---|
21 | ## Example
|
---|
22 | This example shows how the data for a URL can be fetched via the
|
---|
23 | [`http` module](https://nodejs.org/api/http.html), in a proxy-aware way.
|
---|
24 |
|
---|
25 | ```javascript
|
---|
26 | var http = require('http');
|
---|
27 | var parseUrl = require('url').parse;
|
---|
28 | var getProxyForUrl = require('proxy-from-env').getProxyForUrl;
|
---|
29 |
|
---|
30 | var some_url = 'http://example.com/something';
|
---|
31 |
|
---|
32 | // // Example, if there is a proxy server at 10.0.0.1:1234, then setting the
|
---|
33 | // // http_proxy environment variable causes the request to go through a proxy.
|
---|
34 | // process.env.http_proxy = 'http://10.0.0.1:1234';
|
---|
35 | //
|
---|
36 | // // But if the host to be proxied is listed in NO_PROXY, then the request is
|
---|
37 | // // not proxied (but a direct request is made).
|
---|
38 | // process.env.no_proxy = 'example.com';
|
---|
39 |
|
---|
40 | var proxy_url = getProxyForUrl(some_url); // <-- Our magic.
|
---|
41 | if (proxy_url) {
|
---|
42 | // Should be proxied through proxy_url.
|
---|
43 | var parsed_some_url = parseUrl(some_url);
|
---|
44 | var parsed_proxy_url = parseUrl(proxy_url);
|
---|
45 | // A HTTP proxy is quite simple. It is similar to a normal request, except the
|
---|
46 | // path is an absolute URL, and the proxied URL's host is put in the header
|
---|
47 | // instead of the server's actual host.
|
---|
48 | httpOptions = {
|
---|
49 | protocol: parsed_proxy_url.protocol,
|
---|
50 | hostname: parsed_proxy_url.hostname,
|
---|
51 | port: parsed_proxy_url.port,
|
---|
52 | path: parsed_some_url.href,
|
---|
53 | headers: {
|
---|
54 | Host: parsed_some_url.host, // = host name + optional port.
|
---|
55 | },
|
---|
56 | };
|
---|
57 | } else {
|
---|
58 | // Direct request.
|
---|
59 | httpOptions = some_url;
|
---|
60 | }
|
---|
61 | http.get(httpOptions, function(res) {
|
---|
62 | var responses = [];
|
---|
63 | res.on('data', function(chunk) { responses.push(chunk); });
|
---|
64 | res.on('end', function() { console.log(responses.join('')); });
|
---|
65 | });
|
---|
66 |
|
---|
67 | ```
|
---|
68 |
|
---|
69 | ## Environment variables
|
---|
70 | The environment variables can be specified in lowercase or uppercase, with the
|
---|
71 | lowercase name having precedence over the uppercase variant. A variable that is
|
---|
72 | not set has the same meaning as a variable that is set but has no value.
|
---|
73 |
|
---|
74 | ### NO\_PROXY
|
---|
75 |
|
---|
76 | `NO_PROXY` is a list of host names (optionally with a port). If the input URL
|
---|
77 | matches any of the entries in `NO_PROXY`, then the input URL should be fetched
|
---|
78 | by a direct request (i.e. without a proxy).
|
---|
79 |
|
---|
80 | Matching follows the following rules:
|
---|
81 |
|
---|
82 | - `NO_PROXY=*` disables all proxies.
|
---|
83 | - Space and commas may be used to separate the entries in the `NO_PROXY` list.
|
---|
84 | - If `NO_PROXY` does not contain any entries, then proxies are never disabled.
|
---|
85 | - If a port is added after the host name, then the ports must match. If the URL
|
---|
86 | does not have an explicit port name, the protocol's default port is used.
|
---|
87 | - Generally, the proxy is only disabled if the host name is an exact match for
|
---|
88 | an entry in the `NO_PROXY` list. The only exceptions are entries that start
|
---|
89 | with a dot or with a wildcard; then the proxy is disabled if the host name
|
---|
90 | ends with the entry.
|
---|
91 |
|
---|
92 | See `test.js` for examples of what should match and what does not.
|
---|
93 |
|
---|
94 | ### \*\_PROXY
|
---|
95 |
|
---|
96 | The environment variable used for the proxy depends on the protocol of the URL.
|
---|
97 | For example, `https://example.com` uses the "https" protocol, and therefore the
|
---|
98 | proxy to be used is `HTTPS_PROXY` (_NOT_ `HTTP_PROXY`, which is _only_ used for
|
---|
99 | http:-URLs).
|
---|
100 |
|
---|
101 | The library is not limited to http(s), other schemes such as
|
---|
102 | `FTP_PROXY` (ftp:),
|
---|
103 | `WSS_PROXY` (wss:),
|
---|
104 | `WS_PROXY` (ws:)
|
---|
105 | are also supported.
|
---|
106 |
|
---|
107 | If present, `ALL_PROXY` is used as fallback if there is no other match.
|
---|
108 |
|
---|
109 |
|
---|
110 | ## External resources
|
---|
111 | The exact way of parsing the environment variables is not codified in any
|
---|
112 | standard. This library is designed to be compatible with formats as expected by
|
---|
113 | existing software.
|
---|
114 | The following resources were used to determine the desired behavior:
|
---|
115 |
|
---|
116 | - cURL:
|
---|
117 | https://curl.haxx.se/docs/manpage.html#ENVIRONMENT
|
---|
118 | https://github.com/curl/curl/blob/4af40b3646d3b09f68e419f7ca866ff395d1f897/lib/url.c#L4446-L4514
|
---|
119 | https://github.com/curl/curl/blob/4af40b3646d3b09f68e419f7ca866ff395d1f897/lib/url.c#L4608-L4638
|
---|
120 |
|
---|
121 | - wget:
|
---|
122 | https://www.gnu.org/software/wget/manual/wget.html#Proxies
|
---|
123 | http://git.savannah.gnu.org/cgit/wget.git/tree/src/init.c?id=636a5f9a1c508aa39e35a3a8e9e54520a284d93d#n383
|
---|
124 | http://git.savannah.gnu.org/cgit/wget.git/tree/src/retr.c?id=93c1517c4071c4288ba5a4b038e7634e4c6b5482#n1278
|
---|
125 |
|
---|
126 | - W3:
|
---|
127 | https://www.w3.org/Daemon/User/Proxies/ProxyClients.html
|
---|
128 |
|
---|
129 | - Python's urllib:
|
---|
130 | https://github.com/python/cpython/blob/936135bb97fe04223aa30ca6e98eac8f3ed6b349/Lib/urllib/request.py#L755-L782
|
---|
131 | https://github.com/python/cpython/blob/936135bb97fe04223aa30ca6e98eac8f3ed6b349/Lib/urllib/request.py#L2444-L2479
|
---|