Documentation

Get some comments better
Coding style in some documents

Author: Ricardo Malta

bin/index.js

@@ -1,46 +1,35 @@
 #!/usr/bin/env node
 
-/**
- * Module dependencies.
- */
+// Module dependencies.
 const app = require('../lib/app');
 const debug = require('debug')('node-rethinkdb-echo:server');
 const http = require('http');
 const config = require('config');
 const log = require('../lib/logger').log('www');
 const socket = require('../lib/socket');
 
-/**
- * Get port from environment and store in Express.
- */
+ // Get port from environment and store in Express.
 const port = normalizePort(process.env.PORT || config.get('web.port'));
 app.set('port', port);
 
-/**
- * Create HTTP server.
- */
+ // Create HTTP server.
 const server = http.createServer(app);
 
-/**
- *  Create the Socket IO server
- */
+ // Create the Socket IO server
 socket(server, (err, res) => {
   if (err) {
     log.error(err);
   } else {
     log.info('Socket.io initialized successefully!');
   }
 });
-/**
- * Listen on provided port, on all network interfaces.
- */
+
+// Listen on provided port, on all network interfaces.
 server.listen(port, '0.0.0.0');
 server.on('error', onError);
 server.on('listening', onListening);
 
-/**
- * Normalize a port into a number, string, or false.
- */
+// Normalize a port into a number, string, or false.
 function normalizePort (val) {
   const port = parseInt(val, 10);
 
@@ -57,9 +46,7 @@ function normalizePort (val) {
   return false;
 }
 
-/**
- * Event listener for HTTP server "error" event.
- */
+// Event listener for HTTP server "error" event.
 function onError (error) {
   if (error.syscall !== 'listen') {
     throw error;
@@ -84,9 +71,7 @@ function onError (error) {
   }
 }
 
-/**
- * Event listener for HTTP server "listening" event.
- */
+// Event listener for HTTP server "listening" event.
 function onListening () {
   const addr = server.address();
   const bind = typeof addr === 'string'

config/nginx/site.conf

@@ -1,34 +1,33 @@
 upstream service {
-    server 127.0.0.1:9700;
+  server 127.0.0.1:9700;
 }
 
 server {
-        listen 443 ssl default_server;
-        server_name api.earfy.net;
+  listen 443 ssl default_server;
+  server_name api.earfy.net;
 
-        # ssl_certificate /etc/letsencrypt/live/MY_HOST_DOMAIN/fullchain.pem;
-        # ssl_certificate_key /etc/letsencrypt/live/MY_HOST_DOMAIN/privkey.pem;
+  # ssl_certificate /etc/letsencrypt/live/MY_HOST_DOMAIN/fullchain.pem;
+  # ssl_certificate_key /etc/letsencrypt/live/MY_HOST_DOMAIN/privkey.pem;
 
-        location / {
+  location / {
+    auth_basic "Restricted Content";
+    auth_basic_user_file /etc/nginx/.htpasswd;
 
-                auth_basic "Restricted Content";
-                auth_basic_user_file /etc/nginx/.htpasswd;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header Host $host;
+    proxy_set_header X-NginX-Proxy true;
 
-                proxy_set_header X-Real-IP $remote_addr;
-                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-                proxy_set_header Host $host;
-                proxy_set_header X-NginX-Proxy true;
+    proxy_pass http://service;
+    proxy_redirect off;
+  }
 
-                proxy_pass http://service;
-                proxy_redirect off;
-        }
-
-        location /socket.io {
-                proxy_set_header Upgrade $http_upgrade;
-                proxy_set_header Connection "upgrade";
-                proxy_http_version 1.1;
-                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-                proxy_set_header Host $host;
-                proxy_pass http://service;
-        }
+  location /socket.io {
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_http_version 1.1;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header Host $host;
+    proxy_pass http://service;
+  }
 }

lib/broker.js

@@ -3,14 +3,16 @@
 const log = require('./logger').log('broker');
 const EventEmitter = require('events').EventEmitter;
 
+// create and extends from the EventEmitter
 class Broker extends EventEmitter {
 
+  // ensure format and send messages to the listeners.
   send (event = 'unknown', room = 'public', message) {
     if (!message) {
       log.error('Nothing to send, aborting the event emit!');
       return;
     }
-
+    // just to ensure that the event looper is healthy.
     setImmediate(() => {
       this.emit(event, { room, message });
     });

lib/controllers/messages.js

@@ -9,13 +9,14 @@ const models = require('../models');
 router.post('/', function (req, res, next) {
   var objects = req.body || null;
 
+  // no objects in the http body, then let the user now that he is doing something wrong!
   if (objects == null) {
     res.status(400);
     return res.json({error: 'Invalid POST format.'});
   }
 
   var items = typeof objects === 'object' && objects instanceof Array ? objects : [objects];
-
+  // Before save the message items in the DB, lets do some checks to each one.
   async.each(items,
     function (item, next) {
       // enforce author to be a string without spaces
@@ -26,6 +27,7 @@ router.post('/', function (req, res, next) {
       if (typeof item.Room === 'string' && !item.Room.match(/^\w+$/)) {
         return next('Invalid room name!');
       }
+      // send the message to the model, in order to save it in the DB.
       models.messages.insert(item.Author, item.Room, item.Text, next);
     },
     function (err) {

lib/db.js

@@ -4,8 +4,10 @@ const log = require('./logger').log('db');
 const config = require('config');
 const thinky = require('thinky')(config.get('rethinkdb'));
 
+// expose the Thinky instance.
 exports.thinky = thinky;
 
+// use close to dispose the database connections properly (aka: gracefully shutdown).
 exports.close = (callback) => {
   thinky.r.getPoolMaster().on('log', log.info);
   thinky.r.getPoolMaster().drain();

lib/logger.js

@@ -4,11 +4,11 @@ const winston = require('winston');
 const expressWinston = require('express-winston');
 const loggers = {};
 
+// an abstration to wiston logger.
 exports.log = (name) => {
   if (loggers[name]) {
     return loggers[name];
   }
-
   loggers[name] = new winston.Logger({
     transports: [
       new winston.transports.Console({
@@ -25,6 +25,7 @@ exports.log = (name) => {
   return loggers[name];
 };
 
+// to HTTP
 exports.http = expressWinston.logger({
   transports: [
     new winston.transports.Console({

lib/models/messages.js

@@ -8,22 +8,30 @@ const r = thinky.r;
 
 // Define the Message model
 const Message = thinky.createModel('messages', {
+  // non optional string field with maximum 1024 caracthers.
   Text: type.string().max(1024).required(),
   Room: type.string().default('public'),
   CreateDate: type.date().default(r.now())
 });
 
 // Ensure the secondary indexes
+// optional, to get all messages form a user, its nice to have the proper index.
 Message.ensureIndex('Author');
+// mandatory to list the messages of a room.
 Message.ensureIndex('Room');
+// mandatory to order the results chronologically.
 Message.ensureIndex('CreateDate');
 
 // Message change feed registration and handling
+// Here is where the magic happens, every change in the message colletion will end up here.
+// this implementation is based on the Thinky syntax: https://thinky.io/documentation/feeds/
 Message.changes().then((changes) => {
+  // just in case...
   if (changes == null) {
     return;
   }
 
+  // the changes argument cames in a list of changes.
   return changes.each((err, message) => {
     if (err) {
       log.error(err);
@@ -36,38 +44,49 @@ Message.changes().then((changes) => {
     }
 
     log.info(message);
+    // send the message throught the intra-process message broker
     broker.send('message', message.Room, message);
   });
 }).error((error) => {
+  // if there is an error at this stage, it doesn't manner, just log it.
   log.error(error);
 });
 
+// List messages by room.
 exports.list = (room = 'public', callback) => {
+  // implememed using the Thinky model and the standard ReQL syntax to:
+  // Order, spefic room, limit to the last 50 (first step to pagination)
   Message
+    // Order by CreateDate descendently.
     .orderBy({index: r.desc('CreateDate')})
+    // Filter the results by the Room index
     .filter(r.row('Room').eq(room))
+    // Slice for the first 50 results. (use slice and skip to pagination)
     .slice(0, 50)
+    // ask for execute
     .run()
+    // after the promise is resolved
     .then((objects) => {
       return callback(null, objects);
     })
+    // if its rejected!
     .error((err) => {
       log.error(err);
       return callback(err);
     });
 };
 
-/*
-    TODO:
-    Check the room authorization
-*/
+// insert new messages.
 exports.insert = (user = 'Blaster', room = 'public', text, callback) => {
   // with the Message model, save a new message
   Message
+    // I just use a list, because I can. It could save a single object or a list of objects
     .save([
       { Author: user, Room: room, Text: text }
+      // after the promise is resolved
     ]).then((result) => {
       return callback(null, result);
+      // if its rejected!
     }).error((err) => {
       log.error(err);
       return callback(err);

lib/socket.js

@@ -5,6 +5,7 @@ const log = require('./logger').log('socket.io');
 const models = require('./models');
 const broker = require('./broker');
 
+// this is a business level abstration of the sockets.
 module.exports = (server, callback) => {
   let io;
   try {
@@ -14,7 +15,9 @@ module.exports = (server, callback) => {
     log.error(e);
     return callback(e);
   }
-
+  // everytime someone connects:
+  //  1. join the public room (private rooms perfectly possible).
+  //  2. receive the last few messages in the public channel.
   io.on('connection', (socket) => {
     socket.join('public');
     log.info(socket.id, 'connected');
@@ -30,6 +33,7 @@ module.exports = (server, callback) => {
     });
   });
 
+  // listen to every message send.
   broker.on('message', (data) => {
     log.info(`message to ${data.room} channel: ${data.message.Text}`);
     io.to(data.room).emit('messages', data.message);