koa-lite/lib/application.js


/**
 * Module dependencies.
 */

var debug = require('debug')('koa:application');
var Emitter = require('events').EventEmitter;
var compose = require('koa-compose');
var context = require('./context');
var Cookies = require('cookies');
var Stream = require('stream');
var http = require('http');
var co = require('co');

/**
 * Application prototype.
 */

var app = Application.prototype;

/**
 * Expose `Application`.
 */

exports = module.exports = Application;

/**
 * Initialize a new `Application`.
 *
 * @api public
 */

function Application() {
  if (!(this instanceof Application)) return new Application;
  this.env = process.env.NODE_ENV || 'development';
  this.on('error', this.onerror);
  this.outputErrors = 'test' != this.env;
  this.subdomainOffset = 2;
  this.poweredBy = true;
  this.jsonSpaces = 2;
  this.middleware = [];
  this.Context = createContext();
  this.context(context);
}

/**
 * Inherit from `Emitter.prototype`.
 */

Application.prototype.__proto__ = Emitter.prototype;

/**
 * Shorthand for:
 *
 *    http.createServer(app.callback()).listen(...)
 *
 * @param {Mixed} ...
 * @return {Server}
 * @api public
 */

app.listen = function(){
  var server = http.createServer(this.callback());
  return server.listen.apply(server, arguments);
};

/**
 * Use the given middleware `fn`.
 *
 * @param {Function} fn
 * @return {Application} self
 * @api public
 */

app.use = function(fn){
  debug('use %s', fn.name || '-');
  this.middleware.push(fn);
  return this;
};

/**
 * Mixin `obj` to this app's context.
 *
 *   app.context({
 *     get something(){
 *       return 'hi';
 *     },
 *
 *     set something(val){
 *       this._something = val;
 *     },
 *
 *     render: function(){
 *       this.body = '<html></html>';
 *     }
 *   });
 *
 * @param {Object} obj
 * @return {Application} self
 * @api public
 */

app.context = function(obj){
  var ctx = this.Context.prototype;
  var names = Object.getOwnPropertyNames(obj);

  debug('context: %j', names);
  names.forEach(function(name){
    if (Object.getOwnPropertyDescriptor(ctx, name)) {
      debug('context: overwriting %j', name);
    }
    var descriptor = Object.getOwnPropertyDescriptor(obj, name);
    Object.defineProperty(ctx, name, descriptor);
  });

  return this;
};

/**
 * Return a request handler callback
 * for node's native http server.
 *
 * @return {Function}
 * @api public
 */

app.callback = function(){
  var mw = [respond].concat(this.middleware);
  var fn = compose(mw)(downstream);
  var self = this;

  return function(req, res){
    var ctx = new self.Context(self, req, res);

    co.call(ctx, function *(){
      yield fn;
    }, function(err){
      if (err) ctx.onerror(err);
    });
  }
};

/**
 * Default error handler.
 *
 * @param {Error} err
 * @api private
 */

app.onerror = function(err){
  if (!this.outputErrors) return;
  if (404 == err.status) return;
  console.error(err.stack);
};

/**
 * Response middleware.
 */

function respond(next){
  return function *respond(){
    this.status = 200;
    if (this.app.poweredBy) this.set('X-Powered-By', 'koa');

    yield next;

    var app = this.app;
    var res = this.res;
    var body = this.body;
    var head = 'HEAD' == this.method;
    var noContent = 204 == this.status || 304 == this.status;

    // 404
    if (null == body && 200 == this.status) {
      this.status = 404;
    }

    // ignore body
    if (noContent) return res.end();

    // status body
    if (null == body) {
      this.type = 'text';
      body = http.STATUS_CODES[this.status];
    }

    // Buffer body
    if (Buffer.isBuffer(body)) {
      if (head) return res.end();
      return res.end(body);
    }

    // string body
    if ('string' == typeof body) {
      if (head) return res.end();
      return res.end(body);
    }

    // Stream body
    if (body instanceof Stream) {
      body.on('error', this.onerror.bind(this));
      if (head) return res.end();
      return body.pipe(res);
    }

    // body: json
    body = JSON.stringify(body, null, this.app.jsonSpaces);
    this.length = Buffer.byteLength(body);
    if (head) return res.end();
    res.end(body);
  }
}

/**
 * Default downstream middleware.
 *
 * @api private
 */

function *downstream(){}

/**
 * Create a new `Context` constructor.
 *
 * @return {Function}
 * @api private
 */

function createContext() {
  return function Context(app, req, res){
    this.app = app;
    this.req = req;
    this.res = res;
    this.cookies = new Cookies(req, res);
  }
}
Initial commit 2013-08-17 07:15:57 +00:00
			`/**`
			`* Module dependencies.`
			`*/`

change "unnamed" middleware to -, less junk output 2013-08-28 04:23:11 +00:00			`var debug = require('debug')('koa:application');`
Initial commit 2013-08-17 07:15:57 +00:00			`var Emitter = require('events').EventEmitter;`
			`var compose = require('koa-compose');`
