Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More structured readme #912

Merged
merged 2 commits into from
Nov 23, 2015
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Added back to top helpers
  • Loading branch information
donasaur committed Nov 23, 2015
commit 6106d4c32f7c7960f0391591661e6f0d229db52d
32 changes: 31 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ proxies and load balancers.

### Table of Contents
* [Installation](#installation)
* [Upgrading from 0.8.x ?](#upgrade-from-08x)
* [Upgrading from 0.8.x ?](#upgrading-from-08x-)
* [Core Concept](#core-concept)
* [Use Cases](#use-cases)
* [Setup a basic stand-alone proxy server](#setup-a-basic-stand-alone-proxy-server)
Expand All @@ -42,10 +42,14 @@ proxies and load balancers.

`npm install http-proxy --save`

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

### Upgrading from 0.8.x ?

Click [here](UPGRADING.md)

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

### Core Concept

A new proxy is created by calling `createProxyServer` and passing
Expand Down Expand Up @@ -93,6 +97,8 @@ The first pipeline (ingoing) is responsible for the creation and manipulation of
The second pipeline (outgoing) is responsible for the creation and manipulation of the stream that, from your target, returns data
to the client.

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

### Use Cases

#### Setup a basic stand-alone proxy server
Expand All @@ -116,6 +122,8 @@ http.createServer(function (req, res) {
```
†Invoking listen(..) triggers the creation of a web server. Otherwise, just the proxy instance is created.

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

#### Setup a stand-alone proxy server with custom server logic
This example show how you can proxy a request using your own HTTP server
and also you can put your own logic to handle the request.
Expand Down Expand Up @@ -144,6 +152,8 @@ console.log("listening on port 5050")
server.listen(5050);
```

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

#### Setup a stand-alone proxy server with proxy request header re-writing
This example shows how you can proxy a request using your own HTTP server that
modifies the outgoing proxy request by adding a special header.
Expand Down Expand Up @@ -181,11 +191,15 @@ console.log("listening on port 5050")
server.listen(5050);
```

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

#### Modify a response from a proxied server
Sometimes when you have received a HTML/XML document from the server of origin you would like to modify it before forwarding it on.

[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.

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

#### Setup a stand-alone proxy server with latency

```js
Expand Down Expand Up @@ -220,6 +234,8 @@ http.createServer(function (req, res) {
}).listen(9008);
```

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

#### Using HTTPS
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.

Expand Down Expand Up @@ -257,6 +273,8 @@ httpProxy.createServer({
}).listen(443);
```

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

#### Proxying WebSockets
You can activate the websocket support for the proxy using `ws:true` in the options.

Expand Down Expand Up @@ -297,6 +315,8 @@ proxyServer.on('upgrade', function (req, socket, head) {
proxyServer.listen(8015);
```

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

### Options

`httpProxy.createProxyServer` supports the following options:
Expand Down Expand Up @@ -327,6 +347,8 @@ If you are using the `proxyServer.listen` method, the following options are also
* **ssl**: object to be passed to https.createServer()
* **ws**: true/false, if you want to proxy websockets

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

### Listening for proxy events

* `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.**
Expand Down Expand Up @@ -383,6 +405,8 @@ proxy.on('close', function (req, socket, head) {
});
```

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

### Shutdown

* When testing or running server within another program it may be necessary to close the proxy.
Expand All @@ -399,6 +423,8 @@ var proxy = new httpProxy.createProxyServer({
proxy.close();
```

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

### Miscellaneous

#### ProxyTable API
Expand All @@ -415,6 +441,8 @@ $ npm test

Logo created by [Diego Pasquali](https://dribbble.com/diegopq)

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

### Contributing and Issues

* Search on Google/Github
Expand All @@ -423,6 +451,8 @@ Logo created by [Diego Pasquali](https://dribbble.com/diegopq)
* Commit to your local branch (which must be different from `master`)
* Submit your Pull Request (be sure to include tests and update documentation)

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

### License

>The MIT License (MIT)
Expand Down