git.cworth.org Git - obsolete/notmuch-web/blob - node_modules/express/lib/request.js

   1
   2 /*!
   3  * Express - request
   4  * Copyright(c) 2010 TJ Holowaychuk <tj@vision-media.ca>
   5  * MIT Licensed
   6  */
   7
   8 /**
   9  * Module dependencies.
  10  */
  11
  12 var http = require('http')
  13   , req = http.IncomingMessage.prototype
  14   , utils = require('./utils')
  15   , mime = require('mime');
  16
  17 /**
  18  * Default flash formatters.
  19  *
  20  * @type Object
  21  */
  22
  23 var flashFormatters = exports.flashFormatters = {
  24   s: function(val){
  25     return String(val);
  26   }
  27 };
  28
  29 /**
  30  * Return request header or optional default.
  31  *
  32  * The `Referrer` header field is special-cased,
  33  * both `Referrer` and `Referer` will yield are
  34  * interchangeable.
  35  *
  36  * Examples:
  37  *
  38  *     req.header('Content-Type');
  39  *     // => "text/plain"
  40  *
  41  *     req.header('content-type');
  42  *     // => "text/plain"
  43  *
  44  *     req.header('Accept');
  45  *     // => undefined
  46  *
  47  *     req.header('Accept', 'text/html');
  48  *     // => "text/html"
  49  *
  50  * @param {String} name
  51  * @param {String} defaultValue
  52  * @return {String}
  53  * @api public
  54  */
  55
  56 req.header = function(name, defaultValue){
  57   switch (name = name.toLowerCase()) {
  58     case 'referer':
  59     case 'referrer':
  60       return this.headers.referrer
  61         || this.headers.referer
  62         || defaultValue;
  63     default:
  64       return this.headers[name] || defaultValue;
  65   }
  66 };
  67
  68 /**
  69  * Check if the _Accept_ header is present, and includes the given `type`.
  70  *
  71  * When the _Accept_ header is not present `true` is returned. Otherwise
  72  * the given `type` is matched by an exact match, and then subtypes. You
  73  * may pass the subtype such as "html" which is then converted internally
  74  * to "text/html" using the mime lookup table.
  75  *
  76  * Examples:
  77  *
  78  *     // Accept: text/html
  79  *     req.accepts('html');
  80  *     // => true
  81  *
  82  *     // Accept: text/*; application/json
  83  *     req.accepts('html');
  84  *     req.accepts('text/html');
  85  *     req.accepts('text/plain');
  86  *     req.accepts('application/json');
  87  *     // => true
  88  *
  89  *     req.accepts('image/png');
  90  *     req.accepts('png');
  91  *     // => false
  92  *
  93  * @param {String} type
  94  * @return {Boolean}
  95  * @api public
  96  */
  97
  98 req.accepts = function(type){
  99   var accept = this.header('Accept');
 100
 101   // normalize extensions ".json" -> "json"
 102   if (type && '.' == type[0]) type = type.substr(1);
 103
 104   // when Accept does not exist, or is '*/*' return true
 105   if (!accept || '*/*' == accept) {
 106     return true;
 107   } else if (type) {
 108     // allow "html" vs "text/html" etc
 109     if (type.indexOf('/') < 0) {
 110       type = mime.lookup(type);
 111     }
 112
 113     // check if we have a direct match
 114     if (~accept.indexOf(type)) return true;
 115
 116     // check if we have type/*
 117     type = type.split('/')[0] + '/*';
 118     return accept.indexOf(type) >= 0;
 119   } else {
 120     return false;
 121   }
 122 };
 123
 124 /**
 125  * Return the value of param `name` when present or `defaultValue`.
 126  *
 127  *  - Checks route placeholders, ex: _/user/:id_
 128  *  - Checks query string params, ex: ?id=12
 129  *  - Checks urlencoded body params, ex: id=12
 130  *
 131  * To utilize urlencoded request bodies, `req.body`
 132  * should be an object. This can be done by using
 133  * the `connect.bodyParser` middleware.
 134  *
 135  * @param {String} name
 136  * @param {Mixed} defaultValue
 137  * @return {String}
 138  * @api public
 139  */
 140
 141 req.param = function(name, defaultValue){
 142   // route params like /user/:id
 143   if (this.params && this.params.hasOwnProperty(name) && undefined !== this.params[name]) {
 144     return this.params[name];
 145   }
 146   // query string params
 147   if (undefined !== this.query[name]) {
 148     return this.query[name];
 149   }
 150   // request body params via connect.bodyParser
 151   if (this.body && undefined !== this.body[name]) {
 152     return this.body[name];
 153   }
 154   return defaultValue;
 155 };
 156
 157 /**
 158  * Queue flash `msg` of the given `type`.
 159  *
 160  * Examples:
 161  *
 162  *      req.flash('info', 'email sent');
 163  *      req.flash('error', 'email delivery failed');
 164  *      req.flash('info', 'email re-sent');
 165  *      // => 2
 166  *
 167  *      req.flash('info');
 168  *      // => ['email sent', 'email re-sent']
 169  *
 170  *      req.flash('info');
 171  *      // => []
 172  *
 173  *      req.flash();
 174  *      // => { error: ['email delivery failed'], info: [] }
 175  *
 176  * Formatting:
 177  *
 178  * Flash notifications also support arbitrary formatting support.
 179  * For example you may pass variable arguments to `req.flash()`
 180  * and use the %s specifier to be replaced by the associated argument:
 181  *
 182  *     req.flash('info', 'email has been sent to %s.', userName);
 183  *
 184  * To add custom formatters use the `exports.flashFormatters` object.
 185  *
 186  * @param {String} type
 187  * @param {String} msg
 188  * @return {Array|Object|Number}
 189  * @api public
 190  */
 191
 192 req.flash = function(type, msg){
 193   if (this.session === undefined) throw Error('req.flash() requires sessions');
 194   var msgs = this.session.flash = this.session.flash || {};
 195   if (type && msg) {
 196     var i = 2
 197       , args = arguments
 198       , formatters = this.app.flashFormatters || {};
 199     formatters.__proto__ = flashFormatters;
 200     msg = utils.miniMarkdown(utils.escape(msg));
 201     msg = msg.replace(/%([a-zA-Z])/g, function(_, format){
 202       var formatter = formatters[format];
 203       if (formatter) return formatter(args[i++]);
 204     });
 205     return (msgs[type] = msgs[type] || []).push(msg);
 206   } else if (type) {
 207     var arr = msgs[type];
 208     delete msgs[type];
 209     return arr || [];
 210   } else {
 211     this.session.flash = {};
 212     return msgs;
 213   }
 214 };
 215
 216 /**
 217  * Check if the incoming request contains the "Content-Type"
 218  * header field, and it contains the give mime `type`.
 219  *
 220  * Examples:
 221  *
 222  *      // With Content-Type: text/html; charset=utf-8
 223  *      req.is('html');
 224  *      req.is('text/html');
 225  *      // => true
 226  *
 227  *      // When Content-Type is application/json
 228  *      req.is('json');
 229  *      req.is('application/json');
 230  *      // => true
 231  *
 232  *      req.is('html');
 233  *      // => false
 234  *
 235  * Ad-hoc callbacks can also be registered with Express, to perform
 236  * assertions again the request, for example if we need an expressive
 237  * way to check if our incoming request is an image, we can register "an image"
 238  * callback:
 239  *
 240  *       app.is('an image', function(req){
 241  *         return 0 == req.headers['content-type'].indexOf('image');
 242  *       });
 243  *
 244  *  Now within our route callbacks, we can use to to assert content types
 245  *  such as "image/jpeg", "image/png", etc.
 246  *
 247  *      app.post('/image/upload', function(req, res, next){
 248  *        if (req.is('an image')) {
 249  *          // do something
 250  *        } else {
 251  *          next();
 252  *        }
 253  *      });
 254  *
 255  * @param {String} type
 256  * @return {Boolean}
 257  * @api public
 258  */
 259
 260 req.is = function(type){
 261   var fn = this.app.is(type);
 262   if (fn) return fn(this);
 263   var contentType = this.headers['content-type'];
 264   if (!contentType) return;
 265   if (!~type.indexOf('/')) type = mime.lookup(type);
 266   if (~type.indexOf('*')) {
 267     type = type.split('/')
 268     contentType = contentType.split('/');
 269     if ('*' == type[0] && type[1] == contentType[1]) return true;
 270     if ('*' == type[1] && type[0] == contentType[0]) return true;
 271   }
 272   return ~contentType.indexOf(type);
 273 };
 274
 275 // Callback for isXMLHttpRequest / xhr
 276
 277 function isxhr() {
 278   return this.header('X-Requested-With', '').toLowerCase() === 'xmlhttprequest';
 279 }
 280
 281 /**
 282  * Check if the request was an _XMLHttpRequest_.
 283  *
 284  * @return {Boolean}
 285  * @api public
 286  */
 287
 288 req.__defineGetter__('isXMLHttpRequest', isxhr);
 289 req.__defineGetter__('xhr', isxhr);