Update 5x API docs with missing 4x changes (#1886)

* Include 4.18 API doc updates in 5.x

5c98ee4

Co-authored-by: Douglas Christopher Wilson <doug@somethingdoug.com>

* Copy acceptsLanguages documentation improvements to 5.x

#1402

Co-authored-by: Jon Ege Ronnenberg <jon.ronnenberg@gmail.com>

* Add warning boxes to {app,res}.render

5e918ea

Co-authored-by: Douglas Christopher Wilson <doug@somethingdoug.com>

* Copy warning around securing locals to 5.x

fcaca7f

Co-authored-by: Douglas Christopher Wilson <doug@somethingdoug.com>

* Copy res.cookie `partitioned` option docs

#1456

Co-authored-by: Rich Hodgkins <rhodgkins@gmail.com>

* Update req.body to point to built-in middleware

a5ca5b0

Co-Authored-By: Douglas Wilson <doug@somethingdoug.com>

* Copy setting multiple cookies example to 5.x

#1063

Co-Authored-By: Mo <hematy61@gmail.com>

---------

Co-authored-by: krzysdz <krzysdz@users.noreply.github.com>
Co-authored-by: Douglas Christopher Wilson <doug@somethingdoug.com>
Co-authored-by: Jon Ege Ronnenberg <jon.ronnenberg@gmail.com>
Co-authored-by: Rich Hodgkins <rhodgkins@gmail.com>
Co-authored-by: Mo <hematy61@gmail.com>

Author: 5 people

_includes/api/en/5x/app-locals.md

@@ -3,6 +3,14 @@
 The `app.locals` object has properties that are local variables within the application,
 and will be available in templates rendered with [res.render](#res.render).
 
+<div class="doc-box doc-warn" markdown="1">
+The `locals` object is used by view engines to render a response. The object
+keys may be particularly sensitive and should not contain user-controlled
+input, as it may affect the operation of the view engine or provide a path to
+cross-site scripting. Consult the documentation for the used view engine for
+additional considerations.
+</div>
+
 ```js
 console.dir(app.locals.title)
 // => 'My App'

_includes/api/en/5x/app-render.md

@@ -9,6 +9,20 @@ Think of `app.render()` as a utility function for generating rendered view strin
 Internally `res.render()` uses `app.render()` to render views.
 </div>
 
+<div class="doc-box doc-warn" markdown="1">
+The `view` argument performs file system operations like reading a file from
+disk and evaluating Node.js modules, and as so for security reasons should not
+contain input from the end-user.
+</div>
+
+<div class="doc-box doc-warn" markdown="1">
+The `locals` object is used by view engines to render a response. The object
+keys may be particularly sensitive and should not contain user-controlled
+input, as it may affect the operation of the view engine or provide a path to
+cross-site scripting. Consult the documentation for the used view engine for
+additional considerations.
+</div>
+
 <div class="doc-box doc-notice" markdown="1">
 The local variable `cache` is reserved for enabling view cache. Set it to `true`, if you want to
 cache view during development; view caching is enabled in production by default.

_includes/api/en/5x/req-acceptsLanguages.md

@@ -1,7 +1,15 @@
-<h3 id='req.acceptsLanguages'>req.acceptsLanguages(lang [, ...])</h3>
+<h3 id='req.acceptsLanguages'>req.acceptsLanguages([lang, ...])</h3>
 
 Returns the first accepted language of the specified languages,
 based on the request's `Accept-Language` HTTP header field.
 If none of the specified languages is accepted, returns `false`.
 
+If no `lang` argument is given, then `req.acceptsLanguages()`
+returns all languages from the HTTP `Accept-Language` header
+as an `Array`.
+
 For more information, or if you have issues or concerns, see [accepts](https://github.com/expressjs/accepts).
+
+Express (5.x) source: [request.js line 172](https://github.com/expressjs/express/blob/v5.1.0/lib/request.js#L172)
+
+Accepts (2.0) source: [index.js line 195](https://github.com/jshttp/accepts/blob/2.0.0/index.js#L195)

_includes/api/en/5x/req-body.md

@@ -2,7 +2,7 @@
 
 Contains key-value pairs of data submitted in the request body.
 By default, it is `undefined`, and is populated when you use body-parsing middleware such
-as [body-parser](https://www.npmjs.org/package/body-parser) and [multer](https://www.npmjs.org/package/multer).
+as [`express.json()`](#express.json) or [`express.urlencoded()`](#express.urlencoded).
 
 <div class="doc-box doc-warn" markdown="1">
 As `req.body`'s shape is based on user-controlled input, all properties and values in this object are untrusted and should be validated before trusting. For example, `req.body.foo.toString()` may fail in multiple ways, for example `foo` may not be there or may not be a string, and `toString` may not be a function and instead a string or other user-input.
@@ -11,15 +11,14 @@ As `req.body`'s shape is based on user-controlled input, all properties and valu
 The following example shows how to use body-parsing middleware to populate `req.body`.
 
 ```js
-const app = require('express')()
-const bodyParser = require('body-parser')
-const multer = require('multer') // v1.0.5
-const upload = multer() // for parsing multipart/form-data
+const express = require('express')
 
-app.use(bodyParser.json()) // for parsing application/json
-app.use(bodyParser.urlencoded({ extended: true })) // for parsing application/x-www-form-urlencoded
+const app = express()
 
-app.post('/profile', upload.array(), (req, res, next) => {
+app.use(express.json()) // for parsing application/json
+app.use(express.urlencoded({ extended: true })) // for parsing application/x-www-form-urlencoded
+
+app.post('/profile', (req, res, next) => {
   console.log(req.body)
   res.json(req.body)
 })

_includes/api/en/5x/res-cookie.md

@@ -4,17 +4,19 @@ Sets cookie `name` to `value`.  The `value` parameter may be a string or object
 
 The `options` parameter is an object that can have the following properties.
 
-| Property    | Type |  Description                                                             |
-|-------------|-------------------------------------------------------------------------|
-| `domain`    | String | Domain name for the cookie. Defaults to the domain name of the app.
-| `encode`    | Function | A synchronous function used for cookie value encoding. Defaults to `encodeURIComponent`.
-| `expires`   | Date | Expiry date of the cookie in GMT. If not specified or set to 0, creates a session cookie.
-| `httpOnly`  | Boolean | Flags the cookie to be accessible only by the web server.
-| `maxAge`    | Number | Convenient option for setting the expiry time relative to the current time in milliseconds.
-| `path`      | String | Path for the cookie. Defaults to "/".
-| `secure`    | Boolean | Marks the cookie to be used with HTTPS only.
-| `signed`    | Boolean | Indicates if the cookie should be signed.
-| `sameSite`  | Boolean or String | Value of the "SameSite" **Set-Cookie** attribute. More information at [https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00#section-4.1.1](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00#section-4.1.1).
+| Property      | Type |  Description                                                             |
+|---------------|-------------------------------------------------------------------------|
+| `domain`      | String | Domain name for the cookie. Defaults to the domain name of the app.
+| `encode`      | Function | A synchronous function used for cookie value encoding. Defaults to `encodeURIComponent`.
+| `expires`     | Date | Expiry date of the cookie in GMT. If not specified or set to 0, creates a session cookie.
+| `httpOnly`    | Boolean | Flags the cookie to be accessible only by the web server.
+| `maxAge`      | Number | Convenient option for setting the expiry time relative to the current time in milliseconds.
+| `path`        | String | Path for the cookie. Defaults to "/".
+| `partitioned` | Boolean | Indicates that the cookie should be stored using partitioned storage. See [Cookies Having Independent Partitioned State (CHIPS)](https://developer.mozilla.org/en-US/docs/Web/Privacy/Partitioned_cookies) for more details.
+| `priority`    | String | Value of the "Priority" **Set-Cookie** attribute.
+| `secure`      | Boolean | Marks the cookie to be used with HTTPS only.
+| `signed`      | Boolean | Indicates if the cookie should be signed.
+| `sameSite`    | Boolean or String | Value of the "SameSite" **Set-Cookie** attribute. More information at [https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00#section-4.1.1](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00#section-4.1.1).
 
 <div class="doc-box doc-notice" markdown="1">
 All `res.cookie()` does is set the HTTP `Set-Cookie` header with the options provided.
@@ -28,6 +30,18 @@ res.cookie('name', 'tobi', { domain: '.example.com', path: '/admin', secure: tru
 res.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true })
 ```
 
+You can set multiple cookies in a single response by calling `res.cookie` multiple times, for example:
+
+```js
+res
+  .status(201)
+  .cookie('access_token', `Bearer ${token}`, {
+    expires: new Date(Date.now() + 8 * 3600000) // cookie will be removed after 8 hours
+  })
+  .cookie('test', 'test')
+  .redirect(301, '/admin')
+```
+
 The `encode` option allows you to choose the function used for cookie value encoding.
 Does not support asynchronous functions.
 

_includes/api/en/5x/res-download.md

@@ -6,7 +6,17 @@ The optional `options` argument is supported by Express v4.16.0 onwards.
 
 Transfers the file at `path` as an "attachment". Typically, browsers will prompt the user for download.
 By default, the `Content-Disposition` header "filename=" parameter is derived from the `path` argument, but can be overridden with the `filename` parameter.
-If `path` is relative, then it will be based on the current working directory of the process.
+If `path` is relative, then it will be based on the current working directory of the process or
+the `root` option, if provided.
+
+<div class="doc-box doc-warn" markdown="1">
+This API provides access to data on the running file system. Ensure that either (a) the way in
+which the `path` argument was constructed is secure if it contains user input or (b) set the `root`
+option to the absolute path of a directory to contain access within.
+
+When the `root` option is provided, Express will validate that the relative path provided as
+`path` will resolve within the given `root` option.
+</div>
 
 The following table provides details on the `options` parameter.
 
@@ -19,6 +29,7 @@ The optional `options` argument is supported by Express v4.16.0 onwards.
 | Property        | Description                                     | Default     | Availability |
 |-----------------|-------------------------------------------------|-------------|--------------|
 | `maxAge`        | Sets the max-age property of the `Cache-Control` header in milliseconds or a string in [ms format](https://www.npmjs.org/package/ms)| 0 | 4.16+ |
+| `root`          | Root directory for relative filenames.|  | 4.18+ |
 | `lastModified`  | Sets the `Last-Modified` header to the last modified date of the file on the OS. Set `false` to disable it.| Enabled | 4.16+ |
 | `headers`       | Object containing HTTP headers to serve with the file. The header `Content-Disposition` will be overridden by the `filename` argument.|  | 4.16+ |
 | `dotfiles`      | Option for serving dotfiles. Possible values are "allow", "deny", "ignore".| "ignore" | 4.16+ |

_includes/api/en/5x/res-locals.md

@@ -4,6 +4,14 @@ Use this property to set variables accessible in templates rendered with [res.re
 The variables set on `res.locals` are available within a single request-response cycle, and will not
 be shared between requests.
 
+<div class="doc-box doc-warn" markdown="1">
+The `locals` object is used by view engines to render a response. The object
+keys may be particularly sensitive and should not contain user-controlled
+input, as it may affect the operation of the view engine or provide a path to
+cross-site scripting. Consult the documentation for the used view engine for
+additional considerations.
+</div>
+
 In order to keep local variables for use in template rendering between requests, use
 [app.locals](#app.locals) instead.
 

_includes/api/en/5x/res-render.md

@@ -10,7 +10,13 @@ The `view` argument is a string that is the file path of the view file to render
 
 For more information, see [Using template engines with Express](/{{page.lang}}/guide/using-template-engines.html).
 
-{% include admonitions/note.html content="The `view` argument performs file system operations like reading a file from disk and evaluating Node.js modules, and as so for security reasons should not contain input from the end-user." %}
+{% include admonitions/warning.html content="The `view` argument performs file system operations like reading a file from disk and evaluating Node.js modules, and as so for security reasons should not contain input from the end-user." %}
+
+{% include admonitions/warning.html content="The `locals` object is used by view engines to render a response. The object
+keys may be particularly sensitive and should not contain user-controlled
+input, as it may affect the operation of the view engine or provide a path to
+cross-site scripting. Consult the documentation for the used view engine for
+additional considerations." %}
 
 {% include admonitions/caution.html content="The local variable `cache` enables view caching. Set it to `true`,
 to cache the view during development; view caching is enabled in production by default." %}