diff --git a/Documentation/Books/Manual/Foxx/Router/Request.mdpp b/Documentation/Books/Manual/Foxx/Router/Request.mdpp index f58a9ccd83..a242174bf5 100644 --- a/Documentation/Books/Manual/Foxx/Router/Request.mdpp +++ b/Documentation/Books/Manual/Foxx/Router/Request.mdpp @@ -2,4 +2,283 @@ TODO -TODO Mention trustProxy +The request object specifies the following properties: + +* **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. + + TODO + +* **context**: `Context` + + The [service context][CONTEXT] in which the router was mounted (rather than the context in which the route was defined). + + TODO + +* **database**: `string` + + The name of the database in which the request is being handled, e.g. `"_system"`. + +* **headers**: `object` + + The raw headers object. + + TODO + +* **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` + + TODO + +* **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 service is configured to trust proxy headers, + this is set to the port portion of the `X-Forwarded-Host` header (or approriate 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 service is configured to trust proxy headers, + this is set to the value of the `X-Forwarded-Proto` header if present. + +* **queryParams**: `object` + + TODO + +* **rawBody**: `Buffer` + + TODO + +* **remoteAddress**: `string` + + The IP of the client that made the request. + + If the service is configured to trust proxy headers, + this is set to the first IP listed in the `X-Forwarded-For` header if present. + +* **remoteAddresses**: `Array` + + A list containing the IP addresses used to make the request. + + Defaults to the value of *remoteAddress* wrapped in an array. + + If the service is configured to trust proxy headers, + 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 service is configured to trust proxy headers, + 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` + + TODO + +* **url**: `string` + + TODO + +* **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. + +!SECTION 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][ACCEPTS]for the current request. + +**Examples** + +```js +if (req.accepts(['json', 'html']) === 'html') { + // Client explicitly prefers HTML over JSON + res.write('

Client prefers HTML

'); +} else { + // Otherwise just send JSON + res.json({success: true}); +} +``` + +!SECTION cookie + +`req.cookie(name, options): any` + +TODO + +**Arguments** + +* **name**: `string` + + TODO + +* **options**: `object` (optional) + + An object with any of the following properties: + + * **secret**: `string` (optional) + + TODO + + * **algorithm**: `string` (Default: `"sha256"`) + + TODO + +If a string is passed instead of an options object it will be interpreted as the *secret* option. + +TODO + +!SECTION get / header + +`req.get(name): string` + +`req.header(name): string` + +TODO + +**Arguments** + +* **name**: `string` + + TODO + +TODO + +!SECTION is + +`req.is(types): string` + +`req.is(...types): string` + +This method wraps the (request body) content type detection method of the [type-is module][TYPEIS] for the current request. + +**Arguments** + +* **types**: `Array` + + TODO + +TODO + +!SECTION json + +`req.json(): any` + +TODO + +!SECTION makeAbsolute + +`req.makeAbsolute(path, [query]): string` + +TODO + +**Arguments** + +* **path**: `string` + + TODO + +* **query**: `string | object` + + TODO + +TODO + +!SECTION params + +`req.param(name): any` + +**Arguments** + +TODO + +* **name**: `string` + + TODO + +TODO + +!SECTION range + +`req.range([size]): Ranges | number` + +This method wraps the range header parsing method of the [range-parser module][RANGEPARSER] 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" +``` + +[CONTEXT]: ../Context.md +[ACCEPTS]: https://github.com/jshttp/accepts +[RANGEPARSER]: https://github.com/jshttp/range-parser +[TYPEIS]: https://github.com/jshttp/type-is