Expand request stub docs

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<string>`
+
+  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('<h1>Client prefers HTML</h1>');
+} 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<string>`
+
+  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