Skip to content

Commit 0b642d4

Browse files
yawntyawnt
committed
Merge remote-tracking branch 'origin/caronte' into caronte-merge
2 parents a4ee8f9 + 2c8edc1 commit 0b642d4

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+3721
-0
lines changed

‎.gitignore

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
node_modules
2+
*.swp
3+
cov
4+
atest.js
5+
notes
6+
primus-proxy.js
7+
tes.js

‎.travis.yml

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
language: node_js
2+
node_js:
3+
- "0.10"
4+
- "0.11"
5+
6+
notifications:
7+
email:
8+
- [email protected]
9+
irc: "irc.freenode.org#nodejitsu"
10+
11+
script:
12+
npm test

‎CHANGELOG.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
### v 1.0.0-alpha
2+
3+
- Complete refactor with new API
4+

‎LICENSE

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
2+
node-http-proxy
3+
4+
Copyright (c) Nodejitsu 2013
5+
6+
Permission is hereby granted, free of charge, to any person obtaining
7+
a copy of this software and associated documentation files (the
8+
"Software"), to deal in the Software without restriction, including
9+
without limitation the rights to use, copy, modify, merge, publish,
10+
distribute, sublicense, and/or sell copies of the Software, and to
11+
permit persons to whom the Software is furnished to do so, subject to
12+
the following conditions:
13+
14+
The above copyright notice and this permission notice shall be
15+
included in all copies or substantial portions of the Software.
16+
17+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
21+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
22+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
23+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

