Update middleware readmes

_includes/readmes/cookie-parser.md

@@ -18,24 +18,41 @@ $ npm install cookie-parser
 
 ## API
 
+<!-- eslint-disable no-unused-vars -->
+
 ```js
-var express = require('express')
 var cookieParser = require('cookie-parser')
-
-var app = express()
-app.use(cookieParser())
 ```
 
 ### cookieParser(secret, options)
 
+Create a new cookie parser middleware function using the given `secret` and
+`options`.
+
 - `secret` a string or array used for signing cookies. This is optional and if
   not specified, will not parse signed cookies. If a string is provided, this
   is used as the secret. If an array is provided, an attempt will be made to
   unsign the cookie with each secret in order.
-- `options` an object that is passed to `cookie.parse` as the second option. Se
+- `options` an object that is passed to `cookie.parse` as the second option. See
   [cookie](https://www.npmjs.org/package/cookie) for more information.
   - `decode` a function to decode the value of the cookie
 
+The middleware will parse the `Cookie` header on the request and expose the
+cookie data as the property `req.cookies` and, if a `secret` was provided, as
+the property `req.signedCookies`. These properties are name value pairs of the
+cookie name to cookie value.
+
+When `secret` is provided, this module will unsign and validate any signed cookie
+values and move those name value pairs from `req.cookies` into `req.signedCookies`.
+A signed cookie is a cookie that has a value prefixed with `s:`. Signed cookies
+that fail signature validation will have the value `false` instead of the tampered
+value.
+
+In addition, this module supports special "JSON cookies". These are cookie where
+the value is prefixed with `j:`. When these values are encountered, the value will
+be exposed as the result of `JSON.parse`. If parsing fails, the original value will
+remain.
+
 ### cookieParser.JSONCookie(str)
 
 Parse a cookie value as a JSON cookie. This will return the parsed JSON value
@@ -91,7 +108,9 @@ app.listen(8080)
 // curl http://127.0.0.1:8080 --cookie "Cho=Kim;Greet=Hello"
 ```
 
-### [MIT Licensed](LICENSE)
+## License
+
+[MIT](LICENSE)
 
 [coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/cookie-parser/master
 [coveralls-url]: https://coveralls.io/r/expressjs/cookie-parser?branch=master

_includes/readmes/cors.md

@@ -91,19 +91,31 @@ app.listen(80, function () {
 
 ### Configuring CORS w/ Dynamic Origin
 
+This module supports validating the origin dynamically using a function provided
+to the `origin` option. This function will be passed a string that is the origin
+(or `undefined` if the request has no origin), and a `callback` with the signature
+`callback(error, origin)`.
+
+The `origin` argument to the callback can be any value allowed for the `origin`
+option of the middleware, except a function. See the
+[confugration options](#configuration-options) section for more information on all
+the possible value types.
+
+This function is designed to allow the dynamic loading of allowed origin(s) from
+a backing datasource, like a database.
+
 ```javascript
 var express = require('express')
 var cors = require('cors')
 var app = express()
 
-var whitelist = ['http://example1.com', 'http://example2.com']
 var corsOptions = {
   origin: function (origin, callback) {
-    if (whitelist.indexOf(origin) !== -1) {
-      callback(null, true)
-    } else {
-      callback(new Error('Not allowed by CORS'))
-    }
+    // db.loadOrigins is an example call to load
+    // a list of origins from a backing database
+    db.loadOrigins(function (error, origins) {
+      callback(error, origins)
+    })
   }
 }
 
@@ -116,21 +128,6 @@ app.listen(80, function () {
 })
 ```
 
-If you do not want to block REST tools or server-to-server requests,
-add a `!origin` check in the origin function like so:
-
-```javascript
-var corsOptions = {
-  origin: function (origin, callback) {
-    if (whitelist.indexOf(origin) !== -1 || !origin) {
-      callback(null, true)
-    } else {
-      callback(new Error('Not allowed by CORS'))
-    }
-  }
-}
-```
-
 ### Enabling CORS Pre-Flight
 
 Certain CORS requests are considered 'complex' and require an initial
@@ -161,6 +158,10 @@ You can also enable pre-flight across-the-board like so:
 app.options('*', cors()) // include before other routes
 ```
 
+NOTE: When using this middleware as an application level middleware (for
+example, `app.use(cors())`), pre-flight requests are already handled for all
+routes.
+
 ### Configuring CORS Asynchronously
 
 ```javascript
@@ -195,7 +196,7 @@ app.listen(80, function () {
   - `String` - set `origin` to a specific origin. For example if you set it to `"http://example.com"` only requests from "http://example.com" will be allowed.
   - `RegExp` - set `origin` to a regular expression pattern which will be used to test the request origin. If it's a match, the request origin will be reflected. For example the pattern `/example\.com$/` will reflect any request that is coming from an origin ending with "example.com".
   - `Array` - set `origin` to an array of valid origins. Each origin can be a `String` or a `RegExp`. For example `["http://example1.com", /\.example2\.com$/]` will accept any request from "http://example1.com" or from a subdomain of "example2.com".
-  - `Function` - set `origin` to a function implementing some custom logic. The function takes the request origin as the first parameter and a callback (which expects the signature `err [object], allow [bool]`) as the second.
+  - `Function` - set `origin` to a function implementing some custom logic. The function takes the request origin as the first parameter and a callback (called as `callback(err, origin)`, where `origin` is a non-function value of the `origin` option) as the second.
 * `methods`: Configures the **Access-Control-Allow-Methods** CORS header. Expects a comma-delimited string (ex: 'GET,PUT,POST') or an array (ex: `['GET', 'PUT', 'POST']`).
 * `allowedHeaders`: Configures the **Access-Control-Allow-Headers** CORS header. Expects a comma-delimited string (ex: 'Content-Type,Authorization') or an array (ex: `['Content-Type', 'Authorization']`). If not specified, defaults to reflecting the headers specified in the request's **Access-Control-Request-Headers** header.
 * `exposedHeaders`: Configures the **Access-Control-Expose-Headers** CORS header. Expects a comma-delimited string (ex: 'Content-Range,X-Content-Range') or an array (ex: `['Content-Range', 'X-Content-Range']`). If not specified, no custom headers are exposed.

_includes/readmes/morgan.md

@@ -9,6 +9,16 @@ HTTP request logger middleware for node.js
 
 > Named after [Dexter](http://en.wikipedia.org/wiki/Dexter_Morgan), a show you should not watch until completion.
 
+## Installation
+
+This is a [Node.js](https://nodejs.org/en/) module available through the
+[npm registry](https://www.npmjs.com/). Installation is done using the
+[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
+
+```sh
+$ npm install morgan
+```
+
 ## API
 
 <!-- eslint-disable no-unused-vars -->
@@ -248,7 +258,7 @@ advanced uses, this compile function is directly available.
 
 ### express/connect
 
-Simple app that will log all request in the Apache combined format to STDOUT
+Sample app that will log all request in the Apache combined format to STDOUT
 
 ```js
 var express = require('express')
@@ -265,7 +275,7 @@ app.get('/', function (req, res) {
 
 ### vanilla http server
 
-Simple app that will log all request in the Apache combined format to STDOUT
+Sample app that will log all request in the Apache combined format to STDOUT
 
 ```js
 var finalhandler = require('finalhandler')
@@ -291,7 +301,7 @@ http.createServer(function (req, res) {
 
 #### single file
 
-Simple app that will log all requests in the Apache combined format to the file
+Sample app that will log all requests in the Apache combined format to the file
 `access.log`.
 
 ```js
@@ -315,7 +325,7 @@ app.get('/', function (req, res) {
 
 #### log file rotation
 
-Simple app that will log all requests in the Apache combined format to one log
+Sample app that will log all requests in the Apache combined format to one log
 file per day in the `log/` directory using the
 [rotating-file-stream module](https://www.npmjs.com/package/rotating-file-stream).
 

_includes/readmes/multer.md

@@ -12,6 +12,7 @@ This README is also available in other languages:
 - [简体中文](https://github.com/expressjs/multer/blob/master/doc/README-zh-cn.md) (Chinese)
 - [한국어](https://github.com/expressjs/multer/blob/master/doc/README-ko.md) (Korean)
 - [Русский язык](https://github.com/expressjs/multer/blob/master/doc/README-ru.md) (Russian)
+- [Português](https://github.com/expressjs/multer/blob/master/doc/README-pt-br.md) (Português Brazil)
 
 ## Installation
 
@@ -75,6 +76,32 @@ app.post('/profile', upload.none(), function (req, res, next) {
 })
 ```
 
+Here's an example on how multer is used an HTML form. Take special note of the `enctype="multipart/form-data"` and `name="uploaded_file"` fields:
+
+```html
+<form action="/stats" enctype="multipart/form-data" method="post">
+  <div class="form-group">
+    <input type="file" class="form-control-file" name="uploaded_file">
+    <input type="text" class="form-control" placeholder="Number of speakers" name="nspeakers">
+    <input type="submit" value="Get me the stats!" class="btn btn-default">            
+  </div>
+</form>
+```
+
+Then in your javascript file you would add these lines to access both the file and the body. It is important that you use the `name` field value from the form in your upload function. This tells multer which field on the request it should look for the files in. If these fields aren't the same in the HTML form and on your server, your upload will fail:
+
+```javascript
+var multer  = require('multer')
+var upload = multer({ dest: './public/data/uploads/' })
+app.post('/stats', upload.single('uploaded_file'), function (req, res) {
+   // req.file is the name of your file in the form above, here 'uploaded_file'
+   // req.body will hold the text fields, if there were any 
+   console.log(req.file, req.body)
+});
+```
+
+
+
 ## API
 
 ### File information

_includes/readmes/session.md

@@ -829,6 +829,24 @@ app.get('/bar', function (req, res, next) {
 })
 ```
 
+## Debugging
+
+This module uses the [debug](https://www.npmjs.com/package/debug) module
+internally to log information about session operations.
+
+To see all the internal logs, set the `DEBUG` environment variable to
+`express-session` when launching your app (`npm start`, in this example):
+
+```sh
+$ DEBUG=express-session npm start
+```
+
+On Windows, use the corresponding command;
+
+```sh
+> set DEBUG=express-session & npm start
+```
+
 ## License
 
 [MIT](LICENSE)