ravel/dist/ravel.js

'use strict';

const AsyncEventEmitter = require('./util/event_emitter');
const coreSymbols = require('./core/symbols');
const Rest = require('./util/rest');

const sInitialized = Symbol('isInitialized');
const sListening = Symbol('isListening');
const sLog = Symbol('$log');
const sErr = Symbol('$err');
const sCWD = Symbol('cwd');
const sCallback = Symbol('callback');
const sServer = Symbol('server');
const sUncaughtRejections = Symbol('uncaughtRejections');
const sKeygripKeys = Symbol('keygripKeys');
const sKeygrip = Symbol('keygrip');

/**
                                     * This class provides Ravel, a lightweight but powerful framework
                                     * for the rapid creation of enterprise Node.js applications which
                                     * scale horizontally with ease and support the latest in web technology.
                                     *
                                     * @example
                                     * const Ravel = require('ravel');
                                     * const app = new Ravel();
                                     */let
Ravel = class Ravel extends AsyncEventEmitter {
  /**
                                                * Creates a new Ravel app instance.
                                                *
                                                * @example
                                                * const Ravel = require('ravel');
                                                * const app = new Ravel();
                                                */
  constructor() {
    super();

    this[sUncaughtRejections] = 0;
    this[sInitialized] = false;
    this[sListening] = false;
    this[sKeygripKeys] = [];

    // how we store modules for dependency injection
    this[coreSymbols.modules] = Object.create(null);
    // how we store routes for later access
    this[coreSymbols.routes] = Object.create(null);
    // how we store resources for later access
    this[coreSymbols.resource] = Object.create(null);
    // how we store middleware for dependency injection
    this[coreSymbols.middleware] = Object.create(null);

    // current working directory of the app using the
    // ravel library, so that client modules can be
    // loaded with relative paths.
    this[sCWD] = process.cwd();

    this[coreSymbols.knownParameters] = Object.create(null);
    this[coreSymbols.params] = Object.create(null);
    // a list of registered module factories which haven't yet been instantiated
    this[coreSymbols.moduleFactories] = Object.create(null);
    this[coreSymbols.resourceFactories] = Object.create(null);
    this[coreSymbols.routesFactories] = Object.create(null);
    // Allows us to detect duplicate binds
    this[coreSymbols.endpoints] = new Map();
    // a list of known modules, resources and routes so that metadata can be retrieved from them
    this[coreSymbols.knownComponents] = Object.create(null);

    // init errors
    this[sErr] = require('./util/application_error');

    // init logging system
    this[sLog] = new (require('./util/log'))(this);

    // init dependency injection utility, which is used by most everything else
    this[coreSymbols.injector] = new (require('./core/injector'))(this,
    module.parent !== null ? module.parent : module);

    // Register known ravel parameters
    // websocket parameters
    this.registerParameter('enable websockets', true, true);
    this.registerParameter('max websocket payload bytes', true, 100 * 1024 * 1024);
    this.registerParameter('redis websocket channel prefix', true, 'ravel.ws');
    // redis parameters
    this.registerParameter('redis host', false);
    this.registerParameter('redis port', true, 6379);
    this.registerParameter('redis password');
    this.registerParameter('redis max retries', true, 10);
    this.registerParameter('redis keepalive interval', true, 1000);
    // Node/koa parameters
    this.registerParameter('port', true, 8080);
    this.registerParameter('https', true, false);
    // supports any option from https://nodejs.org/api/tls.html#tls_tls_createserver_options_secureconnectionlistener
    this.registerParameter('https options', true, {});
    this.registerParameter('public directory');
    this.registerParameter('favicon path');
    this.registerParameter('keygrip keys', true);
    // session parameters
    this.registerParameter('session key', true, 'ravel.sid');
    this.registerParameter('session max age', true, null);
    this.registerParameter('session secure', true, true);
    this.registerParameter('session rolling', true, false);
    // Passport parameters
    this.registerParameter('app route', false, '/');
    this.registerParameter('login route', false, '/login');
  }

  /**
     * The current working directory of the app using the `ravel` library.
     *
     * @type String
     */
  get cwd() {
    return this[sCWD];
  }

  /**
     * Return the app instance of Logger.
     * See [`Logger`](#logger) for more information.
     *
     * @type Logger
     * @example
     * app.$log.error('Something terrible happened!');
     */
  get $log() {
    return this[sLog];
  }

  /**
     * A hash of all built-in error types. See [`$err`](#$err) for more information.
     *
     * @type Object
     */
  get $err() {
    return this[sErr];
  }

  /**
     * Value is `true` iff init() or start() has been called on this app instance.
     *
     * @type boolean
     */
  get initialized() {
    return this[sInitialized];
  }

  /**
     * Value is `true` iff `listen()` or `start()` has been called on this app instance.
     *
     * @type boolean
     */
  get listening() {
    return this[sListening];
  }

  /**
     * The underlying koa callback for this Ravel instance.
     * Useful for [testing](#testing-ravel-applications) with `supertest`.
     * Only available after `init()` (i.e. use `@postinit`).
     *
     * @type {Function}
     */
  get callback() {
    return this[sCallback];
  }

  /**
     * The underlying HTTP server for this Ravel instance.
     * Only available after `init()` (i.e. use `@postinit`).
     * Useful for [testing](#testing-ravel-applications) with `supertest`.
     *
     * @type {http.Server}
     */
  get server() {
    return this[sServer];
  }

  /**
     * The underlying Keygrip instance for cookie signing.
     *
     * @type {Keygrip}
     */
  get keys() {
    return this[sKeygrip];
  }

  /**
     * Register a provider, such as a DatabaseProvider or AuthenticationProvider.
     *
     * @param {Function} ProviderClass - The provider class.
     * @param {...any} args - Arguments to be provided to the provider's constructor
     *                        (prepended automatically with a reference to app).
     */
  registerProvider(ProviderClass, ...args) {
    return new ProviderClass(this, ...args);
  }

  /**
     * Initializes the application, when the client is finished
     * supplying parameters and registering modules, resources
     * routes and rooms.
     *
     * @example
     * await app.init();
     */
  async init() {
    // application configuration is completed in constructor
    await this.emit('pre init');

    // log uncaught errors to prevent ES6 promise error swallowing
    // https://www.hacksrus.net/blog/2015/08/a-solution-to-swallowed-exceptions-in-es6s-promises/
    process.removeAllListeners('unhandledRejection');
    process.on('unhandledRejection', err => {
      this[sUncaughtRejections] += 1;
      const message = `Detected uncaught error in promise: \n ${err ? err.stack : err}`;
      if (this[sUncaughtRejections] >= 10) {
        this.$log.error(message);
        this.$log.error(`Encountered ${this[sUncaughtRejections]} or more uncaught rejections. Re-run ` +
        'node and ravel with full logging output for more information:' +
        '\n- node --trace-warnings app.js' +
        '\n- app.set(\'log level\', app.$log.TRACE);');
      } else {
        this.$log.debug(message);
      }
    });

    // load parameters from .ravelrc.json file, if any
    await this.emit('pre load parameters');
    this[coreSymbols.loadParameters]();
    await this.emit('post load parameters');

    this[sInitialized] = true;

    this.$db = require('./db/database')(this);
    this.$kvstore = require('./util/kvstore')(this);

    // App dependencies.
    const http = require('http');
    const https = require('https');
    const upath = require('upath');
    const Koa = require('koa');
    const session = require('koa-session');
    const compression = require('koa-compress');
    const favicon = require('koa-favicon');
    const router = new (require('koa-router'))();

    // configure koa
    const app = new Koa();
    app.proxy = true;

    // the first piece of middleware is the exception handler
    // catch all errors and return appropriate error codes
    // to the client
    app.use(new Rest(this).errorHandler());

    // enable gzip compression
    app.use(compression());

    // configure redis session store
    this[sKeygripKeys] = [...this.get('keygrip keys')];
    this[sKeygrip] = require('keygrip')(this[sKeygripKeys], 'sha256', 'base64');
    app.keys = this[sKeygrip];

    // configure session options
    if (!this.get('https') && !this.get('session secure')) {
      this.$log.warn("app.set('session secure', false) results in insecure sessions" +
      ' over HTTP and introduces critical security vulnerabilities.' +
      ' This is intended for development purposes only, or for use' +
      ' behind a TLS termination proxy.');
    }
    const sessionOptions = {
      store: new (require('./util/redis_session_store'))(this),
      key: this.get('session key'),
      maxAge: Number(this.get('session max age')),
      overwrite: true, /* (boolean) can overwrite or not (default true) */
      httpOnly: true, /* (boolean) httpOnly or not (default true) */
      signed: true, /* (boolean) signed or not (default true) */
      secure: this.get('https') || this.get('session secure'), /* (boolean) secure or not (default true) */
      rolling: this.get('session rolling') /* (boolean) Force a session identifier cookie to be set on every response.
                                           The expiration is reset to the original maxAge, resetting the expiration
                                           countdown. default is false */ };

    app.use(session(sessionOptions, app));

    // favicon
    if (this.get('favicon path')) {
      app.use(favicon(upath.toUnix(upath.posix.join(this.cwd, this.get('favicon path')))));
    }

    // static file serving
    if (this.get('public directory')) {
      const koaStatic = require('koa-static');
      const root = upath.toUnix(upath.posix.join(this.cwd, this.get('public directory')));
      app.use(koaStatic(root, {
        gzip: false // this should be handled by koa-compressor?
      }));
    }

    // initialize authentication/authentication
    require('./auth/passport_init.js')(this, router);

    // create websocket broker
    const WebsocketBroker = require('./core/websocket.js');
    this[coreSymbols.websocketBroker] = new WebsocketBroker(this);

    // basic koa configuration is completed
    await this.emit('post config koa', app);

    // create registered modules using factories
    await this[coreSymbols.moduleInit]();

    await this.emit('post module init');

    await this.emit('pre routes init', app);

    // create registered resources using factories
    this[coreSymbols.resourceInit](router);

    // create routes using factories
    this[coreSymbols.routesInit](router);

    // include routes as middleware
    app.use(router.routes());
    app.use(router.allowedMethods());

    // Create koa callback and server
    this[sCallback] = app.callback();
    this[sServer] = this.get('https') ?
    https.createServer(this.get('https options'), this[sCallback]) :
    http.createServer(this[sCallback]);

    // application configuration is completed
    await this.emit('post init');
  }

  /**
     * Rotate a new cookie signing key in, and the oldest key out.
     *
     * @param {string} newKey - The new key.
     */
  rotateKeygripKey(newKey) {
    this[sKeygripKeys].unshift(newKey);
    this[sKeygripKeys].pop();
  }

  /**
     * Starts the application. Must be called after `initialize()`.
     *
     * @example
     * await app.listen();
     */
  async listen() {
    if (!this[sInitialized]) {
      throw new this.$err.NotAllowed('Cannot call Ravel.listen() before Ravel.init()');
    } else {
      await this.emit('pre listen');
      return new Promise((resolve, reject) => {
        // validate parameters
        this[coreSymbols.validateParameters]();
        // Start Koa server
        this[sServer].listen(this.get('port'), () => {
          /* eslint-disable max-len */
          this.$log.info(`Application server listening for ${this.get('https') ? 'https' : 'http'} traffic on port ${this.get('port')}`);
          /* eslint-enable max-len */
          this[sListening] = true;
          this.emit('post listen');
          resolve();
        });
      });
    }
  }

  /**
     * Intializes and starts the application.
     *
     * @example
     * await app.start();
     */
  async start() {
    await this.init();
    return this.listen();
  }

  /**
     * Stops the application. A no op if the server isn't running.
     *
     * @example
     * await app.close();
     */
  async close() {
    await this.emit('end');
    if (this[sServer] && this[sListening]) {
      return new Promise(resolve => {
        this[sServer].close(() => {
          this.$log.info('Application server terminated.');
          this[sListening] = false;
          resolve();
        });
      });
    }
  }};


