/*!
|
* express
|
* Copyright(c) 2009-2013 TJ Holowaychuk
|
* Copyright(c) 2013 Roman Shtylman
|
* Copyright(c) 2014-2015 Douglas Christopher Wilson
|
* MIT Licensed
|
*/
|
|
'use strict';
|
|
/**
|
* Module dependencies.
|
* @private
|
*/
|
|
var finalhandler = require('finalhandler');
|
var Router = require('./router');
|
var methods = require('methods');
|
var middleware = require('./middleware/init');
|
var query = require('./middleware/query');
|
var debug = require('debug')('express:application');
|
var View = require('./view');
|
var http = require('http');
|
var compileETag = require('./utils').compileETag;
|
var compileQueryParser = require('./utils').compileQueryParser;
|
var compileTrust = require('./utils').compileTrust;
|
var deprecate = require('depd')('express');
|
var flatten = require('array-flatten');
|
var merge = require('utils-merge');
|
var resolve = require('path').resolve;
|
var setPrototypeOf = require('setprototypeof')
|
|
/**
|
* Module variables.
|
* @private
|
*/
|
|
var hasOwnProperty = Object.prototype.hasOwnProperty
|
var slice = Array.prototype.slice;
|
|
/**
|
* Application prototype.
|
*/
|
|
var app = exports = module.exports = {};
|
|
/**
|
* Variable for trust proxy inheritance back-compat
|
* @private
|
*/
|
|
var trustProxyDefaultSymbol = '@@symbol:trust_proxy_default';
|
|
/**
|
* Initialize the server.
|
*
|
* - setup default configuration
|
* - setup default middleware
|
* - setup route reflection methods
|
*
|
* @private
|
*/
|
|
app.init = function init() {
|
this.cache = {};
|
this.engines = {};
|
this.settings = {};
|
|
this.defaultConfiguration();
|
};
|
|
/**
|
* Initialize application configuration.
|
* @private
|
*/
|
|
app.defaultConfiguration = function defaultConfiguration() {
|
var env = process.env.NODE_ENV || 'development';
|
|
// default settings
|
this.enable('x-powered-by');
|
this.set('etag', 'weak');
|
this.set('env', env);
|
this.set('query parser', 'extended');
|
this.set('subdomain offset', 2);
|
this.set('trust proxy', false);
|
|
// trust proxy inherit back-compat
|
Object.defineProperty(this.settings, trustProxyDefaultSymbol, {
|
configurable: true,
|
value: true
|
});
|
|
debug('booting in %s mode', env);
|
|
this.on('mount', function onmount(parent) {
|
// inherit trust proxy
|
if (this.settings[trustProxyDefaultSymbol] === true
|
&& typeof parent.settings['trust proxy fn'] === 'function') {
|
delete this.settings['trust proxy'];
|
delete this.settings['trust proxy fn'];
|
}
|
|
// inherit protos
|
setPrototypeOf(this.request, parent.request)
|
setPrototypeOf(this.response, parent.response)
|
setPrototypeOf(this.engines, parent.engines)
|
setPrototypeOf(this.settings, parent.settings)
|
});
|
|
// setup locals
|
this.locals = Object.create(null);
|
|
// top-most app is mounted at /
|
this.mountpath = '/';
|
|
// default locals
|
this.locals.settings = this.settings;
|
|
// default configuration
|
this.set('view', View);
|
this.set('views', resolve('views'));
|
this.set('jsonp callback name', 'callback');
|
|
if (env === 'production') {
|
this.enable('view cache');
|
}
|
|
Object.defineProperty(this, 'router', {
|
get: function() {
|
throw new Error('\'app.router\' is deprecated!\nPlease see the 3.x to 4.x migration guide for details on how to update your app.');
|
}
|
});
|
};
|
|
/**
|
* lazily adds the base router if it has not yet been added.
|
*
|
* We cannot add the base router in the defaultConfiguration because
|
* it reads app settings which might be set after that has run.
|
*
|
* @private
|
*/
|
app.lazyrouter = function lazyrouter() {
|
if (!this._router) {
|
this._router = new Router({
|
caseSensitive: this.enabled('case sensitive routing'),
|
strict: this.enabled('strict routing')
|
});
|
|
this._router.use(query(this.get('query parser fn')));
|
this._router.use(middleware.init(this));
|
}
|
};
|
|
/**
|
* Dispatch a req, res pair into the application. Starts pipeline processing.
|
*
|
* If no callback is provided, then default error handlers will respond
|
* in the event of an error bubbling through the stack.
|
*
|
* @private
|
*/
|
|
app.handle = function handle(req, res, callback) {
|
var router = this._router;
|
|
// final handler
|
var done = callback || finalhandler(req, res, {
|
env: this.get('env'),
|
onerror: logerror.bind(this)
|
});
|
|
// no routes
|
if (!router) {
|
debug('no routes defined on app');
|
done();
|
return;
|
}
|
|
router.handle(req, res, done);
|
};
|
|
/**
|
* Proxy `Router#use()` to add middleware to the app router.
|
* See Router#use() documentation for details.
|
*
|
* If the _fn_ parameter is an express app, then it will be
|
* mounted at the _route_ specified.
|
*
|
* @public
|
*/
|
|
app.use = function use(fn) {
|
var offset = 0;
|
var path = '/';
|
|
// default path to '/'
|
// disambiguate app.use([fn])
|
if (typeof fn !== 'function') {
|
var arg = fn;
|
|
while (Array.isArray(arg) && arg.length !== 0) {
|
arg = arg[0];
|
}
|
|
// first arg is the path
|
if (typeof arg !== 'function') {
|
offset = 1;
|
path = fn;
|
}
|
}
|
|
var fns = flatten(slice.call(arguments, offset));
|
|
if (fns.length === 0) {
|
throw new TypeError('app.use() requires a middleware function')
|
}
|
|
// setup router
|
this.lazyrouter();
|
var router = this._router;
|
|
fns.forEach(function (fn) {
|
// non-express app
|
if (!fn || !fn.handle || !fn.set) {
|
return router.use(path, fn);
|
}
|
|
debug('.use app under %s', path);
|
fn.mountpath = path;
|
fn.parent = this;
|
|
// restore .app property on req and res
|
router.use(path, function mounted_app(req, res, next) {
|
var orig = req.app;
|
fn.handle(req, res, function (err) {
|
setPrototypeOf(req, orig.request)
|
setPrototypeOf(res, orig.response)
|
next(err);
|
});
|
});
|
|
// mounted an app
|
fn.emit('mount', this);
|
}, this);
|
|
return this;
|
};
|
|
/**
|
* Proxy to the app `Router#route()`
|
* Returns a new `Route` instance for the _path_.
|
*
|
* Routes are isolated middleware stacks for specific paths.
|
* See the Route api docs for details.
|
*
|
* @public
|
*/
|
|
app.route = function route(path) {
|
this.lazyrouter();
|
return this._router.route(path);
|
};
|
|
/**
|
* Register the given template engine callback `fn`
|
* as `ext`.
|
*
|
* By default will `require()` the engine based on the
|
* file extension. For example if you try to render
|
* a "foo.ejs" file Express will invoke the following internally:
|
*
|
* app.engine('ejs', require('ejs').__express);
|
*
|
* For engines that do not provide `.__express` out of the box,
|
* or if you wish to "map" a different extension to the template engine
|
* you may use this method. For example mapping the EJS template engine to
|
* ".html" files:
|
*
|
* app.engine('html', require('ejs').renderFile);
|
*
|
* In this case EJS provides a `.renderFile()` method with
|
* the same signature that Express expects: `(path, options, callback)`,
|
* though note that it aliases this method as `ejs.__express` internally
|
* so if you're using ".ejs" extensions you don't need to do anything.
|
*
|
* Some template engines do not follow this convention, the
|
* [Consolidate.js](https://github.com/tj/consolidate.js)
|
* library was created to map all of node's popular template
|
* engines to follow this convention, thus allowing them to
|
* work seamlessly within Express.
|
*
|
* @param {String} ext
|
* @param {Function} fn
|
* @return {app} for chaining
|
* @public
|
*/
|
|
app.engine = function engine(ext, fn) {
|
if (typeof fn !== 'function') {
|
throw new Error('callback function required');
|
}
|
|
// get file extension
|
var extension = ext[0] !== '.'
|
? '.' + ext
|
: ext;
|
|
// store engine
|
this.engines[extension] = fn;
|
|
return this;
|
};
|
|
/**
|
* Proxy to `Router#param()` with one added api feature. The _name_ parameter
|
* can be an array of names.
|
*
|
* See the Router#param() docs for more details.
|
*
|
* @param {String|Array} name
|
* @param {Function} fn
|
* @return {app} for chaining
|
* @public
|
*/
|
|
app.param = function param(name, fn) {
|
this.lazyrouter();
|
|
if (Array.isArray(name)) {
|
for (var i = 0; i < name.length; i++) {
|
this.param(name[i], fn);
|
}
|
|
return this;
|
}
|
|
this._router.param(name, fn);
|
|
return this;
|
};
|
|
/**
|
* Assign `setting` to `val`, or return `setting`'s value.
|
*
|
* app.set('foo', 'bar');
|
* app.set('foo');
|
* // => "bar"
|
*
|
* Mounted servers inherit their parent server's settings.
|
*
|
* @param {String} setting
|
* @param {*} [val]
|
* @return {Server} for chaining
|
* @public
|
*/
|
|
app.set = function set(setting, val) {
|
if (arguments.length === 1) {
|
// app.get(setting)
|
var settings = this.settings
|
|
while (settings && settings !== Object.prototype) {
|
if (hasOwnProperty.call(settings, setting)) {
|
return settings[setting]
|
}
|
|
settings = Object.getPrototypeOf(settings)
|
}
|
|
return undefined
|
}
|
|
debug('set "%s" to %o', setting, val);
|
|
// set value
|
this.settings[setting] = val;
|
|
// trigger matched settings
|
switch (setting) {
|
case 'etag':
|
this.set('etag fn', compileETag(val));
|
break;
|
case 'query parser':
|
this.set('query parser fn', compileQueryParser(val));
|
break;
|
case 'trust proxy':
|
this.set('trust proxy fn', compileTrust(val));
|
|
// trust proxy inherit back-compat
|
Object.defineProperty(this.settings, trustProxyDefaultSymbol, {
|
configurable: true,
|
value: false
|
});
|
|
break;
|
}
|
|
return this;
|
};
|
|
/**
|
* Return the app's absolute pathname
|
* based on the parent(s) that have
|
* mounted it.
|
*
|
* For example if the application was
|
* mounted as "/admin", which itself
|
* was mounted as "/blog" then the
|
* return value would be "/blog/admin".
|
*
|
* @return {String}
|
* @private
|
*/
|
|
app.path = function path() {
|
return this.parent
|
? this.parent.path() + this.mountpath
|
: '';
|
};
|
|
/**
|
* Check if `setting` is enabled (truthy).
|
*
|
* app.enabled('foo')
|
* // => false
|
*
|
* app.enable('foo')
|
* app.enabled('foo')
|
* // => true
|
*
|
* @param {String} setting
|
* @return {Boolean}
|
* @public
|
*/
|
|
app.enabled = function enabled(setting) {
|
return Boolean(this.set(setting));
|
};
|
|
/**
|
* Check if `setting` is disabled.
|
*
|
* app.disabled('foo')
|
* // => true
|
*
|
* app.enable('foo')
|
* app.disabled('foo')
|
* // => false
|
*
|
* @param {String} setting
|
* @return {Boolean}
|
* @public
|
*/
|
|
app.disabled = function disabled(setting) {
|
return !this.set(setting);
|
};
|
|
/**
|
* Enable `setting`.
|
*
|
* @param {String} setting
|
* @return {app} for chaining
|
* @public
|
*/
|
|
app.enable = function enable(setting) {
|
return this.set(setting, true);
|
};
|
|
/**
|
* Disable `setting`.
|
*
|
* @param {String} setting
|
* @return {app} for chaining
|
* @public
|
*/
|
|
app.disable = function disable(setting) {
|
return this.set(setting, false);
|
};
|
|
/**
|
* Delegate `.VERB(...)` calls to `router.VERB(...)`.
|
*/
|
|
methods.forEach(function(method){
|
app[method] = function(path){
|
if (method === 'get' && arguments.length === 1) {
|
// app.get(setting)
|
return this.set(path);
|
}
|
|
this.lazyrouter();
|
|
var route = this._router.route(path);
|
route[method].apply(route, slice.call(arguments, 1));
|
return this;
|
};
|
});
|
|
/**
|
* Special-cased "all" method, applying the given route `path`,
|
* middleware, and callback to _every_ HTTP method.
|
*
|
* @param {String} path
|
* @param {Function} ...
|
* @return {app} for chaining
|
* @public
|
*/
|
|
app.all = function all(path) {
|
this.lazyrouter();
|
|
var route = this._router.route(path);
|
var args = slice.call(arguments, 1);
|
|
for (var i = 0; i < methods.length; i++) {
|
route[methods[i]].apply(route, args);
|
}
|
|
return this;
|
};
|
|
// del -> delete alias
|
|
app.del = deprecate.function(app.delete, 'app.del: Use app.delete instead');
|
|
/**
|
* Render the given view `name` name with `options`
|
* and a callback accepting an error and the
|
* rendered template string.
|
*
|
* Example:
|
*
|
* app.render('email', { name: 'Tobi' }, function(err, html){
|
* // ...
|
* })
|
*
|
* @param {String} name
|
* @param {Object|Function} options or fn
|
* @param {Function} callback
|
* @public
|
*/
|
|
app.render = function render(name, options, callback) {
|
var cache = this.cache;
|
var done = callback;
|
var engines = this.engines;
|
var opts = options;
|
var renderOptions = {};
|
var view;
|
|
// support callback function as second arg
|
if (typeof options === 'function') {
|
done = options;
|
opts = {};
|
}
|
|
// merge app.locals
|
merge(renderOptions, this.locals);
|
|
// merge options._locals
|
if (opts._locals) {
|
merge(renderOptions, opts._locals);
|
}
|
|
// merge options
|
merge(renderOptions, opts);
|
|
// set .cache unless explicitly provided
|
if (renderOptions.cache == null) {
|
renderOptions.cache = this.enabled('view cache');
|
}
|
|
// primed cache
|
if (renderOptions.cache) {
|
view = cache[name];
|
}
|
|
// view
|
if (!view) {
|
var View = this.get('view');
|
|
view = new View(name, {
|
defaultEngine: this.get('view engine'),
|
root: this.get('views'),
|
engines: engines
|
});
|
|
if (!view.path) {
|
var dirs = Array.isArray(view.root) && view.root.length > 1
|
? 'directories "' + view.root.slice(0, -1).join('", "') + '" or "' + view.root[view.root.length - 1] + '"'
|
: 'directory "' + view.root + '"'
|
var err = new Error('Failed to lookup view "' + name + '" in views ' + dirs);
|
err.view = view;
|
return done(err);
|
}
|
|
// prime the cache
|
if (renderOptions.cache) {
|
cache[name] = view;
|
}
|
}
|
|
// render
|
tryRender(view, renderOptions, done);
|
};
|
|
/**
|
* Listen for connections.
|
*
|
* A node `http.Server` is returned, with this
|
* application (which is a `Function`) as its
|
* callback. If you wish to create both an HTTP
|
* and HTTPS server you may do so with the "http"
|
* and "https" modules as shown here:
|
*
|
* var http = require('http')
|
* , https = require('https')
|
* , express = require('express')
|
* , app = express();
|
*
|
* http.createServer(app).listen(80);
|
* https.createServer({ ... }, app).listen(443);
|
*
|
* @return {http.Server}
|
* @public
|
*/
|
|
app.listen = function listen() {
|
var server = http.createServer(this);
|
return server.listen.apply(server, arguments);
|
};
|
|
/**
|
* Log error using console.error.
|
*
|
* @param {Error} err
|
* @private
|
*/
|
|
function logerror(err) {
|
/* istanbul ignore next */
|
if (this.get('env') !== 'test') console.error(err.stack || err.toString());
|
}
|
|
/**
|
* Try rendering a view.
|
* @private
|
*/
|
|
function tryRender(view, options, callback) {
|
try {
|
view.render(options, callback);
|
} catch (err) {
|
callback(err);
|
}
|
}
|
