restify/lib/server.js

// Copyright 2012 Mark Cavage, Inc.  All rights reserved.

'use strict';

var domain = require('domain');
var EventEmitter = require('events').EventEmitter;
var http = require('http');
var https = require('https');
var util = require('util');

var _ = require('lodash');
var assert = require('assert-plus');
var errors = require('restify-errors');
var mime = require('mime');
var spdy = require('spdy');
var vasync = require('vasync');

var Chain = require('./chain');
var dtrace = require('./dtrace');
var formatters = require('./formatters');
var shallowCopy = require('./utils').shallowCopy;
var upgrade = require('./upgrade');
var deprecationWarnings = require('./deprecationWarnings');
var customErrorTypes = require('./errorTypes');

// Ensure these are loaded
var patchRequest = require('./request');
var patchResponse = require('./response');

var http2;

patchResponse(http.ServerResponse);
patchRequest(http.IncomingMessage);

///--- Globals

var sprintf = util.format;

///--- API

/**
 * Creates a new Server.
 *
 * @public
 * @class
 * @param {Object} options  - an options object
 * @param {String} options.name - Name of the server.
 * @param {Boolean} [options.dtrace=false] - enable DTrace support
 * @param {Router} options.router - Router
 * @param {Object} options.log - [bunyan](https://github.com/trentm/node-bunyan)
 * instance.
 * @param {String} [options.url] - Once listen() is called, this will be filled
 * in with where the server is running.
 * @param {String|Buffer} [options.certificate] - If you want to create an HTTPS
 * server, pass in a PEM-encoded certificate and key.
 * @param {String|Buffer} [options.key] - If you want to create an HTTPS server,
 * pass in a PEM-encoded certificate and key.
 * @param {Object} [options.formatters] - Custom response formatters for
 * `res.send()`.
 * @param {Boolean} [options.handleUncaughtExceptions=false] - When true restify
 * will use a domain to catch and respond to any uncaught
 * exceptions that occur in it's handler stack.
 * Comes with significant negative performance impact.
 * [bunyan](https://github.com/trentm/node-bunyan) instance.
 * response header, default is `restify`. Pass empty string to unset the header.
 * @param {Object} [options.spdy] - Any options accepted by
 * [node-spdy](https://github.com/indutny/node-spdy).
 * @param {Object} [options.http2] - Any options accepted by
 * [http2.createSecureServer](https://nodejs.org/api/http2.html).
 * @param {Boolean} [options.handleUpgrades=false] - Hook the `upgrade` event
 * from the node HTTP server, pushing `Connection: Upgrade` requests through the
 *  regular request handling chain.
 * @param {Boolean} [options.onceNext=false] - Prevents calling next multiple
 *  times
 * @param {Boolean} [options.strictNext=false] - Throws error when next() is
 *  called more than once, enabled onceNext option
 * @param {Object} [options.httpsServerOptions] - Any options accepted by
 * [node-https Server](http://nodejs.org/api/https.html#https_https).
 * If provided the following restify server options will be ignored:
 * spdy, ca, certificate, key, passphrase, rejectUnauthorized, requestCert and
 * ciphers; however these can all be specified on httpsServerOptions.
 * @param {Boolean} [options.noWriteContinue=false] - prevents
 *  `res.writeContinue()` in `server.on('checkContinue')` when proxing
 * @param {Boolean} [options.ignoreTrailingSlash=false] - ignore trailing slash
 * on paths
 * @param {Boolean} [options.strictFormatters=true] - enables strict formatters
 * behavior: a formatter matching the response's content-type is required. If
 * not found, the response's content-type is automatically set to
 * 'application/octet-stream'. If a formatter for that content-type is not
 * found, sending the response errors.
 * @example
 * var restify = require('restify');
 * var server = restify.createServer();
 *
 * server.listen(8080, function () {
 *   console.log('ready on %s', server.url);
 * });
 */
