lemonade/kernel/kernel.js

/******************************************************************************
 * Lemonade JS
 * https://lemonadejs.com
 *
 * ----
 *
 * KERNEL
 *
 *   Holds links to adaptors and daemons, main methods for including modules,
 *   logging (stdout and stderr), emits and listens for various events.
 *
 *   Has 3 run levels : boot, run, shutdown.
 *
 *   When constructed, it requires:
 *
 *    - configuration object that will hold constants available
 *      everywhere via "this.kernel.config.*"
 *
 *    - an object for each runlevel containing what "links" are created
 *      in each respective runlevel. All links will be available in the
 *      same manner as the configuration object via "this.linkname"
 *
 * @param {object} config
 * @param {object} boot
 * @param {object} run
 * @param {object} shutdown
 * @param {string} loglevel
 *
 *****************************************************************************/

function Kernel (config, boot, run, shutdown, loglevel) {
    /**
     * Set the loglevel
     */
    if (loglevel !== this.LOGLEVEL_DEBUG &&
        loglevel !== this.LOGLEVEL_NORMAL &&
        loglevel !== this.LOGLEVEL_QUIET) {
        loglevel =   this.LOGLEVEL_NORMAL;
    }
    this.loglevel = loglevel;
    /**
     * Get the appdir
     */
    this.appdir = process.cwd() + '/';
    /**
     * Attach utility methods
     */
    this.utility = this.include(this.kerneldir + 'utility').singleton();
    /**
     * Merge config properties
     */
    this.config = this.include(this.kerneldir + 'config').singleton();
    if (config) {
        for (var key in config) {
            this.config[key] = config[key];
        }
    }
    this.debug(
        'merged config : \n' + util.inspect(this.config, { depth : 0 })
        , this._debugfile
    );
    /**
     * Say hello
     */
    if (this.loglevel !== this.LOGLEVEL_QUIET) {
        console.log();
        console.log(this.utility.ansi('yellow', this.config.project));
        console.log();
    }
    /**
     * Fetch the link scripts
     */
    this._fetchlinks();
    /**
     * Attach listeners
     */
    this._listen();
    /**
     * Say hello 2
     */
    this.log('Lemonade '   + this.version + ' (' + this.name + ')');
    this.log('app path : ' + this.appdir);
    /**
     * Check logpath
     */
    if (!fs.existsSync(this.config.logpath)) {
        try {
            fs.mkdirSync(this.config.logpath);
            this.log(
                'creating log path : ' + this.config.logpath + ' - ' +
                this.utility.ansi('green', 'ok')
            );
        } catch (e) {
            this.error(
                new Error('Failed to create log path : ' + e)
            );
        }
    } else {
        this.log('log path : ' + this.config.logpath);
    }
    /**
     * Attach the links to the kernel and prepare their loaders
     */
    var links = { boot : boot, run : run, shutdown : shutdown };
    this.debug(
        'preparing to attach links : \n' + util.inspect(links)
        , this._debugfile
    );
    for (var level in links) {
        for (var link in links[level]) {
            this._attach(
                link, links[level][link], level
            );
        }
    }
    this.debug(
        'kernellinks : \n' + util.inspect(this._kernellinks, { depth : 3 })
        , this._debugfile
    );
    /**
     * Loops and switches runlevels when needed
     */
    this._heartbeat();
}

/**
 * Module dependencies
 */
var
        events   =  require('events')
    ,   util     =  require('util')
    ,   fs       =  require('fs')
    ,   os       =  require('os')
    ,   include  =  require('./include.js');

/**
 * Add emitter methods to the Kernel
 */
util.inherits(Kernel, events.EventEmitter);

/**
 * Kernel version
 * @type {string}
 */
Kernel.prototype.version = require('../package.json').version;

/**
 * Kernel major version name
 * @type {string}
 */
Kernel.prototype.name = 'Chrysanths';

/**
 * Event that will be emitted on each heartbeat loop. Should be useful
 * for apps that use lemonade to check that it's still running
 * @type {string}
 */
Kernel.prototype.HEARTBEAT = 'hearbeat';

/**
 * Event that will be emitted once the kernel goes into runlevel run and
 * all links are ready
 * @type {string}
 */
Kernel.prototype.ONLINE  = 'kernel-online';

/**
 * Event that will be emitted once the kernel has gracefully shut down
 * @type {string}
 */
Kernel.prototype.OFFLINE = 'kernel-offline';

/**
 * The kernel will listen for log or error events and call the appropriate
 * methods : kernel.log / .error / .fatal. Used for asyncing the log/error
 * operations. For sync calls the kernel methods can be accessed directly.
 * @type {string}
 */
