1 | proxy-agent
|
2 | ===========
|
3 | ### Maps proxy protocols to `http.Agent` implementations
|
4 |
|
5 | This module provides an `http.Agent` implementation which automatically uses
|
6 | proxy servers based off of the various proxy-related environment variables
|
7 | (`HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` among others).
|
8 |
|
9 | Which proxy is used for each HTTP request is determined by the
|
10 | [`proxy-from-env`](https://www.npmjs.com/package/proxy-from-env) module, so
|
11 | check its documentation for instructions on configuring your environment variables.
|
12 |
|
13 | An LRU cache is used so that `http.Agent` instances are transparently re-used for
|
14 | subsequent HTTP requests to the same proxy server.
|
15 |
|
16 | The currently implemented protocol mappings are listed in the table below:
|
17 |
|
18 |
|
19 | | Protocol | Proxy Agent for `http` requests | Proxy Agent for `https` requests | Example
|
20 | |:----------:|:-------------------------------:|:--------------------------------:|:--------:
|
21 | | `http` | [http-proxy-agent][] | [https-proxy-agent][] | `http://proxy-server-over-tcp.com:3128`
|
22 | | `https` | [http-proxy-agent][] | [https-proxy-agent][] | `https://proxy-server-over-tls.com:3129`
|
23 | | `socks(v5)`| [socks-proxy-agent][] | [socks-proxy-agent][] | `socks://username:password@some-socks-proxy.com:9050` (username & password are optional)
|
24 | | `socks5` | [socks-proxy-agent][] | [socks-proxy-agent][] | `socks5://username:password@some-socks-proxy.com:9050` (username & password are optional)
|
25 | | `socks4` | [socks-proxy-agent][] | [socks-proxy-agent][] | `socks4://some-socks-proxy.com:9050`
|
26 | | `pac-*` | [pac-proxy-agent][] | [pac-proxy-agent][] | `pac+http://www.example.com/proxy.pac`
|
27 |
|
28 | Example
|
29 | -------
|
30 |
|
31 | ```ts
|
32 | import * as https from 'https';
|
33 | import { ProxyAgent } from 'proxy-agent';
|
34 |
|
35 | // The correct proxy `Agent` implementation to use will be determined
|
36 | // via the `http_proxy` / `https_proxy` / `no_proxy` / etc. env vars
|
37 | const agent = new ProxyAgent();
|
38 |
|
39 | // The rest works just like any other normal HTTP request
|
40 | https.get('https://jsonip.com', { agent }, (res) => {
|
41 | console.log(res.statusCode, res.headers);
|
42 | res.pipe(process.stdout);
|
43 | });
|
44 | ```
|
45 |
|
46 |
|
47 | API
|
48 | ---
|
49 |
|
50 | ### new ProxyAgent(options?: ProxyAgentOptions)
|
51 |
|
52 | Creates an `http.Agent` instance which relies on the various proxy-related
|
53 | environment variables. An LRU cache is used, so the same `http.Agent` instance
|
54 | will be returned if identical args are passed in.
|
55 |
|
56 |
|
57 | License
|
58 | -------
|
59 |
|
60 | (The MIT License)
|
61 |
|
62 | Copyright (c) 2013 Nathan Rajlich <nathan@tootallnate.net>
|
63 |
|
64 | Permission is hereby granted, free of charge, to any person obtaining
|
65 | a copy of this software and associated documentation files (the
|
66 | 'Software'), to deal in the Software without restriction, including
|
67 | without limitation the rights to use, copy, modify, merge, publish,
|
68 | distribute, sublicense, and/or sell copies of the Software, and to
|
69 | permit persons to whom the Software is furnished to do so, subject to
|
70 | the following conditions:
|
71 |
|
72 | The above copyright notice and this permission notice shall be
|
73 | included in all copies or substantial portions of the Software.
|
74 |
|
75 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
76 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
77 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
78 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
79 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
80 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
81 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
82 |
|
83 |
|
84 | [http-proxy-agent]: ../http-proxy-agent
|
85 | [https-proxy-agent]: ../https-proxy-agent
|
86 | [socks-proxy-agent]: ../socks-proxy-agent
|
87 | [pac-proxy-agent]: ../pac-proxy-agent
|