function Server(options) {
    assert.object(options, 'options');
    assert.object(options.log, 'options.log');
    assert.object(options.router, 'options.router');
    assert.string(options.name, 'options.name');
    assert.optionalBool(
        options.handleUncaughtExceptions,
        'options.handleUncaughtExceptions'
    );
    assert.optionalBool(options.dtrace, 'options.dtrace');
    assert.optionalBool(options.socketio, 'options.socketio');
    assert.optionalBool(options.onceNext, 'options.onceNext');
    assert.optionalBool(options.strictNext, 'options.strictNext');
    assert.optionalBool(options.strictFormatters, 'options.strictFormatters');

    var self = this;

    EventEmitter.call(this);

    this.onceNext = !!options.onceNext;
    this.strictNext = !!options.strictNext;
    this.firstChain = [];
    this.preChain = new Chain({
        onceNext: this.onceNext,
        strictNext: this.strictNext
    });
    this.useChain = new Chain({
        onceNext: this.onceNext,
        strictNext: this.strictNext
    });
    this.log = options.log;
    this.name = options.name;
    this.handleUncaughtExceptions = options.handleUncaughtExceptions || false;
    this.router = options.router;
    this.secure = false;
    this.socketio = options.socketio || false;
    this.dtrace = options.dtrace || false;
    this._inflightRequests = 0;

    this.strictFormatters = true;
    if (options.strictFormatters !== undefined) {
        this.strictFormatters = options.strictFormatters;
    }

    var fmt = mergeFormatters(options.formatters);
    this.acceptable = fmt.acceptable;
    this.formatters = fmt.formatters;
    this.proxyEvents = [
        'clientError',
        'close',
        'connection',
        'error',
        'listening',
        'secureConnection'
    ];

    if (options.spdy) {
        this.spdy = true;
        this.server = spdy.createServer(options.spdy);
    } else if (options.http2) {
        // http2 module is not available < v8.4.0 (only with flag <= 8.8.0)
        // load http2 module here to avoid experimental warning in other cases
        if (!http2) {
            try {
                http2 = require('http2');
                patchResponse(http2.Http2ServerResponse);
                patchRequest(http2.Http2ServerRequest);
                // eslint-disable-next-line no-empty
            } catch (err) {}
        }

        assert(
            http2,
            'http2 module is not available, ' +
                'upgrade your Node.js version to >= 8.8.0'
        );

        this.http2 = true;
        this.server = http2.createSecureServer(options.http2);
    } else if ((options.cert || options.certificate) && options.key) {
        this.ca = options.ca;
        this.certificate = options.certificate || options.cert;
        this.key = options.key;
        this.passphrase = options.passphrase || null;
        this.secure = true;

        this.server = https.createServer({
            ca: self.ca,
            cert: self.certificate,
            key: self.key,
            passphrase: self.passphrase,
            rejectUnauthorized: options.rejectUnauthorized,
            requestCert: options.requestCert,
            ciphers: options.ciphers,
            secureOptions: options.secureOptions
        });
    } else if (options.httpsServerOptions) {
        this.server = https.createServer(options.httpsServerOptions);
    } else {
        this.server = http.createServer();
    }

    this.router.on('mount', this.emit.bind(this, 'mount'));

    if (!options.handleUpgrades) {
        this.proxyEvents.push('upgrade');
    }
    this.proxyEvents.forEach(function forEach(e) {
        self.server.on(e, self.emit.bind(self, e));
    });

    // Now the things we can't blindly proxy
    this.server.on('checkContinue', function onCheckContinue(req, res) {
        if (self.listeners('checkContinue').length > 0) {
            self.emit('checkContinue', req, res);
            return;
        }

        if (!options.noWriteContinue) {
            res.writeContinue();
        }

        self._onRequest(req, res);
    });

    if (options.handleUpgrades) {
        this.server.on('upgrade', function onUpgrade(req, socket, head) {
            req._upgradeRequest = true;
            var res = upgrade.createResponse(req, socket, head);
            self._onRequest(req, res);
        });
    }

    this.server.on('request', this._onRequest.bind(this));

    this.__defineGetter__('maxHeadersCount', function getMaxHeadersCount() {
        return self.server.maxHeadersCount;
    });

    this.__defineSetter__('maxHeadersCount', function setMaxHeadersCount(c) {
        self.server.maxHeadersCount = c;
        return c;
    });

    this.__defineGetter__('url', function getUrl() {
        if (self.socketPath) {
            return 'http://' + self.socketPath;
        }

        var addr = self.address();
        var str = '';

        if (self.spdy) {
            str += 'spdy://';
        } else if (self.secure) {
            str += 'https://';
        } else {
            str += 'http://';
        }

        if (addr) {
            str +=
                addr.family === 'IPv6'
                    ? '[' + addr.address + ']'
                    : addr.address;
            str += ':';
            str += addr.port;
        } else {
            str += '169.254.0.1:0000';
        }

        return str;
    });

    // print deprecation messages based on server configuration
    deprecationWarnings(self);
}
util.inherits(Server, EventEmitter);

module.exports = Server;

///--- Server lifecycle methods

// eslint-disable-next-line jsdoc/check-param-names
/**
 * Gets the server up and listening.
 * Wraps node's
 * [listen()](
 * http://nodejs.org/docs/latest/api/net.html#net_server_listen_path_callback).
 *
 * @public
 * @memberof Server
 * @instance
 * @function   listen
 * @throws   {TypeError}
 * @param    {Number} port - Port
 * @param    {Number} [host] - Host
 * @param    {Function} [callback] - optionally get notified when listening.
 * @returns  {undefined} no return value
 * @example
 * <caption>You can call like:</caption>
 * server.listen(80)
 * server.listen(80, '127.0.0.1')
 * server.listen('/tmp/server.sock')
 */
Server.prototype.listen = function listen() {
    var args = Array.prototype.slice.call(arguments);
    return this.server.listen.apply(this.server, args);
};

/**
 * Shuts down this server, and invokes callback (optionally) when done.
 * Wraps node's
 * [close()](http://nodejs.org/docs/latest/api/net.html#net_event_close).
 *
 * @public
 * @memberof Server
 * @instance
 * @function   close
 * @param    {Function}  [callback] - callback to invoke when done
 * @returns  {undefined} no return value
 */
Server.prototype.close = function close(callback) {
    if (callback) {
        assert.func(callback, 'callback');
    }

    this.server.once('close', function onClose() {
        return callback ? callback() : false;
    });

    return this.server.close();
};

///--- Routing methods

/**
 * Server method opts
 * @typedef  {String|Regexp |Object} Server~methodOpts
 * @type     {Object}
 * @property {String} name a name for the route
 * @property {String} path can be any String accepted by
 * [find-my-way](https://github.com/delvedor/find-my-way)
 * @example
 * // a static route
 * server.get('/foo', function(req, res, next) {});
 * // a parameterized route
 * server.get('/foo/:bar', function(req, res, next) {});
 * // a regular expression
 * server.get('/example/:file(^\\d+).png', function(req, res, next) {});
 * // an options object
 * server.get({
 *     path: '/foo',
 * }, function(req, res, next) {});
 */

/**
 * Mounts a chain on the given path against this HTTP verb
 *
 * @public
 * @memberof Server
 * @instance
 * @function get
 * @param   {Server~methodOpts} opts - if string, the URL to handle.
 *                                 if options, the URL to handle, at minimum.
 * @returns {Route}                the newly created route.
 * @example
 * server.get('/', function (req, res, next) {
 *    res.send({ hello: 'world' });
 *    next();
 * });
 */
Server.prototype.get = serverMethodFactory('GET');

/**
 * Mounts a chain on the given path against this HTTP verb
 *
 * @public
 * @memberof Server
 * @instance
 * @function head
 * @param   {Server~methodOpts} opts - if string, the URL to handle.
 *                                 if options, the URL to handle, at minimum.
 * @returns {Route}                the newly created route.
 */
