restify/lib/request.js

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

'use strict';

var url = require('url');
var sprintf = require('util').format;

var assert = require('assert-plus');
var mime = require('mime');
var Negotiator = require('negotiator');
var uuid = require('uuid');

var dtrace = require('./dtrace');

///-- Helpers
/**
 * Creates and sets negotiator on request if one doesn't already exist,
 * then returns it.
 *
 * @private
 * @function negotiator
 * @param    {Object} req - the request object
 * @returns  {Object}     a negotiator
 */
function negotiator(req) {
    var h = req.headers;

    if (!req._negotiator) {
        req._negotiator = new Negotiator({
            headers: {
                accept: h.accept || '*/*',
                'accept-encoding': h['accept-encoding'] || 'identity'
            }
        });
    }

    return req._negotiator;
}

///--- API

/**
 * Patch Request object and extends with extra functionalities
 *
 * @private
 * @function patch
 * @param    {http.IncomingMessage|http2.Http2ServerRequest} Request -
 *                                                           Server Request
 * @returns  {undefined} No return value
 */
function patch(Request) {
    /**
     * Wraps all of the node
     * [http.IncomingMessage](https://nodejs.org/api/http.html)
     * APIs, events and properties, plus the following.
     * @class Request
     * @extends http.IncomingMessage
     */

    ///--- Patches

    /**
     * Builds an absolute URI for the request.
     *
     * @private
     * @memberof Request
     * @instance
     * @function absoluteUri
     * @param    {String} path - a url path
     * @returns  {String} uri
     */
    Request.prototype.absoluteUri = function absoluteUri(path) {
        assert.string(path, 'path');

        var protocol = this.isSecure() ? 'https://' : 'http://';
        var hostname = this.headers.host;
        return url.resolve(protocol + hostname + this.path() + '/', path);
    };

    /**
     * Check if the Accept header is present, and includes the given type.
     * When the Accept header is not present true is returned.
     * Otherwise the given type is matched by an exact match, and then subtypes.
     *
     * @public
     * @memberof Request
     * @instance
     * @function accepts
     * @param    {String | String[]} types - an array of accept type headers
     * @returns  {Boolean} is accepteed
     * @example
     * <caption>
     * You may pass the subtype such as html which is then converted internally
     * to text/html using the mime lookup table:
     * </caption>
     * // Accept: text/html
     * req.accepts('html');
     * // => true
     *
     * // Accept: text/*; application/json
     * req.accepts('html');
     * req.accepts('text/html');
     * req.accepts('text/plain');
     * req.accepts('application/json');
     * // => true
     *
     * req.accepts('image/png');
     * req.accepts('png');
     * // => false
     */
    Request.prototype.accepts = function accepts(types) {
        if (typeof types === 'string') {
            types = [types];
        }

        types = types.map(function map(t) {
            assert.string(t, 'type');

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

        negotiator(this);

        return this._negotiator.preferredMediaType(types);
    };

    /**
     * Checks if the request accepts the encoding type(s) specified.
     *
     * @public
     * @memberof Request
     * @instance
     * @function acceptsEncoding
     * @param    {String | String[]} types - an array of accept type headers
     * @returns  {Boolean} is accepted encoding
     */
    Request.prototype.acceptsEncoding = function acceptsEncoding(types) {
        if (typeof types === 'string') {
            types = [types];
        }

        assert.arrayOfString(types, 'types');

        negotiator(this);

        return this._negotiator.preferredEncoding(types);
    };

    /**
     * Returns the value of the content-length header.
     *
     * @private
     * @memberof Request
     * @instance
     * @function getContentLength
     * @returns {Number} content length
     */
    Request.prototype.getContentLength = function getContentLength() {
        if (this._clen !== undefined) {
            return this._clen === false ? undefined : this._clen;
        }

        // We should not attempt to read and parse the body of an
        // Upgrade request, so force Content-Length to zero:
        if (this.isUpgradeRequest()) {
            return 0;
        }

        var len = this.header('content-length');

        if (!len) {
            this._clen = false;
        } else {
            this._clen = parseInt(len, 10);
        }

        return this._clen === false ? undefined : this._clen;
    };
    /**
     * Returns the value of the content-length header.
     * @public
     * @memberof Request
     * @instance
     * @function contentLength
     * @returns {Number}
     */
    Request.prototype.contentLength = Request.prototype.getContentLength;

    /**
     * Returns the value of the content-type header. If a content-type is not
     * set, this will return a default value of `application/octet-stream`.
     *
     * @private
     * @memberof Request
     * @instance
     * @function getContentType
     * @returns {String} content type
     */
    Request.prototype.getContentType = function getContentType() {
        if (this._contentType !== undefined) {
            return this._contentType;
        }

        var index;
        var type = this.headers['content-type'];

        if (!type) {
            // RFC2616 section 7.2.1
            this._contentType = 'application/octet-stream';
        } else if ((index = type.indexOf(';')) === -1) {
            this._contentType = type;
        } else {
            this._contentType = type.substring(0, index);
        }

        // #877 content-types need to be case insensitive.
        this._contentType = this._contentType.toLowerCase();

        return this._contentType;
    };

    /**
     * Returns the value of the content-type header. If a content-type is not
     * set, this will return a default value of `application/octet-stream`
     * @public
     * @memberof Request
     * @instance
     * @function getContentType
     * @returns {String} content type
     */
    Request.prototype.contentType = Request.prototype.getContentType;

    /**
     * Returns a Date object representing when the request was setup.
     * Like `time()`, but returns a Date object.
     *
     * @public
     * @memberof Request
     * @instance
     * @function date
     * @returns  {Date} date when request began being processed
     */
    Request.prototype.date = function date() {
        return this._date;
    };

    /**
     * Retrieves the complete URI requested by the client.
     *
     * @private
     * @memberof Request
     * @instance
     * @function getHref
     * @returns {String} URI
     */
    Request.prototype.getHref = function getHref() {
        return this.getUrl().href;
    };

    /**
     * Returns the full requested URL.
     * @public
     * @memberof Request
     * @instance
     * @function href
     * @returns {String}
     * @example
     * // incoming request is http://localhost:3000/foo/bar?a=1
     * server.get('/:x/bar', function(req, res, next) {
     *     console.warn(req.href());
     *     // => /foo/bar/?a=1
     * });
     */
    Request.prototype.href = Request.prototype.getHref;

    /**
     * Retrieves the request uuid. was created when the request was setup.
     *
     * @private
     * @memberof Request
     * @instance
     * @function getId
     * @returns  {String} id
     */
    Request.prototype.getId = function getId() {
        if (this._id !== undefined) {
            return this._id;
        }

        this._id = uuid.v4();

        return this._id;
    };

    /**
     * Returns the request id. If a `reqId` value is passed in,
     * this will become the request’s new id. The request id is immutable,
     * and can only be set once. Attempting to set the request id more than
     * once will cause restify to throw.
     *
     * @public
     * @memberof Request
     * @instance
     * @function id
     * @param {String} reqId - request id
     * @returns {String} id
     */
    Request.prototype.id = function id(reqId) {
        var self = this;

        if (reqId) {
            if (self._id) {
                throw new Error(
                    'request id is immutable, cannot be set again!'
                );
            } else {
                assert.string(reqId, 'reqId');
                self._id = reqId;
                return self._id;
            }
        }

        return self.getId();
    };

    /**
     * Retrieves the cleaned up url path.
     * e.g., /foo?a=1  =>  /foo
     *
     * @private
     * @memberof Request
     * @instance
     * @function getPath
     * @returns  {String} path
     */
    Request.prototype.getPath = function getPath() {
        return this.getUrl().pathname;
    };

    /**
     * Returns the cleaned up requested URL.
     * @public
     * @memberof Request
     * @instance
     * @function getPath
     * @returns  {String}
     * @example
     * // incoming request is http://localhost:3000/foo/bar?a=1
     * server.get('/:x/bar', function(req, res, next) {
     *     console.warn(req.path());
     *     // => /foo/bar
     * });
     */
    Request.prototype.path = Request.prototype.getPath;

    /**
     * Returns the raw query string. Returns empty string
     * if no query string is found.
     *
     * @public
     * @memberof Request
     * @instance
     * @function getQuery
     * @returns  {String} query
     * @example
     * // incoming request is /foo?a=1
     * req.getQuery();
     * // => 'a=1'
     * @example
     * <caption>
     * If the queryParser plugin is used, the parsed query string is
     * available under the req.query:
     * </caption>
     * // incoming request is /foo?a=1
     * server.use(restify.plugins.queryParser());
     * req.query;
     * // => { a: 1 }
     */
    Request.prototype.getQuery = function getQuery() {
        // always return a string, because this is the raw query string.
        // if the queryParser plugin is used, req.query will provide an empty
        // object fallback.
        return this.getUrl().query || '';
    };

    /**
     * Returns the raw query string. Returns empty string
     * if no query string is found
     * @private
     * @memberof Request
     * @instance
     * @function query
     * @returns  {String}
     */
    Request.prototype.query = Request.prototype.getQuery;

    /**
     * The number of ms since epoch of when this request began being processed.
     * Like date(), but returns a number.
     *
     * @public
     * @memberof Request
     * @instance
     * @function time
     * @returns  {Number} time when request began being processed in epoch:
     *                    ellapsed milliseconds since
     *                    January 1, 1970, 00:00:00 UTC
     */
    Request.prototype.time = function time() {
        return this._date.getTime();
    };

    /**
     * returns a parsed URL object.
     *
     * @private
     * @memberof Request
     * @instance
     * @function getUrl
     * @returns  {Object} url
     */
    Request.prototype.getUrl = function getUrl() {
        if (this._cacheURL !== this.url) {
            this._url = url.parse(this.url);
            this._cacheURL = this.url;
        }
        return this._url;
    };

    /**
     * Returns the accept-version header.
     *
     * @private
     * @memberof Request
     * @instance
     * @function getVersion
     * @returns  {String} version
     */
    Request.prototype.getVersion = function getVersion() {
        if (this._version !== undefined) {
            return this._version;
        }

        this._version =
            this.headers['accept-version'] ||
            this.headers['x-api-version'] ||
            '*';

        return this._version;
    };

    /**
     * Returns the accept-version header.
     * @public
     * @memberof Request
     * @instance
     * @function version
     * @returns  {String}
     */
    Request.prototype.version = Request.prototype.getVersion;

    /**
     * Returns the version of the route that matched.
     *
     * @private
     * @memberof Request
     * @instance
     * @function matchedVersion
     * @returns {String} version
     */
    Request.prototype.matchedVersion = function matchedVersion() {
        if (this._matchedVersion !== undefined) {
            return this._matchedVersion;
        } else {
            return this.version();
        }
    };

    /**
     * Get the case-insensitive request header key,
     * and optionally provide a default value (express-compliant).
     * Returns any header off the request. also, 'correct' any
     * correctly spelled 'referrer' header to the actual spelling used.
     *
     * @public
     * @memberof Request
     * @instance
     * @function header
     * @param    {String} key - the key of the header
     * @param    {String} [defaultValue] - default value if header isn't
     *                                   found on the req
     * @returns  {String} header value
     * @example
     * req.header('Host');
     * req.header('HOST');
     * req.header('Accept', '*\/*');
     */
    Request.prototype.header = function header(key, defaultValue) {
        assert.string(key, 'key');

        key = key.toLowerCase();

        if (key === 'referer' || key === 'referrer') {
            key = 'referer';
        }

        return this.headers[key] || defaultValue;
    };

    /**
     * Returns any trailer header off the request. Also, 'correct' any
     * correctly spelled 'referrer' header to the actual spelling used.
     *
     * @public
     * @memberof Request
     * @instance
     * @function trailer
     * @param    {String} name - the name of the header
     * @param    {String} value - default value if header isn't found on the req
     * @returns  {String} trailer value
     */
    Request.prototype.trailer = function trailer(name, value) {
        assert.string(name, 'name');
        name = name.toLowerCase();

        if (name === 'referer' || name === 'referrer') {
            name = 'referer';
        }

        return (this.trailers || {})[name] || value;
    };

    /**
     * Check if the incoming request contains the `Content-Type` header field,
     * and if it contains the given mime type.
     *
     * @public
     * @memberof Request
     * @instance
     * @function is
     * @param    {String} type - a content-type header value
     * @returns  {Boolean} is content-type header
     * @example
     * // With Content-Type: text/html; charset=utf-8
     * req.is('html');
     * req.is('text/html');
     * // => true
     *
     * // When Content-Type is application/json
     * req.is('json');
     * req.is('application/json');
     * // => true
     *
     * req.is('html');
     * // => false
     */
    Request.prototype.is = function is(type) {
        assert.string(type, 'type');

        var contentType = this.getContentType();
        var matches = true;

        if (!contentType) {
            return false;
        }

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

        if (type.indexOf('*') !== -1) {
            type = type.split('/');
            contentType = contentType.split('/');
            matches &= type[0] === '*' || type[0] === contentType[0];
            matches &= type[1] === '*' || type[1] === contentType[1];
        } else {
            matches = contentType === type;
        }

        return matches;
    };

    /**
     * Check if the incoming request is chunked.
     *
     * @public
     * @memberof Request
     * @instance
     * @function isChunked
     * @returns  {Boolean} is chunked
     */
    Request.prototype.isChunked = function isChunked() {
        return this.headers['transfer-encoding'] === 'chunked';
    };

    /**
     * Check if the incoming request is kept alive.
     *
     * @public
     * @memberof Request
     * @instance
     * @function isKeepAlive
     * @returns  {Boolean} is keep alive
     */
    Request.prototype.isKeepAlive = function isKeepAlive() {
        if (this._keepAlive !== undefined) {
            return this._keepAlive;
        }

        if (this.headers.connection) {
            this._keepAlive = /keep-alive/i.test(this.headers.connection);
        } else {
            this._keepAlive = this.httpVersion === '1.0' ? false : true;
        }

        return this._keepAlive;
    };

    /**
     * Check if the incoming request is encrypted.
     *
     * @public
     * @memberof Request
     * @instance
     * @function isSecure
     * @returns  {Boolean} is secure
     */
    Request.prototype.isSecure = function isSecure() {
        if (this._secure !== undefined) {
            return this._secure;
        }

        this._secure = this.connection.encrypted ? true : false;
        return this._secure;
    };

    /**
     * Check if the incoming request has been upgraded.
     *
     * @public
     * @memberof Request
     * @instance
     * @function isUpgradeRequest
     * @returns  {Boolean} is upgraded
     */
    Request.prototype.isUpgradeRequest = function isUpgradeRequest() {
        if (this._upgradeRequest !== undefined) {
            return this._upgradeRequest;
        } else {
            return false;
        }
    };

    /**
     * Check if the incoming request is an upload verb.
     *
     * @public
     * @memberof Request
     * @instance
     * @function isUpload
     * @returns  {Boolean} is upload
     */
    Request.prototype.isUpload = function isUpload() {
        var m = this.method;
        return m === 'PATCH' || m === 'POST' || m === 'PUT';
    };

    /**
     * toString serialization
     *
     * @public
     * @memberof Request
     * @instance
     * @function toString
     * @returns  {String} serialized request
     */
    Request.prototype.toString = function toString() {
        var headers = '';
        var self = this;
        var str;

        Object.keys(this.headers).forEach(function forEach(k) {
            headers += sprintf('%s: %s\n', k, self.headers[k]);
        });

        str = sprintf(
            '%s %s HTTP/%s\n%s',
            this.method,
            this.url,
            this.httpVersion,
            headers
        );

        return str;
    };

    /**
     * Returns the user-agent header.
     *
     * @public
     * @memberof Request
     * @instance
     * @function userAgent
     * @returns  {String} user agent
     */
    Request.prototype.userAgent = function userAgent() {
        return this.headers['user-agent'];
    };

    /**
     * Start the timer for a request handler.
     * By default, restify uses calls this automatically for all handlers
     * registered in your handler chain.
     * However, this can be called manually for nested functions inside the
     * handler chain to record timing information.
     *
     * @public
     * @memberof Request
     * @instance
     * @function startHandlerTimer
     * @param    {String}    handlerName - The name of the handler.
     * @returns  {undefined} no return value
     * @example
     * <caption>
     * You must explicitly invoke
     * endHandlerTimer() after invoking this function. Otherwise timing
     * information will be inaccurate.
     * </caption>
     * server.get('/', function fooHandler(req, res, next) {
     *     vasync.pipeline({
     *         funcs: [
     *             function nestedHandler1(req, res, next) {
     *                 req.startHandlerTimer('nestedHandler1');
     *                 // do something
     *                 req.endHandlerTimer('nestedHandler1');
     *                 return next();
     *             },
     *             function nestedHandler1(req, res, next) {
     *                 req.startHandlerTimer('nestedHandler2');
     *                 // do something
     *                 req.endHandlerTimer('nestedHandler2');
     *                 return next();
     *
     *             }...
     *        ]...
     *     }, next);
     * });
     */
    Request.prototype.startHandlerTimer = function startHandlerTimer(
        handlerName
    ) {
        var self = this;

        // For nested handlers, we prepend the top level handler func name
        var name =
            self._currentHandler === handlerName
                ? handlerName
                : self._currentHandler + '-' + handlerName;

        if (!self._timerMap) {
            self._timerMap = {};
        }

        self._timerMap[name] = process.hrtime();

        if (self.dtrace) {
            dtrace._rstfy_probes['handler-start'].fire(function fire() {
                return [
                    self.serverName,
                    self._currentRoute, // set in server._run
                    name,
                    self._dtraceId
                ];
            });
        }
    };

    /**
     * End the timer for a request handler.
     * You must invoke this function if you called `startRequestHandler` on a
     * handler. Otherwise the time recorded will be incorrect.
     *
     * @public
     * @memberof Request
     * @instance
     * @function endHandlerTimer
     * @param    {String}    handlerName - The name of the handler.
     * @returns  {undefined} no return value
     */
    Request.prototype.endHandlerTimer = function endHandlerTimer(handlerName) {
        var self = this;

        // For nested handlers, we prepend the top level handler func name
        var name =
            self._currentHandler === handlerName
                ? handlerName
                : self._currentHandler + '-' + handlerName;

        if (!self.timers) {
            self.timers = [];
        }

        self._timerMap[name] = process.hrtime(self._timerMap[name]);
        self.timers.push({
            name: name,
            time: self._timerMap[name]
        });

        if (self.dtrace) {
            dtrace._rstfy_probes['handler-done'].fire(function fire() {
                return [
                    self.serverName,
                    self._currentRoute, // set in server._run
                    name,
                    self._dtraceId
                ];
            });
        }
    };

    /**
     * Returns the connection state of the request. Current possible values are:
     * - `close` - when the request has been closed by the clien
     *
     * @public
     * @memberof Request
     * @instance
     * @function connectionState
     * @returns {String} connection state (`"close"`)
     */
    Request.prototype.connectionState = function connectionState() {
        var self = this;
        return self._connectionState;
    };

    /**
     * Returns true when connection state is "close"
     *
     * @private
     * @memberof Request
     * @instance
     * @function closed
     * @returns {Boolean} is closed
     */
    Request.prototype.closed = function closed() {
        var self = this;
        return self.connectionState() === 'close';
    };

    /**
     * Returns the route object to which the current request was matched to.
     *
     * @public
     * @memberof Request
     * @instance
     * @function getRoute
     * @returns {Object} route
     * @example
     * <caption>Route info object structure:</caption>
     * {
     *  path: '/ping/:name',
     *  method: 'GET',
     *  versions: [],
     *  name: 'getpingname'
     * }
     */
    Request.prototype.getRoute = function getRoute() {
        var self = this;
        return self.route;
    };
}

module.exports = patch;