Tug · Angelfirenze · Oct 22, 2011 · Oct 25, 2011 · Oct 25, 2011 · Oct 25, 2011
diff --git a/.travis.yml b/.travis.yml
@@ -0,0 +1,10 @@
+language: node_js
+node_js:
+  - 0.8
+  - "0.10"
+  - "0.11"
+
+notifications:
+  email:
+    - travis@nodejitsu.com
+  irc: "irc.freenode.org#nodejitsu"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,70 @@
 ## ChangeLog for: node-http-proxy
 
+## Version 0.10.0 - 3/18/2013
+
+- Breaking change: `proxyResponse` events are emitted on the `HttpProxy` or `RoutingProxy` instances as originally was intended in `0.9.x`.
+
+## Version 0.9.1 - 3/9/2013
+
+- Ensure that `webSocketProxyError` and `proxyError` both receive the error (indexzero).
+
+## Version 0.9.0 - 3/9/2013
+- Fix #276 Ensure response.headers.location is defined (indexzero)
+- Fix #248 Make options immutable in RoutingProxy (indexzero)
+- Fix #359 Do not modify the protocol in redirect request for external sites. (indexzero)
+- Fix #373 Do not use "Transfer-Encoding: chunked" header for proxied DELETE requests with no "Content-Length" header. (indexzero)
+- Fix #338 Set "content-length" header to "0" if it is not already set on DELETE requests. (indexzero)
+- Updates to README.md and Examples (ramitos, jamie-stackhouse, oost, indexzero)
+- Fixes to ProxyTable and Routing Proxy (adjohnson916, otavoijr)
+- New API for ProxyTable (mikkel, tglines)
+- Add `options.timeout` for specifying socket timeouts (pdoran)
+- Improve bin/node-http-proxy (niallo)
+- Don't emit `proxyError` twice (erasmospunk)
+- Fix memory leaks in WebSocket proxying 
+- Support UNIX Sockets (yosefd)
+- Fix truncated chunked respones (jpetazzo)
+- Allow upstream listeners to get `proxyResponse` (colinmollenhour)
+
+## Version 0.8.1 - 6/5/2012
+- Fix re-emitting of events in RoutingProxy                (coderarity)
+- New load balancer and middleware examples                (marak)
+- Docs updated including changelog                         (lot of gently people)
+
+## Version 0.8.0 - 12/23/2011
+- Improve support and tests for url segment routing        (maxogden)
+- Fix aborting connections when request close              (c4milo)
+- Avoid 'Transfer-Encoding' on HTTP/1.0 clients            (koichik).
+- Support for Node.js 0.6.x                                (mmalecki)
+
+## Version 0.7.3 - 10/4/2011
+- Fix setting x-forwarded headers                          (jesusabdullah)
+- Updated examples                                         (AvianFlu)
+
+## Version 0.7.0 - 9/10/2011
+- Handles to every throw-able resume() call                (isaacs)
+- Updated tests, README and package.json                   (indexzero)
+- Added HttpProxy.close() method                           (indexzero)
+
+## Version 0.6.6 - 8/31/2011
+- Add more examples                                        (dominictarr)
+- Use of 'pkginfo'                                         (indexzero)
+- Handle cases where res.write throws                      (isaacs)
+- Handles to every throw-able res.end call                 (isaacs)
+
+## Version 0.5.11 - 6/21/2011
+- Add more examples with WebSockets                        (indexzero)
+- Update the documentation                                 (indexzero)
+
+## Version 0.5.7 - 5/19/2011
+- Fix to README related to markup and fix some examples    (benatkin)
+- Improve WebSockets handling                              (indexzero)
+- Improve WebSockets tests                                 (indexzero)
+- Improve https tests                                      (olauzon)
+- Add devDependencies to package.json                      (olauzon)
+- Add 'proxyError' event                                   (indexzero)
+- Add 'x-forwarded-{port|proto}' headers support           (indexzero)
+- Keep-Alive connection supported                          (indexzero)
+
 ## Version 0.5.0 - 4/15/2011
 - Remove winston in favor of custom events                 (indexzero)
 - Add x-forwarded-for Header                               (indexzero)

diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# node-http-proxy
+# node-http-proxy [![Build Status](https://secure.travis-ci.org/nodejitsu/node-http-proxy.png)](http://travis-ci.org/nodejitsu/node-http-proxy)
 
 <img src="http://i.imgur.com/8fTt9.png" />
 
@@ -18,14 +18,17 @@
 * Written entirely in Javascript
 * Easy to use API
 
+
+node-http-proxy is `<= 0.8.x` compatible, if you're looking for a `>= 0.10` compatible version please check [caronte](https://github.com/nodejitsu/node-http-proxy/tree/caronte)
+
 ### When to use node-http-proxy
 
 Let's suppose you were running multiple http application servers, but you only wanted to expose one machine to the internet. You could setup node-http-proxy on that one machine and then reverse-proxy the incoming http requests to locally running services which were not exposed to the outside network. 
 
 ### Installing npm (node package manager)
 
 ```
-curl http://npmjs.org/install.sh | sh
+curl https://npmjs.org/install.sh | sh
 ```
 
 ### Installing node-http-proxy
