Initial cleanup of 5.x alpha doc

_includes/announcement/announcement-en.md

@@ -1,8 +1,8 @@
 <ul>
   <li>
-    <p class="announcement-title">Express 4.16.0 contains important security updates.</p>
+    <p class="announcement-title">Express 5.0 alpha documentation is now available.</p>
     <p markdown="1">
-     For more information on what was added in this release, see the [4.16.0 changelog](/{{ page.lang }}/changelog/4x.html#4.16.0).
+     The alpha <a href="{{ page.lang }}/5x/api.html">API documentation</a> is a work in progress.  For information on what's in the release, see the Express <a href="https://github.com/expressjs/express/blob/5.0/History.md">release history</a>.
     </p>
   </li>
 </ul>

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

@@ -4,7 +4,7 @@ Routes an HTTP request, where METHOD is the HTTP method of the request, such as
 PUT, POST, and so on, in lowercase. Thus, the actual methods are `app.get()`,
 `app.post()`, `app.put()`, and so on.  See [Routing methods](#routing-methods) below for the complete list.
 
-{% include api/en/4x/routing-args.html %}
+{% include api/en/5x/routing-args.html %}
 
 #### Routing methods
 

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

@@ -3,7 +3,7 @@
 This method is like the standard [app.METHOD()](#app.METHOD) methods,
 except it matches all HTTP verbs.
 
-{% include api/en/4x/routing-args.html %}
+{% include api/en/5x/routing-args.html %}
 
 #### Examples
 

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

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

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

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

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

@@ -10,7 +10,7 @@ Sub-apps will:
 * Not inherit the value of settings that have a default value.  You must set the value in the sub-app.
 * Inherit the value of settings with no default value.
 
-For details, see [Application settings](/en/4x/api.html#app.settings.table).
+For details, see [Application settings](/en/5x/api.html#app.settings.table).
 </div>
 
 ```js

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

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

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

@@ -2,7 +2,7 @@
 
 Routes HTTP PUT requests to the specified path with the specified callback functions.
 
-{% include api/en/4x/routing-args.html %}
+{% include api/en/5x/routing-args.html %}
 
 #### Example
 

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

@@ -17,4 +17,4 @@ app.get('title') // "My Site"
 
 <h4 id='app.settings.table'>Application Settings</h4>
 
-{% include api/en/4x/app-settings.md %}
+{% include api/en/5x/app-settings.md %}

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

@@ -4,7 +4,7 @@ Mounts the specified [middleware](/guide/using-middleware.html) function or func
 at the specified path:
 the middleware function is executed when the base of the requested path matches `path`.
 
-{% include api/en/4x/routing-args.html %}
+{% include api/en/5x/routing-args.html %}
 
 #### Description
 
@@ -30,7 +30,7 @@ Sub-apps will:
 * Not inherit the value of settings that have a default value.  You must set the value in the sub-app.
 * Inherit the value of settings with no default value.
 
-For details, see [Application settings](/en/4x/api.html#app.settings.table).
+For details, see [Application settings](/en/5x/api.html#app.settings.table).
 </div>
 
 Middleware functions are executed sequentially, therefore the order of middleware inclusion is important.

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

@@ -31,93 +31,93 @@ The Express application object can be referred from the [request object](#req) a
 <h3 id='app.properties'>Properties</h3>
 
 <section markdown="1">
-  {% include api/en/4x/app-locals.md %}
+  {% include api/en/5x/app-locals.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-mountpath.md %}
+  {% include api/en/5x/app-mountpath.md %}
 </section>
 
 <h3 id='app.events'>Events</h3>
 
 <section markdown="1">
-  {% include api/en/4x/app-onmount.md %}
+  {% include api/en/5x/app-onmount.md %}
 </section>
 
 <h3 id='app.methods'>Methods</h3>
 
 <section markdown="1">
-  {% include api/en/4x/app-all.md %}
+  {% include api/en/5x/app-all.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-delete-method.md %}
+  {% include api/en/5x/app-delete-method.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-disable.md %}
+  {% include api/en/5x/app-disable.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-disabled.md %}
+  {% include api/en/5x/app-disabled.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-enable.md %}
+  {% include api/en/5x/app-enable.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-enabled.md %}
+  {% include api/en/5x/app-enabled.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-engine.md %}
+  {% include api/en/5x/app-engine.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-get.md %}
+  {% include api/en/5x/app-get.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-get-method.md %}
+  {% include api/en/5x/app-get-method.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-listen.md %}
+  {% include api/en/5x/app-listen.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-METHOD.md %}
+  {% include api/en/5x/app-METHOD.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-param.md %}
+  {% include api/en/5x/app-param.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-path.md %}
+  {% include api/en/5x/app-path.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-post-method.md %}
+  {% include api/en/5x/app-post-method.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-put-method.md %}
+  {% include api/en/5x/app-put-method.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-render.md %}
+  {% include api/en/5x/app-render.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-route.md %}
+  {% include api/en/5x/app-route.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-set.md %}
+  {% include api/en/5x/app-set.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/app-use.md %}
+  {% include api/en/5x/app-use.md %}
 </section>

_includes/api/en/5x/express.json.md

@@ -1,9 +1,5 @@
 <h3 id='express.json' class='h2'>express.json([options])</h3>
 
-<div class="doc-box doc-info" markdown="1">
-This middleware is available in Express v4.16.0 onwards.
-</div>
-
 This is a built-in middleware function in Express. It parses incoming requests
 with JSON payloads and is based on
 [body-parser](/{{ page.lang }}/resources/middleware/body-parser.html).

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

@@ -10,17 +10,17 @@ var app = express()
 <h3 id='express.methods'>Methods</h3>
 
 <section markdown="1">
-  {% include api/en/4x/express.json.md %}
+  {% include api/en/5x/express.json.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/express.static.md %}
+  {% include api/en/5x/express.static.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/express.router.md %}
+  {% include api/en/5x/express.router.md %}
 </section>
 
 <section markdown="1">
-  {% include api/en/4x/express.urlencoded.md %}
+  {% include api/en/5x/express.urlencoded.md %}
 </section>

_includes/api/en/5x/express.raw.md

@@ -0,0 +1,32 @@
+<h3 id='express.raw' class='h2'>express.raw([options])</h3>
+
+This is a built-in middleware function in Express. It parses incoming request
+payloads into a `Buffer` and is based on
+[body-parser](/{{ page.lang }}/resources/middleware/body-parser.html).
+
+Returns middleware that parses all bodies as a `Buffer` and only looks at requests
+where the `Content-Type` header matches the `type` option. This parser accepts
+any Unicode encoding of the body and supports automatic inflation of `gzip` and
+`deflate` encodings.
+
+A new `body` `Buffer` containing the parsed data is populated on the `request`
+object after the middleware (i.e. `req.body`), or an empty object (`{}`) if
+there was no body to parse, the `Content-Type` was not matched, or an error
+occurred.
+
+<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.toString()` may fail in multiple ways, for example
+stacking multiple parsers `req.body` may be from a different parser. Testing
+that `req.body` is a `Buffer` before calling buffer methods is recommended.
+</div>
+
+The following table describes the properties of the optional `options` object.
+
+| Property  | Description                                                           |   Type      | Default         |
+|-----------|-----------------------------------------------------------------------|-------------|-----------------|
+| `inflate` | Enables or disables handling deflated (compressed) bodies; when disabled, deflated bodies are rejected. | Boolean | `true` |
+| `limit`   | Controls the maximum request body size. If this is a number, then the value specifies the number of bytes; if it is a string, the value is passed to the [bytes](https://www.npmjs.com/package/bytes) library for parsing. | Mixed | `"100kb"` |
+| `type`    | This is used to determine what media type the middleware will parse. This option can be a string, array of strings, or a function. If not a function, `type` option is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme) library and this can be an extension name (like `bin`), a mime type (like `application/octet-stream`), or a mime type with a wildcard (like `*/*` or `application/*`). If a function, the `type` option is called as `fn(req)` and the request is parsed if it returns a truthy value. | Mixed | `"application/octet-stream"` |
+| `verify`  | This option, if supplied, is called as `verify(req, res, buf, encoding)`, where `buf` is a `Buffer` of the raw request body and `encoding` is the encoding of the request. The parsing can be aborted by throwing an error. | Function | `undefined` |

_includes/api/en/5x/express.text.md

@@ -0,0 +1,33 @@
+<h3 id='express.text' class='h2'>express.text([options])</h3>
+
+This is a built-in middleware function in Express. It parses incoming request
+payloads into a string and is based on
+[body-parser](/{{ page.lang }}/resources/middleware/body-parser.html).
+
+Returns middleware that parses all bodies as a string and only looks at requests
+where the `Content-Type` header matches the `type` option. This parser accepts
+any Unicode encoding of the body and supports automatic inflation of `gzip` and
+`deflate` encodings.
+
+A new `body` string containing the parsed data is populated on the `request`
+object after the middleware (i.e. `req.body`), or an empty object (`{}`) if
+there was no body to parse, the `Content-Type` was not matched, or an error
+occurred.
+
+<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.trim()` may fail in multiple ways, for example
+stacking multiple parsers `req.body` may be from a different parser. Testing
+that `req.body` is a string before calling string methods is recommended.
+</div>
+
+The following table describes the properties of the optional `options` object.
+
+| Property         | Description                                                           |   Type      | Default         |
+|------------------|-----------------------------------------------------------------------|-------------|-----------------|
+| `defaultCharset` | Specify the default character set for the text content if the charset is not specified in the `Content-Type` header of the request. | String | `"utf-8"` |
+| `inflate`        | Enables or disables handling deflated (compressed) bodies; when disabled, deflated bodies are rejected. | Boolean | `true` |
+| `limit`          | Controls the maximum request body size. If this is a number, then the value specifies the number of bytes; if it is a string, the value is passed to the [bytes](https://www.npmjs.com/package/bytes) library for parsing. | Mixed | `"100kb"` |
+| `type`           | This is used to determine what media type the middleware will parse. This option can be a string, array of strings, or a function. If not a function, `type` option is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme) library and this can be an extension name (like `txt`), a mime type (like `text/plain`), or a mime type with a wildcard (like `*/*` or `text/*`). If a function, the `type` option is called as `fn(req)` and the request is parsed if it returns a truthy value. | Mixed | `"text/plain"` |
+| `verify`         | This option, if supplied, is called as `verify(req, res, buf, encoding)`, where `buf` is a `Buffer` of the raw request body and `encoding` is the encoding of the request. The parsing can be aborted by throwing an error. | Function | `undefined` |

_includes/api/en/5x/express.urlencoded.md

@@ -1,9 +1,5 @@
 <h3 id='express.urlencoded' class='h2'>express.urlencoded([options])</h3>
 
-<div class="doc-box doc-info" markdown="1">
-This middleware is available in Express v4.16.0 onwards.
-</div>
-
 This is a built-in middleware function in Express. It parses incoming requests
 with urlencoded payloads and is based on [body-parser](/{{ page.lang }}/resources/middleware/body-parser.html).
 

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

@@ -2,12 +2,22 @@
 
 Contains the hostname derived from the `Host` HTTP header.
 
-When the [`trust proxy` setting](/4x/api.html#trust.proxy.options.table) does not evaluate to `false`,
-this property will instead have the value of the `X-Forwarded-Host` header field.
-This header can be set by the client or by the proxy.
+When the [`trust proxy` setting](/5x/api.html#trust.proxy.options.table)
+does not evaluate to `false`, this property will instead get the value
+from the `X-Forwarded-Host` header field. This header can be set by
+the client or by the proxy.
+
+If there is more than one `X-Forwarded-Host` header in the request, the
+value of the first header is used. This includes a single header with
+comma-separated values, in which the first value is used.
+
+<div class="doc-box doc-info" markdown="1">
+Prior to Express v4.17.0, the `X-Forwarded-Host` could not contain multiple
+values or be present more than once.
+</div>
 
 ```js
 // Host: "example.com:3000"
 console.dir(req.hostname)
-// => "example.com"
+// => 'example.com'
 ```

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

@@ -2,7 +2,7 @@
 
 Contains the remote IP address of the request.
 
-When the [`trust proxy` setting](/4x/api.html#trust.proxy.options.table) does not evaluate to `false`,
+When the [`trust proxy` setting](/5x/api.html#trust.proxy.options.table) does not evaluate to `false`,
 the value of this property is derived from the left-most entry in the
 `X-Forwarded-For` header. This header can be set by the client or by the proxy.
 

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

@@ -1,6 +1,6 @@
 <h3 id='req.ips'>req.ips</h3>
 
-When the [`trust proxy` setting](/4x/api.html#trust.proxy.options.table) does not evaluate to `false`,
+When the [`trust proxy` setting](/5x/api.html#trust.proxy.options.table) does not evaluate to `false`,
 this property contains an array of IP addresses
 specified in the `X-Forwarded-For` request header. Otherwise, it contains an
 empty array. This header can be set by the client or by the proxy.

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

@@ -16,7 +16,7 @@ console.dir(req.params[0])
 // => "javascripts/jquery.js"
 ```
 
-If you need to make changes to a key in `req.params`, use the [app.param](/{{ page.lang }}/4x/api.html#app.param) handler. Changes are applicable only to [parameters](/{{ page.lang }}/guide/routing.html#route-parameters) already defined in the route path.
+If you need to make changes to a key in `req.params`, use the [app.param](/{{ page.lang }}/5x/api.html#app.param) handler. Changes are applicable only to [parameters](/{{ page.lang }}/guide/routing.html#route-parameters) already defined in the route path.
 
 Any changes made to the `req.params` object in a middleware or route handler will be reset.
 

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

@@ -9,5 +9,5 @@ console.dir(req.path)
 ```
 
 <div class="doc-box doc-info" markdown="1">
-When called from a middleware, the mount point is not included in `req.path`. See [app.use()](/4x/api.html#app.use) for more details.
+When called from a middleware, the mount point is not included in `req.path`. See [app.use()](/5x/api.html#app.use) for more details.
 </div>

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

@@ -10,4 +10,4 @@ console.dir(req.subdomains)
 
 The application property `subdomain offset`, which defaults to 2, is used for determining the
 beginning of the subdomain segments. To change this behavior, change its value
-using [app.set](/{{ page.lang }}/4x/api.html#app.set).
+using [app.set](/{{ page.lang }}/5x/api.html#app.set).