'use strict';

////////////////////////////////////////////////////////////////////////////////
/// @brief Foxx Controller
///
/// @file
///
/// DISCLAIMER
///
/// Copyright 2013 triagens GmbH, Cologne, Germany
///
/// Licensed under the Apache License, Version 2.0 (the "License");
/// you may not use this file except in compliance with the License.
/// You may obtain a copy of the License at
///
///     http://www.apache.org/licenses/LICENSE-2.0
///
/// Unless required by applicable law or agreed to in writing, software
/// distributed under the License is distributed on an "AS IS" BASIS,
/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
/// See the License for the specific language governing permissions and
/// limitations under the License.
///
/// Copyright holder is triAGENS GmbH, Cologne, Germany
///
/// @author Lucas Dohmen
/// @author Copyright 2013, triAGENS GmbH, Cologne, Germany
////////////////////////////////////////////////////////////////////////////////

const deprecated = require('@arangodb/deprecated');
const RequestContext = require('@arangodb/foxx/request_context');
const BaseMiddleware = require('@arangodb/foxx/base_middleware').BaseMiddleware;
const _ = require('underscore');
const is = require('@arangodb/is');
const internal = require('@arangodb/foxx/internals');
const swagger = require('@arangodb/foxx/swagger');

// -----------------------------------------------------------------------------
// --SECTION--                                                       Controller
// -----------------------------------------------------------------------------

var authControllerProps = {
////////////////////////////////////////////////////////////////////////////////
/// JSF_foxx_controller_getUsers
/// @brief Get the users of this controller
////////////////////////////////////////////////////////////////////////////////
  getUsers() {
    const foxxAuthentication = require('@arangodb/foxx/authentication');
    return new foxxAuthentication.Users(this.applicationContext);
  },

////////////////////////////////////////////////////////////////////////////////
/// JSF_foxx_controller_getAuth
/// @brief Get the auth object of this controller
////////////////////////////////////////////////////////////////////////////////
  getAuth() {
    return this.auth;
  },

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_login
///
/// `FoxxController#login(path, opts)`
///
/// Add a route for the login. You can provide further customizations via the
/// the options:
///
/// * *usernameField* and *passwordField* can be used to adjust the expected attributes
///   in the *post* request. They default to *username* and *password*.
/// * *onSuccess* is a function that you can define to do something if the login was
///   successful. This includes sending a response to the user. This defaults to a
///   function that returns a JSON with *user* set to the identifier of the user and
/// * *key* set to the session key.
/// * *onError* is a function that you can define to do something if the login did not
///   work. This includes sending a response to the user. This defaults to a function
///   that sets the response to 401 and returns a JSON with *error* set to
///   "Username or Password was wrong".
///
/// Both *onSuccess* and *onError* should take request and result as arguments.
///
/// @EXAMPLES
///
/// ```js
/// app.login('/login', {
///   onSuccess(req, res) {
///     res.json({"success": true});
///   }
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
  login(route, opts) {
    var authentication = require('@arangodb/foxx/authentication');
    return this.post(route, authentication.createStandardLoginHandler(this.getAuth(), this.getUsers(), opts));
  },

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_logout
///
/// `FoxxController#logout(path, opts)`
///
/// This works pretty similar to the logout function and adds a path to your
/// app for the logout functionality. You can customize it with a custom *onSuccess*
/// and *onError* function:
///
/// * *onSuccess* is a function that you can define to do something if the logout was
///   successful. This includes sending a response to the user. This defaults to a
///   function that returns a JSON with *message* set to "logged out".
/// * *onError* is a function that you can define to do something if the logout did not
///   work. This includes sending a response to the user. This defaults to a function
///   that sets the response to 401 and returns a JSON with *error* set to
///   "No session was found".
///
/// Both *onSuccess* and *onError* should take request and result as arguments.
///
///
/// @EXAMPLES
///
/// ```js
/// app.logout('/logout', {
///   onSuccess(req, res) {
///     res.json({"message": "Bye, Bye"});
///   }
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
  logout(route, opts) {
    var authentication = require('@arangodb/foxx/authentication');
    return this.post(route, authentication.createStandardLogoutHandler(this.getAuth(), opts));
  },

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_register
///
/// `FoxxController#register(path, opts)`
///
/// This works pretty similar to the logout function and adds a path to your
/// app for the register functionality. You can customize it with a custom *onSuccess*
/// and *onError* function:
///
/// * *onSuccess* is a function that you can define to do something if the registration was
///   successful. This includes sending a response to the user. This defaults to a
///   function that returns a JSON with *user* set to the created user document.
/// * *onError* is a function that you can define to do something if the registration did not
///   work. This includes sending a response to the user. This defaults to a function
///   that sets the response to 401 and returns a JSON with *error* set to
///   "Registration failed".
///
/// Both *onSuccess* and *onError* should take request and result as arguments.
///
/// You can also set the fields containing the username and password via *usernameField*
/// (defaults to *username*) and *passwordField* (defaults to *password*).
/// If you want to accept additional attributes for the user document, use the option
/// *acceptedAttributes* and set it to an array containing strings with the names of
/// the additional attributes you want to accept. All other attributes in the request
/// will be ignored.
///
/// If you want default attributes for the accepted attributes or set additional fields
/// (for example *admin*) use the option *defaultAttributes* which should be a hash
/// mapping attribute names to default values.
///
/// @EXAMPLES
///
/// ```js
/// app.register('/logout', {
///   acceptedAttributes: ['name'],
///   defaultAttributes: {
///     admin: false
///   }
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
  register(route, opts) {
    var authentication = require('@arangodb/foxx/authentication');
    return this.post(
      route,
      authentication.createStandardRegistrationHandler(this.getAuth(), this.getUsers(), opts)
    ).errorResponse(authentication.UserAlreadyExistsError, 400, 'User already exists');
  },

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_changePassword
///
/// FoxxController#changePassword(route, opts)`
///
/// Add a route for the logged in user to change the password.
/// You can provide further customizations via the
/// the options:
///
/// * *passwordField* can be used to adjust the expected attribute
///   in the *post* request. It defaults to *password*.
/// * *onSuccess* is a function that you can define to do something if the change was
///   successful. This includes sending a response to the user. This defaults to a
///   function that returns a JSON with *notice* set to "Changed password!".
/// * *onError* is a function that you can define to do something if the login did not
///   work. This includes sending a response to the user. This defaults to a function
///   that sets the response to 401 and returns a JSON with *error* set to
///   "No session was found".
///
/// Both *onSuccess* and *onError* should take request and result as arguments.
///
/// @EXAMPLES
///
/// ```js
/// app.changePassword('/changePassword', {
///   onSuccess(req, res) {
///     res.json({"success": true});
///   }
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
  changePassword(route, opts) {
    var authentication = require('@arangodb/foxx/authentication');
    return this.post(route, authentication.createStandardChangePasswordHandler(this.getUsers(), opts));
  }
};

