4.2 KiB

Raw Blame History

Application

A Koa application is not a 1-to-1 representation of an HTTP server, as one or more Koa applications may be mounted together to form larger applications, with a single HTTP server.

The following is a useless Koa application bound to port 3000:

var koa = require('koa');
var app = koa();
app.listen(3000);

The app.listen(...) method is simply sugar for the following:

var http = require('http');
var koa = require('koa');
var app = koa();
http.createServer(app.callback()).listen(3000);

This means you can spin up the same application as both HTTP and HTTPS, or on multiple addresses:

var http = require('http');
var koa = require('koa');
var app = koa();
http.createServer(app.callback()).listen(3000);
http.createServer(app.callback()).listen(3001);

Settings

Application settings are properties on the app instance, currently the following are supported:

app.name optionally give your application a name
app.env defaulting to the NODE_ENV or "development"
app.proxy when true proxy header fields will be trusted
app.subdomainOffset offset of .subdomains to ignore [2]
app.jsonSpaces default JSON response spaces [2]
app.outputErrors output err.stack to stderr [false in "test" environment]

app.listen(...)

Create and return an HTTP server, passing the given arguments to Server#listen(). These arguments are documented on nodejs.org.

app.callback()

Return a callback function suitable for the http.createServer() method to handle a request. You may also use this callback function to mount your koa app in a Connect/Express app.

app.use(function)

Add the given middleware function to this application. See Middleware for more information.

app.keys=

Set signed cookie keys.

These are passed to KeyGrip, however you may also pass your own KeyGrip instance. For example the following are acceptable:

app.keys = ['im a newer secret', 'i like turtle'];
app.keys = new KeyGrip(['im a newer secret', 'i like turtle'], 'sha256');

These keys may be rotated and are used when signing cookies with the { signed: true } option:

this.cookies.set('name', 'tobi', { signed: true });

Handling Requests

Koa requests are manipulated using a Context object containing both a Koa Request and Response object. For more information on these view:

Error Handling

By default outputs all errors to stderr unless NODE_ENV is "test". To perform custom error-handling logic such as centralized logging you can add an "error" event listener:

app.on('error', function(err){
  log.error('server error', err);
});

If an error in the req/res cycle and it is not possible to respond to the client, the Context instance is also passed:

app.on('error', function(err, ctx){
  log.error('server error', err, ctx);
});

When an error occurs and it is still possible to respond to the client, aka no data has been written to the socket, Koa will respond appropriately with a 500 "Internal Server Error". In either case an app-level "error" is emitted for logging purposes.

Notes

HEAD Support

Koa's upstream response middleware supports HEAD for you, however expensive requests would benefit from custom handling. For example instead of reading a file into memory and piping it to the client, you may wish to stat() and set the Content-* header fields appropriately to bypass the read.

On a valid HEAD request, you should either set the status code to anything but 200 or set this.body = '', otherwise koa will not consider the request "handled" and instead respond with a 404.

Socket Errors

Node http servers emit a "clientError" event when a socket error occurs. You'll probably want to delegate this to your Koa handler by doing the following, in order to centralize logging:

var app = koa();
var srv = app.listen(3000);
srv.on('clientError', function(err){
  app.emit('error', err);
});

4.2 KiB Raw Blame History