koa-lite/docs/api/request.md

255 lines
5.4 KiB
Markdown
Raw Normal View History

# 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
2014-09-25 11:36:23 +00:00
### request.header
Request header object. This is the same as the [`headers`](https://nodejs.org/api/http.html#http_message_headers) field
on node's [`http.IncomingMessage`](https://nodejs.org/api/http.html#http_class_http_incomingmessage).
### request.header=
Set request header object.
2014-09-25 11:36:23 +00:00
### request.headers
2014-09-25 11:36:23 +00:00
Request header object. Alias as `request.header`.
### request.headers=
Set request header object. Alias as `request.header=`.
2014-09-25 11:36:23 +00:00
### request.method
Request method.
2014-09-25 11:36:23 +00:00
### request.method=
Set request method, useful for implementing middleware
such as `methodOverride()`.
2014-09-25 11:36:23 +00:00
### request.length
Return request Content-Length as a number when present, or `undefined`.
2014-09-25 11:36:23 +00:00
### request.url
Get request URL.
2014-09-25 11:36:23 +00:00
### request.url=
Set request URL, useful for url rewrites.
2014-09-25 11:36:23 +00:00
### request.originalUrl
2014-05-06 02:01:34 +00:00
Get request original URL.
2015-10-03 03:38:48 +00:00
### request.origin
Get origin of URL, include `protocol` and `host`.
```js
2016-03-22 18:03:10 +00:00
ctx.request.origin
2015-10-03 03:38:48 +00:00
// => http://example.com
```
### request.href
Get full request URL, include `protocol`, `host` and `url`.
```js
ctx.request.href;
// => http://example.com/foo/bar?q=1
```
2014-09-25 11:36:23 +00:00
### request.path
Get request pathname.
2014-09-25 11:36:23 +00:00
### request.path=
Set request pathname and retain query-string when present.
2014-09-25 11:36:23 +00:00
### request.querystring
2013-12-18 07:53:58 +00:00
Get raw query string void of `?`.
2014-09-25 11:36:23 +00:00
### request.querystring=
2013-12-18 07:53:58 +00:00
Set raw query string.
2014-09-25 11:36:23 +00:00
### request.search
2013-12-18 07:53:58 +00:00
Get raw query string with the `?`.
2014-09-25 11:36:23 +00:00
### request.search=
2013-12-18 07:53:58 +00:00
Set raw query string.
2014-09-25 11:36:23 +00:00
### request.host
2013-12-18 07:53:58 +00:00
2014-05-05 15:44:00 +00:00
Get host (hostname:port) when present. Supports `X-Forwarded-Host`
2013-12-18 07:53:58 +00:00
when `app.proxy` is __true__, otherwise `Host` is used.
2014-09-25 11:36:23 +00:00
### request.hostname
2014-05-05 15:44:00 +00:00
2014-05-04 14:43:58 +00:00
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](https://nodejs.org/dist/latest-v8.x/docs/api/url.html#url_the_whatwg_url_api),
*Note* This may impact performance.
### request.URL
Get WHATWG parsed URL object.
2014-01-07 19:01:11 +00:00
2014-09-25 11:36:23 +00:00
### request.type
2013-12-18 07:53:58 +00:00
Get request `Content-Type` void of parameters such as "charset".
```js
const ct = ctx.request.type;
2013-12-18 07:53:58 +00:00
// => "image/png"
```
2014-09-25 11:36:23 +00:00
### request.charset
2014-02-14 17:38:59 +00:00
Get request charset when present, or `undefined`:
```js
ctx.request.charset;
2014-02-14 17:38:59 +00:00
// => "utf-8"
```
2014-09-25 11:36:23 +00:00
### request.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":
```js
{
color: 'blue',
size: 'small'
}
```
2014-09-25 11:36:23 +00:00
### request.query=
Set query-string to the given object. Note that this
setter does _not_ support nested objects.
```js
ctx.query = { next: '/login' };
```
2014-09-25 11:36:23 +00:00
### request.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.
```js
// freshness check requires status 20x or 304
2016-03-22 18:03:10 +00:00
ctx.status = 200;
ctx.set('ETag', '123');
// cache is ok
2016-03-22 18:03:10 +00:00
if (ctx.fresh) {
ctx.status = 304;
return;
}
// cache is stale
// fetch new data
ctx.body = await db.find('something');
```
2014-09-25 11:36:23 +00:00
### request.stale
2014-09-25 11:36:23 +00:00
Inverse of `request.fresh`.
2014-09-25 11:36:23 +00:00
### request.protocol
Return request protocol, "https" or "http". Supports `X-Forwarded-Proto`
when `app.proxy` is __true__.
2014-09-25 11:36:23 +00:00
### request.secure
2016-03-22 18:03:10 +00:00
Shorthand for `ctx.protocol == "https"` to check if a request was
issued via TLS.
2014-09-25 11:36:23 +00:00
### request.ip
Request remote address. Supports `X-Forwarded-For` when `app.proxy`
is __true__.
2014-09-25 11:36:23 +00:00
### request.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.
2014-09-25 11:36:23 +00:00
### request.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":
2016-03-22 18:03:10 +00:00
If `app.subdomainOffset` is not set, `ctx.subdomains` is `["ferrets", "tobi"]`.
If `app.subdomainOffset` is 3, `ctx.subdomains` is `["tobi"]`.
2014-09-25 11:36:23 +00:00
### request.is(types...)
Check if the incoming request contains the "Content-Type"
header field, and it contains any of the give mime `type`s.
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.
```js
// With Content-Type: text/html; charset=utf-8
2016-03-22 18:03:10 +00:00
ctx.is('html'); // => 'html'
ctx.is('text/html'); // => 'text/html'
ctx.is('text/*', 'text/html'); // => 'text/html'
// When Content-Type is application/json
2016-03-22 18:03:10 +00:00
ctx.is('json', 'urlencoded'); // => 'json'
ctx.is('application/json'); // => 'application/json'
ctx.is('html', 'application/*'); // => 'application/json'
2016-03-22 18:03:10 +00:00
ctx.is('html'); // => false
```
For example if you want to ensure that
only images are sent to a given route:
```js
2016-03-22 18:03:10 +00:00
if (ctx.is('image/*')) {
// process
} else {
2016-03-22 18:03:10 +00:00
ctx.throw(415, 'images only!');
}
```
2014-09-25 11:36:23 +00:00
### request.idempotent
2014-01-17 08:30:35 +00:00
Check if the request is idempotent.
2014-09-25 11:36:23 +00:00
### request.socket
2014-01-17 08:30:35 +00:00
Return the request socket.
2014-09-25 11:36:23 +00:00
### request.get(field)
2014-01-17 08:30:35 +00:00
Return request header with case-insensitive `field`.