Kernel.prototype.LOG   = 'log';
Kernel.prototype.ERROR = 'error';
Kernel.prototype.FATAL = 'fatal-error';

/**
 * Event emitted when a link successfully loads or unloads
 * @type {string}
 * @private
 */
Kernel.prototype._LINK_READY = 'link-ready';

/**
 * Kernel runlevels
 * @private
 */
Kernel.prototype._RUNLEVEL_0         = 0;
Kernel.prototype._RUNLEVEL_BOOT      = 'boot';
Kernel.prototype._RUNLEVEL_RUN       = 'run';
Kernel.prototype._RUNLEVEL_SHUTDOWN  = 'shutdown';
Kernel.prototype._currentrunlevel    = 0;

/**
 * Kernel dir
 * @type {string}
 */
Kernel.prototype.kerneldir = __dirname + '/';

/**
 * Application dir
 * @type {string}
 */
Kernel.prototype.appdir = '';

/**
 * Configuration link
 * @type {}
 */
Kernel.prototype.config = {};

/**
 * Utility link
 * @type {}
 */
Kernel.prototype.utility = {};

/**
 * Loglevels
 * @type {string}
 */
Kernel.prototype.LOGLEVEL_DEBUG  = 'loglevel-debug';
Kernel.prototype.LOGLEVEL_NORMAL = 'loglevel-normal';
Kernel.prototype.LOGLEVEL_QUIET  = 'loglevel-quiet';
Kernel.prototype.loglevel = '';

/**
 * Kernel debug file
 * @type {string}
 * @private
 */
Kernel.prototype._debugfile = 'kernel.debug';

/**
 * Available link scripts (contents of appdir/links)
 * @private
 */
Kernel.prototype._availablelinks = {};

/**
 * Kernel links stuctured to be loaded based on runlevel
 * @private
 */
Kernel.prototype._kernellinks = {
    /**
     * Each kernellink is loaded via a loader script. Each loader script
     * object is included and stored under the kernel link key in its
     * corresponding runlevel
     */
        0        : { } // pre-boot
    ,   boot     : { }
    ,   run      : { }
    ,   shutdown : { }
};

/**
 * Links queued to be loaded for current runlevel
 * @private
 */
Kernel.prototype._queuedfornow = {};

/**
 * Heartbeat interval id
 * @private
 */
Kernel.prototype._heartbeatintv;

/**
 * Include a class file, overload it to contain instantiating
 * methods, bind the kernel and instance object if available
 *
 *  Depending on path's content type (extension based for now),
 * a separate includer will be used. See ./include.js and ./include/*
 *
 * @param {string} path
 * @return {function}
 */
Kernel.prototype.include = function(path) {
    return include(path, this, this);
};

/**
 * Gather up statuses from the kernel and all loaded modules
 * @return {}
 */
Kernel.prototype.status = function() {

    var  memory = process.memoryUsage()
        ,status = {};

    status.kernel = {

         hostname : os.hostname
        ,memory   : {
             heapUsed  : memory.heapUsed
            ,heapTotal : memory.heapTotal
        }
        ,load     : os.loadavg()
        ,node     : process.version
        ,lemonade : {
             version : this.version
            ,name    : this.name
        }

    };

    for (var level in this._kernellinks) {
        for (var link in this._kernellinks[level]) {
            var linkstatus = this._kernellinks[level][link].obj.status();
            if (linkstatus) {
                status[link] = linkstatus;
            } else {
                status[link] = '';
            }
        }
    }

    return status;
};

/**
 * Initiate graceful shutdown
 * @param {string} message
 */
Kernel.prototype.shutdown = function(message) {
    this._runlevel(this._RUNLEVEL_SHUTDOWN, message);
};

/**
 * Generic replacement for console log with date
 * @param {string|Error} message
 * @param {string} file
 * @param {Date} date
 */
Kernel.prototype.log = function(message, file, date) {
    /**
     * Log the error stack if we got an Error object
     */
    if (message instanceof Error) {
        msg     =  this.utility.ansi('red', message.message);
        msg    += '\n\n\n' + message.stack + '\n\n';
        message = msg;
    } else if (this.loglevel === this.LOGLEVEL_QUIET) {
        return;
    }
    if (typeof file !== 'undefined') {
        var  date    = this.utility.date('yyyy-mm-dd HH:ii:ss', date)
            ,logfile = this.config.logpath + file + '.log';
        fs.appendFile(
            logfile
            ,date + ' ' + message + '\n'
            ,function() {}
        );
    } else {
        util.log(message);
    }
};

/**
 * Log an error message
 * @param {string|Error} error
 */
Kernel.prototype.error = function(error) {
    if (!(error instanceof Error)) {
        error = new Error('Unprefixed error : ' + error);
    }
    this.log(error);
};

