Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
arangodb/Documentation/Books/Manual/foxx-reference-routers-requ...

419 lines
11 KiB
Markdown
Raw Permalink Blame History

---
layout: default
description: The request object specifies the following properties
---
Request objects
===============
The request object specifies the following properties:
* **arangoUser**: `string | null`
The authenticated ArangoDB username used to make the request.
This value is only set if authentication is enabled in ArangoDB and the
request set an `authorization` header ArangoDB was able to verify.
You are strongly encouraged to implement
[your own authentication logic](foxx-guides-auth.html) for your own services
but this property can be useful if you need to integrate with ArangoDB's
own authentication mechanisms.
* **arangoVersion**: `number`
The numeric value of the `x-arango-version` header or the numeric version
of the ArangoDB server (e.g. `30102` for version 3.1.2) if no valid header
was provided.
* **auth**: `object | null`
The credentials supplied in the `authorization` header if any.
If the request uses basic authentication, the value is an object like
`{basic: {username: string}}` or
`{basic: {username: string, password: string}}` or
`{basic: {}}` (if the credentials were malformed or empty).
If the request uses bearer authentication, the value is an object like
`{bearer: string}`.
* **baseUrl**: `string`
Root-relative base URL of the service, i.e. the prefix `"/_db/"` followed
by the value of *database*.
* **body**: `any`
The processed and validated request body for the current route.
If no body has been defined for the current route, the value will be
identical to *rawBody*.
For details on how request bodies can be processed and validated by Foxx
see the [body method of the endpoint object](foxx-reference-routers-endpoints.html#body).
* **context**: `Context`
The [service context](foxx-reference-context.html) in which the router was mounted
(rather than the context in which the route was defined).
* **database**: `string`
The name of the database in which the request is being handled, e.g. `"_system"`.
* **headers**: `object`
The raw headers object.
For details on how request headers can be validated by Foxx see the
[header method of the endpoint object](foxx-reference-routers-endpoints.html#header).
* **hostname**: `string`
The hostname (domain name) indicated in the request headers.
Defaults to the hostname portion (i.e. excluding the port) of the `Host`
header and falls back to the listening address of the server.
* **method**: `string`
The HTTP verb used to make the request, e.g. `"GET"`.
* **originalUrl**: `string`
Root-relative URL of the request, i.e. *path* followed by the raw query
parameters, if any.
* **path**: `string`
Database-relative path of the request URL (not including the query parameters).
* **pathParams**: `object`
An object mapping the names of path parameters of the current route to
their validated values.
For details on how path parameters can be validated by Foxx see the
[pathParam method of the endpoint object](foxx-reference-routers-endpoints.html#pathparam).
* **port**: `number`
The port indicated in the request headers.
Defaults to the port portion (i.e. excluding the hostname) of the `Host`
header and falls back to the listening port or the appropriate default
port (`443` for HTTPS or `80` for HTTP, depending on *secure*) if the
header only indicates a hostname.
If the request was made using a trusted proxy (see *trustProxy*),
this is set to the port portion of the `X-Forwarded-Host` header
(or appropriate default port) if present.
* **protocol**: `string`
The protocol used for the request.
Defaults to `"https"` or `"http"` depending on whether ArangoDB is
configured to use SSL or not.
If the request was made using a trusted proxy (see *trustProxy*),
this is set to the value of the `X-Forwarded-Proto` header if present.
* **queryParams**: `object`
An object mapping the names of query parameters of the current route to
their validated values.
For details on how query parameters can be validated by Foxx see the
[queryParam method of the endpoint object](foxx-reference-routers-endpoints.html#queryparam).
* **rawBody**: `Buffer`
The raw, unparsed, unvalidated request body as a buffer.
* **remoteAddress**: `string`
The IP of the client that made the request.
If the request was made using a trusted proxy (see *trustProxy*),
this is set to the first IP listed in the `X-Forwarded-For` header if present.
* **remoteAddresses**: `Array<string>`
A list containing the IP addresses used to make the request.
Defaults to the value of *remoteAddress* wrapped in an array.
If the request was made using a trusted proxy (see *trustProxy*),
this is set to the list of IPs specified in the `X-Forwarded-For` header if present.
* **remotePort**: `number`
The listening port of the client that made the request.
If the request was made using a trusted proxy (see *trustProxy*),
this is set to the port specified in the `X-Forwarded-Port` header if present.
* **secure**: `boolean`
Whether the request was made over a secure connection (i.e. HTTPS).
This is set to `false` when *protocol* is `"http"` and `true` when
*protocol* is `"https"`.
* **suffix**: `string`
The trailing path relative to the current route if the current route ends
in a wildcard (e.g. `/something/*`).
**Note**: Starting with ArangoDB 3.2 is passed into the service as-is, i.e.
percentage escape sequences like `%2F` will no longer be unescaped.
Also note that the suffix may contain path segments like `..` which may have
special meaning if the suffix is used to build filesystem paths.
* **trustProxy**: `boolean`
Indicates whether the request was made using a trusted proxy.
If the origin server's address was specified in the ArangoDB configuration
using `--frontend.trusted-proxy` or the service's `trustProxy` setting is
enabled, this will be `true`, otherwise it will be `false`.
* **url**: `string`
The URL of the request.
* **xhr**: `boolean`
Whether the request indicates it was made within a browser using AJAX.
This is set to `true` if the `X-Requested-With` header is present and is
a case-insensitive match for the value `"xmlhttprequest"`.
Note that this value does not guarantee whether the request was made from
inside a browser or whether AJAX was used and is merely a convention
established by JavaScript frameworks like jQuery.
accepts
-------
`req.accepts(types): string | false`
`req.accepts(...types): string | false`
`req.acceptsCharsets(charsets): string | false`
`req.acceptsCharsets(...charsets): string | false`
`req.acceptsEncodings(encodings): string | false`
`req.acceptsEncodings(...encodings): string | false`
`req.acceptsLanguages(languages): string | false`
`req.acceptsLanguages(...languages): string | false`
These methods wrap the corresponding content negotiation methods of the
[accepts module](https://github.com/jshttp/accepts){:target="_blank"} for the current request.
**Examples**
```js
if (req.accepts(['json', 'html']) === 'html') {
// Client explicitly prefers HTML over JSON
res.write('<h1>Client prefers HTML</h1>');
} else {
// Otherwise just send JSON
res.json({success: true});
}
```
cookie
------
`req.cookie(name, options): string | null`
Gets the value of a cookie by name.
**Arguments**
* **name**: `string`
Name of the cookie.
* **options**: `object` (optional)
An object with any of the following properties:
* **secret**: `string` (optional)
Secret that was used to sign the cookie.
If a secret is specified, the cookie's signature is expected to be present
in a second cookie with the same name and the suffix `.sig`.
Otherwise the signature (if present) will be ignored.
* **algorithm**: `string` (Default: `"sha256"`)
Algorithm that was used to sign the cookie.
If a string is passed instead of an options object it will be interpreted as
the *secret* option.
Returns the value of the cookie or `null` if the cookie is not set or its
signature is invalid.
get / header
------------
`req.get(name): string`
`req.header(name): string`
Gets the value of a header by name. You can validate request headers using the
[header method of the endpoint](foxx-reference-routers-endpoints.html#header).
**Arguments**
* **name**: `string`
Name of the header.
Returns the header value.
is
--
`req.is(types): string`
`req.is(...types): string`
This method wraps the (request body) content type detection method of the
[type-is module](https://github.com/jshttp/type-is){:target="_blank"} for the current request.
**Examples**
```js
const type = req.is('html', 'application/xml', 'application/*+xml');
if (type === false) { // no match
handleDefault(req.rawBody);
} else if (type === 'html') {
handleHtml(req.rawBody);
} else { // is XML
handleXml(req.rawBody);
}
```
json
----
`req.json(): any`
Attempts to parse the raw request body as JSON and returns the result.
It is generally more useful to define a
[request body on the endpoint](foxx-reference-routers-endpoints.html#body) and use the `req.body`
property instead.
Returns `undefined` if the request body is empty. May throw a `SyntaxError`
if the body could not be parsed.
makeAbsolute
------------
`req.makeAbsolute(path, [query]): string`
Resolves the given path relative to the `req.context.service`'s mount path
to a full URL.
**Arguments**
* **path**: `string`
The path to resovle.
* **query**: `string | object`
A string or object with query parameters to add to the URL.
Returns the formatted absolute URL.
params
------
`req.param(name): any`
**Arguments**
Looks up a parameter by name, preferring `pathParams` over `queryParams`.
It's probably better style to use the `req.pathParams` or `req.queryParams`
objects directly.
* **name**: `string`
Name of the parameter.
Returns the (validated) value of the parameter.
range
-----
`req.range([size]): Ranges | number`
This method wraps the range header parsing method of the
[range-parser module](https://github.com/jshttp/range-parser){:target="_blank"} for the current request.
**Arguments**
* **size**: `number` (Default: `Infinity`)
Length of the satisfiable range (e.g. number of bytes in the full response).
If present, ranges exceeding the size will be considered unsatisfiable.
Returns `undefined` if the `Range` header is absent, `-2` if the header is
present but malformed, `-1` if the range is invalid (e.g. start offset is
larger than end offset) or unsatisfiable for the given size.
Otherwise returns an array of objects with the properties *start* and *end*
values for each range. The array has an additional property *type* indicating
the request range type.
**Examples**
```js
console.log(req.headers.range); // "bytes=40-80"
const ranges = req.range(100);
console.log(ranges); // [{start: 40, end: 80}]
console.log(ranges.type); // "bytes"
```
reverse
-------
`req.reverse(name, [params]): string`
Looks up the URL of a named route for the given parameters.
**Arguments**
* **name**: `string`
Name of the route to look up.
* **params**: `object` (optional)
An object containing values for the (path or query) parameters of the route.
Returns the URL of the route for the given parameters.
**Examples**
```js
router.get('/items/:id', function (req, res) {
/* ... */
}, 'getItemById');
router.post('/items', function (req, res) {
// ...
const url = req.reverse('getItemById', {id: createdItem._key});
res.set('location', req.makeAbsolute(url));
});
```
Reference in New Issue View Git Blame Copy Permalink