koa-lite/docs/api.md

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.

app.use(function)

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

Context

A Koa Context encapsulates node's request and response objects into a single object which provides many helpful methods for writing web applications and APIs.

These operations are used so frequently in HTTP server development that they are added at this level, instead of a higher level framework, which would force middlware to re-implement this common functionality.

A Context is created per request, and is referenced in middleware as the receiver, or the this variable.

ctx.req

Node's request object.

ctx.res

Node's response object.

ctx.app

Application instance reference.

ctx.header

Request header object.

ctx.responseHeader

Response header object.

ctx.method

Request method.

ctx.method=

Set request method, useful for implementing middleware such as methodOverride().

ctx.status

Get response status.

ctx.status=

Set response status via numeric code or case-insensitive string:

• 100 "continue"
• 101 "switching protocols"
• 102 "processing"
• 200 "ok"
• 201 "created"
• 202 "accepted"
• 203 "non-authoritative information"
• 204 "no content"
• 205 "reset content"
• 206 "partial content"
• 207 "multi-status"
• 300 "multiple choices"
• 301 "moved permanently"
• 302 "moved temporarily"
• 303 "see other"
• 304 "not modified"
• 305 "use proxy"
• 307 "temporary redirect"
• 400 "bad request"
• 401 "unauthorized"
• 402 "payment required"
• 403 "forbidden"
• 404 "not found"
• 405 "method not allowed"
• 406 "not acceptable"
• 407 "proxy authentication required"
• 408 "request time-out"
• 409 "conflict"
• 410 "gone"
• 411 "length required"
• 412 "precondition failed"
• 413 "request entity too large"
• 414 "request-uri too large"
• 415 "unsupported media type"
• 416 "requested range not satisfiable"
• 417 "expectation failed"
• 418 "i'm a teapot"
• 422 "unprocessable entity"
• 423 "locked"
• 424 "failed dependency"
• 425 "unordered collection"
• 426 "upgrade required"
• 428 "precondition required"
• 429 "too many requests"
• 431 "request header fields too large"
• 500 "internal server error"
• 501 "not implemented"
• 502 "bad gateway"
• 503 "service unavailable"
• 504 "gateway time-out"
• 505 "http version not supported"
• 506 "variant also negotiates"
• 507 "insufficient storage"
• 509 "bandwidth limit exceeded"
• 510 "not extended"
• 511 "network authentication required"

NOTE: don't worry too much about memorizing these strings, if you have a typo an error will be thrown, displaying this list so you can make a correction.

ctx.length=

Set response Content-Length to the given value.

ctx.length

Return request Content-Length as a number when present, or undefined.

ctx.responseLength

Return response Content-Length as a number when present, or deduce from ctx.body when possible, or undefined.

ctx.body

Get response body. When ctx.body is null and ctx.status is still 200 it is considered a 404. This is to prevent the developer from manually specifying this.status = 200 on every response.

ctx.body=

Set response body to one of the following:

• string written
• Buffer written
• Stream piped
• Object json-stringified
• null no content response

String

The Content-Type is defaulted to text/html or text/plain, both with a default charset of utf-8. The Content-Length field is also set.

Buffer

The Content-Type is defaulted to application/octet-stream, and Content-Length is also set.

Stream

The Content-Type is defaulted to application/octet-stream.

Object

The Content-Type is defaulted to application/json.

Notes

To alter the JSON response formatting use the app.jsonSpaces setting, for example to compress JSON responses set:

app.jsonSpaces = 0;

ctx.get(field)

Get a request header field value with case-insensitive field.

var etag = this.get('If-None-Match');

ctx.set(field, value)

Set response header field to value:

this.set('Cache-Control', 'no-cache');

ctx.set(fields)

Set several response header fields with an object:

this.set({
  'Etag': '1234',
  'Last-Modified': date
});

ctx.type

Get request Content-Type void of parameters such as "charset".

var ct = this.type;
// => "image/png"

ctx.type=

Set response Content-Type via mime string or file extension.

this.type = 'text/plain; charset=utf-8';
this.type = 'image/png';
this.type = '.png';
this.type = 'png';

Note: when appropriate a charset is selected for you, for example ctx.type = 'html' will default to "utf-8", however when explicitly defined in full as ctx.type = 'text/html' no charset is assigned.

ctx.url

Get request URL.

ctx.url=

Set request URL, useful for url rewrites.

ctx.path

Get request pathname.

ctx.path=

Set request pathname and retain query-string when present.

ctx.query

Get parsed query-string, returning an empty object when no query-string is present. Note that this getter does not support nested parsing.

For example "color=blue&size=small":

{
  color: 'blue',
  size: 'small'
}

ctx.query=

Set query-string to the given object. Note that this setter does not support nested objects.

this.query = { next: '/login' };

ctx.querystring

Get raw query string void of ?.

ctx.querystring=

Set raw query string.

ctx.host

Get host void of port number when present. Supports X-Forwarded-Host when app.proxy is true, otherwise Host is used.

ctx.fresh

Check if a request cache is "fresh", aka the contents have not changed. This method is for cache negotiation between If-None-Match / ETag, and If-Modified-Since and Last-Modified. It should be referenced after setting one or more of these response headers.

this.set('ETag', '123');

// cache is ok
if (this.fresh) {
  this.status = 304;
  return;
} 

// cache is stale
// fetch new data
this.body = yield db.find('something');

ctx.stale

Inverse of ctx.fresh.

ctx.protocol