app.context: extend the context with your own properties 2013-08-17 22:36:51 +00:00			`var context = require('./context');`
add Context#cookies support. Closes #7 need to add signing support in there as well 2013-08-21 04:51:14 +00:00			`var Cookies = require('cookies');`
Initial commit 2013-08-17 07:15:57 +00:00			`var Stream = require('stream');`
			`var http = require('http');`
			`var co = require('co');`

			`/**`
			`* Application prototype.`
			`*/`

			`var app = Application.prototype;`

			`/**`
			* Expose `Application`.
			`*/`

			`exports = module.exports = Application;`

			`/**`
			* Initialize a new `Application`.
			`*`
			`* @api public`
			`*/`

			`function Application() {`
			`if (!(this instanceof Application)) return new Application;`
			`this.env = process.env.NODE_ENV \|\| 'development';`
remove unnecessary .bind() 2013-09-08 16:37:33 +00:00			`this.on('error', this.onerror);`
change .outputErrors to false for "test" env only good to know in prod ;) 2013-08-22 02:48:47 +00:00			`this.outputErrors = 'test' != this.env;`
Initial commit 2013-08-17 07:15:57 +00:00			`this.subdomainOffset = 2;`
			`this.poweredBy = true;`
			`this.jsonSpaces = 2;`
			`this.middleware = [];`
cleanup trailing whitespace in .js files 2013-10-05 19:27:15 +00:00			`this.Context = createContext();`
app.context: extend the context with your own properties 2013-08-17 22:36:51 +00:00			`this.context(context);`
Initial commit 2013-08-17 07:15:57 +00:00			`}`

			`/**`
			* Inherit from `Emitter.prototype`.
			`*/`

			`Application.prototype.__proto__ = Emitter.prototype;`

			`/**`
			`* Shorthand for:`
			`*`
			`* http.createServer(app.callback()).listen(...)`
			`*`
			`* @param {Mixed} ...`
			`* @return {Server}`
			`* @api public`
			`*/`

			`app.listen = function(){`
			`var server = http.createServer(this.callback());`
			`return server.listen.apply(server, arguments);`
			`};`

			`/**`
			* Use the given middleware `fn`.
			`*`
			`* @param {Function} fn`
			`* @return {Application} self`
			`* @api public`
			`*/`

			`app.use = function(fn){`
change "unnamed" middleware to -, less junk output 2013-08-28 04:23:11 +00:00			`debug('use %s', fn.name \|\| '-');`
Initial commit 2013-08-17 07:15:57 +00:00			`this.middleware.push(fn);`
			`return this;`
			`};`

app.context: extend the context with your own properties 2013-08-17 22:36:51 +00:00			`/**`
docs 2013-08-18 18:15:22 +00:00			* Mixin `obj` to this app's context.
app.context: extend the context with your own properties 2013-08-17 22:36:51 +00:00			`*`
docs 2013-08-18 18:15:22 +00:00			`* app.context({`
			`* get something(){`
			`* return 'hi';`
			`* },`
			`*`
			`* set something(val){`
			`* this._something = val;`
			`* },`
			`*`
			`* render: function(){`
			`* this.body = '<html></html>';`
			`* }`
			`* });`
app.context: extend the context with your own properties 2013-08-17 22:36:51 +00:00			`*`
			`* @param {Object} obj`
			`* @return {Application} self`
			`* @api public`
			`*/`

			`app.context = function(obj){`
add createContext() 2013-08-18 18:14:01 +00:00			`var ctx = this.Context.prototype;`
add context debug() 2013-08-28 04:24:53 +00:00			`var names = Object.getOwnPropertyNames(obj);`
cleanup trailing whitespace in .js files 2013-10-05 19:27:15 +00:00
add context debug() 2013-08-28 04:24:53 +00:00			`debug('context: %j', names);`
			`names.forEach(function(name){`
debug: notify if a property is being overwritten 2013-10-05 19:56:36 +00:00			`if (Object.getOwnPropertyDescriptor(ctx, name)) {`
			`debug('context: overwriting %j', name);`
			`}`
app.context: extend the context with your own properties 2013-08-17 22:36:51 +00:00			`var descriptor = Object.getOwnPropertyDescriptor(obj, name);`
			`Object.defineProperty(ctx, name, descriptor);`
			`});`
cleanup trailing whitespace in .js files 2013-10-05 19:27:15 +00:00
app.context: extend the context with your own properties 2013-08-17 22:36:51 +00:00			`return this;`
			`};`

Initial commit 2013-08-17 07:15:57 +00:00			`/**`
			`* Return a request handler callback`
typo 2013-08-30 21:09:18 +00:00			`* for node's native http server.`
Initial commit 2013-08-17 07:15:57 +00:00			`*`
			`* @return {Function}`
			`* @api public`
			`*/`

			`app.callback = function(){`
			`var mw = [respond].concat(this.middleware);`
			`var fn = compose(mw)(downstream);`
			`var self = this;`

			`return function(req, res){`
add createContext() 2013-08-18 18:14:01 +00:00			`var ctx = new self.Context(self, req, res);`
Initial commit 2013-08-17 07:15:57 +00:00
			`co.call(ctx, function *(){`
			`yield fn;`
