joi-router.js

/*!
 * @koa-better-modules/joi-router
 *
 *
 * Copyright(c) 2021 Koa.js contributions
 * Copyright(c) 2022 imed jaberi
 * MIT Licensed
 */

'use strict';

/**
 * Module dependencies.
 */
const assert = require('node:assert');

const debug = require('debug')('@koa-better-modules/joi-router');
const KoaRouter = require('@koa/router');
const isGenFn = require('is-generator-function');
const parse = require('co-body');
const Joi = require('joi');
// TODO: replace this module with structuredClone once
// we break the support for the Node.js version less than 20.
const clone = require('clone');

const methods = require('./methods');
const busboy = require('./await-busboy');
const slice = require('./sliced');
const OutputValidator = require('./output-validator');

/**
 * Configurable, input validated routing for koa.
 * 
 * @api public
 */
class KoaJoiRouter {
  // expose Joi for use in applications
  static Joi = Joi;

  constructor() {
    this.routes = [];
    this.router = new KoaRouter();
  }

  /**
   * Return koa middleware
   * @return {Function}
   * @api public
   */

  middleware() {
    return this.router.routes();
  }

  /**
   * Adds a route or array of routes to this router, storing the route
   * in `this.routes`.
   *
   * Example:
   *
   *   var admin = router();
   *
   *   admin.route({
   *     method: 'get',
   *     path: '/do/stuff/:id',
   *     handler: () => {},
   *     validate: {
   *       header: Joi object
   *       params: Joi object (:id)
   *       query: Joi object (validate key/val pairs in the querystring)
   *       body: Joi object (the request payload body) (json or form)
   *       maxBody: '64kb' // (json, x-www-form-urlencoded only - not stream size)
   *                       // optional
   *       type: 'json|form|multipart' (required when body is specified)
   *       failure: 400 // http error code to use
   *     },
   *     meta: { // this is ignored but useful for doc generators etc
   *       desc: 'We can use this for docs generation.'
   *       produces: ['application/json']
   *       model: {} // response object definition
   *     }
   *   })
   *
   * @param {Object} spec
   * @return {Router} self
   * @api public
   */

  route(spec) {
    if (Array.isArray(spec)) {
      for (let i = 0; i < spec.length; i++) {
        this._addRoute(spec[i]);
      }
    } else {
      this._addRoute(spec);
    }

    return this;
  }

  // delegate behavoir handler.
  // prefix method
  prefix(prefix) {
    return this.router.prefix(prefix)
  }

  // use method
  use(...args) {
    return this.router.use(...args)
  }

  // param method
  param(param, middleware) {
    return this.router.param(param, middleware)
  }

  /**
   * Adds a route to this router, storing the route
   * in `this.routes`.
   *
   * @param {Object} spec
   * @api private
   */

  _addRoute(spec) {
    this._validateRouteSpec(spec);
    this.routes.push(spec);

    debug('add %s "%s"', spec.method, spec.path);

    const bodyParser = makeBodyParser(spec);
    const specExposer = makeSpecExposer(spec);
    const validator = makeValidator(spec);
    const preHandlers = spec.pre ? flatten(spec.pre) : [];
    const handlers = flatten(spec.handler);

    const args = [
      spec.path
    ].concat(preHandlers, [
      prepareRequest,
      specExposer,
      bodyParser,
      validator
    ], handlers);

    const router = this.router;

    spec.method.forEach((method) => {
      router[method].apply(router, args);
    });
  }

  /**
   * Validate the spec passed to route()
   *
   * @param {Object} spec
   * @api private
   */

  _validateRouteSpec(spec) {
    assert(spec, 'missing spec');

    const ok = typeof spec.path === 'string' || spec.path instanceof RegExp;
    assert(ok, 'invalid route path');

    checkHandler(spec);
    checkPreHandler(spec);
    checkMethods(spec);
    checkValidators(spec);
  }
}

/**
 * Routing shortcuts for all HTTP methods
 *
 * Example:
 *
 *    var admin = router();
 *
 *    admin.get('/user', async function(ctx) {
 *      ctx.body = ctx.session.user;
 *    })
 *
 *    var validator = Joi().object().keys({ name: Joi.string() });
 *    var config = { validate: { body: validator }};
 *
 *    admin.post('/user', config, async function(ctx){
 *      console.log(ctx.body);
 *    })
 *
 *    async function commonHandler(ctx){
 *      // ...
 *    }
 *    admin.post('/account', [commonHandler, async function(ctx){
 *      // ...
 *    }]);
 *
 * @param {String} path
 * @param {Object} [config] optional
 * @param {async function|async function[]} handler(s)
 * @return {App} self
 */

methods.forEach((method) => {
  method = method.toLowerCase();

  KoaJoiRouter.prototype[method] = function (path) {
    // path, handler1, handler2, ...
    // path, config, handler1
    // path, config, handler1, handler2, ...
    // path, config, [handler1, handler2], handler3, ...

    let fns;
    let config;

    if (typeof arguments[1] === 'function' || Array.isArray(arguments[1])) {
      config = {};
      fns = slice(arguments, 1);
    } else if (typeof arguments[1] === 'object') {
      config = arguments[1];
      fns = slice(arguments, 2);
    }

    const spec = {
      path: path,
      method: method,
      handler: fns
    };

    Object.assign(spec, config);

    this.route(spec);
    return this;
  };
});

// utils

/**
 * @api private
 */

function flatten(array) {
  return array.reduce((prev, next) => prev.concat(Array.isArray(next) ? flatten(next) : next), [])
}

/**
 * @api private
 */

function checkHandler(spec) {
  if (!Array.isArray(spec.handler)) {
    spec.handler = [spec.handler];
  }

  return flatten(spec.handler).forEach(isSupportedFunction);
}

/**
 * @api private
 */

function checkPreHandler(spec) {
  if (!spec.pre) {
    return;
  }

  if (!Array.isArray(spec.pre)) {
    spec.pre = [spec.pre];
  }

  return flatten(spec.pre).forEach(isSupportedFunction);
}

/**
 * @api private
 */

function isSupportedFunction(handler) {
  assert.strictEqual(typeof handler, 'function', 'route handler must be a function');

  if (isGenFn(handler)) {
    throw new Error(`route handlers must not be GeneratorFunctions
       Please use "async function" or "function".`);
  }
}

/**
 * Validate the spec.method
 *
 * @param {Object} spec
 * @api private
 */

function checkMethods(spec) {
  assert(spec.method, 'missing route methods');

  if (typeof spec.method === 'string') {
    spec.method = spec.method.split(' ');
  }

  if (!Array.isArray(spec.method)) {
    throw new TypeError('route methods must be an array or string');
  }

  if (spec.method.length === 0) {
    throw new Error('missing route method');
  }

  spec.method.forEach((method, i) => {
    assert(typeof method === 'string', 'route method must be a string');
    spec.method[i] = method.toLowerCase();
  });
}

/**
 * Validate the spec.validators
 *
 * @param {Object} spec
 * @api private
 */

function checkValidators(spec) {
  if (!spec.validate) return;

  let text;
  if (spec.validate.body) {
    text = 'validate.type must be declared when using validate.body';
    assert(/json|form|multipart/.test(spec.validate.type), text);
  }

  if (spec.validate.type) {
    text = 'validate.type must be either json, form, multipart or stream';
    assert(/json|form|multipart|stream/i.test(spec.validate.type), text);
  }

  if (spec.validate.output) {
    spec.validate._outputValidator = new OutputValidator(spec.validate.output);
  }

  // default HTTP status code for failures
  if (!spec.validate.failure) {
    spec.validate.failure = 400;
  }
}

/**
 * Does nothing
 * @param  {[type]}   ctx  [description]
 * @param  {Function} next [description]
 * @return {async function}        [description]
 * @api private
 */

async function noopMiddleware(ctx, next) {
  return await next();
}

/**
 * Handles parser internal errors
 * @param  {Object} spec         [description]
 * @param  {function} parsePayload [description]
 * @return {async function}              [description]
 * @api private
 */

function wrapError(spec, parsePayload) {
  return async function errorHandler(ctx, next) {
    try {
      await parsePayload(ctx);
    } catch (err) {
      captureError(ctx, 'type', err);
      if (!spec.validate.continueOnError) {
        return ctx.throw(err);
      }
    }
    await next();
  };
}

/**
 * Creates JSON body parser middleware.
 *
 * @param {Object} spec
 * @return {async function}
 * @api private
 */

function makeJSONBodyParser(spec) {
  const opts = spec.validate.jsonOptions || {};
  if (typeof opts.limit === 'undefined') {
    opts.limit = spec.validate.maxBody;
  }

  return async function parseJSONPayload(ctx) {
    if (!ctx.request.is('json')) {
      return ctx.throw(400, 'expected json');
    }

    // eslint-disable-next-line require-atomic-updates
    ctx.request.body = ctx.request.body || await parse.json(ctx, opts);
  };
}