Server.prototype.head = serverMethodFactory('HEAD');

/**
 * Mounts a chain on the given path against this HTTP verb
 *
 * @public
 * @memberof Server
 * @instance
 * @function post
 * @param   {Server~methodOpts} post - if string, the URL to handle.
 *                                 if options, the URL to handle, at minimum.
 * @returns {Route}                the newly created route.
 */
Server.prototype.post = serverMethodFactory('POST');

/**
 * Mounts a chain on the given path against this HTTP verb
 *
 * @public
 * @memberof Server
 * @instance
 * @function put
 * @param   {Server~methodOpts} put - if string, the URL to handle.
 *                                 if options, the URL to handle, at minimum.
 * @returns {Route}                the newly created route.
 */
Server.prototype.put = serverMethodFactory('PUT');

/**
 * Mounts a chain on the given path against this HTTP verb
 *
 * @public
 * @memberof Server
 * @instance
 * @function patch
 * @param   {Server~methodOpts} patch - if string, the URL to handle.
 *                                 if options, the URL to handle, at minimum.
 * @returns {Route}                the newly created route.
 */
Server.prototype.patch = serverMethodFactory('PATCH');

/**
 * Mounts a chain on the given path against this HTTP verb
 *
 * @public
 * @memberof Server
 * @instance
 * @function del
 * @param   {Server~methodOpts} opts - if string, the URL to handle.
 *                                 if options, the URL to handle, at minimum.
 * @returns {Route}                the newly created route.
 */
Server.prototype.del = serverMethodFactory('DELETE');

/**
 * Mounts a chain on the given path against this HTTP verb
 *
 * @public
 * @memberof Server
 * @instance
 * @function opts
 * @param   {Server~methodOpts} opts - if string, the URL to handle.
 *                                 if options, the URL to handle, at minimum.
 * @returns {Route}                the newly created route.
 */
Server.prototype.opts = serverMethodFactory('OPTIONS');

///---  Request lifecycle and middleware methods

// eslint-disable-next-line jsdoc/check-param-names
/**
 * Gives you hooks to run _before_ any routes are located.  This gives you
 * a chance to intercept the request and change headers, etc., that routing
 * depends on.  Note that req.params will _not_ be set yet.
 *
 * @public
 * @memberof Server
 * @instance
 * @function pre
 * @param {...Function|Array} handler - Allows you to add handlers that
 * run for all routes. *before* routing occurs.
 * This gives you a hook to change request headers and the like if you need to.
 * Note that `req.params` will be undefined, as that's filled in *after*
 * routing.
 * Takes a function, or an array of functions.
 * variable number of nested arrays of handler functions
 * @returns {Object} returns self
 * @example
 * server.pre(function(req, res, next) {
 *   req.headers.accept = 'application/json';
 *   return next();
 * });
 * @example
 * <caption>For example, `pre()` can be used to deduplicate slashes in
 * URLs</caption>
 * server.pre(restify.pre.dedupeSlashes());
 */
Server.prototype.pre = function pre() {
    var self = this;
    var handlers = Array.prototype.slice.call(arguments);

    argumentsToChain(handlers).forEach(function forEach(handler) {
        handler._name = handler.name || 'pre-' + self.preChain.count();
        self.preChain.add(handler);
    });

    return this;
};

// eslint-disable-next-line jsdoc/check-param-names
/**
 * Gives you hooks that run before restify touches a request. These hooks
 * allow you to do processing early in the request/response life cycle without
 * the overhead of the restify framework. You can not yield the event loop in
 * this handler.
 *
 * The function handler accepts two parameters: req, res. If you want restify
 * to ignore this request, return false from your handler. Return true or
 * undefined to let restify continue handling the request.
 *
 * When false is returned, restify immediately stops handling the request. This
 * means that no further middleware will be executed for any chain and routing
 * will not occure. All request/response handling for an incoming request must
 * be done inside the first handler if you intend to return false. This
 * includes things like closing the response and returning a status code.
 *
 * The only work restify does for a first handler is to increment the number of
 * inflightRequests prior to calling the chain, and decrement that value if the
 * handler returns false. Returning anything other than true, false, undefined,
 * or null will cause an exception to be thrown.
 *
 * Since server.first is designed to bypass the restify framework, there are
 * naturally trade-offs you make when using this API:
 *  * Standard restify lifecycle events such as 'after' are not triggered for
 *    any request that you return false from a handler for
 *  * Invoking any of the restify req/res APIs from within a first handler is
 *    unspecified behavior, as the restify framework hasn't built up state for
 *    the request yet.
 *  * There are no request timers available at the time that the first chain
 *    runs.
 *  * And more! Beware doing anything with restify in these handlers. They are
 *    designed to give you similar access to the req/res as you would have if
 *    you were directly using node.js' http module, they are outside of the
 *    restify framework!
 *
 * @public
 * @memberof Server
 * @instance
 * @function first
 * @param {...Function} handler - Allows you to add handlers that
 * run for all requests, *before* restify touches the request.
 * This gives you a hook to change request headers and the like if you need to.
 * Note that `req.params` will be undefined, as that's filled in *after*
 * routing.

 * Takes one or more functions.
 * @returns {Object} returns self
 * @example
 * server.first(function(req, res) {
 *   if(server.inflightRequests() > 100) {
 *     res.statusCode = 503;
 *     res.end();
 *     return false
 *   }
 *   return true;
 * })
 */
Server.prototype.first = function first() {
    var args = Array.prototype.slice.call(arguments);
    for (var i = 0; i < args.length; i++) {
        assert.func(args[i]);
        this.firstChain.push(args[i]);
    }
    return this;
};

// eslint-disable-next-line jsdoc/check-param-names
/**
 * Allows you to add in handlers that run for all routes. Note that handlers
 * added
 * via `use()` will run only after the router has found a matching route. If no
 * match is found, these handlers will never run. Takes a function, or an array
 * of functions.
 *
 * You can pass in any combination of functions or array of functions.
 *
 * @public
 * @memberof Server
 * @instance
 * @function use
 * @param {...Function|Array} handler - A variable number of handler functions
 * * and/or a
 * variable number of nested arrays of handler functions
 * @returns {Object} returns self
 */