var sessionControllerProps = {
////////////////////////////////////////////////////////////////////////////////
/// JSF_foxx_controller_getSessions
/// @brief Get the sessions object of this controller
////////////////////////////////////////////////////////////////////////////////
  getSessions() {
    return this.sessions;
  },

////////////////////////////////////////////////////////////////////////////////
/// @brief defines a route to logout/destroy the session
////////////////////////////////////////////////////////////////////////////////

  destroySession(route, opts) {
    var method = opts.method;
    if (typeof method === 'string') {
      method = method.toLowerCase();
    }
    if (!method || typeof this[method] !== 'function') {
      method = 'post';
    }
    var sessions = require('@arangodb/foxx/sessions');
    return this[method](route, sessions.createDestroySessionHandler(this.getSessions(), opts));
  }
};

class Controller {

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_initializer
///
/// `new Controller(applicationContext, options)`
///
/// This creates a new Controller. The first argument is the controller
/// context available in the variable *applicationContext*. The second one is an
/// options array with the following attributes:
///
/// * *urlPrefix*: All routes you define within will be prefixed with it.
///
/// @EXAMPLES
///
/// ```js
/// app = new Controller(applicationContext, {
///   urlPrefix: "/meadow"
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

  constructor(context, options) {
    this.currentPriority = 0;

    var urlPrefix, baseMiddleware;
    context.clearComments();

    if (is.notExisty(context)) {
      throw new Error('parameter <context> is missing');
    }
    context.clearComments();

    this.routingInfo = {
      routes: []
    };

    // Models for the Documentation
    this.models = {};

    options = options || {};
    urlPrefix = options.urlPrefix || '';

    if (urlPrefix === '') {
      urlPrefix = context.prefix;
    } else if (context.prefix !== '') {
      urlPrefix = context.prefix + '/' + urlPrefix;
    }

    this.injected = Object.create(null);
    this.injectors = Object.create(null);
    this.routingInfo.urlPrefix = urlPrefix;
    this.collectionPrefix = context.collectionPrefix;

    this.extensions = {};

    baseMiddleware = new BaseMiddleware();

    this.routingInfo.middleware = [
      {
        url: { match: '/*' },
        action: {
          callback: baseMiddleware.functionRepresentation,
          options: {
            name: context.name,
            version: context.version,
            mount: context.mount,
            isDevelopment: context.isDevelopment,
            isProduction: context.isProduction,
            prefix: context.prefix,
            options: context.options
          }
        }
      }
    ];

    this.allRoutes = new RequestContext.Buffer();

    context.foxxes.push(this);

    if (is.existy(context.manifest.rootElement)) {
      this.rootElement = context.manifest.rootElement;
    } else {
      this.rootElement = false;
    }

    this.applicationContext = context;
  }