/**
       * The base class of Ravel `Error`s, which associate
       * HTTP status codes with your custom errors.
       * @example
       * const Ravel = require('ravel');
       * class NotFoundError extends Ravel.Error {
       *   constructor (msg) {
       *     super(msg, Ravel.httpCodes.NOT_FOUND);
       *   }
       * }
       */
Ravel.Error = require('./util/application_error').General;

/**
                                                            * The base class for Ravel `DatabaseProvider`s. See
                                                            * [`DatabaseProvider`](#databaseprovider) for more information.
                                                            * @example
                                                            * const DatabaseProvider = require('ravel').DatabaseProvider;
                                                            * class MySQLProvider extends DatabaseProvider {
                                                            *   // ...
                                                            * }
                                                            */
Ravel.DatabaseProvider = require('./db/database_provider').DatabaseProvider;

/**
                                                                              * Return a list of all registered `DatabaseProvider`s. See
                                                                              * [`DatabaseProvider`](#databaseprovider) for more information.
                                                                              * @returns {Array} a list of `DatabaseProvider`s
                                                                              * @private
                                                                              */
require('./db/database_provider')(Ravel);

/**
                                           * The base class for Ravel `AuthenticationProvider`s. See
                                           * [`AuthenticationProvider`](#authenticationprovider) for more information.
                                           * @example
                                           * const AuthenticationProvider = require('ravel').AuthenticationProvider;
                                           * class GoogleOAuth2Provider extends AuthenticationProvider {
                                           *   // ...
                                           * }
                                           */