@@ -202,6 +205,24 @@ var options = {
 
 Notice here that I have not included paths on the individual domains because this is not possible when using only the HTTP 'Host' header. Care to learn more? See [RFC2616: HTTP/1.1, Section 14.23, "Host"][4].
 
+### Proxy requests using a 'Pathname Only' ProxyTable
+
+If you dont care about forwarding to different hosts, you can redirect based on the request path.
+
+``` js
+var options = {
+  pathnameOnly: true,
+  router: {
+    '/wiki': '127.0.0.1:8001',
+    '/blog': '127.0.0.1:8002',
+    '/api':  '127.0.0.1:8003'
+  }
+}
+```
+
+This comes in handy if you are running separate services or applications on separate paths.  Note, using this option disables routing by hostname entirely.
+
+
 ### Proxy requests with an additional forward proxy
 Sometimes in addition to a reverse proxy, you may want your front-facing server to forward traffic to another location. For example, if you wanted to load test your staging environment. This is possible when using node-http-proxy using similar JSON-based configuration to a proxy table: 
 
@@ -217,6 +238,30 @@ proxyServerWithForwarding.listen(80);
 
 The forwarding option can be used in conjunction with the proxy table options by simply including both the 'forward' and 'router' properties in the options passed to 'createServer'.
 
+### Listening for proxy events
+Sometimes you want to listen to an event on a proxy. For example, you may want to listen to the 'end' event, which represents when the proxy has finished proxying a request.
+
+``` js
+var httpProxy = require('http-proxy');
+
+var server = httpProxy.createServer(function (req, res, proxy) {
+  var buffer = httpProxy.buffer(req);
+
+  proxy.proxyRequest(req, res, {
+    host: '127.0.0.1',
+    port: 9000,
+    buffer: buffer
+  });
+});
+
+server.proxy.on('end', function () {
+  console.log("The request was proxied.");
+});
+
+server.listen(8000);
+```
+
+It's important to remember not to listen for events on the proxy object in the function passed to `httpProxy.createServer`. Doing so would add a new listener on every request, which would end up being a disaster.
 
 ## Using HTTPS
 You have all the full flexibility of node-http-proxy offers in HTTPS as well as HTTP. The two basic scenarios are: with a stand-alone proxy server or in conjunction with another HTTPS server.
@@ -267,6 +312,70 @@ http.createServer(function (req, res) {
 }).listen(8000);
 ```
 
+### Using two certificates
+
+Suppose that your reverse proxy will handle HTTPS traffic for two different domains `fobar.com` and `barbaz.com`.
+If you need to use two different certificates you can take advantage of [Server Name Indication](http://en.wikipedia.org/wiki/Server_Name_Indication).
+
+``` js
+var https = require('https'),
+    path = require("path"),
+    fs = require("fs"),
+    crypto = require("crypto");
+
+//
+// generic function to load the credentials context from disk
+//
+function getCredentialsContext (cer) {
+  return crypto.createCredentials({
+    key:  fs.readFileSync(path.join(__dirname, 'certs', cer + '.key')),
+    cert: fs.readFileSync(path.join(__dirname, 'certs', cer + '.crt'))
+  }).context;
+}
+
+//
+// A certificate per domain hash
+//
+var certs = {
+  "fobar.com":  getCredentialsContext("foobar"),
+  "barbaz.com": getCredentialsContext("barbaz")
+};
+
+//
+// Proxy options
+//
+var options = {
+  https: {
+    SNICallback: function (hostname) {
+      return certs[hostname];
+    },
+    cert: myCert,
+    key: myKey,
+    ca: [myCa]
+  },
+  hostnameOnly: true,
+  router: {
+    'fobar.com':  '127.0.0.1:8001',
+    'barbaz.com': '127.0.0.1:8002'
+  }
+};
+
+//
+// Create a standalone HTTPS proxy server
+//
+httpProxy.createServer(options).listen(8001);
+
+//
+// Create the target HTTPS server
+//
+http.createServer(function (req, res) {
+  res.writeHead(200, { 'Content-Type': 'text/plain' });
+  res.write('hello https\n');
+  res.end();
+}).listen(8000);
+
+```
+
 ### Proxying to HTTPS from HTTPS
 Proxying from HTTPS to HTTPS is essentially the same as proxying from HTTPS to HTTP, but you must include the `target` option in when calling `httpProxy.createServer` or instantiating a new instance of `HttpProxy`.
 
@@ -325,8 +434,31 @@ httpProxy.createServer(
 ).listen(8000);
 ```
 
+A regular request we receive is to support the modification of html/xml content that is returned in the response from an upstream server. 
+
+[Harmon](https://github.com/No9/harmon/) is a stream based middleware plugin that is designed to solve that problem in the most effective way possible. 
+
 ## Proxying WebSockets
-Websockets are handled automatically when using `httpProxy.createServer()`, but if you want to use it in conjunction with a stand-alone HTTP + WebSocket (such as [socket.io][5]) server here's how:
+Websockets are handled automatically when using `httpProxy.createServer()`, however, if you supply a callback inside the createServer call, you will need to handle the 'upgrade' proxy event yourself. Here's how:
+
+```js
+
+var options = {
+    ....
+};
+
+var server = httpProxy.createServer(
+    callback/middleware, 
+    options
+);
+
+server.listen(port, function () { ... });
+server.on('upgrade', function (req, socket, head) {
+    server.proxy.proxyWebSocketRequest(req, socket, head);
+});
+```
+
+If you would rather not use createServer call, and create the server that proxies yourself, see below:
 
 ``` js
 var http = require('http'),
@@ -335,11 +467,12 @@ var http = require('http'),
 //
 // Create an instance of node-http-proxy
 //
-var proxy = new httpProxy.HttpProxy(
-    target: {
-      host: 'localhost',
-      port: 8000
-    });
+var proxy = new httpProxy.HttpProxy({
+  target: {
+    host: 'localhost',
+    port: 8000
+  }
+});
 
 var server = http.createServer(function (req, res) {
   //
@@ -348,12 +481,42 @@ var server = http.createServer(function (req, res) {
   proxy.proxyRequest(req, res);
 });
 
-server.on('upgrade', function(req, socket, head) {
+server.on('upgrade', function (req, socket, head) {
   //
   // Proxy websocket requests too
   //
   proxy.proxyWebSocketRequest(req, socket, head);
 });
+
+server.listen(8080);
+```
+
+### with custom server logic
+
+``` js
+var httpProxy = require('http-proxy')
+
+var server = httpProxy.createServer(function (req, res, proxy) {
+  //
+  // Put your custom server logic here
+  //
+  proxy.proxyRequest(req, res, {
+    host: 'localhost',
+    port: 9000
+  });
+})
+
+server.on('upgrade', function (req, socket, head) {
+  //
+  // Put your custom server logic here
+  //
+  server.proxy.proxyWebSocketRequest(req, socket, head, {
+    host: 'localhost',
+    port: 9000
+  });
+});
+
+server.listen(8080);
 ```
 
 ### Configuring your Socket limits
@@ -363,6 +526,12 @@ By default, `node-http-proxy` will set a 100 socket limit for all `host:port` pr
 1. By passing the `maxSockets` option to `httpProxy.createServer()`
 2. By calling `httpProxy.setMaxSockets(n)`, where `n` is the number of sockets you with to use. 
 
+## POST requests and buffering
+
+express.bodyParser will interfere with proxying of POST requests (and other methods that have a request 
+body). With bodyParser active, proxied requests will never send anything to the upstream server, and 
+the original client will just hang. See https://github.com/nodejitsu/node-http-proxy/issues/180 for options.
+
 ## Using node-http-proxy from the command line
 When you install this package with npm, a node-http-proxy binary will become available to you. Using this binary is easy with some simple options:
 
@@ -384,6 +553,35 @@ options:
 
 If you have a suggestion for a feature currently not supported, feel free to open a [support issue][6]. node-http-proxy is designed to just proxy http requests from one server to another, but we will be soon releasing many other complimentary projects that can be used in conjunction with node-http-proxy.
 
+## Options
+
+### Http Proxy
+
+`createServer()` supports the following options
+
+```javascript
+{
+  forward: { // options for forward-proxy
+    port: 8000,
+    host: 'staging.com'
+  },
+  target : { // options for proxy target
+    port : 8000, 
+    host : 'localhost',
+  };
+  source : { // additional options for websocket proxying 
+    host : 'localhost',
+    port : 8000,
+    https: true
+  },
+  enable : {
+    xforward: true // enables X-Forwarded-For
+  },
+  changeOrigin: false, // changes the origin of the host header to the target URL
+  timeout: 120000 // override the default 2 minute http socket timeout value in milliseconds
+}
+```
+
 ## Run Tests
 The test suite is designed to fully cover the combinatoric possibilities of HTTP and HTTPS proxying:
 
@@ -426,9 +624,9 @@ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 [0]: http://nodejitsu.com
-[1]: https://github.com/nodejitsu/node-http-proxy/blob/master/examples/web-socket-proxy.js
-[2]: https://github.com/nodejitsu/node-http-proxy/blob/master/examples/basic-proxy-https.js
-[3]: https://github.com/nodejitsu/node-http-proxy/tree/v0.5.0/examples
+[1]: https://github.com/nodejitsu/node-http-proxy/blob/master/examples/websocket/websocket-proxy.js
+[2]: https://github.com/nodejitsu/node-http-proxy/blob/master/examples/http/proxy-https-to-http.js
+[3]: https://github.com/nodejitsu/node-http-proxy/tree/master/examples
 [4]: http://www.ietf.org/rfc/rfc2616.txt
 [5]: http://socket.io
 [6]: http://github.com/nodejitsu/node-http-proxy/issues