Server.prototype.use = function use() {
    var self = this;
    var handlers = Array.prototype.slice.call(arguments);

    argumentsToChain(handlers).forEach(function forEach(handler) {
        handler._name = handler.name || 'use-' + self.useChain.count();
        self.useChain.add(handler);
    });

    return this;
};

/**
 * Minimal port of the functionality offered by Express.js Route Param
 * Pre-conditions
 *
 * This basically piggy-backs on the `server.use` method. It attaches a
 * new middleware function that only fires if the specified parameter exists
 * in req.params
 *
 * Exposes an API:
 *   server.param("user", function (req, res, next) {
 *     // load the user's information here, always making sure to call next()
 *   });
 *
 * @see http://expressjs.com/guide.html#route-param%20pre-conditions
 * @public
 * @memberof Server
 * @instance
 * @function param
 * @param    {String}   name - The name of the URL param to respond to
 * @param    {Function} fn -   The middleware function to execute
 * @returns  {Object}        returns self
 */
Server.prototype.param = function param(name, fn) {
    this.use(function _param(req, res, next) {
        if (req.params && req.params.hasOwnProperty(name)) {
            fn.call(this, req, res, next, req.params[name], name);
        } else {
            next();
        }
    });

    return this;
};

/**
 * Removes a route from the server.
 * You pass in the route 'blob' you got from a mount call.
 *
 * @public
 * @memberof Server
 * @instance
 * @function rm
 * @throws   {TypeError} on bad input.
 * @param    {String}    routeName - the route name.
 * @returns  {Boolean}   true if route was removed, false if not.
 */
Server.prototype.rm = function rm(routeName) {
    var route = this.router.unmount(routeName);
    return !!route;
};

///--- Info and debug methods

/**
 * Returns the server address.
 * Wraps node's
 * [address()](http://nodejs.org/docs/latest/api/net.html#net_server_address).
 *
 * @public
 * @memberof Server
 * @instance
 * @function address
 * @returns  {Object} Address of server
 * @example
 * server.address()
 * @example
 * <caption>Output:</caption>
 * { address: '::', family: 'IPv6', port: 8080 }
 */
Server.prototype.address = function address() {
    return this.server.address();
};

/**
 * Returns the number of inflight requests currently being handled by the server
 *
 * @public
 * @memberof Server
 * @instance
 * @function inflightRequests
 * @returns  {number} number of inflight requests
 */
Server.prototype.inflightRequests = function inflightRequests() {
    var self = this;
    return self._inflightRequests;
};

/**
 * Return debug information about the server.
 *
 * @public
 * @memberof Server
 * @instance
 * @function debugInfo
 * @returns {Object} debug info
 * @example
 * server.getDebugInfo()
 * @example
 * <caption>Output:</caption>
 * {
 *   routes: [
 *     {
 *       name: 'get',
 *       method: 'get',
 *       input: '/',
 *       compiledRegex: /^[\/]*$/,
 *       compiledUrlParams: null,
 *       handlers: [Array]
 *      }
 *   ],
 *   server: {
 *     formatters: {
 *       'application/javascript': [Function: formatJSONP],
 *       'application/json': [Function: formatJSON],
 *       'text/plain': [Function: formatText],
 *       'application/octet-stream': [Function: formatBinary]
 *     },
 *     address: '::',
 *     port: 8080,
 *     inflightRequests: 0,
 *     pre: [],
 *     use: [ 'parseQueryString', '_jsonp' ],
 *     after: []
 *   }
 * }
 */
Server.prototype.getDebugInfo = function getDebugInfo() {
    var self = this;

    // map an array of function to an array of function names
    var funcNameMapper = function funcNameMapper(handler) {
        if (handler.name === '') {
            return 'anonymous';
        } else {
            return handler.name;
        }
    };

    if (!self._debugInfo) {
        var addressInfo = self.server.address();

        // output the actual routes registered with restify
        var routeInfo = self.router.getDebugInfo();

        var preHandlers = self.preChain.getHandlers().map(funcNameMapper);
        var useHandlers = self.useChain.getHandlers().map(funcNameMapper);

        // get each route's handler chain
        var routes = _.map(routeInfo, function mapValues(route) {
            route.handlers = Array.prototype.concat.call(
                // TODO: should it contain use handlers?
                useHandlers,
                route.handlers.map(funcNameMapper)
            );
            return route;
        });

        self._debugInfo = {
            routes: routes,
            server: {
                formatters: self.formatters,
                // if server is not yet listening, addressInfo may be null
                address: addressInfo && addressInfo.address,
                port: addressInfo && addressInfo.port,
                inflightRequests: self.inflightRequests(),
                pre: preHandlers,
                use: useHandlers,
                after: self.listeners('after').map(funcNameMapper)
            }
        };
    }

    return self._debugInfo;
};

/**
 * toString() the server for easy reading/output.
 *
 * @public
 * @memberof Server
 * @instance
 * @function toString
 * @returns  {String} stringified server
 * @example
 * server.toString()
 * @example
 * <caption>Output:</caption>
 *	Accepts: application/json, text/plain, application/octet-stream,
 * application/javascript
 *	Name: restify
 *	Pre: []
 *	Router: RestifyRouter:
 *		DELETE: []
 *		GET: [get]
 *		HEAD: []
 *		OPTIONS: []
 *		PATCH: []
 *		POST: []
 *		PUT: []
 *
 *	Routes:
 *		get: [parseQueryString, _jsonp, function]
 *	Secure: false
 *	Url: http://[::]:8080
 *	Version:
 */