/**
 * Log an error message and initiate shutdown
 * @param {string|Error} message
 */
Kernel.prototype.fatal = function(message) {
    this.error(message);
    this.shutdown('fatal error');
};

/**
 * Log a debug message (only if loglevel is set on debug)
 * If param is function executes it only if loglevel debug
 * @param {string|function} message
 * @param {string} optional logfile
 */
Kernel.prototype.debug = function(message, logfile) {
    if (this.loglevel === this.LOGLEVEL_DEBUG) {
        if (typeof message === 'function') {
            message();
        } else {
            this.log('DEBUG : ' + message, logfile);
        }
    }
};

/**
 * Fetch the link scripts (contents of appdir/links)
 * @private
 */
Kernel.prototype._fetchlinks = function() {
    var fetch = function(dir) {
        var arr = fs.readdirSync(dir);
        for (var i = 0, max = arr.length; i < max; i++) {
            var fname = arr[i].substring(0, arr[i].length-3);
            this._availablelinks[fname] = dir + '/' + fname;
        }
    }.bind(this);
    fetch(this.kerneldir + this.config._KERNEL_DIR_LINKS);
    this.debug(
        'base links : \n' + util.inspect(this._availablelinks)
        , this._debugfile
    );
    if (fs.existsSync(this.appdir + this.config._KERNEL_DIR_LINKS)) {
        fetch(this.appdir + this.config._KERNEL_DIR_LINKS);
        this.debug(
            'found custom links dir, read it and merged : \n'
            + util.inspect(this._availablelinks)
            , this._debugfile
        );
    }
};

/**
 * Switch or return the current runlevel
 * @private
 * @param {string} level
 * @param {string} message
 * @return {string}
 */
Kernel.prototype._runlevel = function(level, message) {
    /**
     * Just checking, return the current runlevel
     */
    if (!level || (level === this._currentrunlevel)) {
        return this._currentrunlevel;
    }
    /**
     * Setting a new runlevel
     */
    this._currentrunlevel = level;
    this.log(this.utility.ansi('blue',
         '[ '
            + this._currentrunlevel
            + ((message) ? ' - ' + message : '')
            +
         ' ]'
    ));
    /**
     * Callback to load/unload a link
     */
    var trigger = function(action, linkloader, linkname, level) {
        process.nextTick(function() {
            this._queuedfornow[linkname] = true;
            if (typeof linkloader.obj[action] === 'function') {
                try {
                    if (action === 'load') {
                        this.debug(
                            linkname + '.' + action + '(' + util.inspect(linkloader.loadparams) + ')'
                        );
                        /**
                         * Add a callback to the end of the params
                         * for the load method
                         */
                        linkloader.loadparams.push(function(err, msg) {
                            if (err) {
                                this.fatal(
                                    new Error('[ ' + level + ' ][1] Link error - ' + linkname + ' : ' + err)
                                );
                            } else {
                                /**
                                 * Module is ready, signal it
                                 */
                                delete this._queuedfornow[linkname];
                                this.emit(this._LINK_READY, linkname, msg);
                            }
                        }.bind(this));
                        linkloader.obj[action].apply(linkloader.obj, linkloader.loadparams);
                    } else {
                        this.debug(
                            linkname + '.' + action + '()'
                        );
                        linkloader.obj[action](function(err, msg) {
                            if (err) {
                                this.fatal(
                                    new Error('[ ' + level + ' ][3] Link error - ' + linkname + ' : ' + err)
                                );
                            } else {
                                delete this._queuedfornow[linkname];
                                this.emit(this._LINK_READY, linkname, msg);
                            }
                        }.bind(this));
                    }
                } catch (e) {
                    this.fatal(
                        new Error('[ ' + level + ' ][2] Link error - ' + linkname + ' : ' + e)
                    );
                }
            } else {
                /**
                 * Linkloader has no function defined for action, skip
                 */
                delete this._queuedfornow[linkname];
                this.emit(this._LINK_READY, linkname, 'skipping');
            }
        }.bind(this));
    }.bind(this);
    /**
     * On shutdown, loop through all existing unload methods
     */
    if (this._currentrunlevel === this._RUNLEVEL_SHUTDOWN) {
        for (var level in this._kernellinks) {
            if (level !== this._RUNLEVEL_SHUTDOWN) {
                var currentlinks = this._kernellinks[level];
                for (var link in currentlinks) {
                    trigger(
                        'unload'
                       ,currentlinks[link]
                       ,link
                       ,level
                    );
                }
            }
        }
    } else {
        /**
         * Loop through the queued links and try to load them
         */
        var currentlinks = this._kernellinks[this._currentrunlevel];
        for (var link in currentlinks) {
            trigger(
                 'load'
                ,currentlinks[link]
                ,link
                ,this._currentrunlevel
            );
        }
    }
};

