CHANGELOG.md

@@ -0,0 +1,10 @@
+## ChangeLog for: node-http-proxy
+
+### Version 0.3.1 - 11/22/2010
+- Added node-http-proxy binary script                      (indexzero)
+- Added experimental WebSocket support                     (indutny)
+- Added forward proxy functionality                        (indexzero)
+- Added proxy table for multiple target lookup             (indexzero)
+- Simplified tests using helpers.js                        (indexzero)
+- Fixed uncaughtException bug with invalid proxy target    (indutny)
+- Added configurable logging for HttpProxy and ProxyTable  (indexzero) 

LICENSE

@@ -1,7 +1,7 @@
 
   node-http-proxy
 
-  Copyright (c) 2010 Charlie Robbins, Mikeal Rogers, & Marak Squires
+  Copyright (c) 2010 Charlie Robbins, Mikeal Rogers, Fedor Indutny, & Marak Squires
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the

README.md

@@ -9,6 +9,8 @@
 - reverse-proxies incoming http.Server requests
 - can be used as a CommonJS module in node.js
 - uses event buffering to support application latency in proxied requests
+- can proxy based on simple JSON-based configuration
+- forward proxying based on simple JSON-based configuration
 - minimal request overhead and latency
 - fully-tested
 - battled-hardened through production usage @ [nodejitsu.com][0]
@@ -29,23 +31,35 @@ Let's suppose you were running multiple http application servers, but you only w
   npm install http-proxy
 </pre>
 
-### How to setup a basic proxy server
+## Using node-http-proxy
+
+There are several ways to use node-http-proxy; the library is designed to be flexible so that it can be used by itself, or in conjunction with other node.js libraries / tools:
+
+1. Standalone HTTP Proxy server
+2. Inside of another HTTP server (like Connect)
+3. In conjunction with a Proxy Routing Table
+4. As a forward-proxy with a reverse proxy 
+5. From the command-line as a long running process
+
+See the [demo](http://github.com/nodejitsu/node-http-proxy/blob/master/demo.js) for further examples.
+
+### Setup a basic stand-alone proxy server
 <pre>
   var http = require('http'),
       httpProxy = require('http-proxy');
 
+  // Create your proxy server
   httpProxy.createServer(9000, 'localhost').listen(8000);
 
-  http.createServer(function (req, res){
+  // Create your target server
+  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);
 </pre>
 
-See the [demo](http://github.com/nodejitsu/node-http-proxy/blob/master/demo.js) for further examples.
-
-### How to setup a proxy server with custom server logic
+### Setup a stand-alone proxy server with custom server logic
 <pre>
   var http = require('http'),
       httpProxy = require('http-proxy');
@@ -56,58 +70,103 @@ See the [demo](http://github.com/nodejitsu/node-http-proxy/blob/master/demo.js)
     proxy.proxyRequest(9000, 'localhost');
   }).listen(8000);
 
-  http.createServer(function (req, res){
+  http.createServer(function (req, res) {
     res.writeHead(200, {'Content-Type': 'text/plain'});
     res.write('request successfully proxied: ' + req.url +'\n' + JSON.stringify(req.headers, true, 2));
     res.end();
   }).listen(9000);
 </pre>
 
-### How to setup a proxy server with latency (e.g. IO, etc)
+### Setup a stand-alone proxy server with latency (e.g. IO, etc)
 <pre>
   var http = require('http'),
       httpProxy = require('http-proxy');
 
   // create a proxy server with custom application logic
   httpProxy.createServer(function (req, res, proxy) {
-    // Wait for two seconds then respond
+    // Wait for two seconds then respond: this simulates
+    // performing async actions before proxying a request
     setTimeout(function () {
       proxy.proxyRequest(9000, 'localhost');      
     }, 2000);
   }).listen(8000);
 
-  http.createServer(function (req, res){
+  http.createServer(function (req, res) {
     res.writeHead(200, {'Content-Type': 'text/plain'});
     res.write('request successfully proxied: ' + req.url +'\n' + JSON.stringify(req.headers, true, 2));
     res.end();
   }).listen(9000);
 </pre>
 
-### How to proxy requests with a regular http server
+### Proxy requests within another http server
 <pre>
   var http = require('http'),
       httpProxy = require('http-proxy');
 
   // create a regular http server and proxy its handler
-  http.createServer(function (req, res){
+  http.createServer(function (req, res) {
     // Create a new instance of HttProxy for this request
     // each instance is only valid for serving one request
-    // 
-    // Don't worry benchmarks show the object 
-    // creation is lightning fast 
     var proxy = new httpProxy.HttpProxy(req, res);
 
     // Put your custom server logic here, then proxy
     proxy.proxyRequest(9000, 'localhost', req, res);
   }).listen(8001);
 
-  http.createServer(function (req, res){
+  http.createServer(function (req, res) {
     res.writeHead(200, {'Content-Type': 'text/plain'});
     res.write('request successfully proxied: ' + req.url +'\n' + JSON.stringify(req.headers, true, 2));
     res.end();
   }).listen(9000); 
 </pre>
 
+### Proxy requests using a ProxyTable
+A Proxy Table is a simple lookup table that maps incoming requests to proxy target locations. Take a look at an example of the options you need to pass to httpProxy.createServer:
+<pre>
+  var options = {
+    router: {
+      'foo.com': '127.0.0.1:8001',
+      'bar.com': '127.0.0.1:8002'
+    }
+  };
+</pre> 
+
+The above route table will take incoming requests to 'foo.com' and forward them to '127.0.0.1:8001'. Likewise it will take incoming requests to 'bar.com' and forward them to '127.0.0.1:8002'. The routes themselves are later converted to regular expressions to enable more complex matching functionality. We can create a proxy server with these options by using the following code:
+<pre>
+  var proxyServer = httpProxy.createServer(options);
+  proxyServer.listen(80);
+</pre>
+
+### Proxy requests with an additional forward proxy
+Sometimes in addition to a reverse proxy, you may want your front-facing server to forward traffic to another location. For example, if you wanted to load test your staging environment. This is possible when using node-http-proxy using similar JSON-based configuration to a proxy table: 
+<pre>
+  var proxyServerWithForwarding = httpProxy.createServer(9000, 'localhost', {
+    forward: {
+      port: 9000,
+      host: 'staging.com'
+    }
+  });
+  proxyServerWithForwarding.listen(80);
+</pre> 
+
+The forwarding option can be used in conjunction with the proxy table options by simply including both the 'forward' and 'router' properties in the options passed to 'createServer'.
+
+### Using node-http-proxy from the command line
+When you install this package with npm, a node-http-proxy binary will become available to you. Using this binary is easy with some simple options:
+<pre>
+  usage: node-http-proxy [options] 
+
+  All options should be set with the syntax --option=value
+
+  options:
+    --port   PORT       Port that the proxy server should run on
+    --target HOST:PORT  Location of the server the proxy will target
+    --config OUTFILE    Location of the configuration file for the proxy server
+    --silent            Silence the log output from the proxy server
+    -h, --help          You're staring at it
+</pre>
+
+<br/>
 ### Why doesn't node-http-proxy have more advanced features like x, y, or z?
 
 If you have a suggestion for a feature currently not supported, feel free to open a [support issue](http://github.com/nodejitsu/node-http-proxy/issues). node-http-proxy is designed to just proxy http requests from one server to another, but we will be soon releasing many other complimentary projects that can be used in conjunction with node-http-proxy.
@@ -117,7 +176,7 @@ If you have a suggestion for a feature currently not supported, feel free to ope
 
 (The MIT License)
 
-Copyright (c) 2010 Charlie Robbins, Mikeal Rogers, & Marak Squires
+Copyright (c) 2010 Charlie Robbins, Mikeal Rogers, Fedor Indutny, & Marak Squires
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

bin/node-http-proxy

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+var path = require('path'),
+    fs = require('fs'),
+    util  = require('util'),
+    argv = require('optimist').argv,
+    httpProxy = require('./../lib/node-http-proxy');
+
+var help = [
+    "usage: node-http-proxy [options] ",
+    "",
+    "All options should be set with the syntax --option=value",
+    "",
+    "options:",
+    "  --port   PORT       Port that the proxy server should run on",
+    "  --target HOST:PORT  Location of the server the proxy will target",
+    "  --config OUTFILE    Location of the configuration file for the proxy server",
+    "  --silent            Silence the log output from the proxy server",
+    "  -h, --help          You're staring at it"
+];
+
+if (argv.h || argv.help || Object.keys(argv).length === 2) {
+  util.puts(help.join('\n'));
+  process.exit(0);
+}
+
+var location, config = {},
+    port = argv.port || 80, 
+    target = argv.target;
+
+//
+// If we were passed a config, parse it
+//
+if (argv.config) {
+  try {
+    var data = fs.readFileSync(argv.config);
+    config = JSON.parse(data.toString());
+  } catch (ex) {
+    util.puts('Error starting node-http-proxy: ' + ex);
+    process.exit(1);
+  }
+}
+
+//
+// Check to see if we should silence the logs
+//
+config.silent = typeof argv.silent !== 'undefined' ? argv.silent : config.silent;
+
+//
+// If we were passed a target, parse the url string
+//
+if (target) location = target.split(':');
+
+//
+// Create the server with the specified options
+//
+var server;
+if (location) {
+  var targetPort = location.length === 1 ? 80 : location[1];
+  server = httpProxy.createServer(targetPort, location[0], config);
+}
+else {
+  server = httpProxy.createServer(config);
+}
+
+//
+// Start the server
+//
+server.listen(port);
+
+//
+// Notify that the server is started
+//
+if (!config.silent) {
+  util.puts('node-http-proxy server now listening on port: ' + port);
+}

config.sample.json

@@ -0,0 +1,10 @@
+{
+  "silent": false,
+  "router": {
+    "localhost": "localhost:9000"
+  },
+  "forward": {
+    "port": 9001,
+    "host": "localhost"
+  }
+}

demo.js

@@ -1,7 +1,7 @@
 /*
   demo.js: http proxy for node.js
 
-  Copyright (c) 2010 Charlie Robbins & Marak Squires http://github.com/nodejitsu/node-http-proxy
+  Copyright (c) 2010 Charlie Robbins, Mikeal Rogers, Fedor Indutny, & Marak Squires.
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -24,7 +24,7 @@
 
 */
 
-var sys = require('sys'),
+var util = require('util'),
     colors = require('colors')
     http = require('http'),
     httpProxy = require('./lib/node-http-proxy');
@@ -37,35 +37,75 @@ var welcome = '\
 #    #   #     #   #####        #####  #####  #    #   ##     #   \n\
 #    #   #     #   #            #      #   #  #    #  #  #    #   \n\
 #    #   #     #   #            #      #    #  ####  #    #   #   \n';
-sys.puts(welcome.rainbow.bold);
+util.puts(welcome.rainbow.bold);
 
 
-/****** basic http proxy server ******/ 
+//
+// Basic Http Proxy Server
+//
 httpProxy.createServer(9000, 'localhost').listen(8000);
-sys.puts('http proxy server'.blue + ' started '.green.bold + 'on port '.blue + '8000'.yellow);
+util.puts('http proxy server'.blue + ' started '.green.bold + 'on port '.blue + '8000'.yellow);
 
-/****** http proxy server with latency******/ 
-httpProxy.createServer(function (req, res, proxy){
-  setTimeout(function(){
+//
+// Http Proxy Server with Proxy Table
+//
+httpProxy.createServer({
+  router: {
+    'localhost': 'localhost:9000'
+  }
+}).listen(8001);
+util.puts('http proxy server '.blue + 'started '.green.bold + 'on port '.blue + '8001 '.yellow + 'with proxy table'.magenta.underline)
+
+//
+// Http Proxy Server with Latency
+//
+httpProxy.createServer(function (req, res, proxy) {
+  setTimeout(function() {
     proxy.proxyRequest(9000, 'localhost');
   }, 200)
-}).listen(8001);
-sys.puts('http proxy server '.blue + 'started '.green.bold + 'on port '.blue + '8001 '.yellow + 'with latency'.magenta.underline );
+}).listen(8002);
+util.puts('http proxy server '.blue + 'started '.green.bold + 'on port '.blue + '8002 '.yellow + 'with latency'.magenta.underline);
+
+//
+//
+//
+httpProxy.createServer(9000, 'localhost', {
+  forward: {
+    port: 9001,
+    host: 'localhost'
+  }
+}).listen(8003);
+util.puts('http proxy server '.blue + 'started '.green.bold + 'on port '.blue + '8003 '.yellow + 'with forward proxy'.magenta.underline)
 
-/****** http server with proxyRequest handler and latency******/ 
-http.createServer(function (req, res){
+//
+// Http Server with proxyRequest Handler and Latency
+//
+http.createServer(function (req, res) {
   var proxy = new httpProxy.HttpProxy(req, res);
 
-  setTimeout(function(){
+  setTimeout(function() {
     proxy.proxyRequest(9000, 'localhost');
   }, 200);
-}).listen(8002);
-sys.puts('http server '.blue + 'started '.green.bold + 'on port '.blue + '8002 '.yellow + 'with proxyRequest handler'.cyan.underline + ' and latency'.magenta);
+}).listen(8004);
+util.puts('http server '.blue + 'started '.green.bold + 'on port '.blue + '8004 '.yellow + 'with proxyRequest handler'.cyan.underline + ' and latency'.magenta);
 
-/****** regular http server ******/ 
-http.createServer(function (req, res){
+//
+// Target Http Server
+//
+http.createServer(function (req, res) {
   res.writeHead(200, {'Content-Type': 'text/plain'});
   res.write('request successfully proxied to: ' + req.url + '\n' + JSON.stringify(req.headers, true, 2));
   res.end();
 }).listen(9000);
-sys.puts('http server '.blue + 'started '.green.bold + 'on port '.blue + '9000 '.yellow);
+util.puts('http server '.blue + 'started '.green.bold + 'on port '.blue + '9000 '.yellow);
+
+//
+// Target Http Forwarding Server
+//
+http.createServer(function (req, res) {
+  util.puts('Receiving forward for: ' + req.url)
+  res.writeHead(200, {'Content-Type': 'text/plain'});
+  res.write('request successfully forwarded to: ' + req.url + '\n' + JSON.stringify(req.headers, true, 2));
+  res.end();
+}).listen(9001);
+util.puts('http forward server '.blue + 'started '.green.bold + 'on port '.blue + '9001 '.yellow);