Server.prototype.toString = function toString() {
    var LINE_FMT = '\t%s: %s\n';
    var SUB_LINE_FMT = '\t\t%s: %s\n';
    var str = '';

    function handlersToString(arr) {
        var s =
            '[' +
            arr
                .map(function map(b) {
                    return b.name || 'function';
                })
                .join(', ') +
            ']';

        return s;
    }

    str += sprintf(LINE_FMT, 'Accepts', this.acceptable.join(', '));
    str += sprintf(LINE_FMT, 'Name', this.name);
    str += sprintf(
        LINE_FMT,
        'Pre',
        handlersToString(this.preChain.getHandlers())
    );
    str += sprintf(LINE_FMT, 'Router', '');
    this.router
        .toString()
        .split('\n')
        .forEach(function forEach(line) {
            str += sprintf('\t\t%s\n', line);
        });
    str += sprintf(LINE_FMT, 'Routes', '');
    _.forEach(this.router.getRoutes(), function forEach(route, routeName) {
        var handlers = handlersToString(route.chain.getHandlers());
        str += sprintf(SUB_LINE_FMT, routeName, handlers);
    });
    str += sprintf(LINE_FMT, 'Secure', this.secure);
    str += sprintf(LINE_FMT, 'Url', this.url);

    return str;
};

///--- Private methods

// Lifecycle:
//
// 1. _onRequest (handle new request, setup request and triggers pre)
//   2. _runPre
//     3. _afterPre (runs after pre handlers are finisehd, triggers route)
//       4. _runRoute (route lookup)
//         5. _runUse (runs use handlers, if route exists)
//            6. Runs route handlers
//              7. _afterRoute (runs after route handlers are finised,
//                          triggers use)
// 8. _finishReqResCycle (on response "finish" and "error" events)
//
// Events:
// e.1 after (triggered when response is flushed)
//
// Errors:
// e.1 _onHandlerError (runs when next was called with an Error)
//   e.2 _routeErrorResponse
// e.1 _onHandlerError (when, next('string') called, trigger route by name)
//  e.2 _afterRoute

/**
 * Setup request and calls _onRequest to run middlewares and call router
 *
 * @private
 * @memberof Server
 * @instance
 * @function _onRequest
 * @param    {Object}    req - the request object
 * @param    {Object}    res - the response object
 * @returns  {undefined} no return value
 * @fires Request,Response#request
 */
Server.prototype._onRequest = function _onRequest(req, res) {
    var self = this;

    // Increment the number of inflight requests prior to calling the firstChain
    // handlers. This accomplishes two things. First, it gives earliest an
    // accurate count of how many inflight requests there would be including
    // this new request. Second, it intentionally winds up the inflight request
    // accounting with the implementation of firstChain. Note how we increment
    // here, but decrement down inside the for loop below. It's easy to end up
    // with race conditions betwen inflight request accounting and inflight
    // request load shedding, causing load shedding to reject/allow too many
    // requests. The current implementation of firstChain is designed to
    // remove those race conditions. By winding these implementations up with
    // one another, it makes it clear that moving around the inflight request
    // accounting will change the behavior of earliest.
    self._inflightRequests++;

    // Give the first chain the earliest possible opportunity to process
    // this request before we do any work on it.
    var firstChain = self.firstChain;
    for (var i = 0; i < firstChain.length; i++) {
        var handle = firstChain[i](req, res);
        // Limit the range of values we will accept as return results of
        // first handlers. This helps us maintain forward compatibility by
        // ensuring users don't rely on undocumented/unspecified behavior.
        assert.ok(
            handle === true ||
                handle === false ||
                handle === undefined ||
                handle === null,
            'Return value of first[' +
                i +
                '] must be: ' +
                'boolean, undefined, or null'
        );
        // If the first handler returns false, stop handling the request
        // immediately.
        if (handle === false) {
            self._inflightRequests--;
            return;
        }
    }

    this.emit('request', req, res);

    // Skip Socket.io endpoints
    if (this.socketio && /^\/socket\.io.*/.test(req.url)) {
        self._inflightRequests--;
        return;
    }

    // Decorate req and res objects
    self._setupRequest(req, res);

    // Run in domain to catch async errors
    // It has significant negative performance impact
    // Warning: this feature depends on the deprecated domains module
    if (self.handleUncaughtExceptions) {
        var handlerDomain = domain.create();
        handlerDomain.add(req);
        handlerDomain.add(res);
        handlerDomain.on('error', function onError(err) {
            self._onHandlerError(err, req, res, true);
        });
        handlerDomain.run(function run() {
            self._runPre(req, res);
        });
    } else {
        self._runPre(req, res);
    }
};

/**
 * Run pre handlers
 *
 * @private
 * @memberof Server
 * @instance
 * @function _runPre
 * @param    {Object}    req - the request object
 * @param    {Object}    res - the response object
 * @returns  {undefined} no return value
 * @fires Request,Response#request
 */
Server.prototype._runPre = function _runPre(req, res) {
    var self = this;

    // emit 'pre' event before we run the pre handlers
    self.emit('pre', req, res);

    // Run "pre"
    req._currentHandler = 'pre';
    req._timePreStart = process.hrtime();

    self.preChain.run(req, res, function preChainDone(err) {
        // Execution time of a handler with error can be significantly lower
        req._timePreEnd = process.hrtime();
        self._afterPre(err, req, res);
    });
};

/**
 * After pre handlers finished
 *
 * @private
 * @memberof Server
 * @instance
 * @function _afterPre
 * @param  {Error|false|undefined} err - pre handler error
 * @param  {Request} req - request
 * @param  {Response} res - response
 * @returns {undefined} no return value
 */
Server.prototype._afterPre = function _afterPre(err, req, res) {
    var self = this;

    // Handle error
    if (err) {
        self._onHandlerError(err, req, res);
        self._finishReqResCycle(req, res, err);
        return;
    }

    // Stop
    if (err === false) {
        self._onHandlerStop(req, res);
        return;
    }

    self._runRoute(req, res);
};

