Skip to content

Commit cd1d777

Browse files
donasaurdonasaur
committed
Organized README more
1 parent 642e9cc commit cd1d777

File tree

1 file changed

+113
-87
lines changed

1 file changed

+113
-87
lines changed

‎README.md

+113-87
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,46 @@
55
node-http-proxy
66
=======
77

8+
<p align="left">
9+
<a href="https://travis-ci.org/nodejitsu/node-http-proxy" target="_blank">
10+
<img src="https://travis-ci.org/nodejitsu/node-http-proxy.png"/></a>&nbsp;&nbsp;
11+
<a href="https://coveralls.io/r/nodejitsu/node-http-proxy" target="_blank">
12+
<img src="https://coveralls.io/repos/nodejitsu/node-http-proxy/badge.png"/></a>
13+
</p>
14+
815
`node-http-proxy` is an HTTP programmable proxying library that supports
916
websockets. It is suitable for implementing components such as
1017
proxies and load balancers.
1118

19+
### Table of Contents
20+
* [Installation](#installation)
21+
* [Upgrading from 0.8.x ?](#upgrade-from-08x)
22+
* [Core Concept](#core-concept)
23+
* [Use Cases](#use-cases)
24+
* [Setup a basic stand-alone proxy server](#setup-a-basic-stand-alone-proxy-server)
25+
* [Setup a stand-alone proxy server with custom server logic](#setup-a-stand-alone-proxy-server-with-custom-server-logic)
26+
* [Setup a stand-alone proxy server with proxy request header re-writing](#setup-a-stand-alone-proxy-server-with-proxy-request-header-re-writing)
27+
* [Modify a response from a proxied server](#modify-a-response-from-a-proxied-server)
28+
* [Setup a stand-alone proxy server with latency](#setup-a-stand-alone-proxy-server-with-latency)
29+
* [Using HTTPS](#using-https)
30+
* [Proxying WebSockets](#proxying-websockets)
31+
* [Options](#options)
32+
* [Listening for proxy events](#listening-for-proxy-events)
33+
* [Shutdown](#shutdown)
34+
* [Miscellaneous](#miscellaneous)
35+
* [Test](#test)
36+
* [ProxyTable API](#proxytable-api)
37+
* [Logo](#logo)
38+
* [Contributing and Issues](#contributing-and-issues)
39+
* [License](#license)
40+
1241
### Installation
1342

1443
`npm install http-proxy --save`
1544

16-
### Build Status
17-
18-
<p align="center">
19-
<a href="https://travis-ci.org/nodejitsu/node-http-proxy" target="_blank">
20-
<img src="https://travis-ci.org/nodejitsu/node-http-proxy.png"/></a>&nbsp;&nbsp;
21-
<a href="https://coveralls.io/r/nodejitsu/node-http-proxy" target="_blank">
22-
<img src="https://coveralls.io/repos/nodejitsu/node-http-proxy/badge.png"/></a>
23-
</p>
45+
### Upgrading from 0.8.x ?
2446

25-
### Looking to Upgrade from 0.8.x ? Click [here](UPGRADING.md)
47+
Click [here](UPGRADING.md)
2648

2749
### Core Concept
2850

@@ -32,8 +54,9 @@ an `options` object as argument ([valid properties are available here](lib/http-
3254
```javascript
3355
var httpProxy = require('http-proxy');
3456

35-
var proxy = httpProxy.createProxyServer(options);
57+
var proxy = httpProxy.createProxyServer(options); // See (†)
3658
```
59+
†Unless listen(..) is invoked on the object, this does not create a webserver. See below.
3760

3861
An object will be returned with four values:
3962

@@ -70,6 +93,7 @@ The first pipeline (ingoing) is responsible for the creation and manipulation of
7093
The second pipeline (outgoing) is responsible for the creation and manipulation of the stream that, from your target, returns data
7194
to the client.
7295

96+
### Use Cases
7397

7498
#### Setup a basic stand-alone proxy server
7599

@@ -79,7 +103,7 @@ var http = require('http'),
79103
//
80104
// Create your proxy server and set the target in the options.
81105
//
82-
httpProxy.createProxyServer({target:'http://localhost:9000'}).listen(8000);
106+
httpProxy.createProxyServer({target:'http://localhost:9000'}).listen(8000); // See (†)
83107

84108
//
85109
// Create your target server
@@ -90,6 +114,7 @@ http.createServer(function (req, res) {
90114
res.end();
91115
}).listen(9000);
92116
```
117+
†Invoking listen(..) triggers the creation of a web server. Otherwise, just the proxy instance is created.
93118

94119
#### Setup a stand-alone proxy server with custom server logic
95120
This example show how you can proxy a request using your own HTTP server
@@ -118,11 +143,6 @@ var server = http.createServer(function(req, res) {
118143
console.log("listening on port 5050")
119144
server.listen(5050);
120145
```
121-
#### Modify a response from a proxied server
122-
Sometimes when you have received a HTML/XML document from the server of origin you would like to modify it before forwarding it on.
123-
124-
[Harmon](https://github.com/No9/harmon) allows you to do this in a streaming style so as to keep the pressure on the proxy to a minimum.
125-
126146

127147
#### Setup a stand-alone proxy server with proxy request header re-writing
128148
This example shows how you can proxy a request using your own HTTP server that
@@ -161,6 +181,11 @@ console.log("listening on port 5050")
161181
server.listen(5050);
162182
```
163183

184+
#### Modify a response from a proxied server
185+
Sometimes when you have received a HTML/XML document from the server of origin you would like to modify it before forwarding it on.
186+
187+
[Harmon](https://github.com/No9/harmon) allows you to do this in a streaming style so as to keep the pressure on the proxy to a minimum.
188+
164189
#### Setup a stand-alone proxy server with latency
165190

166191
```js
@@ -195,62 +220,6 @@ http.createServer(function (req, res) {
195220
}).listen(9008);
196221
```
197222

198-
#### Listening for proxy events
199-
200-
* `error`: The error event is emitted if the request to the target fail.
201-
* `proxyReq`: This event is emitted before the data is sent. It gives you a chance to alter the proxyReq request object. Applies to "web" connections
202-
* `proxyReqWs`: This event is emitted before the data is sent. It gives you a chance to alter the proxyReq request object. Applies to "websocket" connections
203-
* `proxyRes`: This event is emitted if the request to the target got a response.
204-
* `open`: This event is emitted once the proxy websocket was created and piped into the target websocket.
205-
* `close`: This event is emitted once the proxy websocket was closed.
206-
* (DEPRECATED) `proxySocket`: Deprecated in favor of `open`.
207-
208-
```js
209-
var httpProxy = require('http-proxy');
210-
// Error example
211-
//
212-
// Http Proxy Server with bad target
213-
//
214-
var proxy = httpProxy.createServer({
215-
target:'http://localhost:9005'
216-
});
217-
218-
proxy.listen(8005);
219-
220-
//
221-
// Listen for the `error` event on `proxy`.
222-
proxy.on('error', function (err, req, res) {
223-
res.writeHead(500, {
224-
'Content-Type': 'text/plain'
225-
});
226-
227-
res.end('Something went wrong. And we are reporting a custom error message.');
228-
});
229-
230-
//
231-
// Listen for the `proxyRes` event on `proxy`.
232-
//
233-
proxy.on('proxyRes', function (proxyRes, req, res) {
234-
console.log('RAW Response from the target', JSON.stringify(proxyRes.headers, true, 2));
235-
});
236-
237-
//
238-
// Listen for the `open` event on `proxy`.
239-
//
240-
proxy.on('open', function (proxySocket) {
241-
// listen for messages coming FROM the target here
242-
proxySocket.on('data', hybiParseAndLogMessage);
243-
});
244-
245-
//
246-
// Listen for the `close` event on `proxy`.
247-
//
248-
proxy.on('close', function (req, socket, head) {
249-
// view disconnected websocket connections
250-
console.log('Client disconnected');
251-
});
252-
```
253-
254223
#### Using HTTPS
255224
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.
256225

@@ -328,17 +297,6 @@ proxyServer.on('upgrade', function (req, socket, head) {
328297
proxyServer.listen(8015);
329298
```
330299

331-
#### ProxyTable API
332-
A proxy table API is available through through this add-on [module](https://github.com/donasaur/http-proxy-rules), which lets you define a set of rules to translate matching routes to target routes that the reverse proxy will talk to.
333-
334-
### Contributing and Issues
335-
336-
* Search on Google/Github
337-
* If you can't find anything, open an issue
338-
* If you feel comfortable about fixing the issue, fork the repo
339-
* Commit to your local branch (which must be different from `master`)
340-
* Submit your Pull Request (be sure to include tests and update documentation)
341-
342300
### Options
343301

344302
`httpProxy.createProxyServer` supports the following options:
@@ -369,6 +327,62 @@ If you are using the `proxyServer.listen` method, the following options are also
369327
* **ssl**: object to be passed to https.createServer()
370328
* **ws**: true/false, if you want to proxy websockets
371329

330+
### Listening for proxy events
331+
332+
* `error`: The error event is emitted if the request to the target fail. **We do not do any error handling of messages passed between client and proxy, and messages passed between proxy and target, so it is recommended that you listen on errors and handle them.**
333+
* `proxyReq`: This event is emitted before the data is sent. It gives you a chance to alter the proxyReq request object. Applies to "web" connections
334+
* `proxyReqWs`: This event is emitted before the data is sent. It gives you a chance to alter the proxyReq request object. Applies to "websocket" connections
335+
* `proxyRes`: This event is emitted if the request to the target got a response.
336+
* `open`: This event is emitted once the proxy websocket was created and piped into the target websocket.
337+
* `close`: This event is emitted once the proxy websocket was closed.
338+
* (DEPRECATED) `proxySocket`: Deprecated in favor of `open`.
339+
340+
```js
341+
var httpProxy = require('http-proxy');
342+
// Error example
343+
//
344+
// Http Proxy Server with bad target
345+
//
346+
var proxy = httpProxy.createServer({
347+
target:'http://localhost:9005'
348+
});
349+
350+
proxy.listen(8005);
351+
352+
//
353+
// Listen for the `error` event on `proxy`.
354+
proxy.on('error', function (err, req, res) {
355+
res.writeHead(500, {
356+
'Content-Type': 'text/plain'
357+
});
358+
359+
res.end('Something went wrong. And we are reporting a custom error message.');
360+
});
361+
362+
//
363+
// Listen for the `proxyRes` event on `proxy`.
364+
//
365+
proxy.on('proxyRes', function (proxyRes, req, res) {
366+
console.log('RAW Response from the target', JSON.stringify(proxyRes.headers, true, 2));
367+
});
368+
369+
//
370+
// Listen for the `open` event on `proxy`.
371+
//
372+
proxy.on('open', function (proxySocket) {
373+
// listen for messages coming FROM the target here
374+
proxySocket.on('data', hybiParseAndLogMessage);
375+
});
376+
377+
//
378+
// Listen for the `close` event on `proxy`.
379+
//
380+
proxy.on('close', function (req, socket, head) {
381+
// view disconnected websocket connections
382+
console.log('Client disconnected');
383+
});
384+
```
385+
372386
### Shutdown
373387

374388
* When testing or running server within another program it may be necessary to close the proxy.
@@ -385,16 +399,30 @@ var proxy = new httpProxy.createProxyServer({
385399
proxy.close();
386400
```
387401

388-
### Test
402+
### Miscellaneous
403+
404+
#### ProxyTable API
405+
406+
A proxy table API is available through through this add-on [module](https://github.com/donasaur/http-proxy-rules), which lets you define a set of rules to translate matching routes to target routes that the reverse proxy will talk to.
407+
408+
#### Test
389409

390410
```
391411
$ npm test
392412
```
393413

394-
### Logo
414+
#### Logo
395415

396416
Logo created by [Diego Pasquali](http://dribbble.com/diegopq)
397417

418+
### Contributing and Issues
419+
420+
* Search on Google/Github
421+
* If you can't find anything, open an issue
422+
* If you feel comfortable about fixing the issue, fork the repo
423+
* Commit to your local branch (which must be different from `master`)
424+
* Submit your Pull Request (be sure to include tests and update documentation)
425+
398426
### License
399427

400428
>The MIT License (MIT)
@@ -418,5 +446,3 @@ Logo created by [Diego Pasquali](http://dribbble.com/diegopq)
418446
>LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
419447
>OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
420448
>THE SOFTWARE.
421-
422-

0 commit comments

Comments
 (0)