6.5 KiB
Request
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.
API
req.header
Request header object.
req.method
Request method.
req.method=
Set request method, useful for implementing middleware
such as methodOverride().
req.length
Return request Content-Length as a number when present, or undefined.
req.type
Get request Content-Type void of parameters such as "charset".
var ct = this.type;
// => "image/png"
req.url
Get request URL.
req.url=
Set request URL, useful for url rewrites.
req.path
Get request pathname.
req.path=
Set request pathname and retain query-string when present.
req.query
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'
}
req.query=
Set query-string to the given object. Note that this setter does not support nested objects.
this.query = { next: '/login' };
req.querystring
Get raw query string void of ?.
req.querystring=
Set raw query string.
req.host
Get host void of port number when present. Supports X-Forwarded-Host
when app.proxy is true, otherwise Host is used.
req.fresh
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.
this.set('ETag', '123');
// cache is ok
if (this.fresh) {
this.status = 304;
return;
}
// cache is stale
// fetch new data
this.body = yield db.find('something');
req.stale
Inverse of req.fresh.
req.protocol
Return request protocol, "https" or "http". Supports X-Forwarded-Proto
when app.proxy is true.
req.secure
Shorthand for this.protocol == "https" to check if a requset was
issued via TLS.
req.ip
Request remote address. Supports X-Forwarded-For when app.proxy
is true.
req.ips
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.
req.subdomains
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, this.subdomains is ["ferrets", "tobi"].
If app.subdomainOffset is 3, this.subdomains is ["tobi"].
req.is(type)
Check if the incoming request contains the Content-Type
header field, and it contains the give mime type.
// With Content-Type: text/html; charset=utf-8
this.is('html');
this.is('.html');
this.is('text/html');
this.is('text/*');
// => true
// When Content-Type is application/json
this.is('json');
this.is('.json');
this.is('application/json');
this.is('application/*');
// => true
this.is('html');
// => false
req.accepts(types)
Check if the given type(s) is acceptable, returning
the best match when true, otherwise undefined, in which
case you should respond with 406 "Not Acceptable".
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"]. When a list or array is given the best match, if any is returned.
// Accept: text/html
this.accepts('html');
// => "html"
// Accept: text/*, application/json
this.accepts('html');
// => "html"
this.accepts('text/html');
// => "text/html"
this.accepts('json', 'text');
// => "json"
this.accepts('application/json');
// => "application/json"
// Accept: text/*, application/json
this.accepts('image/png');
this.accepts('png');
// => undefined
// Accept: text/*;q=.5, application/json
this.accepts(['html', 'json']);
this.accepts('html', 'json');
// => "json"
You may call this.accepts() as may times as you like,
or use a switch:
switch (this.accepts('json', 'html', 'text')) {
case 'json': break;
case 'html': break;
case 'text': break;
}
req.acceptsEncodings(encodings)
Check if encodings are acceptable, returning
the best match when true, otherwise undefined.
// Accept-Encoding: gzip
this.acceptsEncodings('gzip', 'deflate');
// => "gzip"
this.acceptsEncodings(['gzip', 'deflate']);
// => "gzip"
When no arguments are given all accepted encodings are returned as an array:
// Accept-Encoding: gzip, deflate
this.acceptsEncodings();
// => ["gzip", "deflate"]
req.acceptsCharsets(charsets)
Check if charsets are acceptable, returning
the best match when true, otherwise undefined.
// Accept-Charset: utf-8, iso-8859-1;q=0.2, utf-7;q=0.5
this.acceptsCharsets('utf-8', 'utf-7');
// => "utf-8"
this.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
this.acceptsCharsets();
// => ["utf-8", "utf-7", "iso-8859-1"]
req.acceptsLanguages(langs)
Check if langs are acceptable, returning
the best match when true, otherwise undefined.
// Accept-Language: en;q=0.8, es, pt
this.acceptsLanguages('es', 'en');
// => "es"
this.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
this.acceptsLanguages();
// => ["es", "pt", "en"]
req.error(msg, [status])
Helper method to throw an error with a .status property
that will allow Koa to respond appropriately. The following
combinations are allowed:
this.error(403)
this.error('name required', 400)
this.error('something exploded')
For example this.error('name required', 400) is requivalent 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.