/**
 * Find route and run handlers
 *
 * @private
 * @memberof Server
 * @instance
 * @function _runRoute
 * @param    {Object}    req - the request object
 * @param    {Object}    res - the response object
 * @returns  {undefined} no return value
 * @fires Request,Response#request
 */
Server.prototype._runRoute = function _runRoute(req, res) {
    var self = this;

    var routeHandler = self.router.lookup(req, res);

    if (!routeHandler) {
        self.router.defaultRoute(req, res, function afterRouter(err) {
            self._afterRoute(err, req, res);
        });
        return;
    }

    // Emit routed
    self.emit('routed', req, res, req.route);

    self._runUse(req, res, function afterUse() {
        // DTrace
        if (self.dtrace) {
            dtrace._rstfy_probes['route-start'].fire(function fire() {
                return [
                    self.name,
                    req.route.name,
                    req._dtraceId,
                    req.method,
                    req.href(),
                    req.headers
                ];
            });
        }

        req._timeRouteStart = process.hrtime();
        routeHandler(req, res, function afterRouter(err) {
            // Execution time of a handler with error can be significantly lower
            req._timeRouteEnd = process.hrtime();

            // DTrace
            if (self.dtrace) {
                dtrace._rstfy_probes['route-done'].fire(function fire() {
                    return [
                        self.name,
                        req.route.name,
                        req._dtraceId,
                        res.statusCode || 200,
                        res.headers
                    ];
                });
            }

            self._afterRoute(err, req, res);
        });
    });
};

/**
 * After use handlers finished
 *
 * @private
 * @memberof Server
 * @instance
 * @function _afterRoute
 * @param  {Error|false|undefined} err - use handler error
 * @param  {Request} req - request
 * @param  {Response} res - response
 * @returns {undefined} no return value
 */
Server.prototype._afterRoute = function _afterRoute(err, req, res) {
    var self = this;

    res._handlersFinished = true;

    // Handle error
    if (err) {
        self._onHandlerError(err, req, res);
        self._finishReqResCycle(req, res, err);
        return;
    }

    // Trigger finish
    self._finishReqResCycle(req, res, err);
};

/**
 * Run use handlers
 *
 * @private
 * @memberof Server
 * @instance
 * @function _runUse
 * @param    {Object}    req - the request object
 * @param    {Object}    res - the response object
 * @param    {Function}  next - next
 * @returns  {undefined} no return value
 * @fires Request,Response#request
 */
Server.prototype._runUse = function _runUse(req, res, next) {
    var self = this;

    // Run "use"
    req._currentHandler = 'use';
    req._timeUseStart = process.hrtime();

    self.useChain.run(req, res, function useChainDone(err) {
        // Execution time of a handler with error can be significantly lower
        req._timeUseEnd = process.hrtime();
        self._afterUse(err, req, res, next);
    });
};

/**
 * After use handlers finished
 *
 * @private
 * @memberof Server
 * @instance
 * @function _afterUse
 * @param  {Error|false|undefined} err - use handler error
 * @param  {Request} req - request
 * @param  {Response} res - response
 * @param  {Function}  next - next
 * @returns {undefined} no return value
 */
Server.prototype._afterUse = function _afterUse(err, req, res, next) {
    var self = this;

    // Handle error
    if (err) {
        self._onHandlerError(err, req, res);
        self._finishReqResCycle(req, res, err);
        return;
    }

    // Stop
    if (err === false) {
        self._onHandlerStop(req, res);
        return;
    }

    next();
};

/**
 * Runs after next(false) is called
 *
 * @private
 * @memberof Server
 * @instance
 * @function _onHandlerStop
 * @param  {Request} req - request
 * @param  {Response} res - response
 * @returns {undefined} no return value
 */
Server.prototype._onHandlerStop = function _onHandlerStop(req, res) {
    res._handlersFinished = true;
    this._finishReqResCycle(req, res);
};

/**
 * After route handlers finished
 * NOTE: only called when last handler calls next([err])
 *
 * @private
 * @memberof Server
 * @instance
 * @function _onHandlerError
 * @param  {Error|String|undefined} err - router handler error or route name
 * @param  {Request} req - request
 * @param  {Response} res - response
 * @param  {boolean} isUncaught - whether the error is uncaught
 * @returns {undefined} no return value
 */
Server.prototype._onHandlerError = function _onHandlerError(
    err,
    req,
    res,
    isUncaught
) {
    var self = this;

    // Call route by name
    if (!isUncaught && _.isString(err)) {
        var routeName = err;
        var routeHandler = self.router.lookupByName(routeName, req, res);

        // Cannot find route by name, called when next('route-name') doesn't
        // find any route, it's a 5xx error as it's a programatic error
        if (!routeHandler) {
            var routeByNameErr = new customErrorTypes.RouteMissingError(
                "Route by name doesn't exist"
            );
            routeByNameErr.code = 'ENOEXIST';
            self._afterRoute(routeByNameErr, req, res);
            return;
        }
        routeHandler(req, res, function afterRouter(routeErr) {
            self._afterRoute(routeErr, req, res);
        });
        return;
    }

    // Handlers don't continue when error happen
    res._handlersFinished = true;

    // Preserve handler err for finish event
    res.err = res.err || err;

    // Error happened in router handlers
    self._routeErrorResponse(req, res, err, isUncaught);
};

/**
 * Set up the request before routing and execution of handler chain functions.
 *
 * @private
 * @memberof Server
 * @instance
 * @function _setupRequest
 * @param    {Object}    req - the request object
 * @param    {Object}    res - the response object
 * @returns  {undefined} no return value
 */
