[doc] added some documentation to functions and comments to understand better the code

Author: cronopio

lib/caronte/common.js

@@ -37,6 +37,23 @@ common.setupOutgoing = function(outgoing, options, req, forward) {
   return outgoing;
 };
 
+/**
+ * Set the proper configuration for sockets,
+ * set no delay and set keep alive, also set
+ * the timeout to 0.
+ *
+ * Examples:
+ *
+ *    common.setupSocket(socket)
+ *    // => Socket
+ *
+ * @param {Socket} Socket instance to setup
+ * 
+ * @return {Socket} Return the configured socket.
+ *
+ * @api private
+ */
+
 common.setupSocket = function(socket) {
   socket.setTimeout(0);
   socket.setNoDelay(true);

lib/caronte/index.js

@@ -65,6 +65,15 @@ function createRightProxy(type) {
 
       passes.some(function(pass) {
         var evnt = ev + pass.name.toLowerCase() + ':';
+
+        /**
+         * Call of passes functions
+         * pass(req, res, options, head)
+         *
+         * In WebSockets case the `res` variable
+         * refer to the connection socket
+         * pass(req, socket, options, head)
+         */
 
         options.ee.emit(evnt + 'begin', req, res); 
         var val = pass(req, res, options, head); 

lib/caronte/passes/web-incoming.js

@@ -91,22 +91,27 @@ function XHeaders(req, res, options) {
 
 function stream(req, res, options) {
   if(options.forward) {
+    // If forward enable, so just pipe the request
     var forwardReq = (options.forward.protocol === 'https:' ? https : http).request(
       common.setupOutgoing(options.ssl || {}, options, req, 'forward')
     );
     req.pipe(forwardReq);
     return res.end();
   }
 
+  // Request initalization
   var proxyReq = (options.target.protocol === 'https:' ? https : http).request(
     common.setupOutgoing(options.ssl || {}, options, req)
   );
 
+  // Error Handler
   proxyReq.on('error', function(err){
     var ev   = 'caronte:outgoing:web:';
+    // If no error listeners, so throw the error.
     if (options.ee.listeners(ev + 'error').length == 0){
         throw err;
     }
+    // Also emit the error events
     options.ee.emit(ev + 'error', err, req, res); 
   });
 
@@ -117,10 +122,14 @@ function stream(req, res, options) {
 
     options.ee.emit(ev + 'begin', req, res); 
 
+    // When the previous request respond, we apply the
+    // outgoing passes to the response
     web_o.some(function(pass) {
       var evnt = ev + pass.name.toLowerCase() + ':';
 
-      options.ee.emit(evnt + 'begin', req, res); 
+      options.ee.emit(evnt + 'begin', req, res);
+      // Call the pass with the proxy response
+      // pass(ClientRequest, IncomingMessage, proxyResponse)
       var val = pass(req, res, proxyRes); 
       options.ee.emit(evnt + 'end');
 

lib/caronte/passes/web-outgoing.js

@@ -10,12 +10,31 @@ var passes = exports;
 
 [ // <--
 
+  /**
+   * If is a HTTP 1.0 request, remove chunk headers
+   *
+   * @param {ClientRequest} Req Request object
+   * @param {IncomingMessage} Res Response object  
+   * @param {proxyResponse} Res Response object from the proxy request
+   *
+   * @api private
+   */
   function removeChunked(req, res, proxyRes) {
     if(req.httpVersion === '1.0') {
       delete proxyRes.headers['transfer-encoding'];
     }
   },
 
+  /**
+   * If is a HTTP 1.0 request, set the correct connection header
+   * or if connection header not present, then use `keep-alive`
+   *
+   * @param {ClientRequest} Req Request object
+   * @param {IncomingMessage} Res Response object  
+   * @param {proxyResponse} Res Response object from the proxy request
+   *
+   * @api private
+   */
   function setConnection(req, res, proxyRes) {
     if (req.httpVersion === '1.0') {
       if (req.headers.connection) {
@@ -31,12 +50,31 @@ var passes = exports;
     }
   },
 
+  /**
+   * Copy headers from proxyResponse to response
+   * set each header in response object.
+   *
+   * @param {ClientRequest} Req Request object
+   * @param {IncomingMessage} Res Response object  
+   * @param {proxyResponse} Res Response object from the proxy request
+   *
+   * @api private
+   */
   function writeHeaders(req, res, proxyRes) {
     Object.keys(proxyRes.headers).forEach(function(key) {
       res.setHeader(key, proxyRes.headers[key]);
     });
   },
 
+  /**
+   * Set the statusCode from the proxyResponse
+   *
+   * @param {ClientRequest} Req Request object
+   * @param {IncomingMessage} Res Response object  
+   * @param {proxyResponse} Res Response object from the proxy request
+   *
+   * @api private
+   */
   function writeStatusCode(req, res, proxyRes) {
     res.writeHead(proxyRes.statusCode);
   }

lib/caronte/passes/ws-incoming.js

@@ -22,6 +22,11 @@ var passes = exports;
 /**
  * WebSocket requests must have the `GET` method and
  * the `upgrade:websocket` header
+ *
+ * @param {ClientRequest} Req Request object
+ * @param {Socket} Websocket
+ *
+ * @api private
  */
 
 function checkMethodAndHeader (req, socket) {
@@ -35,8 +40,14 @@ function checkMethodAndHeader (req, socket) {
 },
 
 /**
- * Setup socket
+ * Set the proper configuration for sockets,
+ * set no delay and set keep alive, also set
+ * the timeout to 0.
  *
+ * @param {ClientRequest} Req Request object
+ * @param {Socket} Websocket
+ *
+ * @api private
  */
 
 function setupSocket(req, socket) {
@@ -49,6 +60,11 @@ function setupSocket(req, socket) {
 /**
  * Sets `x-forwarded-*` headers if specified in config.
  *
+ * @param {ClientRequest} Req Request object
+ * @param {Socket} Websocket
+ * @param {Object} Options Config object passed to the proxy
+ *
+ * @api private
  */
 
 function XHeaders(req, socket, options) {
@@ -69,8 +85,14 @@ function XHeaders(req, socket, options) {
 },
 
 /**
+ * Does the actual proxying. Make the request and upgrade it
+ * send the Switching Protocols request and pipe the sockets.
  *
+ * @param {ClientRequest} Req Request object
+ * @param {Socket} Websocket
+ * @param {Object} Options Config object passed to the proxy
  *
+ * @api private
  */
 function stream(req, socket, options, head) {
   common.setupSocket(socket);
@@ -81,11 +103,14 @@ function stream(req, socket, options, head) {
   var proxyReq = (~['https:', 'wss:'].indexOf(options.target.protocol) ? https : http).request(
     common.setupOutgoing(options.ssl || {}, options, req)
   );
+  // Error Handler
   proxyReq.on('error', function(err){
     var ev   = 'caronte:outgoing:ws:';
+    // If no error listeners, so throw the error.
     if (options.ee.listeners(ev + 'error').length == 0){
         throw err;
     }
+    // Also emit the error events
     options.ee.emit(ev + 'error', err, req, socket, head);
   });