Skip to content

Commit 222a4d0

Browse files
indexzeroindexzero
committed
Merge pull request #912 from nodejitsu/more-structured-readme
More structured readme
2 parents 642e9cc + 6106d4c commit 222a4d0

File tree

1 file changed

+139
-83
lines changed

1 file changed

+139
-83
lines changed

Diff for: ‎README.md

+139-83
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,50 @@
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 ?](#upgrading-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
45+
**[Back to top](#table-of-contents)**
1746

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>
47+
### Upgrading from 0.8.x ?
2448

25-
### Looking to Upgrade from 0.8.x ? Click [here](UPGRADING.md)
49+
Click [here](UPGRADING.md)
50+
51+
**[Back to top](#table-of-contents)**
2652

2753
### Core Concept
2854

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

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

3865
An object will be returned with four values:
3966

@@ -70,6 +97,9 @@ The first pipeline (ingoing) is responsible for the creation and manipulation of
7097
The second pipeline (outgoing) is responsible for the creation and manipulation of the stream that, from your target, returns data
7198
to the client.
7299

100+
**[Back to top](#table-of-contents)**
101+
102+
### Use Cases
73103

74104
#### Setup a basic stand-alone proxy server
75105

@@ -79,7 +109,7 @@ var http = require('http'),
79109
//
80110
// Create your proxy server and set the target in the options.
81111
//
82-
httpProxy.createProxyServer({target:'http://localhost:9000'}).listen(8000);
112+
httpProxy.createProxyServer({target:'http://localhost:9000'}).listen(8000); // See (†)
83113

84114
//
85115
// Create your target server
@@ -90,6 +120,9 @@ http.createServer(function (req, res) {
90120
res.end();
91121
}).listen(9000);
92122
```
123+
†Invoking listen(..) triggers the creation of a web server. Otherwise, just the proxy instance is created.
124+
125+
**[Back to top](#table-of-contents)**
93126

94127
#### Setup a stand-alone proxy server with custom server logic
95128
This example show how you can proxy a request using your own HTTP server
@@ -118,11 +151,8 @@ var server = http.createServer(function(req, res) {
118151
console.log("listening on port 5050")
119152
server.listen(5050);
120153
```
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.
125154

155+
**[Back to top](#table-of-contents)**
126156

127157
#### Setup a stand-alone proxy server with proxy request header re-writing
128158
This example shows how you can proxy a request using your own HTTP server that
@@ -161,6 +191,15 @@ console.log("listening on port 5050")
161191
server.listen(5050);
162192
```
163193

194+
**[Back to top](#table-of-contents)**
195+
196+
#### Modify a response from a proxied server
197+
Sometimes when you have received a HTML/XML document from the server of origin you would like to modify it before forwarding it on.
198+
199+
[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.
200+
201+
**[Back to top](#table-of-contents)**
202+
164203
#### Setup a stand-alone proxy server with latency
165204

166205
```js
@@ -195,61 +234,7 @@ http.createServer(function (req, res) {
195234
}).listen(9008);
196235
```
197236

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-
```
237+
**[Back to top](#table-of-contents)**
253238

254239
#### Using HTTPS
255240
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.
@@ -288,6 +273,8 @@ httpProxy.createServer({
288273
}).listen(443);
289274
```
290275

276+
**[Back to top](#table-of-contents)**
277+
291278
#### Proxying WebSockets
292279
You can activate the websocket support for the proxy using `ws:true` in the options.
293280

@@ -328,16 +315,7 @@ proxyServer.on('upgrade', function (req, socket, head) {
328315
proxyServer.listen(8015);
329316
```
330317

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)
318+
**[Back to top](#table-of-contents)**
341319

342320
### Options
343321

@@ -369,6 +347,66 @@ If you are using the `proxyServer.listen` method, the following options are also
369347
* **ssl**: object to be passed to https.createServer()
370348
* **ws**: true/false, if you want to proxy websockets
371349

350+
**[Back to top](#table-of-contents)**
351+
352+
### Listening for proxy events
353+
354+
* `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.**
355+
* `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
356+
* `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
357+
* `proxyRes`: This event is emitted if the request to the target got a response.
358+
* `open`: This event is emitted once the proxy websocket was created and piped into the target websocket.
359+
* `close`: This event is emitted once the proxy websocket was closed.
360+
* (DEPRECATED) `proxySocket`: Deprecated in favor of `open`.
361+
362+
```js
363+
var httpProxy = require('http-proxy');
364+
// Error example
365+
//
366+
// Http Proxy Server with bad target
367+
//
368+
var proxy = httpProxy.createServer({
369+
target:'http://localhost:9005'
370+
});
371+
372+
proxy.listen(8005);
373+
374+
//
375+
// Listen for the `error` event on `proxy`.
376+
proxy.on('error', function (err, req, res) {
377+
res.writeHead(500, {
378+
'Content-Type': 'text/plain'
379+
});
380+
381+
res.end('Something went wrong. And we are reporting a custom error message.');
382+
});
383+
384+
//
385+
// Listen for the `proxyRes` event on `proxy`.
386+
//
387+
proxy.on('proxyRes', function (proxyRes, req, res) {
388+
console.log('RAW Response from the target', JSON.stringify(proxyRes.headers, true, 2));
389+
});
390+
391+
//
392+
// Listen for the `open` event on `proxy`.
393+
//
394+
proxy.on('open', function (proxySocket) {
395+
// listen for messages coming FROM the target here
396+
proxySocket.on('data', hybiParseAndLogMessage);
397+
});
398+
399+
//
400+
// Listen for the `close` event on `proxy`.
401+
//
402+
proxy.on('close', function (req, socket, head) {
403+
// view disconnected websocket connections
404+
console.log('Client disconnected');
405+
});
406+
```
407+
408+
**[Back to top](#table-of-contents)**
409+
372410
### Shutdown
373411

374412
* When testing or running server within another program it may be necessary to close the proxy.
@@ -385,16 +423,36 @@ var proxy = new httpProxy.createProxyServer({
385423
proxy.close();
386424
```
387425

388-
### Test
426+
**[Back to top](#table-of-contents)**
427+
428+
### Miscellaneous
429+
430+
#### ProxyTable API
431+
432+
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.
433+
434+
#### Test
389435

390436
```
391437
$ npm test
392438
```
393439

394-
### Logo
440+
#### Logo
395441

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

444+
**[Back to top](#table-of-contents)**
445+
446+
### Contributing and Issues
447+
448+
* Search on Google/Github
449+
* If you can't find anything, open an issue
450+
* If you feel comfortable about fixing the issue, fork the repo
451+
* Commit to your local branch (which must be different from `master`)
452+
* Submit your Pull Request (be sure to include tests and update documentation)
453+
454+
**[Back to top](#table-of-contents)**
455+
398456
### License
399457

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

0 commit comments

Comments
 (0)