1 | https-proxy-agent
|
2 | ================
|
3 | ### An HTTP(s) proxy `http.Agent` implementation for HTTPS
|
4 | [![Build Status](https://travis-ci.org/TooTallNate/node-https-proxy-agent.png?branch=master)](https://travis-ci.org/TooTallNate/node-https-proxy-agent)
|
5 |
|
6 | This module provides an `http.Agent` implementation that connects to a specified
|
7 | HTTP or HTTPS proxy server, and can be used with the built-in `https` module.
|
8 |
|
9 | Specifically, this `Agent` implementation connects to an intermediary "proxy"
|
10 | server and issues the [CONNECT HTTP method][CONNECT], which tells the proxy to
|
11 | open a direct TCP connection to the destination server.
|
12 |
|
13 | Since this agent implements the CONNECT HTTP method, it also works with other
|
14 | protocols that use this method when connecting over proxies (i.e. WebSockets).
|
15 | See the "Examples" section below for more.
|
16 |
|
17 |
|
18 | Installation
|
19 | ------------
|
20 |
|
21 | Install with `npm`:
|
22 |
|
23 | ``` bash
|
24 | $ npm install https-proxy-agent
|
25 | ```
|
26 |
|
27 |
|
28 | Examples
|
29 | --------
|
30 |
|
31 | #### `https` module example
|
32 |
|
33 | ``` js
|
34 | var url = require('url');
|
35 | var https = require('https');
|
36 | var HttpsProxyAgent = require('https-proxy-agent');
|
37 |
|
38 | // HTTP/HTTPS proxy to connect to
|
39 | var proxy = process.env.http_proxy || 'http://168.63.76.32:3128';
|
40 | console.log('using proxy server %j', proxy);
|
41 |
|
42 | // HTTPS endpoint for the proxy to connect to
|
43 | var endpoint = process.argv[2] || 'https://graph.facebook.com/tootallnate';
|
44 | console.log('attempting to GET %j', endpoint);
|
45 | var opts = url.parse(endpoint);
|
46 |
|
47 | // create an instance of the `HttpsProxyAgent` class with the proxy server information
|
48 | var agent = new HttpsProxyAgent(proxy);
|
49 | opts.agent = agent;
|
50 |
|
51 | https.get(opts, function (res) {
|
52 | console.log('"response" event!', res.headers);
|
53 | res.pipe(process.stdout);
|
54 | });
|
55 | ```
|
56 |
|
57 | #### `ws` WebSocket connection example
|
58 |
|
59 | ``` js
|
60 | var url = require('url');
|
61 | var WebSocket = require('ws');
|
62 | var HttpsProxyAgent = require('https-proxy-agent');
|
63 |
|
64 | // HTTP/HTTPS proxy to connect to
|
65 | var proxy = process.env.http_proxy || 'http://168.63.76.32:3128';
|
66 | console.log('using proxy server %j', proxy);
|
67 |
|
68 | // WebSocket endpoint for the proxy to connect to
|
69 | var endpoint = process.argv[2] || 'ws://echo.websocket.org';
|
70 | var parsed = url.parse(endpoint);
|
71 | console.log('attempting to connect to WebSocket %j', endpoint);
|
72 |
|
73 | // create an instance of the `HttpsProxyAgent` class with the proxy server information
|
74 | var opts = url.parse(proxy);
|
75 |
|
76 | // IMPORTANT! Set the `secureEndpoint` option to `false` when connecting
|
77 | // over "ws://", but `true` when connecting over "wss://"
|
78 | opts.secureEndpoint = parsed.protocol ? parsed.protocol == 'wss:' : false;
|
79 |
|
80 | var agent = new HttpsProxyAgent(opts);
|
81 |
|
82 | // finally, initiate the WebSocket connection
|
83 | var socket = new WebSocket(endpoint, { agent: agent });
|
84 |
|
85 | socket.on('open', function () {
|
86 | console.log('"open" event!');
|
87 | socket.send('hello world');
|
88 | });
|
89 |
|
90 | socket.on('message', function (data, flags) {
|
91 | console.log('"message" event! %j %j', data, flags);
|
92 | socket.close();
|
93 | });
|
94 | ```
|
95 |
|
96 | API
|
97 | ---
|
98 |
|
99 | ### new HttpsProxyAgent(opts)
|
100 |
|
101 | The `HttpsProxyAgent` class implements an `http.Agent` subclass that connects
|
102 | to the specified "HTTP(s) proxy server" in order to proxy HTTPS and/or WebSocket
|
103 | requests. This is achieved by using the [HTTP `CONNECT` method][CONNECT].
|
104 |
|
105 | The `opts` argument may either be a string URI of the proxy server to use, or an
|
106 | "options" object with more specific properties:
|
107 |
|
108 | * `host` - String - Proxy host to connect to (may use `hostname` as well). Required.
|
109 | * `port` - Number - Proxy port to connect to. Required.
|
110 | * `secureProxy` - Boolean - If `true`, then use TLS to connect to the proxy. Defaults to `false`.
|
111 | * `secureEndpoint` - Boolean - If `true` then a TLS connection to the endpoint will be established on top of the proxy socket. Defaults to `true`.
|
112 | * Any other options given are passed to the `net.connect()`/`tls.connect()` functions.
|
113 |
|
114 |
|
115 | License
|
116 | -------
|
117 |
|
118 | (The MIT License)
|
119 |
|
120 | Copyright (c) 2013 Nathan Rajlich <nathan@tootallnate.net>
|
121 |
|
122 | Permission is hereby granted, free of charge, to any person obtaining
|
123 | a copy of this software and associated documentation files (the
|
124 | 'Software'), to deal in the Software without restriction, including
|
125 | without limitation the rights to use, copy, modify, merge, publish,
|
126 | distribute, sublicense, and/or sell copies of the Software, and to
|
127 | permit persons to whom the Software is furnished to do so, subject to
|
128 | the following conditions:
|
129 |
|
130 | The above copyright notice and this permission notice shall be
|
131 | included in all copies or substantial portions of the Software.
|
132 |
|
133 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
134 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
135 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
136 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
137 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
138 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
139 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
140 |
|
141 | [CONNECT]: http://en.wikipedia.org/wiki/HTTP_tunnel#HTTP_CONNECT_Tunneling
|