From 5dcdf2b36c24a9584f044b7529265b9ac861d8c7 Mon Sep 17 00:00:00 2001 From: cronopio Date: Fri, 20 Sep 2013 19:28:53 -0500 Subject: [PATCH] [doc] added some documentation to functions and comments to understand better the code --- lib/caronte/common.js | 17 +++++++++++++ lib/caronte/index.js | 9 +++++++ lib/caronte/passes/web-incoming.js | 11 ++++++++- lib/caronte/passes/web-outgoing.js | 38 ++++++++++++++++++++++++++++++ lib/caronte/passes/ws-incoming.js | 27 ++++++++++++++++++++- 5 files changed, 100 insertions(+), 2 deletions(-) diff --git a/lib/caronte/common.js b/lib/caronte/common.js index 6b75c6f..2b9d436 100644 --- a/lib/caronte/common.js +++ b/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); diff --git a/lib/caronte/index.js b/lib/caronte/index.js index ef0187f..c3bb69f 100644 --- a/lib/caronte/index.js +++ b/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); diff --git a/lib/caronte/passes/web-incoming.js b/lib/caronte/passes/web-incoming.js index ce494fe..1c1a6b9 100644 --- a/lib/caronte/passes/web-incoming.js +++ b/lib/caronte/passes/web-incoming.js @@ -91,6 +91,7 @@ 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') ); @@ -98,15 +99,19 @@ function stream(req, res, options) { 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'); diff --git a/lib/caronte/passes/web-outgoing.js b/lib/caronte/passes/web-outgoing.js index 48ff12d..abdaec9 100644 --- a/lib/caronte/passes/web-outgoing.js +++ b/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); } diff --git a/lib/caronte/passes/ws-incoming.js b/lib/caronte/passes/ws-incoming.js index e5bdcf6..ca2b668 100644 --- a/lib/caronte/passes/ws-incoming.js +++ b/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); });