/**
 * Internal loop, will switch runlevels when needed
 * @private
 */
Kernel.prototype._heartbeat = function () {
    /**
     * Start the interval if not running
     */
    if (!this._heartbeatintv) {
        this._heartbeatintv = setInterval(function() {
            this._heartbeat();
        }.bind(this), 1000);
    }
    /**
     * Check if there are any links needing load for the
     * current runlevel
     * @type {Array}
     */
    var left = Object.keys(this._queuedfornow);
    if (left.length > 0) {
        /**
         * Output links still waiting
         */
        this.log(
           'zZz waiting for links (' + this.utility.ansi('red', left.join(',')) + ')'
        );
    } else {
        /**
         * Current runlevel is completed, decide what to do next
         */
        switch (this._currentrunlevel) {
            case this._RUNLEVEL_0 :
                /**
                 * First heartbeat, should initiate boot
                 */
                this._runlevel(this._RUNLEVEL_BOOT);
                break;
            case this._RUNLEVEL_BOOT :
                /**
                 * Boot ready, move on
                 */
                this._runlevel(this._RUNLEVEL_RUN);
                break;
            case this._RUNLEVEL_RUN :
                /**
                 * We are running
                 */
                this.emit(this.ONLINE);
                break;
            case this._RUNLEVEL_SHUTDOWN :
                /**
                 * Shutdown complete, stop the heartbeat
                 */
                this.emit(this.OFFLINE);
                clearInterval(this._heartbeatintv);
                break;
        }
    }
    /**
     * Send out that it's still ticking
     */
    this.emit(this.HEARTBEAT);
};

/**
 * Listen for various events
 * @private
 */
Kernel.prototype._listen = function() {
    /**
     * Logs a message
     */
    this.on(this.LOG, function(message) {
        this.log(message);
    }.bind(this));
    /**
     * Logs an error message
     */
    this.on(this.ERROR, function(message) {
        this.error(message);
    }.bind(this));
    /**
     * Logs an error message and shuts down
     */
    this.on(this.FATAL, function(message) {
       this.fatal(message);
    }.bind(this));
    /**
     * Each link emits when ready
     */
    this.on(this._LINK_READY, function(link, msg) {
        this.log(
              this.utility.ansi('green', 'ok') + ' - '
            + link + (msg ? ' ' + msg : '')
        );
    }.bind(this));
};

/**
 * Attach a kernel link
 * @private
 * @param {string} key
 * @param {string|Array|object} value
 * @param {string|number} level
 */
Kernel.prototype._attach = function(key, value, level) {
    var linkloader = {}, module;
    /**
     * Direct declaration
     */
    if (typeof value === 'function') {
        this.debug(
            'attaching function ' + key + ' : \n' + value
            , this._debugfile
        );
        linkloader = value;
    }
    /**
     * Is the value one of the available link scripts?
     */
    else if (this._availablelinks[value] ||
            (value instanceof Array && this._availablelinks[value[0]])) {

        module = this.include(
            this._availablelinks[((value instanceof Array) ? value[0] : value)]
        );
        this.debug(
            'attaching availablelink ' + key +': \n' + util.inspect(module, { depth : 0 })
            , this._debugfile
        );
        if (module && typeof module.new === 'function') {
            linkloader = module.new();
        }
    }
    /**
     * Value is not one of the available modules, treat it
     * as a string and try to load the path
     */
    else if (fs.existsSync(this.appdir + value + '.js')) {
        try {
            module = this.include(this.appdir + value);
            this.debug(
                'attaching included module ' + key +': \n' + util.inspect(module, { depth : 0 })
                , this._debugfile
            );
            if (module && typeof module.new === 'function') {
                linkloader = module.new();
            }
        } catch (e) {
            this.error(
                new Error('Couldn\'t load ' + key + ' from ' + this.appdir + value + ' : ' +  e)
            );
        }
    }
    /**
     * Check the linkloader for the most important method
     */
    if (typeof linkloader.link === 'function') {
        var params = [];
        if (value instanceof Array) {
            for (var i = 1, max = value.length; i < max; i++) {
                params.push(value[i]);
            }
        }
        /**
         * Reference the object and load params
         */
        this._kernellinks[level][key] = {
            obj : linkloader, loadparams : params, ready : {}
        };
        /**
         * Bind the link method to the kernel
         */
        linkloader.label = key;
        this[key] = linkloader.link.bind(linkloader);
    } else {
        /**
         * Bad link loader, panic!
         */
        this.fatal(
            new Error('Invalid link : ' + key)
        );
    }
};

/**
 * Exports
 */
exports = module.exports = Kernel;