UPGRADING.md

Looking to upgrade from [email protected] to [email protected]? You've come to the right place! [email protected] is a from-scratch implementation of http-proxy and, as such brings some breaking changes to APIs.

Server creation

Available through .createServer() or .createProxyServer().

httpProxy.createServer({
  target:'http://localhost:9003'
}).listen(8003);

Check the README.md for a more detailed explanation of the parameters.

Proxying

Web proying is done by calling the .web() method on a Proxy instance. You can check among some use cases in the examples folder

//
// Create a HTTP Proxy server with a HTTPS target
//
httpProxy.createProxyServer({
  target: 'https://google.com',
  agent : https.globalAgent,
  headers: {
    host: 'google.com'
  }
}).listen(8011);

Websockets are proxied by the .ws() method. The examples folder again provides a lot of useful snippets!

var proxy = new httpProxy.createProxyServer({
  target: {
    host: 'localhost',
    port: 9015
  }
});
var proxyServer = http.createServer(function (req, res) {
  proxy.web(req, res);
});

//
// Listen to the `upgrade` event and proxy the
// WebSocket requests as well.
//
proxyServer.on('upgrade', function (req, socket, head) {
  proxy.ws(req, socket, head);
});

Error Handling

It is possible to listen globally on the error event on the server. In alternative, a callback passed to .web() or .ws() as last parameter is also accepted.

var proxy = httpProxy.createServer({
  target:'http://localhost:9005'
});

//
// Tell the proxy to listen on port 8000
//
proxy.listen(8005);

//
// Listen for the `error` event on `proxy`.
proxy.on('error', function (err, req, res) {
  res.writeHead(500, {
    'Content-Type': 'text/plain'
  });
  
  res.end('Something went wrong. And we are reporting a custom error message.');
});

Dropped

Since the API was rewritten to be extremely flexible we decided to drop some features which were in the core and delegate them to eventual "userland" modules.

• Middleware API
• ProxyTable API

Middleware API

The new API makes it really easy to implement code that behaves like the old Middleware API. You can check some examples here