  addInjector(name, factory) {
    deprecated('2.9', '"addInjector" is deprecated, use regular variables instead');
    if (factory === undefined) {
      _.extend(this.injectors, name);
    } else {
      this.injectors[name] = factory;
    }
  }

////////////////////////////////////////////////////////////////////////////////
///
/// The *handleRequest* method is the raw way to create a new route. You
/// probably wont call it directly, but it is used in the other request methods:
///
/// When defining a route you can also define a so called 'parameterized' route
/// like */goose/:barn*. In this case you can later get the value the user
/// provided for *barn* via the *params* function (see the Request object).
////////////////////////////////////////////////////////////////////////////////

  handleRequest(method, route, callback) {
    var constraints = {queryParams: {}, urlParams: {}};
    var newRoute = internal.constructRoute(method, route, callback, this, constraints);
    var requestContext = new RequestContext(
      this.allRoutes, this.models, newRoute, route, this.rootElement, constraints, this.extensions
    );
    var summary;
    var undocumentedBody;

    this.routingInfo.routes.push(newRoute);

    if (this.applicationContext.comments.length > 0) {
      do {
        summary = this.applicationContext.comments.shift();
      } while (summary === '');
      requestContext.summary(summary || '');
      requestContext.notes(this.applicationContext.comments.join('\n'));
    }

    this.applicationContext.clearComments();

    if (method === 'post' || method === 'put' || method === 'patch') {
      const Model = require('@arangodb/foxx').Model;
      undocumentedBody = class UndocumentedBody extends Model {};
      requestContext.bodyParam('undocumented body', {
        description: 'Undocumented body param',
        type: undocumentedBody,
        allowInvalid: true
      });
    }

    return requestContext;
  }

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_head
///
/// `Controller.head(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `head`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.head('/goose/barn', function (req, res) {
///   // Take this request and deal with it!
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

  head(route, callback) {
    return this.handleRequest('head', route, callback);
  }

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_get
///
/// `Controller.get(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `get`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.get('/goose/barn', function (req, res) {
///   // Take this request and deal with it!
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

  get(route, callback) {
    return this.handleRequest('get', route, callback);
  }

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_post
///
/// `Controller.post(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `post`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.post('/goose/barn', function (req, res) {
///   // Take this request and deal with it!
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

  post(route, callback) {
    return this.handleRequest('post', route, callback);
  }

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_put
///
/// `Controller.put(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `put`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.put('/goose/barn', function (req, res) {
///   // Take this request and deal with it!
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

  put(route, callback) {
    return this.handleRequest('put', route, callback);
  }

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_patch
///
/// `Controller.patch(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `patch`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.patch('/goose/barn', function (req, res) {
///   // Take this request and deal with it!
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

  patch(route, callback) {
    return this.handleRequest('patch', route, callback);
  }

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_delete
///
/// `Controller.delete(path, callback)`
///
/// Defines a new route on `path` that handles requests from the HTTP verb `delete`.
/// This route can also be 'parameterized' like `/goose/:barn`.
/// In this case you can later get the value the user provided for `barn`
/// via the `params` function in the `request`.
/// The function defined in `callback` will be invoked whenever this type of
/// request is recieved.
/// `callback` get's two arguments `request` and `response`, see below for further
/// information about these objects.
///
/// @EXAMPLES
///
/// ```js
/// app.delete('/goose/barn', function (req, res) {
///   // Take this request and deal with it!
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

  delete(route, callback) {
    return this.handleRequest('delete', route, callback);
  }