Ravel.AuthenticationProvider = require('./auth/authentication_provider').AuthenticationProvider;

/**
                                                                                                  * Return a list of all registered `AuthenticationProvider`s. See
                                                                                                  * [`AuthenticationProvider`](#authenticationprovider) for more information.
                                                                                                  * @returns {Array} a list of `AuthenticationProvider`s
                                                                                                  * @private
                                                                                                  */
require('./auth/authentication_provider')(Ravel);

/*
                                                   * Makes the `@inject` decorator available as `Ravel.inject`
                                                   * @example
                                                   * const Ravel = require('ravel');
                                                   * const inject = Ravel.inject;
                                                   */
Ravel.inject = require('./core/decorators/inject');

/*
                                                     * Makes the `@autoinject` decorator available as `Ravel.autoinject`
                                                     * @example
                                                     * const Ravel = require('ravel');
                                                     * const autoinject = Ravel.autoinject;
                                                     */
Ravel.autoinject = require('./core/decorators/autoinject');

/**
                                                             * A dictionary of useful http status codes. See [HTTPCodes](#httpcodes) for more information.
                                                             * @example
                                                             * const Ravel = require('ravel');
                                                             * console.log(Ravel.httpCodes.NOT_FOUND);
                                                             */
Ravel.httpCodes = require('./util/http_codes');

