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 ctx
identifier, as shown in the following snippet:
app.use(async ctx => { ctx; // is the Context ctx.request; // is a Koa Request ctx.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.state
The recommended namespace for passing information through middleware and to your frontend views.
ctx.state.user = await User.find(id);
ctx.app
Application instance reference.
ctx.app.emit
Koa applications extend an internal EventEmitter. ctx.app.emit
emits an event with a type, defined by the first argument. For each event you can hook up "listeners", which is a function that is called when the event is emitted. Consult the error handling docs for more information.
ctx.cookies.get(name, [options])
Get cookie name
with options
:
-
signed
the cookie requested should be signed
Koa uses the cookies module where options are simply passed.
ctx.cookies.set(name, value, [options])
Set cookie name
to value
with options
:
-
maxAge
: a number representing the milliseconds fromDate.now()
for expiry. -
expires
: aDate
object indicating the cookie's expiration date (expires at the end of session by default). -
path
: a string indicating the path of the cookie (/
by default). -
domain
: a string indicating the domain of the cookie (no default). -
secure
: a boolean indicating whether the cookie is only to be sent over HTTPS (false
by default for HTTP,true
by default for HTTPS). Read more about this option. -
httpOnly
: a boolean indicating whether the cookie is only to be sent over HTTP(S), and not made available to client JavaScript (true
by default). -
sameSite
: a boolean or string indicating whether the cookie is a "same site" cookie (false
by default). This can be set to'strict'
,'lax'
,'none'
, ortrue
(which maps to'strict'
). -
signed
: a boolean indicating whether the cookie is to be signed (false
by default). If this is true, another cookie of the same name with the.sig
suffix appended will also be sent, with a 27-byte url-safe base64 SHA1 value representing the hash of cookie-name=cookie-value against the first Keygrip key. This signature key is used to detect tampering the next time a cookie is received. -
overwrite
: a boolean indicating whether to overwrite previously set cookies of the same name (false
by default). If this is true, all cookies set during the same request with the same name (regardless of path or domain) are filtered out of the Set-Cookie header when setting this cookie.
Koa uses the cookies module where options are simply passed.
ctx.throw([status], [msg], [properties])
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:
ctx.throw(400); ctx.throw(400, 'name required'); ctx.throw(400, 'name required', { user: user });
For example ctx.throw(400, 'name required')
is equivalent to:
const err = new Error('name required'); err.status = 400; err.expose = true; 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.
You may optionally pass a properties
object which is merged into the error as-is, useful for decorating machine-friendly errors which are reported to the requester upstream.
ctx.throw(401, 'access_denied', { user: user });
Koa uses http-errors to create errors. status
should only be passed as the first parameter.
ctx.assert(value, [status], [msg], [properties])
Helper method to throw an error similar to .throw()
when !value
. Similar to node's assert() method.
ctx.assert(ctx.state.user, 401, 'User not found. Please login!');
Koa uses http-assert for assertions.
ctx.respond
To bypass Koa's built-in response handling, you may explicitly set ctx.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 property 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.headers
ctx.method
ctx.method=
ctx.url
ctx.url=
ctx.originalUrl
ctx.origin
ctx.href
ctx.path
ctx.path=
ctx.query
ctx.query=
ctx.querystring
ctx.querystring=
ctx.host
ctx.hostname
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.message
ctx.message=
ctx.length=
ctx.length
ctx.type=
ctx.type
ctx.headerSent
ctx.redirect()
ctx.attachment()
ctx.set()
ctx.append()
ctx.remove()
ctx.lastModified=
ctx.etag=
© 2020 Koa contributors
Licensed under the MIT License.
https://github.com/koajs/koa/blob/master/docs/api/context.md