raveljs/ravel

'use strict';

const upath = require('upath');
const symbols = require('./symbols');
const Metadata = require('../util/meta');
const $err = require('../util/application_error');
const rest = new (require('../util/rest'))(this.app);
const AuthenticationMiddleware = require('../auth/authenticate_request');
const ResponseCacheMiddleware = require('../util/response_cache');
const coreServices = require('./services');

// Symbols for HTTP methods
const HEAD = Symbol.for('head');
const GET = Symbol.for('get');
const POST = Symbol.for('post');
const PUT = Symbol.for('put');
const PATCH = Symbol.for('patch');
const DELETE = Symbol.for('delete');

/**
 * Process all methods and add to koa app.
 *
 * @private
 * @param {Ravel} ravelInstance - An instance of a Ravel app.
 * @param {Routes} routes - A reference to a Routes class.
 * @param {object} koaRouter - A reference to a koa router.
 * @param {string} methodName - The name of the handler method within the class.
 * @param {object} meta - Metadata from the corresponding `@mapping` decorator.
 */
function buildRoute (ravelInstance, routes, koaRouter, methodName, meta) {
  const basePath = Metadata.getClassMetaValue(routes, '@role', 'name');
  const fullPath = upath.toUnix(upath.posix.join(basePath, meta.path));

  let verb;
  switch (meta.verb) {
    case HEAD:
      verb = 'head';
      break;
    case PUT:
      verb = 'put';
      break;
    case POST:
      verb = 'post';
      break;
    case PATCH:
      verb = 'patch';
      break;
    case DELETE:
      verb = 'delete';
      break;
    default:
      verb = 'get';
  }

  if (!meta.suppressLog) {
    ravelInstance.$log.info(`Registering endpoint ${verb} ${fullPath}`);
  }

  let args = [fullPath];

  // build middleware from metadata
  const middleware = [];

  // apply class-level @authenticated middleware, if present
  // we only need to check for method-level @authenticated if it isn't on the class
  if (Metadata.getClassMeta(routes, '@authenticated')) {
    const config = Metadata.getClassMetaValue(routes, '@authenticated', 'config', {});
    middleware.push(
      new AuthenticationMiddleware(ravelInstance, config.redirect, config.allowRegistration).middleware());
  } else if (Metadata.getMethodMeta(routes, methodName, '@authenticated')) {
    const config = Metadata.getMethodMetaValue(routes, methodName, '@authenticated', 'config', {});
    middleware.push(
      new AuthenticationMiddleware(ravelInstance, config.redirect, config.allowRegistration).middleware());
  }

  // apply respond middleware automatically
  middleware.push(rest.respond());

  // apply class-level and method-level @transaction middleware, if present (in the correct order)
  let dbProviders;
  if (Metadata.getClassMeta(routes, '@transaction')) {
    dbProviders = Metadata.getClassMetaValue(routes, '@transaction', 'providers', []);
  }
  if (Metadata.getMethodMeta(routes, methodName, '@transaction')) {
    dbProviders = dbProviders || [];
    dbProviders = dbProviders.concat(Metadata.getMethodMetaValue(routes, methodName, '@transaction', 'providers', []));
  }
  if (dbProviders !== undefined) {
    middleware.push(ravelInstance.$db.middleware(...dbProviders));
  }

  // apply class-level @before middleware, if any
  let toInject = [].concat(Metadata.getClassMetaValue(routes, '@before', 'middleware', []));

  // then method-level @before middleware, if any
  toInject = toInject.concat(Metadata.getMethodMetaValue(routes, methodName, '@before', 'middleware', []));

  for (let i = 0; i < toInject.length; i++) {
    const m = toInject[i];
    const middlewareFactory = ravelInstance[symbols.injector].getModule(routes, m);
    let middlewareFn;
    if (typeof middlewareFactory === 'object' && middlewareFactory.isFactory) {
      if (i + middlewareFactory.fn.length >= toInject.length) {
        throw new ravelInstance.$err.IllegalValueError(
          `Middleware ${m} requires ${middlewareFactory.fn.length} arguments for instantiation.
           Specify with @before('${m}', arg1, arg2, ...)`);
      }
      middlewareFn = middlewareFactory.fn(...toInject.slice(i + 1, i + 1 + middlewareFactory.fn.length));
      i += middlewareFactory.fn.length; // skip ahead
    } else if (typeof middlewareFactory === 'object') {
      middlewareFn = middlewareFactory.fn;
    } else {
      middlewareFn = middlewareFactory; // for reverse compatibility
    }
    middleware.push(middlewareFn);
  }

  // then cache middleware, if present
  // method-level @cache overrides class-level cache
  if (Metadata.getMethodMeta(routes, methodName, '@cache')) {
    const config = Metadata.getMethodMetaValue(routes, methodName, '@cache', 'options', {});
    middleware.push(
      new ResponseCacheMiddleware(ravelInstance).middleware(config));
  } else if (Metadata.getClassMeta(routes, '@cache')) {
    const config = Metadata.getClassMetaValue(routes, '@cache', 'options', {});
    middleware.push(
      new ResponseCacheMiddleware(ravelInstance).middleware(config));
  }

  // finally push actual function handler, but wrap it with a generator
  if (meta.endpoint) {
    middleware.push(async function (ctx, next) {
      const result = meta.endpoint.bind(routes)(ctx);
      // if handler returns a Promise, await on it
      if (result && result instanceof Promise) {
        await result;
      }
      // then await next middleware
      await next();
    });
  } else {
    // if there's no handler, this @mapping represents an endpoint which just returns a status code
    middleware.push(async (ctx) => {
      ctx.respondOptions = { okCode: meta.status };
    });
  }

  args = args.concat(middleware);
  // now call underlying koa method to register middleware at specific route
  // check if this is a catch-all route
  if (meta.catchAll) {
    koaRouter.catchAll(verb.toUpperCase(), ...args);
  } else {
    koaRouter[verb](...args);
  }
}

