From 27c16114d55233b591b6c2107f8138f18cf22188 Mon Sep 17 00:00:00 2001 From: Bram van der Veen <96aa48@gmail.com> Date: Sun, 16 Aug 2015 01:37:27 +0200 Subject: [PATCH] Did a big bunch of documenting the code [PART 1]. --- api.js | 26 +++++++++++++++++++ auth.js | 32 ++++++++++++++++++++++- configuration.js | 8 +++++- crypt.js | 67 ++++++++++++++++++++++++++++++------------------ database.js | 11 +++++++- lookup.js | 58 ++++++++++++++++++++++++++++++++++++----- redirecter.js | 8 ++++++ schedule.js | 35 ++++++++++++++++++------- 8 files changed, 201 insertions(+), 44 deletions(-) diff --git a/api.js b/api.js index c4d2d97..fde42ae 100644 --- a/api.js +++ b/api.js @@ -1,7 +1,17 @@ //api.js + +//Importing self-written modules. var lookup = require('./lookup'); var schedule = require('./schedule'); +/** + * Takes the information from the request + * and tries to return information. + * @param {Object} req - Request object supplied by Express. + * @param {Object} res - Response object supplied by Express. + * @param {Function} next - Next function supplied by Express. + * @param {String} api - Type of API request supplied by the user. + */ function parse(req, res, next, api) { req.api = true; @@ -32,6 +42,14 @@ function parse(req, res, next, api) { } } +/** + * Returns an error to the user when the request + * was unable to complete. + * @param {String} str - The error message to display. + * @param {Object} res - Reponse object supplied by Express. + * @param {Function} next - Next function supplied by Express. + * @return {null} + */ function error(str, res, data) { res.set('Content-Type', 'application/json'); var error = JSON.stringify({'error' : str, 'data' : data}, null, 2); @@ -39,6 +57,13 @@ function error(str, res, data) { return; } +/** + * Sends a response to the user that did an API request. + * @param {Object} data - Data object with requested data. + * @param {Object} res - Response object supplied by Express. + * @param {Bool} disablePretty - Boolean to disable pretty printing of the response. + * @return {null} + */ function sendResponse(data, res, disablePretty) { res.set('Content-Type', 'application/json'); var response = JSON.stringify({'data': data}, null, disablePretty ? 0 : 2); @@ -46,4 +71,5 @@ function sendResponse(data, res, disablePretty) { return; } +//Exporting the parse function as a module. module.exports = parse; diff --git a/auth.js b/auth.js index 026c116..753dedd 100644 --- a/auth.js +++ b/auth.js @@ -1,11 +1,20 @@ -//authv2.js +//auth.js + +//Importing first and third-party modules. var qs = require('querystring'); var https = require('socks5-https-client'); +//Importing self-written modules. var crypt = require('./crypt'); var config = require('./configuration'); var lookup = require('./lookup'); +/** + * Function for starting a login request with the Magister servers. + * @param {String} username - Username needed for login. + * @param {String} password - Password needed for login. + * @param {Function} callback - Callback function to be called after request. + */ function getLogin(username, password, callback) { var login = qs.stringify({ GebruikersNaam : username, @@ -29,6 +38,14 @@ function getLogin(username, password, callback) { }).write(login); } +/** + * Function for doing a login to the rooster.io server + * this is being called by the web frontend when the + * user logs in. + * @param {Object} req - Request object supplied by Express. + * @param {Object} res - Response object supplied by Express. + * @param {Function} next - Next function supplied by Express. + */ function login(req, res, next) { var _data = ''; @@ -52,12 +69,24 @@ function login(req, res, next) { }); } +/** + * Function for logging a user out + * of a session on rooster.io. + * @param {Object} req - Request object supplied by Express. + * @param {Object} res - Response object supplied by Express. + */ function logout(req, res) { res.cookie('username', ''); res.cookie('password', ''); res.redirect('/'); } +/** + * Function for checking if the user is currently authenticated. + * @param {Object} req - Request object supplied by Express. + * @param {Object} res - Response object supplied by Express. + * @param {Function} next - Next function supplied by Express. + */ function is(req, res, next) { var cookies = qs.parse((req.headers.cookie || '').replace(/\s/g, ''), ';', '='); if (!cookies.username || !cookies.password) {next(); return;} @@ -79,6 +108,7 @@ function is(req, res, next) { }); } +//Exporting the functions as a module. module.exports = { 'login' : login, 'logout' : logout, diff --git a/configuration.js b/configuration.js index c453d5e..e4ba731 100644 --- a/configuration.js +++ b/configuration.js @@ -1,7 +1,12 @@ //configuration.js + +//Import first-party modules. var fs = require('fs'); -//Function for loading and returning the settings.json file, makes one if there isn't one. +/** + * Module for the return/creating of a settings file/object. + * @return {Object} settings - Object of all the settings. + */ module.exports = function () { if (!fs.existsSync(__dirname + '/settings.json')) { //Template for settings.json if not available. @@ -39,6 +44,7 @@ module.exports = function () { } } +//Testing command when passed a test argument in the commandline if (process.argv[2] == 'test') { console.log(module.exports()); } diff --git a/crypt.js b/crypt.js index 553db26..d2d6746 100644 --- a/crypt.js +++ b/crypt.js @@ -1,35 +1,52 @@ +//crypt.js + +//Import first-party modules. var crypto = require('crypto'); -var clearEncoding = 'utf8'; -var cipherEncoding = 'hex'; +//Set local variables. +var encoding = 'utf8'; +var cryptEncoding = 'hex'; var algo = 'aes192'; -var passwd = 'thisaintnosensitivedataatalldontreadthisorillgetmadatyourfaceyoumofo'; +var passwd = 'JMU6DAQpzt32hJ2WndJxFvk3WHWqFcscq9yMMYkr8kgTtsam'; -module.exports = { - encrypt : function (str) { - var cipher = crypto.createCipher(algo, passwd); - var cipherChunks = []; +//Prepare the ciphering and deciphering. +var cipher = crypto.createCipher(algo, passwd); +var decipher = crypto.createDecipher(algo, passwd); - cipherChunks.push(cipher.update(str, clearEncoding, cipherEncoding)); - cipherChunks.push(cipher.final(cipherEncoding)); +/** + * Function for encrypting a string. + * @param {String} str - String that you want to encrypt. + * @return {String} encryptArray - Encrypted string. + */ +function encrypt(str) { + var encryptArray = []; - return cipherChunks[1]; - }, - decrypt : function (str) { - str = [str]; - var plainChunks = []; - try { - var decipher = crypto.createDecipher(algo, passwd); + encryptArray.push(cipher.update(str, encoding, cryptEncoding)); + encryptArray.push(cipher.final(cryptEncoding)); - for (var i = 0;i < str.length;i++) { - plainChunks.push(decipher.update(str[i], cipherEncoding, clearEncoding)); - } + return encryptArray.join(''); +} - plainChunks.push(decipher.final(clearEncoding)); - return plainChunks.join(''); - } - catch (err) { - return str.join(''); - } +/** + * Function to decrypt a string. + * @param {String} str - String you want to decrypt + */ +function decrypt(str) { + var decryptArray = []; + + try { + decryptArray.push(decipher.update(str, cryptEncoding, encoding)); + decryptArray.push(decipher.final(encoding)); + + return decryptArray.join(''); + } + catch (err) { + return str.join(''); } } + +//Export the functions as a module. +module.exports = { + 'encrypt': encrypt, + 'decrypt': decrypt +} diff --git a/database.js b/database.js index 15ac4fb..9cae635 100644 --- a/database.js +++ b/database.js @@ -1,7 +1,16 @@ //database.js -var config = require('./configuration'); + +//Import first-party modules. var fs = require('fs'); +//Import self-written modules. +var config = require('./configuration'); + +/** + * Module for using a database interface. + * Either local (NeDB) or remote (MongoDB). + * @return {Object} database - Entire database engine (NeDB/MongoDB). + */ module.exports = function () { if (!config().localDatabase) return require('mongoskin').db('mongodb://' + config().database); else { diff --git a/lookup.js b/lookup.js index 240e54f..76577f7 100644 --- a/lookup.js +++ b/lookup.js @@ -1,13 +1,23 @@ //lookup.js -//Getting local variables via the configuration file. -var config = require('./configuration'); -var schoolID = config().schoolID; - -//Getting first and third party modules +//Importing first-party modules. var fs = require('fs'); + +//Importing self-written modules. +var config = require('./configuration'); var database = require('./database')(); +//Getting local variables from the configuration file. +var schoolID = config().schoolID; + +/** + * Function for doing a lookup in the database containing all records + * of students, teachers and classrooms. + * @param {Object} req - Request object supplied by Express. + * @param {Object} res - Response object supplied by Express. + * @param {Function} next - Next function supplied by Express. + * @param {String} search - The search query given by the user. + */ function get(req, res, next, search) { var index = database.collection('index'); easter(search) ? req.easter = easter(search) : null; @@ -28,6 +38,13 @@ function get(req, res, next, search) { } } +/** + * Function for handling a lookup request after it has(n't) found matches. + * @param {Object} req - Request object supplied by Express. + * @param {Object} res - Response object supplied by Express. + * @param {Function} next - Next function supplied by Express. + * @param {Array} databaseEntry - The search query given by the user. + */ function handle(req, res, next, databaseEntry) { if ((req.easter || {}).type == 'RIP') { require('./auth').is(req, res, function () { @@ -52,6 +69,11 @@ function handle(req, res, next, databaseEntry) { } } +/** + * Function for doing a lookup via the API. + * @param {Object} req - Request object supplied by Express.s. + * @param {Function} callback - Callback function needed to return the API call. + */ function api(req, callback) { var index = database.collection('index'); var query = RegExp(req.query.name, 'i'); @@ -65,6 +87,13 @@ function api(req, callback) { }); } +/** + * Function for listing all of the students in a group. + * @param {Object} req - Request object supplied by Express. + * @param {Object} res - Response object supplied by Express. + * @param {Function} next - Next function supplied by Express. + * @param {String} list - The search (group) query given by the user. + */ function list(req, res, next, list) { var index = database.collection('index'); var query = RegExp(list, 'i'); @@ -81,6 +110,12 @@ function list(req, res, next, list) { }); } +/** + * Function for making an url based on the found database match. + * @param {Object} req - Request object supplied by Express. + * @param {Array} databaseEntry - The database object used to create the url. + * @return {String} url - The url that was created. + */ function makeUrl(req, databaseEntry) { var url = 'http://roosters5.gepro-osi.nl/roosters/rooster.php?school=' + schoolID + '&type=' + databaseEntry.type.charAt(0).toUpperCase() + databaseEntry.type.slice(1) + 'rooster'; @@ -107,6 +142,10 @@ function makeUrl(req, databaseEntry) { return url; } +/** + * Function for checking if the requested search query has an easteregg. + * @param {String} search - The user supplied search query. + */ function easter(search) { var list = JSON.parse(fs.readFileSync(__dirname + '/eastereggs.json')); @@ -117,9 +156,14 @@ function easter(search) { return null; } -module.exports = {'get': get, 'api': api, 'list': list}; +//Export the functions as a module. +module.exports = { + 'get': get, + 'api': api, + 'list': list +}; //Testing function, if test is passed in the command line will execute a test. if (process.argv[2] == "test") { - console.log(easter('aardappel')); + console.log(easter('lord of the memeries')); } diff --git a/redirecter.js b/redirecter.js index 07505c2..5c5bc4b 100644 --- a/redirecter.js +++ b/redirecter.js @@ -1,6 +1,14 @@ //redirecter.js + +//Import first-party modules. var qs = require('querystring'); +/** + * Module for redirecting the user after they did a search query in any of the + * search forms. + * @param {Object} req - Request object supplied by Express. + * @param {Object} res - Response object supplied by Express. + */ module.exports = function (req, res) { var referer = req.headers.referer.split('/')[3] || 'rooster'; var _data = ''; diff --git a/schedule.js b/schedule.js index c134e8b..e287c81 100644 --- a/schedule.js +++ b/schedule.js @@ -1,21 +1,28 @@ //schedule.js -var http = require('socks5-http-client'); -var cheerio = require('cheerio'); -var config = require('./configuration'); + +//Import first-party modules. var url = require('url'); -//Wrapper function that is being called by express. +//Import third-party modules. +var http = require('socks5-http-client'); +var cheerio = require('cheerio'); + +//Import self-written modules. +var config = require('./configuration'); + +/** + * Function being called by Express when the user requests a schedule. + * @param {Object} req - Request object supplied by Express. + * @param {Object} res - Response object supplied by Express. + * @param {Function} next - Next function supplied by Express. + */ function get(req, res, next) { getSchedule(req.match.url, function (json) { req.match.json = json; next(); }); } - -function api(lookup, callback) { - getSchedule(lookup.data[0].url, callback); -} - +//FIXME: GO ON WITH THE REST OF THE DOCUMENTATION. //Function for getting the page via http. function getSchedule(getUrl, callback) { var options = url.parse(getUrl); @@ -91,5 +98,15 @@ function toJSON(page) { return scheduleData; } +/** + * Function for doing a lookup in the database containing all records + * of students, teachers and classrooms. + * @param {Object} lookup - Object with all of the information from the request. + * @param {Function} callback - Callback function for the API module. + */ +function api(lookup, callback) { + getSchedule(lookup.data[0].url, callback); +} + //Exporting the schedule function. module.exports = {'get': get, 'api': api};