Server.prototype._setupRequest = function _setupRequest(req, res) {
    var self = this;

    // Extend request
    req._dtraceId = dtrace.nextId();
    req.log = res.log = self.log;
    req._date = new Date();
    req._timeStart = process.hrtime();
    req.serverName = self.name;
    req.params = {};
    req.timers = [];
    req.dtrace = self.dtrace;

    // Extend response
    res.acceptable = self.acceptable;
    res.formatters = self.formatters;
    res.req = req;
    res.serverName = self.name;
    res._handlersFinished = false;
    res._flushed = false;
    res._strictFormatters = this.strictFormatters;

    // set header only if name isn't empty string
    if (self.name !== '') {
        res.setHeader('Server', self.name);
    }

    // Request lifecycle events

    // attach a listener for 'aborted' events, this will let us set
    // a flag so that we can stop processing the request if the client aborts
    // the connection (or we lose the connection).
    // we consider a closed request as flushed from metrics point of view
    function onReqAborted() {
        // Request was aborted, override the status code
        var err = new customErrorTypes.RequestCloseError();
        err.statusCode = 444;

        // For backward compatibility we only set connection state to "close"
        // for RequestCloseError, also aborted is always immediatly followed
        // by a "close" event.
        // We don't set _connectionState to "close" in the happy path
        req._connectionState = 'close';

        // Set status code and err for audit as req is already closed connection
        res.statusCode = err.statusCode;
        res.err = err;
    }

    // Response lifecycle events
    function onResFinish() {
        var processHrTime = process.hrtime();

        res._flushed = true;
        req._timeFlushed = processHrTime;

        // Response may get flushed before handler callback is triggered
        req._timeFlushed = processHrTime;
        req._timePreEnd = req._timePreEnd || processHrTime;
        req._timeUseEnd = req._timeUseEnd || processHrTime;
        req._timeRouteEnd = req._timeRouteEnd || processHrTime;

        // In Node < 10 "close" event dont fire always
        // https://github.com/nodejs/node/pull/20611
        self._finishReqResCycle(req, res);
    }

    // We are handling when connection is being closed prematurely outside of
    // restify. It's not because the req is aborted.
    function onResClose() {
        res._flushed = true;

        // Finish may already set the req._timeFlushed
        req._timeFlushed = req._timeFlushed || process.hrtime();

        self._finishReqResCycle(req, res, res.err);
    }

    // Request events
    req.once('aborted', onReqAborted);

    // Response events
    res.once('finish', onResFinish);
    res.once('close', onResClose);

    // attach a listener for the response's 'redirect' event
    res.on('redirect', function onRedirect(redirectLocation) {
        self.emit('redirect', redirectLocation);
    });
};

/**
 * Maintaining the end of the request-response cycle:
 *  - emitting after event
 *  - updating inflight requests metrics
 * Check if the response is finished, and if not, wait for it before firing the
 * response object.
 *
 * @private
 * @memberof Server
 * @instance
 * @function _finishReqResCycle
 * @param {Object} req - the request object
 * @param {Object} res - the response object
 * @param {Object} [err] - a possible error as a result of failed route matching
 * or failed execution of the handler array.
 * @returns {undefined} no return value
 */
Server.prototype._finishReqResCycle = function _finishReqResCycle(
    req,
    res,
    err
) {
    var self = this;
    var route = req.route; // can be undefined when 404 or error

    if (res._finished) {
        return;
    }

    if (res._flushed && res._handlersFinished) {
        // decrement number of requests
        self._inflightRequests--;
        res._finished = true;
        req._timeFinished = process.hrtime();

        // after event has signature of function(req, res, route, err) {...}
        var finalErr = err || res.err;
        req.emit('restifyDone', route, finalErr);
        self.emit('after', req, res, route, finalErr);
    } else {
        // Store error for when the response is flushed and we actually emit the
        // 'after' event. The "err" object passed to this method takes
        // precedence, but in case it's not set, "res.err" may have been already
        // set by another code path and we want to preserve it. The caveat thus
        // is that the 'after' event will be emitted with the latest error that
        // was set before the response is fully flushed. While not ideal, this
        // is on purpose and accepted as a reasonable trade-off for now.
        res.err = err || res.err;
    }
};

/**
 * Helper function to, when on router error, emit error events and then
 * flush the err.
 *
 * @private
 * @memberof Server
 * @instance
 * @function _routeErrorResponse
 * @param    {Request}     req -    the request object
 * @param    {Response}    res -    the response object
 * @param    {Error}       err -    error
 * @param    {boolean}     isUncaught - whether the error is uncaught
 * @returns  {undefined} no return value
 */
Server.prototype._routeErrorResponse = function _routeErrorResponse(
    req,
    res,
    err,
    isUncaught
) {
    var self = this;

    if (
        isUncaught &&
        self.handleUncaughtExceptions &&
        self.listenerCount('uncaughtException') > 1
    ) {
        self.emit(
            'uncaughtException',
            req,
            res,
            req.route,
            err,
            function uncaughtExceptionCompleted() {
                // We provide a callback to listeners of the 'uncaughtException'
                // event and we call _finishReqResCycle when that callback is
                // called so that, in case the actual request/response lifecycle
                // was completed _before_ the error was thrown or emitted, and
                // thus _before_ route handlers were marked as "finished", we
                // can still mark the req/res lifecycle as complete.
                // This edge case can occur when e.g. a client aborts a request
                // and the route handler that handles that request throws an
                // uncaught exception _after_ the request was aborted and the
                // response was closed.
                self._finishReqResCycle(req, res, err);
            }
        );
        return;
    }

    self._emitErrorEvents(req, res, null, err, function emitError() {
        // Prevent double handling
        if (res._sent) {
            return;
        }

        // only automatically send errors that are known (e.g., restify-errors)
        if (err instanceof Error && _.isNumber(err.statusCode)) {
            res.send(err);
            return;
        }

        // if the thrown exception is not really an Error object, e.g.,
        //    "throw 'foo';"
        // try to do best effort here to pass on that value by casting it to a
        // string. This should work even for falsy values like 0, false, null,
        // or undefined.
        res.send(new errors.InternalError(String(err)));
    });
};

