[doc api test] Rename HttpProxy.pause to HttpProxy.resume. Update...

[doc api test] Rename HttpProxy.pause to HttpProxy.resume. Update documentation and tests accordingly

README.md

@@ -47,11 +47,14 @@ See the [demo](http://github.com/nodejitsu/node-http-proxy/blob/master/demo.js)
 <pre>
   var http = require('http'),
       httpProxy = require('http-proxy');
-
+  //
   // Create your proxy server
+  //
   httpProxy.createServer(9000, 'localhost').listen(8000);
 
+  //
   // 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));
@@ -63,11 +66,15 @@ See the [demo](http://github.com/nodejitsu/node-http-proxy/blob/master/demo.js)
 <pre>
   var http = require('http'),
       httpProxy = require('http-proxy');
-
-  // create a proxy server with custom application logic
+      
+  //
+  // Create a proxy server with custom application logic
+  //
   httpProxy.createServer(function (req, res, proxy) {
+    //
     // Put your custom server logic here
-    proxy.proxyRequest(9000, 'localhost');
+    //
+    proxy.proxyRequest(req, res, 9000, 'localhost');
   }).listen(8000);
 
   http.createServer(function (req, res) {
@@ -81,13 +88,23 @@ See the [demo](http://github.com/nodejitsu/node-http-proxy/blob/master/demo.js)
 <pre>
   var http = require('http'),
       httpProxy = require('http-proxy');
-
-  // create a proxy server with custom application logic
+  
+  //
+  // Create a proxy server with custom application logic
+  //
   httpProxy.createServer(function (req, res, proxy) {
+    //
+    // Buffer the request so that `data` and `end` events
+    // are not lost during async operation(s).
+    //
+    var buffer = proxy.buffer(req);
+    
+    //
     // Wait for two seconds then respond: this simulates
     // performing async actions before proxying a request
+    //
     setTimeout(function () {
-      proxy.proxyRequest(9000, 'localhost');      
+      proxy.proxyRequest(req, res, 9000, 'localhost', buffer);      
     }, 2000);
   }).listen(8000);
 
@@ -102,15 +119,20 @@ See the [demo](http://github.com/nodejitsu/node-http-proxy/blob/master/demo.js)
 <pre>
   var http = require('http'),
       httpProxy = require('http-proxy');
-
-  // create a regular http server and proxy its handler
+      
+  //
+  // Create a new instance of HttProxy to use in your server
+  //
+  var proxy = new httpProxy.HttpProxy();
+
+  //
+  // Create a regular http server and proxy its handler
+  //
   http.createServer(function (req, res) {
-    // Create a new instance of HttProxy for this request
-    // each instance is only valid for serving one request
-    var proxy = new httpProxy.HttpProxy(req, res);
-    
+    //
     // Put your custom server logic here, then proxy
-    proxy.proxyRequest(9000, 'localhost', req, res);
+    //
+    proxy.proxyRequest(req, res, 9000, 'localhost');
   }).listen(8001);
 
   http.createServer(function (req, res) {

bin/node-http-proxy

@@ -9,7 +9,7 @@ var path = require('path'),
 var help = [
     "usage: node-http-proxy [options] ",
     "",
-    "All options should be set with the syntax --option=value",
+    "Starts a node-http-proxy server using the specified command-line options",
     "",
     "options:",
     "  --port   PORT       Port that the proxy server should run on",
@@ -20,8 +20,7 @@ var help = [
 ].join('\n');
 
 if (argv.h || argv.help || Object.keys(argv).length === 2) {
-  util.puts(help);
-  process.exit(0);
+  return util.puts(help);
 }
 
 var location, config = {},

demo.js

@@ -59,9 +59,9 @@ util.puts('http proxy server '.blue + 'started '.green.bold + 'on port '.blue +
 // Http Proxy Server with Latency
 //
 httpProxy.createServer(function (req, res, proxy) {
-  var paused = proxy.pause(req);
+  var buffer = proxy.buffer(req);
   setTimeout(function() {
-    proxy.proxyRequest(req, res, 9000, 'localhost', paused);
+    proxy.proxyRequest(req, res, 9000, 'localhost', buffer);
   }, 200)
 }).listen(8002);
 util.puts('http proxy server '.blue + 'started '.green.bold + 'on port '.blue + '8002 '.yellow + 'with latency'.magenta.underline);
@@ -82,9 +82,9 @@ util.puts('http proxy server '.blue + 'started '.green.bold + 'on port '.blue +
 //
 var standAloneProxy = new httpProxy.HttpProxy();
 http.createServer(function (req, res) {
-  var paused = standAloneProxy.pause(req);
+  var buffer = standAloneProxy.buffer(req);
   setTimeout(function() {
-    proxy.proxyRequest(req, res, 9000, 'localhost', paused);
+    proxy.proxyRequest(req, res, 9000, 'localhost', buffer);
   }, 200);
 }).listen(8004);
 util.puts('http server '.blue + 'started '.green.bold + 'on port '.blue + '8004 '.yellow + 'with proxyRequest handler'.cyan.underline + ' and latency'.magenta);

lib/node-http-proxy.js

@@ -69,8 +69,16 @@ exports.setMaxSockets = function (value) {
 };
 
 //
-// ### function createServer ([port, host, options], handler)
-// 
+// ### function createServer ([port, host, options, handler])
+// #### @port {number} **Optional** Port to use on the proxy target host.
+// #### @host {string} **Optional** Host of the proxy target.
+// #### @options {Object} **Optional** Options for the HttpProxy instance used
+// #### @handler {function} **Optional** Request handler for the server
+// Returns a server that manages an instance of HttpProxy. Flexible arguments allow for:
+//
+// * `httpProxy.createServer(9000, 'localhost')`
+// * `httpProxy.createServer(9000, 'localhost', options)
+// * `httpPRoxy.createServer(function (req, res, proxy) { ... })`
 //
 exports.createServer = function () {
   var args, callback, port, host, forward, 
@@ -172,7 +180,7 @@ var HttpProxy = exports.HttpProxy = function (options) {
 util.inherits(HttpProxy, events.EventEmitter);
 
 //
-// ### function pause (obj) 
+// ### function buffer (obj) 
 // #### @obj {Object} Object to pause events from
 // Pause `data` and `end` events on the given `obj`.
 // Consumers of HttpProxy performing async tasks 
@@ -180,9 +188,9 @@ util.inherits(HttpProxy, events.EventEmitter);
 // the async operation has completed, otherwise these
 // __events will be lost.__
 //
-//      var pause = httpProxy.pause(req);
+//      var buffer = httpProxy.buffer(req);
 //      fs.readFile(path, function(){
-//         httpProxy.proxyRequest(req, res, host, port, paused);
+//         httpProxy.proxyRequest(req, res, host, port, buffer);
 //      });
 //
 // __Attribution:__ This approach is based heavily on 
@@ -191,7 +199,7 @@ util.inherits(HttpProxy, events.EventEmitter);
 // This simply chooses to manage the scope of  the events on a new Object literal as opposed to
 // [on the HttpProxy instance](https://github.com/nodejitsu/node-http-proxy/blob/v0.3.1/lib/node-http-proxy.js#L154).
 //
-HttpProxy.prototype.pause = function (obj) {
+HttpProxy.prototype.buffer = function (obj) {
   var onData, onEnd, events = [];
 
   obj.on('data', onData = function (data, encoding) {
@@ -231,9 +239,9 @@ HttpProxy.prototype.close = function () {
 // #### @res {ServerResponse} Outgoing HTTP Request to write proxied data to.
 // #### @port {number} **Optional** Port to use on the proxy target host.
 // #### @host {string} **Optional** Host of the proxy target.
-// #### @paused {Object} **Optional** Result from `httpProxy.pause(req)`
+// #### @buffer {Object} **Optional** Result from `httpProxy.buffer(req)`
 //
-HttpProxy.prototype.proxyRequest = function (req, res, port, host, paused) {
+HttpProxy.prototype.proxyRequest = function (req, res, port, host, buffer) {
   var self = this, reverseProxy, location, errState = false;
   
   //
@@ -258,11 +266,11 @@ HttpProxy.prototype.proxyRequest = function (req, res, port, host, paused) {
     // When using the ProxyTable in conjunction with an HttpProxy instance
     // only the following arguments are valid:
     // 
-    // * `proxy.proxyRequest(req, res, port, host, paused)`: This will be skipped
-    // * `proxy.proxyRequest(req, res, paused)`: Paused will get updated appropriately
+    // * `proxy.proxyRequest(req, res, port, host, buffer)`: This will be skipped
+    // * `proxy.proxyRequest(req, res, buffer)`: Buffer will get updated appropriately
     // * `proxy.proxyRequest(req, res)`: No effect `undefined = undefined` 
     //
-    paused = port;
+    buffer = port;
     port = location.port;
     host = location.host;
   }
@@ -297,7 +305,7 @@ HttpProxy.prototype.proxyRequest = function (req, res, port, host, paused) {
     headers: req.headers
   }, function (response) {
     
-    // Process the reverse_proxy response when it's received.
+    // Process the reverseProxy response when it's received.
     if (response.headers.connection) {
       if (req.headers.connection) response.headers.connection = req.headers.connection;
       else response.headers.connection = 'close';
@@ -345,11 +353,18 @@ HttpProxy.prototype.proxyRequest = function (req, res, port, host, paused) {
     }
   });
 
-  if (paused && !errState) {
-    paused.resume();
+  // If we have been passed buffered data, resume it.
+  if (buffer && !errState) {
+    buffer.resume();
   }
 };
   
+//
+// ### @private function _forwardRequest (req)
+// #### @req {ServerRequest} Incoming HTTP Request to proxy.
+// Forwards the specified `req` to the location specified
+// by `this.options.forward` ignoring errors and the subsequent response.
+//
 HttpProxy.prototype._forwardRequest = function (req) {
   var self = this, port, host, forwardProxy;
 

test/helpers.js

@@ -100,7 +100,7 @@ TestRunner.prototype.startProxyServer = function (port, targetPort, host, callba
 TestRunner.prototype.startLatentProxyServer = function (port, targetPort, host, latency, callback) {
   // Initialize the nodeProxy and start proxying the request
   var that = this, proxyServer = httpProxy.createServer(function (req, res, proxy) {
-    var data = proxy.pause(req);
+    var data = proxy.buffer(req);
     
     setTimeout(function () {
       proxy.proxyRequest(req, res, targetPort, host, data);
@@ -133,9 +133,9 @@ TestRunner.prototype.startProxyServerWithTableAndLatency = function (port, laten
   // Initialize the nodeProxy and start proxying the request
   var proxyServer, that = this, proxy = new httpProxy.HttpProxy(options);
   proxyServer = http.createServer(function (req, res) {
-    var paused = proxy.pause(req);
+    var buffer = proxy.buffer(req);
     setTimeout(function () {
-      proxy.proxyRequest(req, res, paused);
+      proxy.proxyRequest(req, res, buffer);
     }, latency);
   });