/**
                                                 * Requires Ravel's parameter system
                                                 * See `core/params` for more information.
                                                 * @example
                                                 * app.registerParameter('my parameter', true, 'default value');
                                                 * const value = app.get('my parameter');
                                                 * app.set('my parameter', 'another value');
                                                 * @private
                                                 */
require('./core/params')(Ravel);

/**
                                  * The base decorator for Ravel `Module`s. See
                                  * [`Module`](#module) for more information.
                                  * @example
                                  * const Module = require('ravel').Module;
                                  * @Module
                                  * class MyModule {
                                  *   // ...
                                  * }
                                  * module.exports = MyModule;
                                  */
Ravel.Module = require('./core/module').Module;

/**
                                                 * Requires Ravel's `Module` retrieval and registration system
                                                 * See [`Module`](#module) for more information.
                                                 * @example
                                                 * app.scan('./modules/mymodule');
                                                 * @private
                                                 */
require('./core/module')(Ravel);

/**
                                  * Requires Ravel's recursive component registration system.
                                  *
                                  * See [`Module`](#module), [`Resource`](#resource) and [`Routes`](#routes) for more information.
                                  * @example
                                  * // recursively load all Modules in a directory
                                  * app.scan('./modules');
                                  * // a Module 'modules/test.js' in ./modules can be injected as `@inject('test')`
                                  * // a Module 'modules/stuff/test.js' in ./modules can be injected as `@inject('stuff.test')`
                                  * @example
                                  * // recursively load all Resources in a directory
                                  * app.scan('./resources');
                                  * // recursively load all Resources in a directory
                                  * app.scan('./routes');
                                  * @private
                                  */
require('./core/scan')(Ravel);

/**
                                * The base class for Ravel `Routes`. See
                                * [`Routes`](#routes) for more information.
                                * @example
                                * const Routes = require('ravel').Routes;
                                * // @Routes('/')
                                * class MyRoutes {
                                *   // ...
                                * }
                                * module.exports = MyRoutes;
                                */
Ravel.Routes = require('./core/routes').Routes;

/**
                                                 * Requires Ravel's `Routes` registration system
                                                 * See [`Routes`](#routes) for more information.
                                                 * @example
                                                 * app.routes('./routes/myroutes');
                                                 * @private
                                                 */
require('./core/routes')(Ravel);

/**
                                  * The base class for Ravel `Resource`. See
                                  * [`Resource`](#resource) for more information.
                                  * @example
                                  * const Resource = require('ravel').Resource;
                                  * // @Resource('/')
                                  * class MyResource {
                                  *   // ...
                                  * }
                                  * module.exports = MyResource;
                                  */
Ravel.Resource = require('./core/resource').Resource;

/**
                                                       * Requires Ravel's `Resource` registration system
                                                       * See [`Resource`](#resource) for more information.
                                                       * @example
                                                       * app.resource('./resources/myresource');
                                                       * @private
                                                       */
require('./core/resource')(Ravel);

/**
                                    * Requires Ravel's lightweight reflection/metadata system.
                                    *
                                    * See `core/reflect` for more information.
                                    * @example
                                    * // examine a registered Module, Resource or Route by file path
                                    * app.reflect('./modules/mymodule.js');
                                    * @private
                                    */
require('./core/reflect')(Ravel);

module.exports = Ravel;