+322
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,322 @@
1+
<p align="center">
2+
<img src="doc/logo.png?raw=true"/>
3+
</p>
4+
5+
node-http-proxy
6+
=======
7+
8+
`node-http-proxy` is an HTTP programmable proxying library that supports
9+
websockets. It is suitable for implementing components such as
10+
proxies and load balancers.
11+
12+
### Build Status
13+
14+
<p align="center">
15+
<a href="https://travis-ci.org/nodejitsu/node-http-proxy" target="_blank">
16+
<img src="https://travis-ci.org/nodejitsu/node-http-proxy.png?branch=caronte"/></a>&nbsp;&nbsp;
17+
<a href="https://coveralls.io/r/nodejitsu/node-http-proxy" target="_blank">
18+
<img src="https://coveralls.io/repos/nodejitsu/node-http-proxy/badge.png?branch=caronte"/></a>
19+
</p>
20+
21+
### Looking to Upgrade from 0.8.x ? Click [here](UPGRADING.md)
22+
23+
### Core Concept
24+
25+
A new proxy is created by calling `createProxyServer` and passing
26+
an `options` object as argument ([valid properties are available here](lib/http-proxy.js#L26-L39))
27+
28+
```javascript
29+
var httpProxy = require('http-proxy');
30+
31+
var proxy = httpProxy.createProxyServer(options);
32+
```
33+
34+
An object will be returned with four values:
35+
36+
* web `req, res, [options]` (used for proxying regular HTTP(S) requests)
37+
* ws `req, socket, head, [options]` (used for proxying WS(S) requests)
38+
* listen `port` (a function that wraps the object in a webserver, for your convenience)
39+
40+
Is it then possible to proxy requests by calling these functions
41+
42+
```javascript
43+
require('http').createServer(function(req, res) {
44+
proxy.web(req, res, { target: 'http://mytarget.com:8080' });
45+
});
46+
```
47+
48+
Errors can be listened on either using the Event Emitter API
49+
50+
```javascript
51+
proxy.on('error', function(e) {
52+
...
53+
});
54+
```
55+
56+
or using the callback API
57+
58+
```javascript
59+
proxy.web(req, res, { target: 'http://mytarget.com:8080' }, function(e) { ... });
60+
```
61+
62+
When a request is proxied it follows two different pipelines ([available here](lib/http-proxy/passes))
63+
which apply transformations to both the `req` and `res` object.
64+
The first pipeline (ingoing) is responsible for the creation and manipulation of the stream that connects your client to the target.
65+
The second pipeline (outgoing) is responsible for the creation and manipulation of the stream that, from your target, returns data
66+
to the client.
67+
68+
69+
#### Setup a basic stand-alone proxy server
70+
71+
```js
72+
var http = require('http'),
73+
httpProxy = require('http-proxy');
74+
//
75+
// Create your proxy server and set the target in the options.
76+
//
77+
httpProxy.createProxyServer({target:'http://localhost:9000'}).listen(8000);
78+
79+
//
80+
// Create your target server
81+
//
82+
http.createServer(function (req, res) {
83+
res.writeHead(200, { 'Content-Type': 'text/plain' });
84+
res.write('request successfully proxied!' + '\n' + JSON.stringify(req.headers, true, 2));
85+
res.end();
86+
}).listen(9000);
87+
```
88+
89+
#### Setup a stand-alone proxy server with custom server logic
90+
This example show how you can proxy a request using your own HTTP server
91+
and also you can put your own logic to handle the request.
92+
93+
```js
94+
var http = require('http'),
95+
httpProxy = require('http-proxy');
96+
97+
//
98+
// Create a proxy server with custom application logic
99+
//
100+
var proxy = httpProxy.createProxyServer({});
101+
102+
//
103+
// Create your custom server and just call `proxy.web()` to proxy
104+
// a web request to the target passed in the options
105+
// also you can use `proxy.ws()` to proxy a websockets request
106+
//
107+
var server = require('http').createServer(function(req, res) {
108+
// You can define here your custom logic to handle the request
109+
// and then proxy the request.
110+
proxy.web(req, res, { target: 'http://127.0.0.1:5060' });
111+
});
112+
113+
console.log("listening on port 5050")
114+
server.listen(5050);
115+
```
116+
117+
#### Setup a stand-alone proxy server with latency
118+
119+
```js
120+
var http = require('http'),
121+
httpProxy = require('http-proxy');
122+
123+
//
124+
// Create a proxy server with latency
125+
//
126+
var proxy = httpProxy.createProxyServer();
127+
128+
//
129+
// Create your server that make an operation that take a while
130+
// and then proxy de request
131+
//
132+
http.createServer(function (req, res) {
133+
// This simulate an operation that take 500ms in execute
134+
setTimeout(function () {
135+
proxy.web(req, res, {
136+
target: 'http://localhost:9008'
137+
});
138+
}, 500);
139+
}).listen(8008);
140+
141+
//
142+
// Create your target server
143+
//
144+
http.createServer(function (req, res) {
145+
res.writeHead(200, { 'Content-Type': 'text/plain' });
146+
res.write('request successfully proxied to: ' + req.url + '\n' + JSON.stringify(req.headers, true, 2));
147+
res.end();
148+
}).listen(9008);
149+
```
150+
151+
#### Listening for proxy events
152+
153+
* `error`: The error event is emitted if the request to the target fail.
154+
* `proxyRes`: This event is emitted if the request to the target got a response.
155+
156+
```js
157+
var httpProxy = require('http-proxy');
158+
// Error example
159+
//
160+
// Http Proxy Server with bad target
161+
//
162+
var proxy = httpProxy.createServer({
163+
target:'http://localhost:9005'
164+
});
165+
166+
proxy.listen(8005);
167+
168+
//
169+
// Listen for the `error` event on `proxy`.
170+
proxy.on('error', function (err, req, res) {
171+
res.writeHead(500, {
172+
'Content-Type': 'text/plain'
173+
});
174+
175+
res.end('Something went wrong. And we are reporting a custom error message.');
176+
});
177+
178+
//
179+
// Listen for the `proxyRes` event on `proxy`.
180+
//
181+
proxy.on('proxyRes', function (res) {
182+
console.log('RAW Response from the target', JSON.stringify(res.headers, true, 2));
183+
});
184+
185+
```
186+
187+
#### Using HTTPS
188+
You can activate the validation of a secure SSL certificate to the target connection (avoid self signed certs), just set `secure: true` in the options.
189+
190+
##### HTTPS -> HTTP
191+
192+
```js
193+
//
194+
// Create the HTTPS proxy server in front of a HTTP server
195+
//
196+
httpProxy.createServer({
197+
target: {
198+
host: 'localhost',
199+
port: 9009
200+
},
201+
ssl: {
202+
key: fs.readFileSync('valid-ssl-key.pem'), 'utf8'),
203+
cert: fs.readFileSync('valid-ssl-cert.pem'), 'utf8')
204+
}
205+
}).listen(8009);
206+
```
207+
208+
##### HTTPS -> HTTPS
209+
210+
```js
211+
//
212+
// Create the proxy server listening on port 443
213+
//
214+
httpProxy.createServer({
215+
ssl: {
216+
key: fs.readFileSync('valid-ssl-key.pem'), 'utf8'),
217+
cert: fs.readFileSync('valid-ssl-cert.pem'), 'utf8')
218+
},
219+
target: 'https://localhost:9010',
220+
secure: true // Depends on your needs, could be false.
221+
}).listen(443);
222+
```
223+
224+
#### Proxying WebSockets
225+
You can activate the websocket support for the proxy using `ws:true` in the options.
226+
227+
```js
228+
//
229+
// Create a proxy server for websockets
230+
//
231+
httpProxy.createServer({
232+
target: 'ws://localhost:9014',
233+
ws: true
234+
}).listen(8014);
235+
```
236+
237+
Also you can proxy the websocket requests just calling the `ws(req, socket, head)` method.
238+
239+
```js
240+
//
241+
// Setup our server to proxy standard HTTP requests
242+
//
243+
var proxy = new httpProxy.createProxyServer({
244+
target: {
245+
host: 'localhost',
246+
port: 9015
247+
}
248+
});
249+
var proxyServer = http.createServer(function (req, res) {
250+
proxy.web(req, res);
251+
});
252+
253+
//
254+
// Listen to the `upgrade` event and proxy the
255+
// WebSocket requests as well.
256+
//
257+
proxyServer.on('upgrade', function (req, socket, head) {
258+
proxy.ws(req, socket, head);
259+
});
260+
261+
proxyServer.listen(8015);
262+
```
263+
264+
### Contributing and Issues
265+
266+
* Search on Google/Github
267+
* If you can't find anything, open an issue
268+
* If you feel comfortable about fixing the issue, fork the repo
269+
* Commit to your local branch (which must be different from `master`)
270+
* Submit your Pull Request (be sure to include tests and update documentation)
271+
272+
### Options
273+
274+
`httpProxy.createProxyServer` supports the following options:
275+
276+
* **target**: url string to be parsed with the url module
277+
* **forward**: url string to be parsed with the url module
278+
* **agent**: object to be passed to http(s).request (see Node's [https agent](http://nodejs.org/api/https.html#https_class_https_agent) and [http agent](http://nodejs.org/api/http.html#http_class_http_agent) objects)
279+
* **secure**: true/false, if you want to verify the SSL Certs
280+
281+
If you are using the `proxyServer.listen` method, the following options are also applicable:
282+
283+
* **ssl**: object to be passed to https.createServer()
284+
* **ws**: true/false, if you want to proxy websockets
285+
* **xfwd**: true/false, adds x-forward headers
286+
287+
288+
### Test
289+
290+
```
291+
$ npm test
292+
```
293+
294+
### Logo
295+
296+
Logo created by [Diego Pasquali](http://dribbble.com/diegopq)
297+
298+
### License
299+
300+
>The MIT License (MIT)
301+
>
302+
>Copyright (c) 2010 - 2013 Nodejitsu Inc.
303+
>
304+
>Permission is hereby granted, free of charge, to any person obtaining a copy
305+
>of this software and associated documentation files (the "Software"), to deal
306+
>in the Software without restriction, including without limitation the rights
307+
>to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
308+
>copies of the Software, and to permit persons to whom the Software is
309+
>furnished to do so, subject to the following conditions:
310+
>
311+
>The above copyright notice and this permission notice shall be included in
312+
>all copies or substantial portions of the Software.
313+
>
314+
>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
315+
>IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
316+
>FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
317+
>AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
318+
>LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
319+
>OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
320+
>THE SOFTWARE.
321+
322+

0 commit comments

Comments
 (0)