/**
 * Initializer for this `Routes` class.
 *
 * @param {Ravel} ravelInstance - Instance of a Ravel app.
 * @param {object} koaRouter - Instance a koa router.
 * @private
 */
function initRoutes (ravelInstance, koaRouter) {
  const proto = Object.getPrototypeOf(this);
  // handle class-level @mapping decorators
  const classMeta = Metadata.getClassMeta(proto, '@mapping', Object.create(null));
  for (const r of Object.keys(classMeta)) {
    buildRoute(ravelInstance, this, koaRouter, r, classMeta[r]);
  }

  // handle methods decorated with @mapping
  const meta = Metadata.getMeta(proto).method;
  const annotatedMethods = Object.keys(meta);
  for (const r of annotatedMethods) {
    const methodMeta = Metadata.getMethodMetaValue(proto, r, '@mapping', 'info');
    if (methodMeta) {
      buildRoute(ravelInstance, this, koaRouter, r, methodMeta);
    }
  }
}

/*!
 * Populate `Ravel` class with `routes` method and initialization function
 */
module.exports = function (Ravel) {
  /**
   * Retrieve an initialized Ravel `Routes` module by its `basePath`, after `app.init()`.
   * Useful for [testing](#testing-ravel-applications).
   *
   * @param {string} basePath - The basePath of the Routes module.
   */
  Ravel.prototype.routes = function (basePath) {
    if (!this.initialized) {
      throw new this.$err.General('Cannot retrieve a Routes reference from Ravel before app.init().');
    }
    return this[symbols.routes][basePath];
  };

  /**
   * Register a bunch of plain koa endpoints with Ravel which
   * will be available, by name, at the given base path.
   *
   * @private
   * @param {Function} routesClass - A Routes class.
   */
  Ravel.prototype[symbols.loadRoutes] = function (routesClass) {
    const basePath = Metadata.getClassMetaValue(routesClass.prototype, '@role', 'name');
    // if routes with this base path has already been registered, error out
    if (this[symbols.endpoints].has(basePath)) {
      throw new $err.DuplicateEntry(
        `Resource or Routes with name '${basePath}' has already been registered.`);
    } else {
      this.basePath = basePath;
      this[symbols.endpoints].set(basePath, true);
    }
    // store reference to this ravel instance in metadata
    Metadata.putClassMeta(routesClass.prototype, 'ravel', 'instance', this);
    // store known routes module with path as the key, so someone can reflect on the class
    this[symbols.registerClassFunc](basePath, routesClass);
    // build routes instantiation function, which takes the
    // current koa app as an argument
    this[symbols.routesFactories][basePath] = (koaRouter) => {
      const routes = this[symbols.injector].inject(coreServices(this, basePath), routesClass);
      initRoutes.call(routes, this, koaRouter);
      this[symbols.routes][basePath] = routes;
      return routes;
    };
  };

  /**
   * Performs routes initialization, executing routes factories
   * in dependency order in `Ravel.init()`.
   *
   * @param {object} router - A reference to a koa router object.
   * @private
   */
  Ravel.prototype[symbols.routesInit] = function (router) {
    for (const r of Object.keys(this[symbols.routesFactories])) {
      this[symbols.routesFactories][r](router);
    }
  };
};

