lib/application.js

   1 /*!
   2  * express
   3  * Copyright(c) 2009-2013 TJ Holowaychuk
   4  * Copyright(c) 2013 Roman Shtylman
   5  * Copyright(c) 2014-2015 Douglas Christopher Wilson
   6  * MIT Licensed
   7  */
   8
   9 'use strict';
  10
  11 /**
  12  * Module dependencies.
  13  * @private
  14  */
  15
  16 var finalhandler = require('finalhandler');
  17 var methods = require('methods');
  18 var debug = require('debug')('express:application');
  19 var View = require('./view');
  20 var http = require('http');
  21 var compileETag = require('./utils').compileETag;
  22 var compileQueryParser = require('./utils').compileQueryParser;
  23 var compileTrust = require('./utils').compileTrust;
  24 var merge = require('utils-merge');
  25 var resolve = require('path').resolve;
  26 var once = require('once')
  27 var Router = require('router');
  28 var setPrototypeOf = require('setprototypeof')
  29
  30 /**
  31  * Module variables.
  32  * @private
  33  */
  34
  35 var slice = Array.prototype.slice;
  36 var flatten = Array.prototype.flat;
  37
  38 /**
  39  * Application prototype.
  40  */
  41
  42 var app = exports = module.exports = {};
  43
  44 /**
  45  * Variable for trust proxy inheritance back-compat
  46  * @private
  47  */
  48
  49 var trustProxyDefaultSymbol = '@@symbol:trust_proxy_default';
  50
  51 /**
  52  * Initialize the server.
  53  *
  54  *   - setup default configuration
  55  *   - setup default middleware
  56  *   - setup route reflection methods
  57  *
  58  * @private
  59  */
  60
  61 app.init = function init() {
  62   var router = null;
  63
  64   this.cache = Object.create(null);
  65   this.engines = Object.create(null);
  66   this.settings = Object.create(null);
  67
  68   this.defaultConfiguration();
  69
  70   // Setup getting to lazily add base router
  71   Object.defineProperty(this, 'router', {
  72     configurable: true,
  73     enumerable: true,
  74     get: function getrouter() {
  75       if (router === null) {
  76         router = new Router({
  77           caseSensitive: this.enabled('case sensitive routing'),
  78           strict: this.enabled('strict routing')
  79         });
  80       }
  81
  82       return router;
  83     }
  84   });
  85 };
  86
  87 /**
  88  * Initialize application configuration.
  89  * @private
  90  */
  91
  92 app.defaultConfiguration = function defaultConfiguration() {
  93   var env = process.env.NODE_ENV || 'development';
  94
  95   // default settings
  96   this.enable('x-powered-by');
  97   this.set('etag', 'weak');
  98   this.set('env', env);
  99   this.set('query parser', 'simple')
 100   this.set('subdomain offset', 2);
 101   this.set('trust proxy', false);
 102
 103   // trust proxy inherit back-compat
 104   Object.defineProperty(this.settings, trustProxyDefaultSymbol, {
 105     configurable: true,
 106     value: true
 107   });
 108
 109   debug('booting in %s mode', env);
 110
 111   this.on('mount', function onmount(parent) {
 112     // inherit trust proxy
 113     if (this.settings[trustProxyDefaultSymbol] === true
 114       && typeof parent.settings['trust proxy fn'] === 'function') {
 115       delete this.settings['trust proxy'];
 116       delete this.settings['trust proxy fn'];
 117     }
 118
 119     // inherit protos
 120     setPrototypeOf(this.request, parent.request)
 121     setPrototypeOf(this.response, parent.response)
 122     setPrototypeOf(this.engines, parent.engines)
 123     setPrototypeOf(this.settings, parent.settings)
 124   });
 125
 126   // setup locals
 127   this.locals = Object.create(null);
 128
 129   // top-most app is mounted at /
 130   this.mountpath = '/';
 131
 132   // default locals
 133   this.locals.settings = this.settings;
 134
 135   // default configuration
 136   this.set('view', View);
 137   this.set('views', resolve('views'));
 138   this.set('jsonp callback name', 'callback');
 139
 140   if (env === 'production') {
 141     this.enable('view cache');
 142   }
 143 };
 144
 145 /**
 146  * Dispatch a req, res pair into the application. Starts pipeline processing.
 147  *
 148  * If no callback is provided, then default error handlers will respond
 149  * in the event of an error bubbling through the stack.
 150  *
 151  * @private
 152  */
 153
 154 app.handle = function handle(req, res, callback) {
 155   // final handler
 156   var done = callback || finalhandler(req, res, {
 157     env: this.get('env'),
 158     onerror: logerror.bind(this)
 159   });
 160
 161   // set powered by header
 162   if (this.enabled('x-powered-by')) {
 163     res.setHeader('X-Powered-By', 'Express');
 164   }
 165
 166   // set circular references
 167   req.res = res;
 168   res.req = req;
 169
 170   // alter the prototypes
 171   setPrototypeOf(req, this.request)
 172   setPrototypeOf(res, this.response)
 173
 174   // setup locals
 175   if (!res.locals) {
 176     res.locals = Object.create(null);
 177   }
 178
 179   this.router.handle(req, res, done);
 180 };
 181
 182 /**
 183  * Proxy `Router#use()` to add middleware to the app router.
 184  * See Router#use() documentation for details.
 185  *
 186  * If the _fn_ parameter is an express app, then it will be
 187  * mounted at the _route_ specified.
 188  *
 189  * @public
 190  */
 191
 192 app.use = function use(fn) {
 193   var offset = 0;
 194   var path = '/';
 195
 196   // default path to '/'
 197   // disambiguate app.use([fn])
 198   if (typeof fn !== 'function') {
 199     var arg = fn;
 200
 201     while (Array.isArray(arg) && arg.length !== 0) {
 202       arg = arg[0];
 203     }
 204
 205     // first arg is the path
 206     if (typeof arg !== 'function') {
 207       offset = 1;
 208       path = fn;
 209     }
 210   }
 211
 212   var fns = flatten.call(slice.call(arguments, offset), Infinity);
 213
 214   if (fns.length === 0) {
 215     throw new TypeError('app.use() requires a middleware function')
 216   }
 217
 218   // get router
 219   var router = this.router;
 220
 221   fns.forEach(function (fn) {
 222     // non-express app
 223     if (!fn || !fn.handle || !fn.set) {
 224       return router.use(path, fn);
 225     }
 226
 227     debug('.use app under %s', path);
 228     fn.mountpath = path;
 229     fn.parent = this;
 230
 231     // restore .app property on req and res
 232     router.use(path, function mounted_app(req, res, next) {
 233       var orig = req.app;
 234       fn.handle(req, res, function (err) {
 235         setPrototypeOf(req, orig.request)
 236         setPrototypeOf(res, orig.response)
 237         next(err);
 238       });
 239     });
 240
 241     // mounted an app
 242     fn.emit('mount', this);
 243   }, this);
 244
 245   return this;
 246 };
 247
 248 /**
 249  * Proxy to the app `Router#route()`
 250  * Returns a new `Route` instance for the _path_.
 251  *
 252  * Routes are isolated middleware stacks for specific paths.
 253  * See the Route api docs for details.
 254  *
 255  * @public
 256  */
 257
 258 app.route = function route(path) {
 259   return this.router.route(path);
 260 };
 261
 262 /**
 263  * Register the given template engine callback `fn`
 264  * as `ext`.
 265  *
 266  * By default will `require()` the engine based on the
 267  * file extension. For example if you try to render
 268  * a "foo.ejs" file Express will invoke the following internally:
 269  *
 270  *     app.engine('ejs', require('ejs').__express);
 271  *
 272  * For engines that do not provide `.__express` out of the box,
 273  * or if you wish to "map" a different extension to the template engine
 274  * you may use this method. For example mapping the EJS template engine to
 275  * ".html" files:
 276  *
 277  *     app.engine('html', require('ejs').renderFile);
 278  *
 279  * In this case EJS provides a `.renderFile()` method with
 280  * the same signature that Express expects: `(path, options, callback)`,
 281  * though note that it aliases this method as `ejs.__express` internally
 282  * so if you're using ".ejs" extensions you don't need to do anything.
 283  *
 284  * Some template engines do not follow this convention, the
 285  * [Consolidate.js](https://github.com/tj/consolidate.js)
 286  * library was created to map all of node's popular template
 287  * engines to follow this convention, thus allowing them to
 288  * work seamlessly within Express.
 289  *
 290  * @param {String} ext
 291  * @param {Function} fn
 292  * @return {app} for chaining
 293  * @public
 294  */
 295
 296 app.engine = function engine(ext, fn) {
 297   if (typeof fn !== 'function') {
 298     throw new Error('callback function required');
 299   }
 300
 301   // get file extension
 302   var extension = ext[0] !== '.'
 303     ? '.' + ext
 304     : ext;
 305
 306   // store engine
 307   this.engines[extension] = fn;
 308
 309   return this;
 310 };
 311
 312 /**
 313  * Proxy to `Router#param()` with one added api feature. The _name_ parameter
 314  * can be an array of names.
 315  *
 316  * See the Router#param() docs for more details.
 317  *
 318  * @param {String|Array} name
 319  * @param {Function} fn
 320  * @return {app} for chaining
 321  * @public
 322  */
 323
 324 app.param = function param(name, fn) {
 325   if (Array.isArray(name)) {
 326     for (var i = 0; i < name.length; i++) {
 327       this.param(name[i], fn);
 328     }
 329
 330     return this;
 331   }
 332
 333   this.router.param(name, fn);
 334
 335   return this;
 336 };
 337
 338 /**
 339  * Assign `setting` to `val`, or return `setting`'s value.
 340  *
 341  *    app.set('foo', 'bar');
 342  *    app.set('foo');
 343  *    // => "bar"
 344  *
 345  * Mounted servers inherit their parent server's settings.
 346  *
 347  * @param {String} setting
 348  * @param {*} [val]
 349  * @return {Server} for chaining
 350  * @public
 351  */
 352
 353 app.set = function set(setting, val) {
 354   if (arguments.length === 1) {
 355     // app.get(setting)
 356     return this.settings[setting];
 357   }
 358
 359   debug('set "%s" to %o', setting, val);
 360
 361   // set value
 362   this.settings[setting] = val;
 363
 364   // trigger matched settings
 365   switch (setting) {
 366     case 'etag':
 367       this.set('etag fn', compileETag(val));
 368       break;
 369     case 'query parser':
 370       this.set('query parser fn', compileQueryParser(val));
 371       break;
 372     case 'trust proxy':
 373       this.set('trust proxy fn', compileTrust(val));
 374
 375       // trust proxy inherit back-compat
 376       Object.defineProperty(this.settings, trustProxyDefaultSymbol, {
 377         configurable: true,
 378         value: false
 379       });
 380
 381       break;
 382   }
 383
 384   return this;
 385 };
 386
 387 /**
 388  * Return the app's absolute pathname
 389  * based on the parent(s) that have
 390  * mounted it.
 391  *
 392  * For example if the application was
 393  * mounted as "/admin", which itself
 394  * was mounted as "/blog" then the
 395  * return value would be "/blog/admin".
 396  *
 397  * @return {String}
 398  * @private
 399  */
 400
 401 app.path = function path() {
 402   return this.parent
 403     ? this.parent.path() + this.mountpath
 404     : '';
 405 };
 406
 407 /**
 408  * Check if `setting` is enabled (truthy).
 409  *
 410  *    app.enabled('foo')
 411  *    // => false
 412  *
 413  *    app.enable('foo')
 414  *    app.enabled('foo')
 415  *    // => true
 416  *
 417  * @param {String} setting
 418  * @return {Boolean}
 419  * @public
 420  */
 421
 422 app.enabled = function enabled(setting) {
 423   return Boolean(this.set(setting));
 424 };
 425
 426 /**
 427  * Check if `setting` is disabled.
 428  *
 429  *    app.disabled('foo')
 430  *    // => true
 431  *
 432  *    app.enable('foo')
 433  *    app.disabled('foo')
 434  *    // => false
 435  *
 436  * @param {String} setting
 437  * @return {Boolean}
 438  * @public
 439  */
 440
 441 app.disabled = function disabled(setting) {
 442   return !this.set(setting);
 443 };
 444
 445 /**
 446  * Enable `setting`.
 447  *
 448  * @param {String} setting
 449  * @return {app} for chaining
 450  * @public
 451  */
 452
 453 app.enable = function enable(setting) {
 454   return this.set(setting, true);
 455 };
 456
 457 /**
 458  * Disable `setting`.
 459  *
 460  * @param {String} setting
 461  * @return {app} for chaining
 462  * @public
 463  */
 464
 465 app.disable = function disable(setting) {
 466   return this.set(setting, false);
 467 };
 468
 469 /**
 470  * Delegate `.VERB(...)` calls to `router.VERB(...)`.
 471  */
 472
 473 methods.forEach(function(method){
 474   app[method] = function(path){
 475     if (method === 'get' && arguments.length === 1) {
 476       // app.get(setting)
 477       return this.set(path);
 478     }
 479
 480     var route = this.route(path);
 481     route[method].apply(route, slice.call(arguments, 1));
 482     return this;
 483   };
 484 });
 485
 486 /**
 487  * Special-cased "all" method, applying the given route `path`,
 488  * middleware, and callback to _every_ HTTP method.
 489  *
 490  * @param {String} path
 491  * @param {Function} ...
 492  * @return {app} for chaining
 493  * @public
 494  */
 495
 496 app.all = function all(path) {
 497   var route = this.route(path);
 498   var args = slice.call(arguments, 1);
 499
 500   for (var i = 0; i < methods.length; i++) {
 501     route[methods[i]].apply(route, args);
 502   }
 503
 504   return this;
 505 };
 506
 507 /**
 508  * Render the given view `name` name with `options`
 509  * and a callback accepting an error and the
 510  * rendered template string.
 511  *
 512  * Example:
 513  *
 514  *    app.render('email', { name: 'Tobi' }, function(err, html){
 515  *      // ...
 516  *    })
 517  *
 518  * @param {String} name
 519  * @param {Object|Function} options or fn
 520  * @param {Function} callback
 521  * @public
 522  */
 523
 524 app.render = function render(name, options, callback) {
 525   var cache = this.cache;
 526   var done = callback;
 527   var engines = this.engines;
 528   var opts = options;
 529   var renderOptions = {};
 530   var view;
 531
 532   // support callback function as second arg
 533   if (typeof options === 'function') {
 534     done = options;
 535     opts = {};
 536   }
 537
 538   // merge app.locals
 539   merge(renderOptions, this.locals);
 540
 541   // merge options._locals
 542   if (opts._locals) {
 543     merge(renderOptions, opts._locals);
 544   }
 545
 546   // merge options
 547   merge(renderOptions, opts);
 548
 549   // set .cache unless explicitly provided
 550   if (renderOptions.cache == null) {
 551     renderOptions.cache = this.enabled('view cache');
 552   }
 553
 554   // primed cache
 555   if (renderOptions.cache) {
 556     view = cache[name];
 557   }
 558
 559   // view
 560   if (!view) {
 561     var View = this.get('view');
 562
 563     view = new View(name, {
 564       defaultEngine: this.get('view engine'),
 565       root: this.get('views'),
 566       engines: engines
 567     });
 568
 569     if (!view.path) {
 570       var dirs = Array.isArray(view.root) && view.root.length > 1
 571         ? 'directories "' + view.root.slice(0, -1).join('", "') + '" or "' + view.root[view.root.length - 1] + '"'
 572         : 'directory "' + view.root + '"'
 573       var err = new Error('Failed to lookup view "' + name + '" in views ' + dirs);
 574       err.view = view;
 575       return done(err);
 576     }
 577
 578     // prime the cache
 579     if (renderOptions.cache) {
 580       cache[name] = view;
 581     }
 582   }
 583
 584   // render
 585   tryRender(view, renderOptions, done);
 586 };
 587
 588 /**
 589  * Listen for connections.
 590  *
 591  * A node `http.Server` is returned, with this
 592  * application (which is a `Function`) as its
 593  * callback. If you wish to create both an HTTP
 594  * and HTTPS server you may do so with the "http"
 595  * and "https" modules as shown here:
 596  *
 597  *    var http = require('http')
 598  *      , https = require('https')
 599  *      , express = require('express')
 600  *      , app = express();
 601  *
 602  *    http.createServer(app).listen(80);
 603  *    https.createServer({ ... }, app).listen(443);
 604  *
 605  * @return {http.Server}
 606  * @public
 607  */
 608
 609 app.listen = function listen () {
 610   var server = http.createServer(this)
 611   var args = Array.prototype.slice.call(arguments)
 612   if (typeof args[args.length - 1] === 'function') {
 613     var done = args[args.length - 1] = once(args[args.length - 1])
 614     server.once('error', done)
 615   }
 616   return server.listen.apply(server, args)
 617 }
 618
 619 /**
 620  * Log error using console.error.
 621  *
 622  * @param {Error} err
 623  * @private
 624  */
 625
 626 function logerror(err) {
 627   /* istanbul ignore next */
 628   if (this.get('env') !== 'test') console.error(err.stack || err.toString());
 629 }
 630
 631 /**
 632  * Try rendering a view.
 633  * @private
 634  */
 635
 636 function tryRender(view, options, callback) {
 637   try {
 638     view.render(options, callback);
 639   } catch (err) {
 640     callback(err);
 641   }
 642 }