Merge branch 'gh-pages' into update-socket-io

.github/workflows/ci.yml

@@ -7,10 +7,16 @@ on:
   push:
     branches:
     - gh-pages
+  pull_request_review:
+      types: [submitted]
 
 jobs:
   test:
     runs-on: ubuntu-latest
+    if: |
+      github.event.pull_request.draft != true &&
+      (github.event_name == 'pull_request_review' && github.event.review.state == 'approved') ||
+      github.event_name != 'pull_request_review'
     strategy:
       matrix:
         node-version:

_data/express.yml

@@ -1 +1 @@
-current_version: "4.18.0"
+current_version: "4.18.1"

_includes/api/en/3x/menu.md

@@ -94,6 +94,8 @@
             </li>
             <li><a href="#req.acceptsLanguage">req.acceptsLanguage()</a>
             </li>
+            <li><a href="#req.res">req.res</a>
+            </li>
         </ul>
     </li>
     <li id="res-api"> <a href="#response">Response</a>

_includes/api/en/4x/app-METHOD.md

@@ -59,4 +59,4 @@ The method, `app.all()`, is not derived from any HTTP method and loads middlewar
 the specified path for _all_ HTTP request methods.
 For more information, see [app.all](#app.all).
 
-For more information on routing, see the [routing guide](/guide/routing.html).
+For more information on routing, see the [routing guide](/{{page.lang}}/guide/routing.html).

_includes/api/en/4x/app-delete-method.md

@@ -1,7 +1,7 @@
 <h3 id='app.delete.method'>app.delete(path, callback [, callback ...])</h3>
 
 Routes HTTP DELETE requests to the specified path with the specified callback functions.
-For more information, see the [routing guide](/guide/routing.html).
+For more information, see the [routing guide](/{{page.lang}}/guide/routing.html).
 
 {% include api/en/4x/routing-args.html %}
 

_includes/api/en/4x/app-get-method.md

@@ -4,7 +4,7 @@ Routes HTTP GET requests to the specified path with the specified callback funct
 
 {% include api/en/4x/routing-args.html %}
 
-For more information, see the [routing guide](/guide/routing.html).
+For more information, see the [routing guide](/{{page.lang}}/guide/routing.html).
 
 #### Example
 

_includes/api/en/4x/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/4x/app-post-method.md

@@ -1,7 +1,7 @@
 <h3 id='app.post.method'>app.post(path, callback [, callback ...])</h3>
 
 Routes HTTP POST requests to the specified path with the specified callback functions.
-For more information, see the [routing guide](/guide/routing.html).
+For more information, see the [routing guide](/{{page.lang}}/guide/routing.html).
 
 {% include api/en/4x/routing-args.html %}
 

_includes/api/en/4x/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/4x/app-settings.md

@@ -198,7 +198,7 @@ A custom query string parsing function will receive the complete query string, a
   <h5 id="trust.proxy.options.table">Options for `trust proxy` setting</h5>
 
   <p markdown="1">
-  Read [Express behind proxies](/guide/behind-proxies.html) for more
+  Read [Express behind proxies](/{{page.lang}}/guide/behind-proxies.html) for more
   information.
   </p>
 

_includes/api/en/4x/app-use.md

@@ -1,6 +1,6 @@
 <h3 id='app.use'>app.use([path,] callback [, callback...])</h3>
 
-Mounts the specified [middleware](/guide/using-middleware.html) function or functions
+Mounts the specified [middleware](/{{page.lang}}/guide/using-middleware.html) function or functions
 at the specified path:
 the middleware function is executed when the base of the requested path matches `path`.
 
@@ -284,7 +284,7 @@ app.use(mw1, [mw2, r1, r2], subApp)
 
 </table>
 
-Following are some examples of using the [express.static](/guide/using-middleware.html#middleware.built-in)
+Following are some examples of using the [express.static](/{{page.lang}}/guide/using-middleware.html#middleware.built-in)
 middleware in an Express app.
 
 Serve static content for the app from the "public" directory in the application directory:

_includes/api/en/4x/menu.md

@@ -98,6 +98,8 @@
             </li>
             <li><a href="#req.query">req.query</a>
             </li>
+            <li><a href="#req.res">req.res</a>
+            </li>
             <li><a href="#req.route">req.route</a>
             </li>
             <li><a href="#req.secure">req.secure</a>

_includes/api/en/4x/req-query.md

@@ -6,3 +6,14 @@ When [query parser](#app.settings.table) is set to disabled, it is an empty obje
 <div class="doc-box doc-warn" markdown="1">
 As `req.query`'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.query.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.
 </div>
+
+The value of this property can be configured with the [query parser application setting](#app.settings.table) to work how your application needs it. A very popular query string parser is the [`qs` module](https://www.npmjs.org/package/qs), and this is used by default. The `qs` module is very configurable with many settings, and it may be desirable to use different settings than the default to populate `req.query`:
+
+```js
+var qs = require('qs')
+app.setting('query parser', function (str) {
+  return qs.parse(str, { /* custom options */ })
+})
+```
+
+Check out the [query parser application setting](#app.settings.table) documentation for other customization options.

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

@@ -1,7 +1,7 @@
 <h3 id='res.download'>res.download(path [, filename] [, options] [, fn])</h3>
 
 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 derrived from the `path` argument, but can be overridden with the `filename` parameter.
+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 or
 the `root` option, if provided.
 
@@ -27,7 +27,7 @@ The optional `options` argument is supported by Express v4.16.0 onwards.
 | `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 overriden by the `filename` argument.|  | 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+ |
 | `acceptRanges`  | Enable or disable accepting ranged requests. | `true` | 4.16+ |
 | `cacheControl`  | Enable or disable setting `Cache-Control` response header.| `true` | 4.16+ |

_includes/api/en/4x/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/4x/res-render.md

@@ -8,9 +8,21 @@ Optional parameters:
 
 The `view` argument is a string that is the file path of the view file to render. This can be an absolute path, or a path relative to the `views` setting. If the path does not contain a file extension, then the `view engine` setting determines the file extension. If the path does contain a file extension, then Express will load the module for the specified template engine (via `require()`) and render it using the loaded module's `__express` function.
 
-For more information, see [Using template engines with Express](/guide/using-template-engines.html).
+For more information, see [Using template engines with Express](/{{page.lang}}/guide/using-template-engines.html).
 
-**NOTE:** 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 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` enables view caching. Set it to `true`,

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

@@ -59,4 +59,4 @@ The method, `app.all()`, is not derived from any HTTP method and loads middlewar
 the specified path for _all_ HTTP request methods.
 For more information, see [app.all](#app.all).
 
-For more information on routing, see the [routing guide](/guide/routing.html).
+For more information on routing, see the [routing guide](/{{page.lang}}/guide/routing.html).

_includes/api/en/5x/app-delete-method.md

@@ -1,7 +1,7 @@
 <h3 id='app.delete.method'>app.delete(path, callback [, callback ...])</h3>
 
 Routes HTTP DELETE requests to the specified path with the specified callback functions.
-For more information, see the [routing guide](/guide/routing.html).
+For more information, see the [routing guide](/{{page.lang}}/guide/routing.html).
 
 {% include api/en/5x/routing-args.html %}
 

_includes/api/en/5x/app-get-method.md

@@ -4,7 +4,7 @@ Routes HTTP GET requests to the specified path with the specified callback funct
 
 {% include api/en/5x/routing-args.html %}
 
-For more information, see the [routing guide](/guide/routing.html).
+For more information, see the [routing guide](/{{page.lang}}/guide/routing.html).
 
 #### Example
 

_includes/api/en/5x/app-post-method.md

@@ -1,7 +1,7 @@
 <h3 id='app.post.method'>app.post(path, callback [, callback ...])</h3>
 
 Routes HTTP POST requests to the specified path with the specified callback functions.
-For more information, see the [routing guide](/guide/routing.html).
+For more information, see the [routing guide](/{{page.lang}}/guide/routing.html).
 
 {% include api/en/5x/routing-args.html %}
 

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

@@ -198,7 +198,7 @@ A custom query string parsing function will receive the complete query string, a
   <h5 id="trust.proxy.options.table">Options for `trust proxy` setting</h5>
 
   <p markdown="1">
-  Read [Express behind proxies](/guide/behind-proxies.html) for more
+  Read [Express behind proxies]/{{page.lang}}/behind-proxies.html) for more
   information.
   </p>
 

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

@@ -1,6 +1,6 @@
 <h3 id='app.use'>app.use([path,] callback [, callback...])</h3>
 
-Mounts the specified [middleware](/guide/using-middleware.html) function or functions
+Mounts the specified [middleware](/{{page.lang}}/guide/using-middleware.html) function or functions
 at the specified path:
 the middleware function is executed when the base of the requested path matches `path`.
 
@@ -259,7 +259,7 @@ app.use(mw1, [mw2, r1, r2], subApp)
 
 </table>
 
-Following are some examples of using the [express.static](/guide/using-middleware.html#middleware.built-in)
+Following are some examples of using the [express.static](/{{page.lang}}/guide/using-middleware.html#middleware.built-in)
 middleware in an Express app.
 
 Serve static content for the app from the "public" directory in the application directory:

_includes/api/en/5x/menu.md

@@ -100,6 +100,8 @@
             </li>
             <li><a href="#req.query">req.query</a>
             </li>
+            <li><a href="#req.res">req.res</a>
+            </li>
             <li><a href="#req.route">req.route</a>
             </li>
             <li><a href="#req.secure">req.secure</a>
@@ -126,8 +128,6 @@
             </li>
             <li><a href="#req.is">req.is()</a>
             </li>
-            <li><a href="#req.param">req.param()</a>
-            </li>
             <li><a href="#req.range">req.range()</a>
             </li>
         </ul>

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

@@ -6,3 +6,13 @@ When [query parser](#app.settings.table) is set to disabled, it is an empty obje
 <div class="doc-box doc-warn" markdown="1">
 As `req.query`'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.query.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.
 </div>
+
+The value of this property can be configured with the [query parser application setting](#app.settings.table) to work how your application needs it. A very popular query string parser is the [`qs` module](https://www.npmjs.org/package/qs), and this is used by default. The `qs` module is very configurable with many settings, and it may be desirable to use different settings than the default to populate `req.query`:
+
+```js
+const qs = require('qs')
+app.setting('query parser',
+  (str) => qs.parse(str, { /* custom options */ }))
+```
+
+Check out the [query parser application setting](#app.settings.table) documentation for other customization options.

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

@@ -5,7 +5,7 @@ The optional `options` argument is supported by Express v4.16.0 onwards.
 </div>
 
 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 derrived from the `path` argument, but can be overridden with the `filename` parameter.
+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.
 
 The following table provides details on the `options` parameter.
@@ -20,7 +20,7 @@ The optional `options` argument is supported by Express v4.16.0 onwards.
 |-----------------|-------------------------------------------------|-------------|--------------|
 | `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+ |
 | `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 overriden by the `filename` argument.|  | 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+ |
 | `acceptRanges`  | Enable or disable accepting ranged requests. | `true` | 4.16+ |
 | `cacheControl`  | Enable or disable setting `Cache-Control` response header.| `true` | 4.16+ |

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

@@ -8,7 +8,7 @@ Optional parameters:
 
 The `view` argument is a string that is the file path of the view file to render. This can be an absolute path, or a path relative to the `views` setting. If the path does not contain a file extension, then the `view engine` setting determines the file extension. If the path does contain a file extension, then Express will load the module for the specified template engine (via `require()`) and render it using the loaded module's `__express` function.
 
-For more information, see [Using template engines with Express](/guide/using-template-engines.html).
+For more information, see [Using template engines with Express](/{{page.lang}}/guide/using-template-engines.html).
 
 **NOTE:** 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.
 

_includes/mw-list.md

@@ -4,7 +4,6 @@
 - [cookie-parser](/resources/middleware/cookie-parser.html)
 - [cookie-session](/resources/middleware/cookie-session.html)
 - [cors](/resources/middleware/cors.html)
-- [csurf](/resources/middleware/csurf.html)
 - [errorhandler](/resources/middleware/errorhandler.html)
 - [method-override](/resources/middleware/method-override.html)
 - [morgan](/resources/middleware/morgan.html)

_includes/readmes/body-parser.md

@@ -1,8 +1,8 @@
 # body-parser
 
-[![NPM Version][npm-image]][npm-url]
-[![NPM Downloads][downloads-image]][downloads-url]
-[![Build Status][github-actions-ci-image]][github-actions-ci-url]
+[![NPM Version][npm-version-image]][npm-url]
+[![NPM Downloads][npm-downloads-image]][npm-url]
+[![Build Status][ci-image]][ci-url]
 [![Test Coverage][coveralls-image]][coveralls-url]
 
 Node.js body parsing middleware.
@@ -346,7 +346,7 @@ call `req.setEncoding` when using this module. The `status` property is set to
 
 This error will occur when the request is no longer readable when this middleware
 attempts to read it. This typically means something other than a middleware from
-this module read the reqest body already and the middleware was also configured to
+this module read the request body already and the middleware was also configured to
 read the same request. The `status` property is set to `500` and the `type`
 property is set to `'stream.not.readable'`.
 
@@ -454,11 +454,12 @@ app.use(bodyParser.text({ type: 'text/html' }))
 
 [MIT](LICENSE)
 
-[npm-image]: https://img.shields.io/npm/v/body-parser.svg
-[npm-url]: https://npmjs.org/package/body-parser
-[coveralls-image]: https://img.shields.io/coveralls/expressjs/body-parser/master.svg
+[ci-image]: https://badgen.net/github/checks/expressjs/body-parser/master?label=ci
+[ci-url]: https://github.com/expressjs/body-parser/actions/workflows/ci.yml
+[coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/body-parser/master
 [coveralls-url]: https://coveralls.io/r/expressjs/body-parser?branch=master
-[downloads-image]: https://img.shields.io/npm/dm/body-parser.svg
-[downloads-url]: https://npmjs.org/package/body-parser
-[github-actions-ci-image]: https://img.shields.io/github/workflow/status/expressjs/body-parser/ci/master?label=ci
-[github-actions-ci-url]: https://github.com/expressjs/body-parser/actions/workflows/ci.yml
+[node-version-image]: https://badgen.net/npm/node/body-parser
+[node-version-url]: https://nodejs.org/en/download
+[npm-downloads-image]: https://badgen.net/npm/dm/body-parser
+[npm-url]: https://npmjs.org/package/body-parser
+[npm-version-image]: https://badgen.net/npm/v/body-parser