Return request protocol, "https" or "http". Supports X-Forwarded-Proto when app.proxy is true.

ctx.secure

Shorthand for this.protocol == "https" to check if a requset was issued via TLS.

ctx.ip

Request remote address. Supports X-Forwarded-For when app.proxy is true.

ctx.ips

When X-Forwarded-For is present and app.proxy is enabled an array of these ips is returned, ordered from upstream -> downstream. When disabled an empty array is returned.

ctx.subdomains

Return subdomains as an array.

Subdomains are the dot-separated parts of the host before the main domain of the app. By default, the domain of the app is assumed to be the last two parts of the host. This can be changed by setting app.subdomainOffset.

For example, if the domain is "tobi.ferrets.example.com": If app.subdomainOffset is not set, this.subdomains is ["ferrets", "tobi"]. If app.subdomainOffset is 3, this.subdomains is ["tobi"].

ctx.is(type)

Check if the incoming request contains the Content-Type header field, and it contains the give mime type.

// With Content-Type: text/html; charset=utf-8
this.is('html');
this.is('.html');
this.is('text/html');
this.is('text/*');
// => true

// When Content-Type is application/json
this.is('json');
this.is('.json');
this.is('application/json');
this.is('application/*');
// => true

this.is('html');
// => false

ctx.redirect(url, [alt])

Perform a 302 redirect to url.

The string "back" is special-cased to provide Referrer support, when Referrer is not present alt or "/" is used.

this.redirect('back');
this.redirect('back', '/index.html');
this.redirect('/login');
this.redirect('http://google.com');

To alter the default status of 302 or the response body simply re-assign after this call:

this.redirect('/cart');
this.status = 301;
this.body = 'Redirecting to shopping cart';

ctx.attachment([filename])

Set Content-Disposition to "attachment" to signal the client to prompt for download. Optionally specify the filename of the download.

ctx.accepts(types)

Check if the given type(s) is acceptable, returning the best match when true, otherwise undefined, in which case you should respond with 406 "Not Acceptable".

The type value may be one or more mime type string such as "application/json", the extension name such as "json", or an array ["json", "html", "text/plain"]. When a list or array is given the best match, if any is returned.

// Accept: text/html
this.accepts('html');
// => "html"

// Accept: text/*, application/json
this.accepts('html');
// => "html"
this.accepts('text/html');
// => "text/html"
this.accepts('json', 'text');
// => "json"
this.accepts('application/json');
// => "application/json"

// Accept: text/*, application/json
this.accepts('image/png');
this.accepts('png');
// => undefined

// Accept: text/*;q=.5, application/json
this.accepts(['html', 'json']);
this.accepts('html', 'json');
// => "json"

You may call this.accepts() as may times as you like, or use a switch:

switch (this.accepts('json', 'html', 'text')) {
  case 'json': break;
  case 'html': break;
  case 'text': break;
}

ctx.acceptsEncodings(encodings)

Check if encodings are acceptable, returning the best match when true, otherwise undefined.

// Accept-Encoding: gzip
this.acceptsEncodings('gzip', 'deflate');
// => "gzip"

this.acceptsEncodings(['gzip', 'deflate']);
// => "gzip"

When no arguments are given all accepted encodings are returned as an array:

// Accept-Encoding: gzip, deflate
this.acceptsEncodings();
// => ["gzip", "deflate"]

ctx.acceptsCharsets(charsets)

Check if charsets are acceptable, returning the best match when true, otherwise undefined.

// Accept-Charset: utf-8, iso-8859-1;q=0.2, utf-7;q=0.5
this.acceptsCharsets('utf-8', 'utf-7');
// => "utf-8"

this.acceptsCharsets(['utf-7', 'utf-8']);
// => "utf-8"

When no arguments are given all accepted charsets are returned as an array:

// Accept-Charset: utf-8, iso-8859-1;q=0.2, utf-7;q=0.5
this.acceptsCharsets();
// => ["utf-8", "utf-7", "iso-8859-1"]

ctx.acceptsLanguages(langs)

Check if langs are acceptable, returning the best match when true, otherwise undefined.

// Accept-Language: en;q=0.8, es, pt
this.acceptsLanguages('es', 'en');
// => "es"

this.acceptsLanguages(['en', 'es']);
// => "es"

When no arguments are given all accepted languages are returned as an array:

// Accept-Language: en;q=0.8, es, pt
this.acceptsLanguages();
// => ["es", "pt", "en"]

ctx.headerSent

Check if a response header has already been sent. Useful for seeing if the client may be notified on error.

ctx.cookies.get(name, [options])

Get cookie name with options:

• signed the cookie requested should be signed

ctx.cookies.set(name, value, [options])

Set cookie name to value with options:

• signed sign the cookie value
• expires a Date for cookie expiration
• path cookie path, /' by default
• domain cookie domain
• secure secure cookie
• httpOnly server-accessible cookie, true by default

ctx.socket

Request socket object.

ctx.error(msg, [status])

Helper method to throw an error with a .status property that will allow Koa to respond appropriately. The following combinations are allowed:

this.error(403)
this.error('name required', 400)
this.error('something exploded')

For example this.error('name required', 400) is requivalent to:

var err = new Error('name required');
err.status = 400;
throw err;

Note that these are user-level errors and are flagged with err.expose meaning the messages are appropriate for client responses, which is typically not the case for error messages since you do not want to leak failure details.

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){
  log.error('server error', err);
});

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.

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);
});

License

MIT