Basic v0.2 functionality complete. Lots of dox strings added.

Justin Slattery · Justin Slattery · commit 65e3fb977bbc · 2011-03-24T21:49:02.000-07:00
diff --git a/core.js b/core.js
@@ -1,55 +1,69 @@
-var express = require('express')
-    , app = express.createServer()
-    , connect = require('connect')
-    , jade = require('jade')
-    , socket = require('socket.io').listen(app)
-    , _ = require('underscore')._
+/*!
+ * nodechat.js
+ * Copyright(c) 2011 Justin Slattery <justin.slattery@fzysqr.com> 
+ * MIT Licensed
+ */
+
+/**
+ * Include core dependencies.  
+ */
+var _ = require('underscore')._
     , Backbone = require('backbone')
-    , models = require('./models/models')
+
+/**
+ * Include our own modules
+ */
+var models = require('./models/models')
     , auth = require('./lib/auth');
 
+/**
+ * Require redis and setup the client 
+ */
 var redis = require('redis')
     , rc = redis.createClient()
-    , redisStore = require('connect-redis');
 
 rc.on('error', function(err) {
     console.log('Error ' + err);
 });
 
+/**
+ * Setup connect, express, socket, and the connect-redis session store
+ */
+var express = require('express')
+    , app = express.createServer()
+    , connect = require('connect')
+    , jade = require('jade')
+    , socket = require('socket.io').listen(app)
+    , redisStore = require('connect-redis');
 
-//configure express to use jade
 app.set('view engine', 'jade');
 app.set('view options', {layout: false});
-
-//configure express to use redis as session store
 app.use(express.bodyParser());
 app.use(express.cookieParser());
 app.use(express.session({ store: new redisStore(), secret: 'Secretly I am an elephant' }));
 
-
-//setup routes
-app.get('/logout', function(req, res){
-    // destroy the user's session to log them out
-    // will be re-created next request
-    req.session.destroy(function(){
-        res.redirect('home');
-    });
-});
-
+/**
+ * Route: GET /login
+ *
+ * Template: login.jade 
+ */
 app.get('/login', function(req, res){
     res.render('login');
 });
 