/*!
 * Export `Routes` decorator, and other useful things
 */
module.exports.Routes = require('./decorators/routes');

/*!
 * Export `Routes` init function for use in Resources
 */
module.exports.initRoutes = initRoutes;

/**
 * Used with the @mapping decorator to indicate the `HEAD` HTTP verb.
 *
 * @type Symbol
 * @example
 * const Routes = require('ravel').Routes;
 * const mapping = Routes.mapping;
 * // &#64;Routes('/')
 * class MyRoutes {
 *   // &#64;mapping(Routes.HEAD, '/something')
 *   async handler (ctx) {
 *     //...
 *   }
 * }
 * @memberof Routes
 */
module.exports.Routes.HEAD = HEAD;

/**
 * Used with the @mapping decorator to indicate the `GET` HTTP verb.
 *
 * @type Symbol
 * @example
 * const Routes = require('ravel').Routes;
 * const mapping = Routes.mapping;
 * // &#64;Routes('/')
 * class MyRoutes {
 *   // &#64;mapping(Routes.GET, '/something')
 *   async handler (ctx) {
 *     //...
 *   }
 * }
 * @memberof Routes
 */
module.exports.Routes.GET = GET;

/**
 * Used with the @mapping decorator to indicate the `POST` HTTP verb.
 *
 * @type Symbol
 * @example
 * const Routes = require('ravel').Routes;
 * const mapping = Routes.mapping;
 * // &#64;Routes('/')
 * class MyRoutes {
 *   // &#64;mapping(Routes.POST, '/something')
 *   async handler (ctx) {
 *     //...
 *   }
 * }
 * @memberof Routes
 */
module.exports.Routes.POST = POST;

/**
 * Used with the @mapping decorator to indicate the `PUT` HTTP verb.
 *
 * @type Symbol
 * @example
 * const Routes = require('ravel').Routes;
 * const mapping = Routes.mapping;
 * // &#64;Routes('/')
 * class MyRoutes {
 *   // &#64;mapping(Routes.PUT, '/something')
 *   async handler (ctx) {
 *     //...
 *   }
 * }
 * @memberof Routes
 */
module.exports.Routes.PUT = PUT;

/**
 * Used with the @mapping decorator to indicate the `PATCH` HTTP verb.
 *
 * @type Symbol
 * @example
 * const Routes = require('ravel').Routes;
 * const mapping = Routes.mapping;
 * // &#64;Routes('/')
 * class MyRoutes {
 *   // &#64;mapping(Routes.PATCH, '/something')
 *   async handler (ctx) {
 *     //...
 *   }
 * }
 * @memberof Routes
 */
module.exports.Routes.PATCH = PATCH;

/**
 * Used with the @mapping decorator to indicate the `DELETE` HTTP verb.
 *
 * @type Symbol
 * @example
 * const Routes = require('ravel').Routes;
 * const mapping = Routes.mapping;
 * // &#64;Routes('/')
 * class MyRoutes {
 *   // &#64;mapping(Routes.DELETE, '/something')
 *   async handler (ctx) {
 *     //...
 *   }
 * }
 * @memberof Routes
 */
module.exports.Routes.DELETE = DELETE;

/**
 * The `@mapping` decorator for `Routes` classes.
 *
 * See [`mapping`](#mapping) for more information.
 *
 * @memberof Routes
 */
module.exports.Routes.mapping = require('./decorators/mapping');

/**
 * The `@before` decorator for `Routes` and `Resource` classes.
 *
 * See [`before`](#before) for more information.
 *
 * @memberof Routes
 */
module.exports.Routes.before = require('./decorators/before');

/**
 * The `@transaction` decorator for `Routes` and `Resource` classes.
 *
 * See [`transaction`](#transaction) for more information.
 *
 * @memberof Routes
 */
module.exports.Routes.transaction = require('../db/decorators/transaction');

/**
 * The `@authenticated` decorator for `Routes` and `Resource` classes.
 *
 * See [`authenticated`](#authenticated) for more information.
 *
 * @memberof Routes
 */
module.exports.Routes.authenticated = require('../auth/decorators/authenticated');

/**
 * The `@cache` decorator for `Routes` and `Resource` calsses.
 *
 * See [`cache`](#cache) for more information.
 *
 * @memberof Routes
 */
module.exports.Routes.cache = require('./decorators/cache');