  del(route, callback) {
    deprecated('2.9', '"del" is deprecated, use "delete" instead');
    return this.delete(route, callback);
  }

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_before
///
/// `Controller.before(path, callback)`
///
/// Defines an additional function on the route `path` which will be executed
/// before the callback defined for a specific HTTP verb is executed.
/// The `callback` function has the same signature as the `callback` in the
/// specific route.
/// You can also omit the `path`, in this case `callback` will be executed
/// before handleing any request in this Controller.
///
/// If `callback` returns the Boolean value `false`, the route handling
/// will not proceed. You can use this to intercept invalid or unauthorized
/// requests and prevent them from being passed to the matching routes.
///
/// @EXAMPLES
///
/// ```js
/// app.before('/high/way', function(req, res) {
///   //Do some crazy request logging
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

  before(path, func) {
    if (is.notExisty(func)) {
      func = path;
      path = '/*';
    }

    this.routingInfo.middleware.push({
      priority: this.currentPriority = this.currentPriority + 1,
      url: {match: path},
      action: {
        callback(req, res, opts, next) {
          var result = func(req, res, opts);
          if (result !== false) {
            next();
          }
        }
      }
    });
  }

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_after
///
/// `Controller.after(path, callback)`
///
/// Similar to `Controller.before(path, callback)` but `callback` will be invoked
/// after the request is handled in the specific route.
///
/// @EXAMPLES
///
/// ```js
/// app.after('/high/way', function(req, res) {
///   //Do some crazy response logging
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

  after(path, func) {
    if (is.notExisty(func)) {
      func = path;
      path = '/*';
    }

    this.routingInfo.middleware.push({
      priority: this.currentPriority = this.currentPriority + 1,
      url: {match: path},
      action: {
        callback(req, res, opts, next) { next(); func(req, res, opts); }
      }
    });
  }

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_around
///
/// `Controller.around(path, callback)`
///
/// Similar to `Controller.before(path, callback)` `callback` will be invoked
/// instead of the specific handler.
/// `callback` takes two additional paramaters `opts` and `next` where
/// `opts` contains options assigned to the route and `next` is a function.
/// Whenever you call `next` in `callback` the specific handler is invoked,
/// if you do not call `next` the specific handler will not be invoked at all.
/// So using around you can execute code before and after a specific handler
/// and even call the handler only under certain circumstances.
/// If you omit `path` `callback` will be called on every request.
///
/// @EXAMPLES
///
/// ```js
/// app.around('/high/way', function(req, res, opts, next) {
///   //Do some crazy request logging
///   next();
///   //Do some more crazy request logging
/// });
/// ```
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

  around(path, func) {

    if (is.notExisty(func)) {
      func = path;
      path = '/*';
    }

    this.routingInfo.middleware.push({
      priority: this.currentPriority = this.currentPriority + 1,
      url: {match: path},
      action: {
        callback(req, res, opts, next) {
          func(req, res, opts, next);
        }
      }
    });
  }

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_activateAuthentication
///
/// `Controller.activateAuthentication(opts)`
///
/// To activate authentication for this controller, call this function before defining any routes.
/// In the `opts` object you can set the following keys:
///
/// * *type*: Currently we only support *cookie*, but this will change in the future
/// * *cookieLifetime*: An integer. Lifetime of cookies in seconds
/// * *cookieName*: A string used as the name of the cookie
/// * *sessionLifetime*: An integer. Lifetime of sessions in seconds
///
/// @EXAMPLES
///
/// ```js
/// app.activateAuthentication({
///   type: "cookie",
///   cookieLifetime: 360000,
///   cookieName: "my_cookie",
///   sessionLifetime: 400,
/// });
/// ```
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
  activateAuthentication(opts) {
    var authentication = require('@arangodb/foxx/authentication');
    _.extend(this, authControllerProps);

    this.auth = authentication.createAuthObject(this.applicationContext, opts);
    this.before('/*', authentication.createAuthenticationMiddleware(this.auth, this.applicationContext));
    this.after('/*', authentication.createSessionUpdateMiddleware());
  }

////////////////////////////////////////////////////////////////////////////////
/// @brief activate sessions with the giveon options for this controller
////////////////////////////////////////////////////////////////////////////////