/**
 * Creates form body parser middleware.
 *
 * @param {Object} spec
 * @return {async function}
 * @api private
 */

function makeFormBodyParser(spec) {
  const opts = spec.validate.formOptions || {};
  if (typeof opts.limit === 'undefined') {
    opts.limit = spec.validate.maxBody;
  }
  return async function parseFormBody(ctx) {
    if (!ctx.request.is('urlencoded')) {
      return ctx.throw(400, 'expected x-www-form-urlencoded');
    }

    // eslint-disable-next-line require-atomic-updates
    ctx.request.body = ctx.request.body || await parse.form(ctx, opts);
  };
}

/**
 * Creates stream/multipart-form body parser middleware.
 *
 * @param {Object} spec
 * @return {async function}
 * @api private
 */

function makeMultipartParser(spec) {
  const opts = spec.validate.multipartOptions || {};
  if (typeof opts.autoFields === 'undefined') {
    opts.autoFields = true;
  }
  return async function parseMultipart(ctx) {
    if (!ctx.request.is('multipart/*')) {
      return ctx.throw(400, 'expected multipart');
    }
    ctx.request.parts = busboy(ctx, opts);
  };
}

/**
 * Creates body parser middleware.
 *
 * @param {Object} spec
 * @return {async function}
 * @api private
 */

function makeBodyParser(spec) {
  if (!(spec.validate && spec.validate.type)) return noopMiddleware;

  switch (spec.validate.type) {
    case 'json':
      return wrapError(spec, makeJSONBodyParser(spec));
    case 'form':
      return wrapError(spec, makeFormBodyParser(spec));
    case 'stream':
    case 'multipart':
      return wrapError(spec, makeMultipartParser(spec));
    default:
      throw new Error(`unsupported body type: ${spec.validate.type}`);
  }
}

/**
 * @api private
 */

function captureError(ctx, type, err) {
  // expose Error message to JSON.stringify()
  err.msg = err.message;
  if (!ctx.invalid) ctx.invalid = {};
  ctx.invalid[type] = err;
}

/**
 * Creates validator middleware.
 *
 * @param {Object} spec
 * @return {async function}
 * @api private
 */

function makeValidator(spec) {
  const props = 'header query params body'.split(' ');

  return async function validator(ctx, next) {
    if (!spec.validate) return await next();

    let err;

    for (let i = 0; i < props.length; ++i) {
      const prop = props[i];

      if (spec.validate[prop]) {
        err = validateInput(prop, ctx, spec.validate);

        if (err) {
          captureError(ctx, prop, err);
          if (!spec.validate.continueOnError) return ctx.throw(err);
        }
      }
    }

    await next();

    if (spec.validate._outputValidator) {
      debug('validating output');

      err = spec.validate._outputValidator.validate(ctx);
      if (err) {
        err.status = 500;
        return ctx.throw(err);
      }
    }
  };
}

/**
 * Exposes route spec
 * @param {Object} spec The route spec
 * @returns {async Function} Middleware
 * @api private
 */
function makeSpecExposer(spec) {
  const defn = clone(spec);
  return async function specExposer(ctx, next) {
    ctx.state.route = defn;
    await next();
  };
}

/**
 * Middleware which creates `request.params`.
 *
 * @api private
 */

async function prepareRequest(ctx, next) {
  ctx.request.params = ctx.params;
  await next();
}

/**
 * Validates request[prop] data with the defined validation schema.
 *
 * @param {String} prop
 * @param {koa.Request} request
 * @param {Object} validate
 * @returns {Error|undefined}
 * @api private
 */

function validateInput(prop, ctx, validate) {
  debug('validating %s', prop);

  const request = ctx.request;
  const res = Joi.compile(validate[prop]).validate(request[prop], validate.validateOptions || {});

  if (res.error) {
    res.error.status = validate.failure;
    return res.error;
  }

  // update our request w/ the casted values
  switch (prop) {
    case 'header': // request.header is getter only, cannot set it
    case 'query': // setting request.query directly causes casting back to strings
      Object.keys(res.value).forEach((key) => {
        request[prop][key] = res.value[key];
      });
      break;
    case 'params':
      request.params = ctx.params = res.value;
      break;
    default:
      request[prop] = res.value;
  }
}

/**
 * Expose `KoaJoiRouter`.
 */
module.exports = KoaJoiRouter