# 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: ```js 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. ```js ctx.state.user = await User.find(id); ``` ### ctx.app Application instance reference. ### ctx.app.emit Koa applications extend an internal [EventEmitter](https://nodejs.org/dist/latest-v11.x/docs/api/events.html). `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](https://koajs.com/#error-handling) for more information. ### ctx.cookies.get(name, [options]) Get cookie `name` with `options`: - `signed` the cookie requested should be signed Koa uses the [cookies](https://github.com/pillarjs/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 from `Date.now()` for expiry. * `expires`: a `Date` 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](https://github.com/pillarjs/cookies#secure-cookies). * `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). * `partitioned`: a boolean indicating whether to partition the cookie in Chrome for the [CHIPS Update](https://developers.google.com/privacy-sandbox/3pcd/chips) (`false` by default). If this is true, Cookies from embedded sites will be partitioned and only readable from the same top level site from which it was created. * `priority`: a string indicating the cookie priority. This can be set to `'low'`, `'medium'`, or `'high'`. * `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'`, or `true` (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](https://www.npmjs.com/package/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](https://github.com/pillarjs/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: ```js 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: ```js 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. ```js ctx.throw(401, 'access_denied', { user: user }); ``` Koa uses [http-errors](https://github.com/jshttp/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()](http://nodejs.org/api/assert.html) method. ```js ctx.assert(ctx.state.user, 401, 'User not found. Please login!'); ``` Koa uses [http-assert](https://github.com/jshttp/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](request.md) 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](response.md) equivalents: - `ctx.body` - `ctx.body=` - `ctx.has()` - `ctx.status` - `ctx.status=` - `ctx.message` - `ctx.message=` - `ctx.length=` - `ctx.length` - `ctx.type=` - `ctx.type` - `ctx.vary()` - `ctx.headerSent` - `ctx.redirect()` - `ctx.attachment()` - `ctx.set()` - `ctx.append()` - `ctx.remove()` - `ctx.lastModified=` - `ctx.etag=` - `ctx.writable`