  activateSessions(opts) {
    var sessions = require('@arangodb/foxx/sessions');
    _.extend(this, sessionControllerProps);

    this.sessions = new sessions.Sessions(opts);
    sessions.decorateController(this.sessions, this);
  }

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_apiDocumentation
///
/// `Controller.apiDocumentation(path, [opts])`
///
/// Mounts the API documentation (Swagger) at the given `path`.
///
/// Note that the `path` can use path parameters as usual but must not use any
/// wildcard (`*`) or optional (`:name?`) parameters.
///
/// The optional **opts** can be an object with any of the following properties:
///
/// * **before**: a function that will be executed before a request to
///   this endpoint is processed further.
/// * **appPath**: the mount point of the app for which documentation will be
///   shown. Default: the mount point of the active app.
/// * **indexFile**: file path or file name of the Swagger HTML file.
///   Default: `"index.html"`.
/// * **swaggerJson**: file path or file name of the Swagger API description JSON
///   file or a function `swaggerJson(req, res, opts)` that sends a Swagger API
///   description in JSON. Default: the built-in Swagger description generator.
/// * **swaggerRoot**: absolute path that will be used as the path path for any
///   relative paths of the documentation assets, **swaggerJson** file and
///   the **indexFile**. Default: the built-in Swagger distribution.
///
/// If **opts** is a function, it will be used as the value of **opts.before**.
///
/// If **opts.before** returns `false`, the request will not be processed
/// further.
///
/// If **opts.before** returns an object, any properties will override the
/// equivalent properties of **opts** for the current request.
///
/// Of course all **before**, **after** or **around** functions defined on the
/// controller will also be executed as usual.
///
/// **Examples**
///
/// ```js
/// controller.apiDocumentation('/my/dox');
///
/// ```
///
/// A request to `/my/dox` will be redirect to `/my/dox/index.html`,
/// which will show the API documentation of the active app.
///
/// ```js
/// controller.apiDocumentation('/my/dox', function (req, res) {
///   if (!req.session.get('uid')) {
///     res.status(403);
///     res.json({error: 'only logged in users may see the API'});
///     return false;
///   }
///   return {appPath: req.parameters.mount};
/// });
/// ```
///
/// A request to `/my/dox/index.html?mount=/_admin/aardvark` will show the
/// API documentation of the admin frontend (mounted at `/_admin/aardvark`).
/// If the user is not logged in, the error message will be shown instead.
///
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////
  apiDocumentation(route, opts) {
    if (route.charAt(route.length - 1) !== '/') {
      route += '/';
    }
    var mountPath = this.applicationContext.mount;
    return this.get(route + '*', swagger.createSwaggerRouteHandler(mountPath, opts));
  }

////////////////////////////////////////////////////////////////////////////////
/// @startDocuBlock JSF_foxx_controller_extend
///
/// `Controller.extend(extensions)`
///
/// Extends all functions to define routes in this controller.
/// This allows to combine several route extensions with the invocation
/// of a single function.
/// This is especially useful if you use the same input parameter in several routes of
/// your controller and want to apply the same validation, documentation and error handling
/// for it.
///
/// The `extensions` parameter is a JSON object with arbitrary keys.
/// Each key is used as the name of the function you want to define (you cannot overwrite
/// internal functions like `pathParam`) and the value is a function that will be invoked.
/// This function can get arbitrary many arguments and the `this` of the function is bound
/// to the route definition object (e.g. you can use `this.pathParam()`).
/// Your newly defined function is chainable similar to the internal functions.
///
/// **Examples**
///
/// Define a validator for a queryParameter, including documentation and errorResponses
/// in a single command:
///
/// ```js
/// controller.extend({
///   myParam: function (maxValue) {
///     this.queryParam("value", {type: joi.number().required()});
///     this.onlyIf(function(req) {
///       var v = req.param("value");
///       if (v > maxValue) {
///         throw new NumberTooLargeError();
///       }
///     });
///     this.errorResponse(NumberTooLargeError, 400, "The given value is too large");
///   }
/// });
///
/// controller.get("/goose/barn", function(req, res) {
///   // Will only be invoked if the request has parameter value and it is less or equal 5.
/// }).myParam(5);
/// ```
/// 
/// @endDocuBlock
////////////////////////////////////////////////////////////////////////////////

  extend(extensions) {
    var attr;
    var extensionWrapper = function(scope, functionName) {
      return function() {
        this.applyChain.push({
          functionName: functionName,
          argumentList: arguments
        });
        return this;
      }.bind(scope);
    };
    for (attr in extensions) {
      if (extensions.hasOwnProperty(attr)) {
        this.extensions[attr] = extensions[attr];
        this.allRoutes[attr] = extensionWrapper(this.allRoutes, attr);
      }
    }
  }

}

exports.Controller = Controller;

// -----------------------------------------------------------------------------
// --SECTION--                                                       END-OF-FILE
// -----------------------------------------------------------------------------

/// Local Variables:
/// mode: outline-minor
/// outline-regexp: "/// @brief\\|/// @addtogroup\\|/// @page\\|// --SECTION--\\|/// @\\}\\|/\\*jslint"
/// End: