nodejitsu/node-http-proxy — pull request #665 by msporny (2014-06-29 22:05:25+00:00)
Title: [api] Add modifyProxyConnection feature to available options.

### Problem Description

In some proxy scenarios, it's helpful to modify the outgoing proxy request before the initial connection is made. For example, if a developer would like to add a few custom proxy-specific headers, the cleanest way to do this is to add the headers to the _http.ClientRequest_ __proxyReq__ object. Unfortunately, there is no way to access the proxyReq object pre-flight.

The problem manifested itself when I attempted to digitally sign an outgoing proxy request. In order to perform a digital signature on the HTTP headers using the HTTP Signatures specification you have to have access to all of the finalized headers. Since http-proxy modifies/adds headers, the digital signature should only be performed after all such modifications have been made but before the data is piped.

### Solution

Add the __modifyProxyConnection__ option to the __options__ variable which takes a function. The function has the following signature: function(_http.ClientRequest_ __proxyReq__, _http.IncomingMessage_ __req__, _http.ServerResponse_ __res__, _Object_ __options__). This enables the developer to modify the outgoing proxy connection in a variety of very flexible ways.

### Potential Issues

1. If __options.forward__ is specified, modification isn't supported. I think that's how it should work, but core implementers may disagree with that approach.
2. There is currently no way to take the body of the HTTP message into account when calling __modifyProxyConnection__, which means that performing a header modification on the body isn't possible. For example, it's not possible to add a header specifying a Digest SHA-256 sum for the body. Adding this feature could create scalability nightmares as one would need to do a full read of the data stream in some cases (which could be multiple megabytes or gigabytes of data).