/**
 * Emit error events when errors are encountered either while attempting to
 * route the request (via router) or while executing the handler chain.
 *
 * @private
 * @memberof Server
 * @instance
 * @function _emitErrorEvents
 * @param    {Object} req -    the request object
 * @param    {Object} res -    the response object
 * @param    {Object} route -  the current route, if applicable
 * @param    {Object} err -    an error object
 * @param    {Object} cb -     callback function
 * @returns  {undefined} no return value
 * @fires Error#restifyError
 */
Server.prototype._emitErrorEvents = function _emitErrorEvents(
    req,
    res,
    route,
    err,
    cb
) {
    var self = this;
    // Error can be of any type: undefined, Error, Number, etc. so we need
    // to protect ourselves from trying to resolve names from non Error objects
    var errName = err && err.name;
    var normalizedErrName = errName && errEvtNameFromError(err);

    req.log.trace(
        {
            err: err,
            errName: normalizedErrName
        },
        'entering emitErrorEvents',
        errName
    );

    var errEvtNames = [];

    // if we have listeners for the specific error, fire those first.
    // if there's no error name, we should not emit an event
    if (normalizedErrName && self.listeners(normalizedErrName).length > 0) {
        errEvtNames.push(normalizedErrName);
    }

    // or if we have a generic error listener. always fire generic error event
    // listener afterwards.
    if (self.listeners('restifyError').length > 0) {
        errEvtNames.push('restifyError');
    }

    // kick off the async listeners
    return vasync.forEachPipeline(
        {
            inputs: errEvtNames,
            func: function emitError(errEvtName, vasyncCb) {
                self.emit(errEvtName, req, res, err, function emitErrDone() {
                    // the error listener may return arbitrary objects, throw
                    // them away and continue on. don't want vasync to take
                    // that error and stop, we want to emit every single event.
                    return vasyncCb();
                });
            }
        },
        // eslint-disable-next-line handle-callback-err
        function onResult(__, results) {
            // vasync will never return error here since we throw them away.
            return cb();
        }
    );
};

///--- Helpers

/**
 * Verify and flatten a nested array of request handlers.
 *
 * @private
 * @function argumentsToChain
 * @throws   {TypeError}
 * @param    {Function[]} handlers - pass through of funcs from server.[method]
 * @returns  {Array} request handlers
 */
function argumentsToChain(handlers) {
    assert.array(handlers, 'handlers');

    var chain = [];

    // A recursive function for unwinding a nested array of handlers into a
    // single chain.
    function process(array) {
        for (var i = 0; i < array.length; i++) {
            if (Array.isArray(array[i])) {
                // Recursively call on nested arrays
                process(array[i]);
                continue;
            }
            // If an element of the array isn't an array, ensure it is a
            // handler function and then push it onto the chain of handlers
            assert.func(array[i], 'handler');
            chain.push(array[i]);
        }

        return chain;
    }

    // Return the chain, note that if `handlers` is an empty array, this will
    // return an empty array.
    return process(handlers);
}

/**
 * merge optional formatters with the default formatters to create a single
 * formatters object. the passed in optional formatters object looks like:
 * formatters: {
 *   'application/foo': function formatFoo(req, res, body) {...}
 * }
 * @private
 * @function mergeFormatters
 * @param    {Object} fmt user specified formatters object
 * @returns  {Object}
 */

function mergeFormatters(fmt) {
    var arr = [];
    var obj = {};

    function addFormatter(src, k) {
        assert.func(src[k], 'formatter');

        var q = 1.0; // RFC 2616 sec14 - The default value is q=1
        var t = k;

        if (k.indexOf(';') !== -1) {
            var tmp = k.split(/\s*;\s*/);
            t = tmp[0];

            if (tmp[1].indexOf('q=') !== -1) {
                q = parseFloat(tmp[1].split('=')[1]);
            }
        }

        if (k.indexOf('/') === -1) {
            k = mime.getType(k);
        }

        obj[t] = src[k];
        arr.push({
            q: q,
            t: t
        });
    }

    Object.keys(formatters).forEach(addFormatter.bind(this, formatters));
    Object.keys(fmt || {}).forEach(addFormatter.bind(this, fmt || {}));

    arr = arr
        .sort(function sort(a, b) {
            return b.q - a.q;
        })
        .map(function map(a) {
            return a.t;
        });

    return {
        formatters: obj,
        acceptable: arr
    };
}

/**
 * Map an Error's .name property into the actual event name that is emitted
 * by the restify server object.
 *
 * @function
 * @private errEvtNameFromError
 * @param {Object} err - an error object
 * @returns {String} an event name to emit
 */
function errEvtNameFromError(err) {
    if (err.name === 'ResourceNotFoundError') {
        // remap the name for router errors
        return 'NotFound';
    } else if (err.name === 'InvalidVersionError') {
        // remap the name for router errors
        return 'VersionNotAllowed';
    } else if (err.name) {
        return err.name.replace(/Error$/, '');
    }
    // If the err is not an Error, then just return an empty string
    return '';
}

/**
 * Mounts a chain on the given path against this HTTP verb
 *
 * @private
 * @function serverMethodFactory
 * @param {String} method - name of the HTTP method
 * @returns {Function} factory
 */
function serverMethodFactory(method) {
    return function serverMethod(opts) {
        if (opts instanceof RegExp || typeof opts === 'string') {
            opts = {
                path: opts
            };
        } else if (typeof opts === 'object') {
            opts = shallowCopy(opts);
        } else {
            throw new TypeError('path (string) required');
        }

        if (arguments.length < 2) {
            throw new TypeError('handler (function) required');
        }

        opts.method = method;
        opts.path = opts.path || opts.url;

        // We accept both a variable number of handler functions, a
        // variable number of nested arrays of handler functions, or a mix
        // of both
        var handlers = Array.prototype.slice.call(arguments, 1);
        var chain = argumentsToChain(handlers);
        var route = this.router.mount(opts, chain);

        return route.name;
    };
}