Created by: msporny
Problem Description
In some proxy scenarios, it's helpful to modify the outgoing proxy request before the headers are sent. 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 a proxyReq event that a proxy server can listen to in order to modify the request before it is sent. The event handler 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
- 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.
- There is currently no way to take the body of the HTTP message into account when the event is called, 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).