4.2 KiB
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 middleware to re-implement this common functionality.
A Context
is created per request, and is referenced in middleware
as the receiver, or the this
identifier, as shown in the following
snippet:
app.use(function *(){
this; // is the Context
this.request; // is a koa Request
this.response; // is a koa Response
});
Many of the context's accessors and methods simply delegate to their ctx.request
or ctx.response
equivalents for convenience, and are otherwise identical. For example ctx.type
and ctx.length
delegate to the response
object, and ctx.path
and ctx.method
delegate to the request
.
API
Context
specific methods and accessors.
ctx.req
Node's request
object.
ctx.res
Node's response
object.
Bypassing Koa's response handling is not supported. Avoid using the following node properties:
res.statusCode
res.writeHead()
res.write()
res.end()
ctx.request
A koa Request
object.
ctx.response
A koa Response
object.
ctx.app
Application instance reference.
ctx.cookies.get(name, [options])
Get cookie name
with options
:
signed
the cookie requested should be signed
Note: koa uses the cookies module where options are simply passed.
ctx.cookies.set(name, value, [options])
Set cookie name
to value
with options
:
signed
sign the cookie valueexpires
aDate
for cookie expirationpath
cookie path,/'
by defaultdomain
cookie domainsecure
secure cookiehttpOnly
server-accessible cookie, true by default
Note: koa uses the cookies module where options are simply passed.
ctx.throw(msg, [status])
Helper method to throw an error with a .status
property
defaulting to 500
that will allow Koa to respond appropriately.
The following combinations are allowed:
this.throw(403)
this.throw('name required', 400)
this.throw(400, 'name required')
this.throw('something exploded')
For example this.throw('name required', 400)
is equivalent 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.
ctx.respond
To bypass Koa's built-in response handling, you may explicitly set this.respond = false;
. Use this if you want to write to the raw res
object instead of letting Koa handle the response for you.
Note that using this is not supported by Koa. This may break intended functionality of Koa middleware and Koa itself. Using this properly is considered a hack and is only a convenience to those wishing to use traditional fn(req, res)
functions and middleware within Koa.
Request aliases
The following accessors and alias Request equivalents:
ctx.header
ctx.method
ctx.method=
ctx.url
ctx.url=
ctx.path
ctx.path=
ctx.query
ctx.query=
ctx.querystring
ctx.querystring=
ctx.type
ctx.host
ctx.host=
ctx.fresh
ctx.stale
ctx.socket
ctx.protocol
ctx.secure
ctx.ip
ctx.ips
ctx.subdomains
ctx.is()
ctx.accepts()
ctx.acceptsEncodings()
ctx.acceptsCharsets()
ctx.acceptsLanguages()
ctx.get()
Response aliases
The following accessors and alias Response equivalents:
ctx.body
ctx.body=
ctx.status
ctx.status=
ctx.length
ctx.length=
ctx.type
ctx.type=
ctx.charset
ctx.charset=
ctx.headerSent
ctx.redirect()
ctx.attachment()
ctx.set()
ctx.remove()
ctx.lastModified=
ctx.etag=