[api] Add event-based ability to modify pre-flight proxy requests.

Author: msporny

README.md

@@ -114,6 +114,43 @@ console.log("listening on port 5050")
 server.listen(5050);
 ```
 
+#### 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.
+
+```js
+var http = require('http'),
+    httpProxy = require('http-proxy');
+
+//
+// Create a proxy server with custom application logic
+//
+var proxy = httpProxy.createProxyServer({});
+
+// To modify the proxy connection before data is sent, you can listen
+// for the 'proxyReq' event. When the event is fired, you will receive
+// the following arguments:
+// (http.ClientRequest proxyReq, http.IncomingMessage req,
+//  http.ServerResponse res, Object options). This mechanism is useful when
+// you need to modify the proxy request before the proxy connection
+// is made to the target.
+//
+proxy.on('proxyReq', function(proxyReq, req, res, options) {
+  proxyReq.setHeader('X-Special-Proxy-Header', 'foobar');
+});
+
+var server = require('http').createServer(function(req, res) {
+  // You can define here your custom logic to handle the request
+  // and then proxy the request.
+  proxy.web(req, res, {
+    target: 'http://127.0.0.1:5060'
+  });
+});
+
+console.log("listening on port 5050")
+server.listen(5050);
+```
+
 #### Setup a stand-alone proxy server with latency
 
 ```js

lib/http-proxy/passes/web-incoming.js

@@ -109,6 +109,11 @@ web_o = Object.keys(web_o).map(function(pass) {
       common.setupOutgoing(options.ssl || {}, options, req)
     );
 
+    // Enable developers to modify the proxyReq before headers are sent
+    proxyReq.on('socket', function(socket) {
+      if(server) { server.emit('proxyReq', proxyReq, req, res, options); }
+    });
+
     // allow outgoing socket to timeout so that we could
     // show an error page at the initial request
     if(options.proxyTimeout) {

test/lib-http-proxy-passes-web-incoming-test.js

@@ -74,6 +74,34 @@ describe('#createProxyServer.web() using own http server', function () {
     http.request('http://127.0.0.1:8081', function() {}).end();
   });
 
+  it('should detect a proxyReq event and modify headers', function (done) {
+    var proxy = httpProxy.createProxyServer({
+      target: 'http://127.0.0.1:8080',
+    });
+
+    proxy.on('proxyReq', function(proxyReq, req, res, options) {
+      proxyReq.setHeader('X-Special-Proxy-Header', 'foobar');
+    });
+
+    function requestHandler(req, res) {
+      proxy.web(req, res);
+    }
+
+    var proxyServer = http.createServer(requestHandler);
+
+    var source = http.createServer(function(req, res) {
+      source.close();
+      proxyServer.close();
+      expect(req.headers['x-special-proxy-header']).to.eql('foobar');
+      done();
+    });
+
+    proxyServer.listen('8081');
+    source.listen('8080');
+
+    http.request('http://127.0.0.1:8081', function() {}).end();
+  });
+
   it('should proxy the request and handle error via callback', function(done) {
     var proxy = httpProxy.createProxyServer({
       target: 'http://127.0.0.1:8080'