lib/utils.js

   1 /*!
   2  * express
   3  * Copyright(c) 2009-2013 TJ Holowaychuk
   4  * Copyright(c) 2014-2015 Douglas Christopher Wilson
   5  * MIT Licensed
   6  */
   7
   8 'use strict';
   9
  10 /**
  11  * Module dependencies.
  12  * @api private
  13  */
  14
  15 var Buffer = require('safe-buffer').Buffer
  16 var contentType = require('content-type');
  17 var etag = require('etag');
  18 var mime = require('mime-types')
  19 var proxyaddr = require('proxy-addr');
  20 var qs = require('qs');
  21 var querystring = require('querystring');
  22
  23 /**
  24  * Return strong ETag for `body`.
  25  *
  26  * @param {String|Buffer} body
  27  * @param {String} [encoding]
  28  * @return {String}
  29  * @api private
  30  */
  31
  32 exports.etag = createETagGenerator({ weak: false })
  33
  34 /**
  35  * Return weak ETag for `body`.
  36  *
  37  * @param {String|Buffer} body
  38  * @param {String} [encoding]
  39  * @return {String}
  40  * @api private
  41  */
  42
  43 exports.wetag = createETagGenerator({ weak: true })
  44
  45 /**
  46  * Normalize the given `type`, for example "html" becomes "text/html".
  47  *
  48  * @param {String} type
  49  * @return {Object}
  50  * @api private
  51  */
  52
  53 exports.normalizeType = function(type){
  54   return ~type.indexOf('/')
  55     ? acceptParams(type)
  56     : { value: (mime.lookup(type) || 'application/octet-stream'), params: {} }
  57 };
  58
  59 /**
  60  * Normalize `types`, for example "html" becomes "text/html".
  61  *
  62  * @param {Array} types
  63  * @return {Array}
  64  * @api private
  65  */
  66
  67 exports.normalizeTypes = function(types){
  68   var ret = [];
  69
  70   for (var i = 0; i < types.length; ++i) {
  71     ret.push(exports.normalizeType(types[i]));
  72   }
  73
  74   return ret;
  75 };
  76
  77 /**
  78  * Parse accept params `str` returning an
  79  * object with `.value`, `.quality` and `.params`.
  80  *
  81  * @param {String} str
  82  * @return {Object}
  83  * @api private
  84  */
  85
  86 function acceptParams (str) {
  87   var parts = str.split(/ *; */);
  88   var ret = { value: parts[0], quality: 1, params: {} }
  89
  90   for (var i = 1; i < parts.length; ++i) {
  91     var pms = parts[i].split(/ *= */);
  92     if ('q' === pms[0]) {
  93       ret.quality = parseFloat(pms[1]);
  94     } else {
  95       ret.params[pms[0]] = pms[1];
  96     }
  97   }
  98
  99   return ret;
 100 }
 101
 102 /**
 103  * Compile "etag" value to function.
 104  *
 105  * @param  {Boolean|String|Function} val
 106  * @return {Function}
 107  * @api private
 108  */
 109
 110 exports.compileETag = function(val) {
 111   var fn;
 112
 113   if (typeof val === 'function') {
 114     return val;
 115   }
 116
 117   switch (val) {
 118     case true:
 119     case 'weak':
 120       fn = exports.wetag;
 121       break;
 122     case false:
 123       break;
 124     case 'strong':
 125       fn = exports.etag;
 126       break;
 127     default:
 128       throw new TypeError('unknown value for etag function: ' + val);
 129   }
 130
 131   return fn;
 132 }
 133
 134 /**
 135  * Compile "query parser" value to function.
 136  *
 137  * @param  {String|Function} val
 138  * @return {Function}
 139  * @api private
 140  */
 141
 142 exports.compileQueryParser = function compileQueryParser(val) {
 143   var fn;
 144
 145   if (typeof val === 'function') {
 146     return val;
 147   }
 148
 149   switch (val) {
 150     case true:
 151     case 'simple':
 152       fn = querystring.parse;
 153       break;
 154     case false:
 155       break;
 156     case 'extended':
 157       fn = parseExtendedQueryString;
 158       break;
 159     default:
 160       throw new TypeError('unknown value for query parser function: ' + val);
 161   }
 162
 163   return fn;
 164 }
 165
 166 /**
 167  * Compile "proxy trust" value to function.
 168  *
 169  * @param  {Boolean|String|Number|Array|Function} val
 170  * @return {Function}
 171  * @api private
 172  */
 173
 174 exports.compileTrust = function(val) {
 175   if (typeof val === 'function') return val;
 176
 177   if (val === true) {
 178     // Support plain true/false
 179     return function(){ return true };
 180   }
 181
 182   if (typeof val === 'number') {
 183     // Support trusting hop count
 184     return function(a, i){ return i < val };
 185   }
 186
 187   if (typeof val === 'string') {
 188     // Support comma-separated values
 189     val = val.split(',')
 190       .map(function (v) { return v.trim() })
 191   }
 192
 193   return proxyaddr.compile(val || []);
 194 }
 195
 196 /**
 197  * Set the charset in a given Content-Type string.
 198  *
 199  * @param {String} type
 200  * @param {String} charset
 201  * @return {String}
 202  * @api private
 203  */
 204
 205 exports.setCharset = function setCharset(type, charset) {
 206   if (!type || !charset) {
 207     return type;
 208   }
 209
 210   // parse type
 211   var parsed = contentType.parse(type);
 212
 213   // set charset
 214   parsed.parameters.charset = charset;
 215
 216   // format type
 217   return contentType.format(parsed);
 218 };
 219
 220 /**
 221  * Create an ETag generator function, generating ETags with
 222  * the given options.
 223  *
 224  * @param {object} options
 225  * @return {function}
 226  * @private
 227  */
 228
 229 function createETagGenerator (options) {
 230   return function generateETag (body, encoding) {
 231     var buf = !Buffer.isBuffer(body)
 232       ? Buffer.from(body, encoding)
 233       : body
 234
 235     return etag(buf, options)
 236   }
 237 }
 238
 239 /**
 240  * Parse an extended query string with qs.
 241  *
 242  * @param {String} str
 243  * @return {Object}
 244  * @private
 245  */
 246
 247 function parseExtendedQueryString(str) {
 248   return qs.parse(str, {
 249     allowPrototypes: true
 250   });
 251 }