195 lines
5.9 KiB
Markdown
195 lines
5.9 KiB
Markdown
# Installation
|
|
|
|
Koa is supported in all versions of [iojs](https://iojs.org) without any flags.
|
|
|
|
To use Koa with node, you must be running __node 0.11.16__ or higher for generator and promise support, and must run node(1)
|
|
with the `--harmony-generators` or `--harmony` flag.
|
|
|
|
You can quickly install a supposed version of node/iojs with your favorite version manager:
|
|
|
|
```bash
|
|
$ nvm install iojs
|
|
$ npm i koa
|
|
$ node my-koa-app.js
|
|
```
|
|
|
|
# Application
|
|
|
|
A Koa application is an object containing an array of middleware generator functions
|
|
which are composed and executed in a stack-like manner upon request. Koa is similar to many
|
|
other middleware systems that you may have encountered such as Ruby's Rack, Connect, and so on -
|
|
however a key design decision was made to provide high level "sugar" at the otherwise low-level
|
|
middleware layer. This improves interoperability, robustness, and makes writing middleware much
|
|
more enjoyable.
|
|
|
|
This includes methods for common tasks like content-negotiation, cache freshness, proxy support, and redirection
|
|
among others. Despite supplying a reasonably large number of helpful methods Koa maintains a small footprint, as
|
|
no middleware are bundled.
|
|
|
|
The obligatory hello world application:
|
|
|
|
```js
|
|
var koa = require('koa');
|
|
var app = koa();
|
|
|
|
app.use(function *(){
|
|
this.body = 'Hello World';
|
|
});
|
|
|
|
app.listen(3000);
|
|
```
|
|
|
|
## Cascading
|
|
|
|
Koa middleware cascade in a more traditional way as you may be used to with similar tools -
|
|
this was previously difficult to make user friendly with node's use of callbacks.
|
|
However with generators we can achieve "true" middleware. Contrasting Connect's implementation which
|
|
simply passes control through series of functions until one returns, Koa yields "downstream", then
|
|
control flows back "upstream".
|
|
|
|
The following example responds with "Hello World", however first the request flows through
|
|
the `x-response-time` and `logging` middleware to mark when the request started, then continue
|
|
to yield control through the response middleware. When a middleware invokes `yield next`
|
|
the function suspends and passes control to the next middleware defined. After there are no more
|
|
middleware to execute downstream, the stack will unwind and each middleware is resumed to perform
|
|
its upstream behaviour.
|
|
|
|
```js
|
|
var koa = require('koa');
|
|
var app = koa();
|
|
|
|
// x-response-time
|
|
|
|
app.use(function *(next){
|
|
var start = new Date;
|
|
yield next;
|
|
var ms = new Date - start;
|
|
this.set('X-Response-Time', ms + 'ms');
|
|
});
|
|
|
|
// logger
|
|
|
|
app.use(function *(next){
|
|
var start = new Date;
|
|
yield next;
|
|
var ms = new Date - start;
|
|
console.log('%s %s - %s', this.method, this.url, ms);
|
|
});
|
|
|
|
// response
|
|
|
|
app.use(function *(){
|
|
this.body = 'Hello World';
|
|
});
|
|
|
|
app.listen(3000);
|
|
```
|
|
|
|
## 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.listen(...)
|
|
|
|
A Koa application is not a 1-to-1 representation of a HTTP server.
|
|
One or more Koa applications may be mounted together to form larger
|
|
applications with a single HTTP server.
|
|
|
|
Create and return an HTTP server, passing the given arguments to
|
|
`Server#listen()`. These arguments are documented on [nodejs.org](http://nodejs.org/api/http.html#http_server_listen_port_hostname_backlog_callback). The following is a useless Koa application bound to port `3000`:
|
|
|
|
```js
|
|
var koa = require('koa');
|
|
var app = koa();
|
|
app.listen(3000);
|
|
```
|
|
|
|
The `app.listen(...)` method is simply sugar for the following:
|
|
|
|
```js
|
|
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:
|
|
|
|
```js
|
|
var http = require('http');
|
|
var koa = require('koa');
|
|
var app = koa();
|
|
http.createServer(app.callback()).listen(3000);
|
|
http.createServer(app.callback()).listen(3001);
|
|
```
|
|
|
|
## 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](https://github.com/koajs/koa/wiki#middleware) for
|
|
more information.
|
|
|
|
## app.keys=
|
|
|
|
Set signed cookie keys.
|
|
|
|
These are passed to [KeyGrip](https://github.com/jed/keygrip),
|
|
however you may also pass your own `KeyGrip` instance. For
|
|
example the following are acceptable:
|
|
|
|
```js
|
|
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:
|
|
|
|
```js
|
|
this.cookies.set('name', 'tobi', { signed: true });
|
|
```
|
|
|
|
## app.context
|
|
|
|
The recommended namespace to extend with information that's useful
|
|
throughout the lifetime of your application, as opposed to a per request basis.
|
|
|
|
```js
|
|
app.context.db = db();
|
|
```
|
|
|
|
## 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:
|
|
|
|
```js
|
|
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:
|
|
|
|
```js
|
|
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.
|