1 | proxy-agent
|
2 | ===========
|
3 | ### Maps proxy protocols to `http.Agent` implementations
|
4 | [![Build Status](https://travis-ci.org/TooTallNate/node-proxy-agent.svg?branch=master)](https://travis-ci.org/TooTallNate/node-proxy-agent)
|
5 |
|
6 | This module provides a function that returns proxying `http.Agent` instances to
|
7 | use based off of a given proxy URI.
|
8 |
|
9 | An LRU cache is used so that `http.Agent` instances are transparently re-used for
|
10 | subsequent HTTP requests to the same proxy server.
|
11 |
|
12 | The currently implemented protocol mappings are listed in the table below:
|
13 |
|
14 |
|
15 | | Protocol | Proxy Agent for `http` requests | Proxy Agent for `https` requests | Example
|
16 | |:----------:|:-------------------------------:|:--------------------------------:|:--------:
|
17 | | `http` | [http-proxy-agent][] | [https-proxy-agent][] | `http://proxy-server-over-tcp.com:3128`
|
18 | | `https` | [http-proxy-agent][] | [https-proxy-agent][] | `https://proxy-server-over-tls.com:3129`
|
19 | | `socks(v5)`| [socks-proxy-agent][] | [socks-proxy-agent][] | `socks://username:password@some-socks-proxy.com:9050` (username & password are optional)
|
20 | | `socks5` | [socks-proxy-agent][] | [socks-proxy-agent][] | `socks5://username:password@some-socks-proxy.com:9050` (username & password are optional)
|
21 | | `socks4` | [socks-proxy-agent][] | [socks-proxy-agent][] | `socks4://some-socks-proxy.com:9050`
|
22 | | `pac` | [pac-proxy-agent][] | [pac-proxy-agent][] | `pac+http://www.example.com/proxy.pac`
|
23 |
|
24 |
|
25 | Installation
|
26 | ------------
|
27 |
|
28 | Install with `npm`:
|
29 |
|
30 | ``` bash
|
31 | $ npm install proxy-agent
|
32 | ```
|
33 |
|
34 |
|
35 | Example
|
36 | -------
|
37 |
|
38 | ``` js
|
39 | var http = require('http');
|
40 | var ProxyAgent = require('proxy-agent');
|
41 |
|
42 | // HTTP, HTTPS, or SOCKS proxy to use
|
43 | var proxyUri = process.env.http_proxy || 'http://168.63.43.102:3128';
|
44 |
|
45 | var opts = {
|
46 | method: 'GET',
|
47 | host: 'jsonip.org',
|
48 | path: '/',
|
49 | // this is the important part!
|
50 | agent: new ProxyAgent(proxyUri)
|
51 | };
|
52 |
|
53 | // the rest works just like any other normal HTTP request
|
54 | http.get(opts, onresponse);
|
55 |
|
56 | function onresponse (res) {
|
57 | console.log(res.statusCode, res.headers);
|
58 | res.pipe(process.stdout);
|
59 | }
|
60 | ```
|
61 |
|
62 |
|
63 | API
|
64 | ---
|
65 |
|
66 | ### new ProxyAgent(Object|String opts|uri)
|
67 |
|
68 | Returns an `http.Agent` instance based off of the given proxy `opts` or URI
|
69 | string. An LRU cache is used, so the same `http.Agent` instance will be
|
70 | returned if identical args are passed in.
|
71 |
|
72 |
|
73 | License
|
74 | -------
|
75 |
|
76 | (The MIT License)
|
77 |
|
78 | Copyright (c) 2013 Nathan Rajlich <nathan@tootallnate.net>
|
79 |
|
80 | Permission is hereby granted, free of charge, to any person obtaining
|
81 | a copy of this software and associated documentation files (the
|
82 | 'Software'), to deal in the Software without restriction, including
|
83 | without limitation the rights to use, copy, modify, merge, publish,
|
84 | distribute, sublicense, and/or sell copies of the Software, and to
|
85 | permit persons to whom the Software is furnished to do so, subject to
|
86 | the following conditions:
|
87 |
|
88 | The above copyright notice and this permission notice shall be
|
89 | included in all copies or substantial portions of the Software.
|
90 |
|
91 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
92 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
93 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
94 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
95 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
96 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
97 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
98 |
|
99 |
|
100 | [http-proxy-agent]: https://github.com/TooTallNate/node-http-proxy-agent
|
101 | [https-proxy-agent]: https://github.com/TooTallNate/node-https-proxy-agent
|
102 | [socks-proxy-agent]: https://github.com/TooTallNate/node-socks-proxy-agent
|
103 | [pac-proxy-agent]: https://github.com/TooTallNate/node-pac-proxy-agent
|