http-proxy

The Middleware API and ProxyTable API from version 0.x.x have been removed in version 1.x.x to increase core flexibility.

• Middleware: You can implement custom logic that behaves like the old Middleware API using the new flexible API structure.
• ProxyTable: To simulate the old ProxyTable API, use an add-on module like http-proxy-rules.

In version 1.x.x, proxying is split into two distinct methods based on the protocol:

1. HTTP/HTTPS: Use the .web(req, res) method on a proxy instance.
2. WebSockets: Use the .ws(req, socket, head) method. This typically requires listening to the upgrade event on your HTTP server to intercept WebSocket requests.

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
proxyServer.on('upgrade', function (req, socket, head) {
  proxy.ws(req, socket, head);
});

To perform the Simple HTTP benchmark, you must have three separate terminal sessions running simultaneously: one for the proxy server, one for the target server, and one for the wrk load testing process.

# 1. Start the proxy server
node benchmark/scripts/proxy.js

# 2. Start the target server
node benchmark/scripts/hello.js

# 3. Run the wrk process
wrk -c 20 -d5m -t 2 http://127.0.0.1:8000

You can modify the outgoing request to the target server by listening for the proxyReq event. This is useful for adding custom headers (like authentication or tracking IDs) before the connection is established.

var http = require('http'),
    httpProxy = require('http-proxy');

var proxy = httpProxy.createProxyServer({});

// Listen for 'proxyReq' to modify the request before it is sent to the target
proxy.on('proxyReq', function(proxyReq, req, res, options) {
  proxyReq.setHeader('X-Special-Proxy-Header', 'foobar');
});

var server = http.createServer(function(req, res) {
  proxy.web(req, res, { target: 'http://127.0.0.1:5050' });
});

server.listen(5050);

Install the http-proxy package using npm to use it in your Node.js project.

npm install http-proxy --save

The library supports various HTTPS configurations:

HTTPS -> HTTP

Set the ssl option with key and cert to provide the proxy's certificate.

HTTPS -> HTTPS

Set target to an https:// URL and use secure: true to enable SSL certificate validation (prevents self-signed certs).

HTTP -> HTTPS (using PKCS12)

Provide a pfx file and passphrase in the target object.

// HTTPS -> HTTPS example
httpProxy.createServer({
  ssl: {
    key: fs.readFileSync('valid-ssl-key.pem', 'utf8'),
    cert: fs.readFileSync('valid-ssl-cert.pem', 'utf8')
  },
  target: 'https://localhost:9010',
  secure: true
}).listen(443);

To support WebSockets, you must set ws: true in the proxy options. You also need to listen for the 'upgrade' event on your HTTP server and manually call proxy.ws(req, socket, head) to pipe the WebSocket connection.

var http = require('http'),
    httpProxy = require('http-proxy');

var proxy = new httpProxy.createProxyServer({
  target: {
    host: 'localhost',
    port: 9015
  },
  ws: true
});

var proxyServer = http.createServer(function (req, res) {
  proxy.web(req, res);
});

// Handle WebSocket upgrades
proxyServer.on('upgrade', function (req, socket, head) {
  proxy.ws(req, socket, head);
});

proxyServer.listen(8015);

Upgrading from http-proxy@0.x.x to http-proxy@1.0 (and later 1.x.x versions) involves breaking changes because the 1.0+ versions are a from-scratch implementation. Key changes include new methods for server creation, proxying (web vs websocket), and the removal of the built-in Middleware and ProxyTable APIs in favor of external modules or custom implementations.

// Example of the new server creation pattern in 1.x.x
httpProxy.createServer({
  target:'http://localhost:9003'
}).listen(8003);

To create a simple proxy that listens on a specific port and forwards all traffic to a target, use createProxyServer with a target option and call .listen().

var http = require('http'),
    httpProxy = require('http-proxy');

// Create your proxy server and set the target in the options.
// Invoking listen(..) triggers the creation of a web server.
httpProxy.createProxyServer({target:'http://localhost:9000'}).listen(8000);

// Create your target server for testing
http.createServer(function (req, res) {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.write('request successfully proxied!' + '\n' + JSON.stringify(req.headers, true, 2));
  res.end();
}).listen(9000);

You can handle errors in two ways:

1. Globally: Listen for the error event on the proxy instance. The callback receives (err, req, res).
2. Locally: Pass a callback as the last parameter to the .web() or .ws() methods.

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

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.');
});