caronte-proxy

Caronte Proxy (caronte-proxy)

What's this for?

Caronte is my answer to the need of hosting a feature-rich-enough HTTP Proxy in NodeJS.

I have tons of NodeJS code that has to deal with Proxies, and such code needs testing. I started digging, and I found many libraries to build proxies (like the famous http-proxy), but no "out of the box" solutions that fit my needs.

So I made one.

This is in no way something you want to use in production: this Proxy is built for testing and I haven't spent a second checking memory consumption nor performance. This Proxy is to provide you with a testing ground: so my focus is on adding typical commercial Proxy features, rather then being production-ready.

Some features include:

• Support for HTTP and HTTPS proxying
• Support for HTTPS (it uses a self-signed certificate by default, but you can provide one)
• Support for Proxy Basic HTTP Authentication

Eventually I'd like to add SOCKS support but it's not an urgent need of mine, so it can wait. Maybe you will build that!

Setup

var options = {};
var caronteProxy = require('caronte-proxy')(options, function (req, res, err) {
  if (!err) {
    console.log('A soul has approached Caronte with a coin for its journey...');
  } else {
    console.error('A soul has approached Caronte without a coin, so it\'s going to remain in Limbo for ethernity...');
  }
});

caronteProxy.on('listening', function () {
  console.log('Caronte is ready to carry new souls across the Acheronte...');
});

caronteProxy.listen(6666);

And here is how the default options look like:

const defaultProxyOptions = {
  key: fs.readFileSync(__dirname + '/lib/proxy.selfsigned.key'),    //< TLS key to be used for HTTPS proxying (default: built-in self signed key)
  cert: fs.readFileSync(__dirname + '/lib/proxy.selfsigned.cert'),  //< TLS certificate to be used for HTTPS proxying (default: built-in self signed certificate)
  httpAgent: false,       //< http.Agent to use for HTTP traffic (default: 'false', i.e. no Agent, no socket reuse)
  httpsAgent: false,      //< https.Agent to use for HTTPS traffic (default: 'false', i.e. no Agent, no socket reuse)
  auth: false             //< Example value: { username: USERNAME, password: PASSWORD[, realm: USED_ONLY_IF_NOT_EMPTY]}
};

Any of those properties can be overridden.

Agents and testing in NodeJS itself

If you are testing code that involves setting/manipulating the NodeJS Agents and Global Agents, it's important that the options httpAgent and httpsAgent are left to false: this will ensure that the communication though the proxy will not directed to the Node default Global Agents, making your code very hard to test.

In other words, avoid Agent inception.

Debugging

Caronte uses the NPM module debug, so debugging is trivial: just set the ENV variable DEBUG to caronte:*.

Something like:

DEBUG=caronte:* npm test

Check out debug for more fine tuning.

"Caronte"?

In Greek mythology, Charon or Kharon (/ˈkɛərɒn/ or /ˈkɛərən/; Greek Χάρων; Italian Caronte) is the ferryman of Hades who carries souls of the newly deceased across the rivers Styx and Acheron that divided the world of the living from the world of the dead.

Credit for this awesome name goes to Antonio Pironti, friend and currently colleague.

Disclaimer

This project is heavily inspired by cloudberry, but I forked away because I needed it to:

• Run on more than just latest NodeJS
• Avoid using the Global Agent, and instead create for every request a fresh connection
• Support for HTTP Basic Authentication
• Ability to override the HTTP(s) Agent used by the Proxy
• Debug-ability

If you are after a Proxy written with latest NodeJS bells and wissle, you should check cloudberry out.

License

Apache 2.0 (txt)