A Koa Request object is an abstraction on top of Node's vanilla request object,
providing additional functionality that is useful for every day HTTP server
development.
Request header object. This is the same as the headers field
on Node's http.IncomingMessage.
Set request header object.
Request header object. Alias as request.header.
Set request header object. Alias as request.header=.
Request method.
Set request method, useful for implementing middleware
such as methodOverride().
Return request Content-Length as a number when present, or undefined.
Get request URL.
Set request URL, useful for url rewrites.
Get request original URL.
Get origin of URL, include protocol and host.
ctx.request.origin
// => http://example.comGet full request URL, include protocol, host and url.
ctx.request.href;
// => http://example.com/foo/bar?q=1Get request pathname.
Set request pathname and retain query-string when present.
Get raw query string void of ?.
Set raw query string.
Get raw query string with the ?.
Set raw query string.
Get host (hostname:port) when present. Supports X-Forwarded-Host
when app.proxy is true, otherwise Host is used.
Get hostname when present. Supports X-Forwarded-Host
when app.proxy is true, otherwise Host is used.
If host is IPv6, Koa delegates parsing to WHATWG URL API, Note This may impact performance.
Get WHATWG parsed URL object.
Get request Content-Type void of parameters such as "charset".
const ct = ctx.request.type;
// => "image/png"Get request charset when present, or undefined:
ctx.request.charset;
// => "utf-8"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'
}Set query-string to the given object. Note that this setter does not support nested objects.
ctx.query = { next: '/login' };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.
// freshness check requires status 20x or 304
ctx.status = 200;
ctx.set('ETag', '123');
// cache is ok
if (ctx.fresh) {
ctx.status = 304;
return;
}
// cache is stale
// fetch new data
ctx.body = await db.find('something');Inverse of request.fresh.
Return request protocol, "https" or "http". Supports X-Forwarded-Proto
when app.proxy is true.
Shorthand for ctx.protocol == "https" to check if a request was
issued via TLS.
Request remote address. Supports X-Forwarded-For when app.proxy
is true.
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.
For example if the value were "client, proxy1, proxy2",
you would receive the array ["client", "proxy1", "proxy2"].
Most of the reverse proxy(nginx) set x-forwarded-for via
proxy_add_x_forwarded_for, which poses a certain security risk.
A malicious attacker can forge a client's ip address by forging
a X-Forwarded-Forrequest header. The request sent by the client
has an X-Forwarded-For request header for 'forged'. After being
forwarded by the reverse proxy, request.ips will be
['forged', 'client', 'proxy1', 'proxy2'].
Koa offers two options to avoid being bypassed.
If you can control the reverse proxy, you can avoid bypassing
by adjusting the configuration, or use the app.proxyIpHeader
provided by koa to avoid reading x-forwarded-for to get ips.
const app = new Koa({
proxy: true,
proxyIpHeader: 'X-Real-IP',
});If you know exactly how many reverse proxies are in front of
the server, you can avoid reading the user's forged request
header by configuring app.maxIpsCount:
const app = new Koa({
proxy: true,
maxIpsCount: 1, // only one proxy in front of the server
});
// request.header['X-Forwarded-For'] === [ '127.0.0.1', '127.0.0.2' ];
// ctx.ips === [ '127.0.0.2' ];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, ctx.subdomains is ["ferrets", "tobi"].
If app.subdomainOffset is 3, ctx.subdomains is ["tobi"].
Check if the incoming request contains the "Content-Type"
header field, and it contains any of the give mime types.
If there is no request body, null is returned.
If there is no content type, or the match fails false is returned.
Otherwise, it returns the matching content-type.
// With Content-Type: text/html; charset=utf-8
ctx.is('html'); // => 'html'
ctx.is('text/html'); // => 'text/html'
ctx.is('text/*', 'text/html'); // => 'text/html'
// When Content-Type is application/json
ctx.is('json', 'urlencoded'); // => 'json'
ctx.is('application/json'); // => 'application/json'
ctx.is('html', 'application/*'); // => 'application/json'
ctx.is('html'); // => falseFor example if you want to ensure that only images are sent to a given route:
if (ctx.is('image/*')) {
// process
} else {
ctx.throw(415, 'images only!');
}Koa's request object includes helpful content negotiation utilities powered by accepts and negotiator. These utilities are:
request.accepts(types)request.acceptsEncodings(types)request.acceptsCharsets(charsets)request.acceptsLanguages(langs)
If no types are supplied, all acceptable types are returned.
If multiple types are supplied, the best match will be returned. If no matches are found, a false is returned, and you should send a 406 "Not Acceptable" response to the client.
In the case of missing accept headers where any type is acceptable, the first type will be returned. Thus, the order of types you supply is important.
Check if the given type(s) is acceptable, returning the best match when true, otherwise false. 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"].
// Accept: text/html
ctx.accepts('html');
// => "html"
// Accept: text/*, application/json
ctx.accepts('html');
// => "html"
ctx.accepts('text/html');
// => "text/html"
ctx.accepts('json', 'text');
// => "json"
ctx.accepts('application/json');
// => "application/json"
// Accept: text/*, application/json
ctx.accepts('image/png');
ctx.accepts('png');
// => false
// Accept: text/*;q=.5, application/json
ctx.accepts(['html', 'json']);
ctx.accepts('html', 'json');
// => "json"
// No Accept header
ctx.accepts('html', 'json');
// => "html"
ctx.accepts('json', 'html');
// => "json"You may call ctx.accepts() as many times as you like,
or use a switch:
switch (ctx.accepts('json', 'html', 'text')) {
case 'json': break;
case 'html': break;
case 'text': break;
default: ctx.throw(406, 'json, html, or text only');
}Check if encodings are acceptable, returning the best match when true, otherwise false. Note that you should include identity as one of the encodings!
// Accept-Encoding: gzip
ctx.acceptsEncodings('gzip', 'deflate', 'identity');
// => "gzip"
ctx.acceptsEncodings(['gzip', 'deflate', 'identity']);
// => "gzip"When no arguments are given all accepted encodings are returned as an array:
// Accept-Encoding: gzip, deflate
ctx.acceptsEncodings();
// => ["gzip", "deflate", "identity"]Note that the identity encoding (which means no encoding) could be unacceptable if the client explicitly sends identity;q=0. Although this is an edge case, you should still handle the case where this method returns false.
Check if charsets are acceptable, returning
the best match when true, otherwise false.
// Accept-Charset: utf-8, iso-8859-1;q=0.2, utf-7;q=0.5
ctx.acceptsCharsets('utf-8', 'utf-7');
// => "utf-8"
ctx.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
ctx.acceptsCharsets();
// => ["utf-8", "utf-7", "iso-8859-1"]Check if langs are acceptable, returning
the best match when true, otherwise false.
// Accept-Language: en;q=0.8, es, pt
ctx.acceptsLanguages('es', 'en');
// => "es"
ctx.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
ctx.acceptsLanguages();
// => ["es", "pt", "en"]Check if the request is idempotent.
Return the request socket.
Return request header with case-insensitive field.