From 50c07b8e3e346c83c507bcf2cdd1ae1b7f71b092 Mon Sep 17 00:00:00 2001 From: Douglas Christopher Wilson Date: Wed, 3 Jun 2020 19:55:14 -0400 Subject: [PATCH] Update middleware readmes --- _includes/readmes/cookie-parser.md | 31 ++++++++++++++++---- _includes/readmes/cors.md | 45 +++++++++++++++--------------- _includes/readmes/morgan.md | 18 +++++++++--- _includes/readmes/multer.md | 27 ++++++++++++++++++ _includes/readmes/session.md | 18 ++++++++++++ 5 files changed, 107 insertions(+), 32 deletions(-) diff --git a/_includes/readmes/cookie-parser.md b/_includes/readmes/cookie-parser.md index bc0d27109a..f1ff334f70 100644 --- a/_includes/readmes/cookie-parser.md +++ b/_includes/readmes/cookie-parser.md @@ -18,24 +18,41 @@ $ npm install cookie-parser ## API + + ```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 diff --git a/_includes/readmes/cors.md b/_includes/readmes/cors.md index 175b078129..d1bcadb18a 100644 --- a/_includes/readmes/cors.md +++ b/_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. diff --git a/_includes/readmes/morgan.md b/_includes/readmes/morgan.md index fc1c4b4a66..7d4540b953 100644 --- a/_includes/readmes/morgan.md +++ b/_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 @@ -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). diff --git a/_includes/readmes/multer.md b/_includes/readmes/multer.md index 351e284294..d3ec0dcc9e 100644 --- a/_includes/readmes/multer.md +++ b/_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 +
+
+ + + +
+
+``` + +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 diff --git a/_includes/readmes/session.md b/_includes/readmes/session.md index a1ed3fa1ff..fe5076d813 100644 --- a/_includes/readmes/session.md +++ b/_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)