change app to emit "error" events instead of app.error(fn) 2013-08-28 03:24:04 +00:00			`}, function(err){`
			`if (err) ctx.onerror(err);`
			`});`
Initial commit 2013-08-17 07:15:57 +00:00			`}`
			`};`

add err.status support. Closes #20 2013-08-22 02:47:56 +00:00			`/**`
			`* Default error handler.`
			`*`
			`* @param {Error} err`
			`* @api private`
			`*/`

			`app.onerror = function(err){`
change app.onerror to ignore 404s so you can easily unwind the stack for 404s 2013-09-14 03:54:52 +00:00			`if (!this.outputErrors) return;`
			`if (404 == err.status) return;`
			`console.error(err.stack);`
add err.status support. Closes #20 2013-08-22 02:47:56 +00:00			`};`

Initial commit 2013-08-17 07:15:57 +00:00			`/**`
			`* Response middleware.`
			`*/`

			`function respond(next){`
add basic instrumentation 2013-08-29 04:10:25 +00:00			`return function *respond(){`
move downstream logic to response middleware 2013-09-01 23:27:03 +00:00			`this.status = 200;`
			`if (this.app.poweredBy) this.set('X-Powered-By', 'koa');`

Initial commit 2013-08-17 07:15:57 +00:00			`yield next;`

change app to emit "error" events instead of app.error(fn) 2013-08-28 03:24:04 +00:00			`var app = this.app;`
Initial commit 2013-08-17 07:15:57 +00:00			`var res = this.res;`
			`var body = this.body;`
			`var head = 'HEAD' == this.method;`
add ctx.body= setter this prevents a bunch of redundant checks that middleware may need to check response length, type etc. the less code floating around based on our supported response body types the better, giving us more freedom to change these as needed, and just less error-prone code in general. 2013-09-14 22:54:17 +00:00			`var noContent = 204 == this.status \|\| 304 == this.status;`
Initial commit 2013-08-17 07:15:57 +00:00
			`// 404`
			`if (null == body && 200 == this.status) {`
			`this.status = 404;`
			`}`

			`// ignore body`
add ctx.body= setter this prevents a bunch of redundant checks that middleware may need to check response length, type etc. the less code floating around based on our supported response body types the better, giving us more freedom to change these as needed, and just less error-prone code in general. 2013-09-14 22:54:17 +00:00			`if (noContent) return res.end();`
Initial commit 2013-08-17 07:15:57 +00:00
			`// status body`
			`if (null == body) {`
add ctx.body= setter this prevents a bunch of redundant checks that middleware may need to check response length, type etc. the less code floating around based on our supported response body types the better, giving us more freedom to change these as needed, and just less error-prone code in general. 2013-09-14 22:54:17 +00:00			`this.type = 'text';`
Initial commit 2013-08-17 07:15:57 +00:00			`body = http.STATUS_CODES[this.status];`
			`}`
app.context: extend the context with your own properties 2013-08-17 22:36:51 +00:00
Initial commit 2013-08-17 07:15:57 +00:00			`// Buffer body`
			`if (Buffer.isBuffer(body)) {`
			`if (head) return res.end();`
			`return res.end(body);`
			`}`

			`// string body`
			`if ('string' == typeof body) {`
			`if (head) return res.end();`
			`return res.end(body);`
			`}`

			`// Stream body`
			`if (body instanceof Stream) {`
fix .onerror bind for stream "error" handling 2013-08-22 02:50:32 +00:00			`body.on('error', this.onerror.bind(this));`
Initial commit 2013-08-17 07:15:57 +00:00			`if (head) return res.end();`
			`return body.pipe(res);`
			`}`
app.context: extend the context with your own properties 2013-08-17 22:36:51 +00:00
Initial commit 2013-08-17 07:15:57 +00:00			`// body: json`
			`body = JSON.stringify(body, null, this.app.jsonSpaces);`
add ctx.body= setter this prevents a bunch of redundant checks that middleware may need to check response length, type etc. the less code floating around based on our supported response body types the better, giving us more freedom to change these as needed, and just less error-prone code in general. 2013-09-14 22:54:17 +00:00			`this.length = Buffer.byteLength(body);`
Initial commit 2013-08-17 07:15:57 +00:00			`if (head) return res.end();`
			`res.end(body);`
			`}`
			`}`

			`/**`
			`* Default downstream middleware.`
add createContext() 2013-08-18 18:14:01 +00:00			`*`
			`* @api private`
Initial commit 2013-08-17 07:15:57 +00:00			`*/`

move downstream logic to response middleware 2013-09-01 23:27:03 +00:00			`function *downstream(){}`
add createContext() 2013-08-18 18:14:01 +00:00
			`/**`
			* Create a new `Context` constructor.
			`*`
			`* @return {Function}`
			`* @api private`
			`*/`

			`function createContext() {`
			`return function Context(app, req, res){`
			`this.app = app;`
			`this.req = req;`
			`this.res = res;`
add Context#cookies support. Closes #7 need to add signing support in there as well 2013-08-21 04:51:14 +00:00			`this.cookies = new Cookies(req, res);`
add createContext() 2013-08-18 18:14:01 +00:00			`}`
			`}`