-
+/**
+ * Route: POST /login
+ *
+ * Calls the authentication module to verify login details. Failures are redirected back to the login page.
+ *
+ * If the authentication module gives us a user object back, we ask connect to regenerate the session and send the client back to index. Note: we specify a _long_ cookie age so users won't have to log in frequently. We also set the httpOnly flag to false (I know, not so secure) to make the cookie available over [Flash Sockets](http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/net/Socket.html).
+ */ 
 app.post('/login', function(req, res){
     auth.authenticateUser(req.body.username, req.body.password, function(err, user){
         if (user) {
-            // Regenerate session when signing in
-            // to prevent fixation 
+            // Regenerate session when signing in to prevent fixation 
             req.session.regenerate(function(){
-                // Store the user's primary key 
-                // in the session store to be retrieved,
-                // or in this case the entire user object
+                // Store the user's primary key in the session store to be retrieved, or in this case the entire user object
                 console.log('regenerated session id ' + req.session.id);
                 req.session.cookie.maxAge = 100 * 24 * 60 * 60 * 1000; //Force longer cookie age
                 req.session.cookie.httpOnly = false;
@@ -65,13 +79,23 @@ app.post('/login', function(req, res){
     });
 });
 
+/**
+ * Route: GET /signup:
+ *
+ * Template: signup.jade
+ */
 app.get('/signup', function(req, res){
     res.render('signup');
 });
 
+/**
+ * Route: POST /signup
+ *
+ * Calls createNewUserAccount() in the auth module, redirects to /login if a user object is returned. Redirects to /signup if not.
+ */
 app.post('/signup', function(req, res) {
     auth.createNewUserAccount(req.body.username, req.body.password1, req.body.password2, req.body.email, req.body.ponies, function(err, user){
-        if (err) {
+        if ((err) || (!user)) {
             req.session.error = 'New user failed, please check your username and password.';
             res.redirect('back');
         }
@@ -82,17 +106,45 @@ app.post('/signup', function(req, res) {
 
 });
 
+/**
+ *  Tell connect to destory the session.
+ */
+
+app.get('/logout', function(req, res){
+    req.session.destroy(function(){
+        res.redirect('home');
+    });
+});
+
+
+/**
+ * Serve up any static file requested by the client
+ *
+ * TODO: should restrict this to only server *public* routes.
+ */
 app.get('/*.(js|css)', function(req, res){
     res.sendfile('./'+req.url);
 });
 
+/**
+ * Server up the main index view. 
+ *
+ * Calls the restrictAccess() middleware.
+ *
+ *
+ *
+ */
 app.get('/', restrictAccess, function(req, res){
     res.render('index', {
         locals: { name: req.session.user.name, hashPass: JSON.stringify(req.session.user.hashPass) }
     });
 });
 
-//This method decides what a valid login looks like. In this case, just verify that we have a session object for the user
+/**
+ *  Middleware that decides what a valid login looks like. In this case, just verify that we have a session object for the user.
+ *
+ *  This is an express [route middleware](http://expressjs.com/guide.html#route-middleware). Control is passed to the middleware function before the route function is called. We use restrictAccess() to verify that we have a valid user key in the session, implying that authentication has succeeded, before we send the client to the index.jade template. If we do not have a valid user in the session, then we redirect to the '/login' route. This effectively locks down our '/' route from unauthenticated access. You could add the restrictAccess() all to any route you want to protect.
+ */
 function restrictAccess(req, res, next) {
     if (req.session.user) {
         next();
@@ -107,17 +159,28 @@ function restrictAccess(req, res, next) {
 var activeClients = 0;
 var nodeChatModel = new models.NodeChatModel();
 
-
+/**
+ * When we have a client that shouldn't be connected, __kick 'em off!__' 
+ * 
+ * @param {object} client
+ * @param {function} fn
+ */
 function disconnectAndRedirectClient(client, fn) {
     console.log('Disconnecting unauthenticated user');
     client.send({ event: 'disconnect' });
     client.connection.end();
-    fn();
-    return;
+    return fn();
 }
 
+/*
+ *
+ * Handle the new connection event for socket. 
+ * 
+ * connectSession() is a helper method that will verify a client's validity by checking for a cookie in the request header, then, if we find it,  _pulling their session out of redis_. 
+ *
+ * We then use the helper method in the 'connection' handler for our socket listener. Instead accepting any user connection, we are going to check that the client has a valid session (meaning they logged in). If they don't, give them the boot! If they do, then we store a copy of the session data (yay we have access!) in the client object and then setup the rest of the socket events. Finally, send them a welcome message just to prove that we remembered their profile. 
+ */
 socket.on('connection', function(client){
-    // helper function that goes inside your socket connection
     client.connectSession = function(fn) {
         if (!client.request || !client.request.headers || !client.request.headers.cookie) {
             disconnectAndRedirectClient(client,function() {
@@ -149,6 +212,8 @@ socket.on('connection', function(client){
             return;
         }
 
+        client.user = data.user;
+
         activeClients += 1;
         client.on('disconnect', function(){clientDisconnect(client)});
         client.on('message', function(msg){chatMessage(client, socket, msg)});
@@ -169,6 +234,13 @@ socket.on('connection', function(client){
     });
 });
 
+/*
+ * Event handler for new chat messages. Stores the chat in redis and broadcasts it to all connected clients.
+ * 
+ * @param {object} client
+ * @param {object} socket
+ * @param {json string} msg
+ */
 function chatMessage(client, socket, msg){
     var chat = new models.ChatEntry();
     chat.mport(msg);
@@ -177,7 +249,7 @@ function chatMessage(client, socket, msg){
         chat.set({id: newId});
         nodeChatModel.chats.add(chat);
         
-        var expandedMsg = chat.get('id') + ' ' + chat.get('name') + ': ' + chat.get('text');
+        var expandedMsg = chat.get('id') + ' ' + client.user.name + ': ' + chat.get('text');
         console.log('(' + client.sessionId + ') ' + expandedMsg);
 
         rc.rpush('chatentries', chat.xport(), redis.print);
@@ -190,9 +262,17 @@ function chatMessage(client, socket, msg){
     }); 
 }
 
+/*
+ * Event handler for client disconnectes. Simply broadcasts the new active client count.
+ * 
+ * @param {object} client
+ */
 function clientDisconnect(client) {
     activeClients -= 1;
     client.broadcast({clients:activeClients})
 }
 
+/**
+ * Fire up the webserver 
+ */
 app.listen(8000)
diff --git a/lib/auth.js b/lib/auth.js
@@ -1,12 +1,15 @@
-/* Auth.js 
+/*! Auth.js 
  *
  * Handles new user accounts and authentication
- *
  */
 
+/*
+ * This will be a [CommonJS module](http://www.commonjs.org/) so we need to start off with some setup. 
+ *
+ * Here we are checking to see if this code is included as a module. If it is, we go ahead and include our dependencies (in this case, our models lib, redis, and hash + friends). If we are not a module, we may as well explode because the rest of the code won't run without redis and hash.
+ */
 (function () {
     if (typeof exports !== 'undefined') {
-        auth = exports;
         redis = require('redis');
         rc = redis.createClient();
         models = require('../models/models');
@@ -17,10 +20,18 @@
         require('hash');
     } 
     else {
-        auth = this.auth = {};
+        throw new Error('auth.js must be loaded as a module.');
     }
 
-    auth.authenticateUser = function(name, pass, fn) {
+    /**
+     * Checks to see if the user exists in redis. If it does, it calls verifyUserAccount(). Otherwise callback with an error.
+     *
+     * @param: {string} name
+     * @param: {string} pass
+     * @param: {function} fn
+     * @api: public
+     */
+    exports.authenticateUser = function(name, pass, fn) {
         console.log('[authenticate] Starting auth for ' + name + ' with password ' + pass);
         
         var rKey = 'user:' + name;
@@ -32,42 +43,74 @@
             }
             else {
                 console.log('[authenticateUser] user: ' + name + ' found in store. Verifying password.');
-                auth.verifyUserAccount(data, pass, fn)
+                verifyUserAccount(data, pass, fn)
             }
         });
     };
 
-    auth.verifyUserAccount = function(foundUserName, pass, fn) {
+    /**
+     * Steps through the process of retreiving the salt, calculating the hash of the passed in password, then comparing it to the stored hash in redis.
+     *
+     * If successful, create a new user model and pass it to the callback.
+     *
+     * Otherwise, any failure along the way means we callback with an error.
+     * 
+     * Assumes the passed in user exists in redis. 
+     *
+     * @param: {string} foundUserName
+     * @param: {string} pass
+     * @param: {function} fn
+     * @api: private
+     */
+    var verifyUserAccount = function(foundUserName, pass, fn) {
         var rKey = 'user:' + foundUserName;
 
         rc.get(rKey + '.salt', function(err, data){
             if(err) return fn(new Error('[verifyUserAccount] GET failed for key: ' + rKey + '.salt')); 
 
-            var calculatedHash = Hash.sha512(data + '_' + pass);
-            rc.get(rKey + '.hashPass', function(err, data) {
-                if(err) return fn(new Error('[verifyUserAccount] GET failed for key: ' + rKey + '.hashPass'));
+            if(data) {
+                var calculatedHash = Hash.sha512(data + '_' + pass);
+                rc.get(rKey + '.hashPass', function(err, data) {
+                    if(err) return fn(new Error('[verifyUserAccount] GET failed for key: ' + rKey + '.hashPass'));
 
-                if (calculatedHash === data) {
-                    console.log('[verifyUserAccount] Auth succeeded for ' + foundUserName + ' with password ' + pass);
+                    if (calculatedHash === data) {
+                        console.log('[verifyUserAccount] Auth succeeded for ' + foundUserName + ' with password ' + pass);
 
-                    rc.get(rKey + '.profile', function(err, data) {
-                        if(err) return fn(new Error('[verifyUserAccount] GET failed for key: ' + rKey + '.profile' + ' for user profile'));
+                        rc.get(rKey + '.profile', function(err, data) {
+                            if(err) return fn(new Error('[verifyUserAccount] GET failed for key: ' + rKey + '.profile' + ' for user profile'));
 
-                        var foundUser = new models.User();
-                        foundUser.mport(data);
-                        foundUser.set({'hashPass': calculatedHash});
+                            var foundUser = new models.User();
+                            foundUser.mport(data);
+                            foundUser.set({'hashPass': calculatedHash});
 
-                        return fn(null, foundUser);
-                    });
-                }
-                else {
-                    return fn(new Error('invalid password'));
-                }
-            });
+                            return fn(null, foundUser);
+                        });
+                    }
+                    else {
+                        return fn(new Error('[verifyUserAccount] invalid password'));
+                    }
+                });
+            }
+            else {
+                return fn(new Error('[verifyUserAccount] salt not found'));
+            }
         });
     }
 
-    auth.createNewUserAccount = function(name, pass1, pass2, email, ponies, fn) {
+    /**
+     * Verifies that the two passwords match, then use the current timestamp to salt a hash of the password. Store it all in a user model which we will save as a poor man's profile if everything succeeds.
+     *
+     * Any failure along the way means we callback with an error.
+     * 
+     * @param: {string} name
+     * @param: {string} pass1
+     * @param: {string} pass2
+     * @param: {string} email
+     * @param: {string} ponies
+     * @param: {function} fn
+     * @api: public
+     */
+    exports.createNewUserAccount = function(name, pass1, pass2, email, ponies, fn) {
         if (pass1 !== pass2) return fn(new Error('[createNewUserAccount] Passwords do not match'));
 
         var newUser = new models.User({name: name, email: email, ponies: ponies});
diff --git a/nodechat.html b/nodechat.html
