• built-in middleware, parses incoming requests with JSON payloads and is based on body-parser
• returns middleware that only parses JSON and only looks at requests where the Content-Type header matches the "type" option
• accepts any Unicode encoding of the body and supports automatic inflation of gzip and deflate encodings
• new body object 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

• built-in middleware, serves static files, based on serve-static
• for best results,use a reverse proxy cache to improve performance of serving static asset
• root argument - root directory from which to serve static assets, determines the file to serve by combining req.url with the provided root directory, when a file is not found, instead of sending a 404 response, it instead calls next() to move on to the next middleware, allowing for stacking and fall-backs

      var options = {
        dotfiles: 'ignore',
        etag: false,
        extensions: ['htm', 'html'],
        index: false,
        maxAge: '1d',
        redirect: false,
        setHeaders: function (res, path, stat) {
          res.set('x-timestamp', Date.now())
        }
      }
      app.use(express.static('public', options))
    

• creates a new router object
• add middleware and HTTP method routes (such as get, put, post, and so on) to router just like an application

      var router = express.Router([options])
    

• built-in middleware, parses incoming requests with urlencoded payloads and is based on body-parser
• returns middleware that only parses urlencoded bodies and only looks at requests where the Content-Type header matches the type option
• accepts only UTF-8 encoding of the body and supports automatic inflation of gzip and deflate encodings
• new body object 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. This object will contain key-value pairs, where the value can be a string or array (when extended is false), or any type (when extended is true)
• as req.body 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

      // --- app.locals - local variables within the application
      // once set, persist throughout the life of the application,
      // in contrast with res.locals properties
      // that are valid only for the lifetime of the request
      console.dir(app.locals.title) // => 'My App'
      console.dir(app.locals.email) // => 'me@myapp.com'
      // access local variables in templates rendered within the application
      app.locals.title = 'My App'
      app.locals.strftime = require('strftime')
      app.locals.email = 'me@myapp.com'
      // providing helper functions to templates, as well as application-level data
      // available in middleware via req.app.locals

      // --- app.mountpath - one or more path patterns on which a sub-app was mounted
      // is an instance of express that may be used for handling the request to a route
      var express = require('express')
      var app = express() // the main app
      var admin = express() // the sub app
      admin.get('/', function (req, res) {
        console.log(admin.mountpath) // /admin
        res.send('Admin Homepage')
      })
      app.use('/admin', admin) // mount the sub app
      // similar to the baseUrl property of the req object,
      // except req.baseUrl returns the matched URL path, instead of the matched patterns

      // if a sub-app is mounted on multiple path patterns,
      // app.mountpath returns the list of patterns it is mounted on
      var admin = express()
      admin.get('/', function (req, res) {
        console.dir(admin.mountpath) // [ '/adm*n', '/manager' ]
        res.send('Admin Homepage')
      })
      var secret = express()
      secret.get('/', function (req, res) {
        console.log(secret.mountpath) // /secr*t
        res.send('Admin Secret')
      })
      // load the 'secret' router on '/secr*t', on the 'admin' sub app
      admin.use('/secr*t', secret)
      // load the 'admin' router on '/adm*n' and '/manager', on the parent app
      app.use(['/adm*n', '/manager'], admin)
    

      // --- app.on('mount', callback(parent))
      // fired on a sub-app, when it is mounted on a parent app
      // parent app is passed to the callback function
      // 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
      var admin = express()
      admin.on('mount', function (parent) {
        console.log('Admin Mounted')
        console.log(parent) // refers to the parent app
      })
      admin.get('/', function (req, res) {
        res.send('Admin Homepage')
      })
      app.use('/admin', admin)
    

      // --- app.all(path, callback [, callback ...]) - matches all HTTP verbs
      app.all('/secret', function (req, res, next) {
        console.log('Accessing the secret section ...')
        next() // pass control to the next handler
      })
      // all routes from following point require authentication,
      // and automatically load a user
      // these callbacks do not have to act as end-points:
      // loadUser can perform a task, then call next() to continue matching subsequent routes
      app.all('*', requireAuthentication, loadUser)
      // or
      app.all('*', requireAuthentication)
      app.all('*', loadUser)
      // similar but but it only restricts paths that start with “/api”
      app.all('/api/*', requireAuthentication)

      // --- app.METHOD(path, callback [, callback ...])
      // routes an HTTP request, where METHOD is the HTTP method of the request,
      // such as GET, PUT, POST, and so on, in lowercase
      // path: string, path pattern, regular expression, array of combinations
      // callback: middleware,
      //           series of middleware (separated by commas), array of middleware,
      //           a combination of all of the above
      app.get('/', function (req, res) { // HTTP GET
        res.send('GET request to homepage')
      })
      app.post('/', function (req, res) {
        res.send('POST request to homepage')
      })
      app.put('/', function (req, res) {
        res.send('PUT request to homepage')
      })
      app.delete('/', function (req, res) { // HTTP DELETE
        res.send('DELETE request to homepage')
      })

      // --- app.route(path)
      // returns an instance of a single route,
      // which you can then use to handle HTTP verbs with optional middleware
      // use to avoid duplicate route names (and thus typo errors)
      var app = express()
      app.route('/events')
        .all(function (req, res, next) {
          // runs for all HTTP verbs first
          // think of it as route specific middleware!
        })
        .get(function (req, res, next) {
          res.json({})
        })
        .post(function (req, res, next) {
          // maybe add a new event...
        })

      // --- app.param([name], callback)
      // add callback triggers to route parameters,
      // name - name of the parameter or an array of them,
      // callback - callback function, parameters are:
      // request, response, next middleware, value and name of the parameter.
      // if name is an array - callback trigger is registered for each parameter declared in it,
      // in the order in which they are declared
      // for each declared parameter except the last one,
      // a call to next inside the callback will call the callback for the next declared parameter
      // for the last parameter, a call to next will call the next middleware in place
      // for the route currently being processed, just like it would if name were just a string.
      // map user loading logic when :user is present in a route path
      // to automatically provide req.user to the route, or perform validations on the parameter input
      app.param('user', function (req, res, next, id) {
        // try to get the user details from the User model and attach it to the request object
        User.find(id, function (err, user) {
          if (err) {
            next(err)
          } else if (user) {
            req.user = user
            next()
          } else {
            next(new Error('failed to load user'))
          }
        })
      })
      // param callback functions are local to the router on which they are defined
      // they are not inherited by mounted apps or routers
      // will be triggered only by route parameters defined on app routes.
      // all param callbacks will be called before any handler of any route in which the param occurs,
      // and they will each be called only once in a request-response cycle,
      // even if the parameter is matched in multiple routes
      app.param('id', function (req, res, next, id) {
        console.log('CALLED ONLY ONCE')
        next()
      })
      app.get('/user/:id', function (req, res, next) {
        console.log('although this matches')
        next()
      })
      app.get('/user/:id', function (req, res) {
        console.log('and this matches too')
        res.end()
      })
      // GET /user/42
      //
      //     CALLED ONLY ONCE
      //     although this matches
      //     and this matches too
      //
      app.param(['id', 'page'], function (req, res, next, value) {
        console.log('CALLED ONLY ONCE with', value)
        next()
      })
      app.get('/user/:id/:page', function (req, res, next) {
        console.log('although this matches')
        next()
      })
      app.get('/user/:id/:page', function (req, res) {
        console.log('and this matches too')
        res.end()
      })
      // GET /user/42/3
      //
      //     CALLED ONLY ONCE with 42
      //     CALLED ONLY ONCE with 3
      //     although this matches
      //     and this matches too
      //
      // . - character cant be used to capture a character in your capturing regexp
      // cant use '/user-.+/' to capture 'users-gami',
      // use [\\s\\S] or [\\w\\W] instead (as in '/user-[\\s\\S]+/'
      // captures '1-a_6' but not '543-azser-sder'
      router.get('/[0-9]+-[[\\w]]*', function(){});
      // captures '1-a_6' and '543-az(ser"-sder' but not '5-a s'
      router.get('/[0-9]+-[[\\S]]*', function(){});
      // captures all (equivalent to '.*')
      router.get('[[\\s\\S]]*', function(){});

      // --- app.get(name)
      // --- app.set(name, value)
      // assigns and get value of app settings table
      // certain names can be used to configure the behavior of the server
      app.get('title') // => undefined
      app.set('title', 'My Site')
      app.get('title') // => "My Site"
      // --- app.disable(name)
      // --- app.disabled(name)
      // --- app.enable(name)
      // --- app.enabled(name)
      // set Boolean setting in app settings table
      app.disable('trust proxy')
      app.get('trust proxy') // => false
      app.disabled('trust proxy') // => true
      app.enable('trust proxy')
      app.disabled('trust proxy') // => false
      app.enable('trust proxy')
      app.get('trust proxy') // => true
      app.enabled('trust proxy') // => false
      app.enable('trust proxy')
      app.enabled('trust proxy') // => true

      // --- app.render(view, [locals], callback)
      // returns the rendered HTML of a view via the callback function
      // accepts an optional parameter that is an object containing local variables
      // is like res.render(), except it cannot send the rendered view to the client on its own.
      // utility function for generating rendered view strings.
      // internally res.render() uses app.render() to render views.
      // 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
      app.render('email', function (err, html) {
        // ...
      })
      app.render('email', { name: 'Tobi' }, function (err, html) {
        // ...
      })

      // --- app.engine(ext, callback) - registers the given template engine callback as ext
      app.engine('pug', require('pug').__express)
      // for engines that do not provide .__express out of the box,
      // or to map a different extension to the template engine
      app.engine('html', require('ejs').renderFile)
      // in this case, EJS provides a .renderFile() method
      // with the same signature that Express expects: (path, options, callback),
      // though note that it aliases this method as ejs.__express internally
      // so if you’re using ".ejs" extensions you dont need to do anything
      var engines = require('consolidate')
      app.engine('haml', engines.haml)
      app.engine('html', engines.hogan)

      // --- app.listen(path, [callback])
      // starts a UNIX socket and listens for connections on the given path
      // identical to Node http.Server.listen()
      var express = require('express')
      var app = express()
      app.listen('/tmp/sock')

      // --- app.listen([port[, host[, backlog]]][, callback])
      // binds and listens for connections on the specified host and port
      // identical to Node http.Server.listen()
      // if port is omitted or is 0, the operating system will assign an arbitrary
      // useful for cases like automated tasks (tests, etc.)
      var express = require('express')
      var app = express()
      app.listen(3000)
      // app returned by express() is in fact a JavaScript Function,
      // designed to be passed to Node HTTP servers as a callback to handle requests
      // this makes it easy to provide both HTTP and HTTPS versions of app
      // with the same code base, app does not inherit from these (it is simply a callback)
      var express = require('express')
      var https = require('https')
      var http = require('http')
      var app = express()
      http.createServer(app).listen(80)
      https.createServer(options, app).listen(443)
      // method returns an http.Server object and (for HTTP)
      // is a convenience method for the following
      app.listen = function () {
        var server = http.createServer(this)
        return server.listen.apply(server, arguments)
      }
      // all the forms of Node http.Server.listen() method are in fact actually supported
    

      // --- path
      // paths starting with "/abcd"
      app.use('/abcd', function (req, res, next) {
        next();
      });

      // --- path pattern
      // paths starting with "/abcd" and "/abd"
      app.use('/abc?d', function (req, res, next) {
        next();
      });
      // paths starting with "/abcd", "/abbcd", "/abbbbbcd", and so on
      app.use('/ab+cd', function (req, res, next) {
        next();
      });
      // paths starting with "/abcd", "/abxcd", "/abFOOcd", "/abbArcd", and so on
      app.use('/ab\*cd', function (req, res, next) {
        next();
      });
      // paths starting with "/ad" and "/abcd"
      app.use('/a(bc)?d', function (req, res, next) {
        next();
      });

      // --- regular Expression
      // paths starting with "/abc" and "/xyz"
      app.use(/\/abc|\/xyz/, function (req, res, next) {
        next();
      });

      // --- array
      // paths starting with "/abcd", "/xyza", "/lmn", and "/pqr"
      app.use(['/abcd', '/xyza', /\/lmn|\/pqr/], function (req, res, next) {
        next();
      });
    

• examples of middleware functions that can be used as the callback argument to app.use(), app.METHOD(), and app.all()

      // --- single middleware
      // define and mount a middleware function locally
      app.use(function (req, res, next) {
        next();
      });
      // router is valid middleware
      var router = express.Router();
      router.get('/', function (req, res, next) {
        next();
      });
      app.use(router);
      // Express app is valid middleware
      var subApp = express();
      subApp.get('/', function (req, res, next) {
        next();
      });
      app.use(subApp);

      // --- series of middleware
      // specify more than one middleware function at the same mount path
      var r1 = express.Router();
      r1.get('/', function (req, res, next) {
        next();
      });
      var r2 = express.Router();
      r2.get('/', function (req, res, next) {
        next();
      });
      app.use(r1, r2);

      // --- array
      // to group middleware logically
      // if you pass an array of middleware as the first or only middleware parameters,
      // specify the mount path
      var r1 = express.Router();
      r1.get('/', function (req, res, next) {
        next();
      });
      var r2 = express.Router();
      r2.get('/', function (req, res, next) {
        next();
      });
      app.use('/', [r1, r2]);

      // --- combination
      // combine all the above ways of mounting middleware
      function mw1(req, res, next) { next(); }
      function mw2(req, res, next) { next(); }
      var r1 = express.Router();
      r1.get('/', function (req, res, next) { next(); });
      var r2 = express.Router();
      r2.get('/', function (req, res, next) { next(); });
      var subApp = express();
      subApp.get('/', function (req, res, next) { next(); });
      app.use(mw1, [mw2, r1, r2], subApp);
    

      // serve static content for the app from the "public" directory in the application directory
      // GET /style.css etc
      app.use(express.static(path.join(__dirname, 'public')))
      // mount the middleware at "/static" to serve static content
      // only when their request path is prefixed with "/static"
      // GET /static/style.css etc.
      app.use('/static', express.static(path.join(__dirname, 'public')))
      // disable logging for static content request, load logger middleware after the static middleware
      app.use(express.static(path.join(__dirname, 'public')))
      app.use(logger())
      // serve static files from multiple directories, but give precedence to "./public" over the others
      app.use(express.static(path.join(__dirname, 'public')))
      app.use(express.static(path.join(__dirname, 'files')))
      app.use(express.static(path.join(__dirname, 'uploads')))
    

• apply only to dynamic files, not static files, express.static middleware ignores these settings, ETag functionality is implemented using the etag package

        app.set('etag', function (body, encoding) {
          return generateHash(body, encoding) // consider the function is defined
        })
        

      // --- req.app
      // holds a reference to the instance of the Express app that is using the middleware.
      // create a module that just exports a middleware and require() it in your main file,
      // then the middleware can access the Express instance via req.app
      // index.js
      app.get('/viewdirectory', require('./mymiddleware.js'))
      // mymiddleware.js
      module.exports = function (req, res) {
        res.send('The views directory is ' + req.app.get('views'))
      }

      // --- req.baseUrl
      // URL path on which a router instance was mounted
      // similar to the mountpath property of the app object,
      // except app.mountpath returns the matched path pattern(s)
      var greet = express.Router()
      greet.get('/jp', function (req, res) {
        console.log(req.baseUrl) // /greet
        res.send('Konichiwa!')
      })
      app.use('/greet', greet) // load the router on '/greet'
      // even if you use a path pattern or a set of path patterns to load the router,
      // baseUrl property returns the matched string, not the pattern(s).
      // greet router is loaded on two path patterns
      app.use(['/gre+t', '/hel{2}o'], greet) // load the router on '/gre+t' and '/hel{2}o'
      // when a request is made to /greet/jp, req.baseUrl is "/greet"
      // when a request is made to /hello/jp, req.baseUrl is “/hello”

      // --- req.cookies
      // https://github.com/expressjs/cookie-parser
      // when using cookie-parser middleware, this property is an object
      // that contains cookies sent by the request
      // if the request contains no cookies, it defaults to {}
      // Cookie: name=tj
      console.dir(req.cookies.name) // => 'tj'
      // if the cookie has been signed, use req.signedCookies

      // --- req.fresh
      // https://github.com/jshttp/fresh
      // whether the request is "fresh", opposite of req.stale
      // true, if the cache-control request header doesnt have a no-cache directive
      // and any of the following are true:
      //   if-modified-since request header is specified and last-modified request header
      //     is equal to or earlier than the modified response header
      //   if-none-match request header is *
      //   if-none-match request header, after being parsed into its directives,
      //     does not match the etag response header
      console.dir(req.fresh) // => true

      // --- req.stale
      // whether the request is "stale" and is the opposite of req.fresh
      console.dir(req.stale) // => true

      // --- req.hostname
      // hostname derived from the Host HTTP header or X-Forwarded-Host
      // can be set by the client or by the proxy
      // when more than one X-Forwarded-Host header in the request, first is used
      // Host: "example.com:3000"
      console.dir(req.hostname) // => 'example.com'

      // --- req.ip
      // remote IP address of the request
      // if trust proxy setting does not evaluate to false,
      // value of this property is derived from the left-most entry in the X-Forwarded-For header
      // header can be set by the client or by the proxy
      console.dir(req.ip) // => '127.0.0.1'

      // --- req.ips
      // when the trust proxy setting does not evaluate to false,
      // contains an array of IP addresses specified in the X-Forwarded-For request header
      // or an empty array
      // this header can be set by the client or by the proxy.
      // if X-Forwarded-For is client, proxy1, proxy2,
      // req.ips would be ["client", "proxy1", "proxy2"], where proxy2 is the furthest downstream

      // --- req.method
      // a string corresponding to the HTTP method of the request: GET, POST, PUT, and so on

      // --- req.originalUrl
      // is much like req.url
      // retains the original request URL,
      // allowing you to rewrite req.url freely for internal routing purposes
      // for example, "mounting" feature of app.use() will rewrite req.url to strip the mount point
      // GET /search?q=something
      console.dir(req.originalUrl) // => '/search?q=something'
      // in a middleware function, req.originalUrl is a combination of req.baseUrl and req.path
      app.use('/admin', function (req, res, next) { // GET 'http://www.example.com/admin/new'
        console.dir(req.originalUrl) // '/admin/new'
        console.dir(req.baseUrl) // '/admin'
        console.dir(req.path) // '/new'
        next()
      })

      // --- req.params
      // object containing properties mapped to the named route parameters
      // if you have the route /user/:name, "name" property is available as req.params.name
      // defaults to {}
      // GET /user/tj
      console.dir(req.params.name) // => 'tj'
      // when using a regular expression for the route definition,
      // capture groups are provided in the array using req.params[n],
      // where n is the nth capture group
      // this rule is applied to unnamed wild card matches with string routes such as /file/*
      // GET /file/javascripts/jquery.js
      console.dir(req.params[0]) // => 'javascripts/jquery.js'
      // if you need to make changes to a key in req.params, use the app.param handler
      // changes are applicable only to parameters already defined in the route path
      // any changes made to the req.params object in a middleware or route handler will be reset

      // --- req.path
      // path part of the request URL
      // example.com/users?sort=desc
      console.dir(req.path) // => '/users'

      // --- req.protocol
      // request protocol string: either http or (for TLS requests) https
      // when the trust proxy setting does not evaluate to false
      // will use the value of the X-Forwarded-Proto header field if present.
      // can be set by the client or by the proxy
      console.dir(req.protocol) // => 'http'

      // --- req.query
      // object containing a property for each query string parameter in the route
      // or empty object, {}
      // all properties and values in this object are untrusted and should be validated
      // req.query.foo.toString() may fail in multiple ways:
      //   foo may not be there or may not be a string,
      //   toString may not be a function and instead a string or other user-input
      // GET /search?q=tobi+ferret
      console.dir(req.query.q) // => 'tobi ferret'
      // GET /shoes?order=desc&shoe[color]=blue&shoe[type]=converse
      console.dir(req.query.order) // => 'desc'
      console.dir(req.query.shoe.color) // => 'blue'
      console.dir(req.query.shoe.type) // => 'converse'
      // GET /shoes?color[]=blue&color[]=black&color[]=red
      console.dir(req.query.color) // => ['blue', 'black', 'red']

      // --- req.route
      // currently-matched route, a string
      app.get('/user/:id?', function userIdHandler (req, res) {
        console.log(req.route)
        res.send('GET')
      })
      // output from the previous snippet
      {
        path: '/user/:id?',
        stack: [{
          handle: [Function: userIdHandler],
          name: 'userIdHandler',
          params: undefined,
          path: undefined,
          keys: [],
          regexp: /^\/?$/i,
          method: 'get'
        }],
        methods: { get: true }
      }

      // --- req.secure
      // Boolean property that is true if a TLS connection is established, equivalent to:
      console.dir(req.protocol === 'https') // => true

      // --- req.signedCookies
      // https://github.com/expressjs/cookie-parser
      // when using cookie-parser middleware, this property contains signed cookies
      // sent by the request, unsigned and ready for use
      // signed cookies reside in a different object to show developer intent;
      // otherwise, a malicious attack could be placed on req.cookie values (which are easy to spoof).
      // signing a cookie does not make it "hidden" or encrypted;
      // but simply prevents tampering (because the secret used to sign is private).
      // if no signed cookies are sent, the property defaults to {}
      // Cookie: user=tobi.CP7AWaXDfAKIRfH49dQzKJx7sKzzSoPq7/AcBBRVwlI3
      console.dir(req.signedCookies.user) // => 'tobi'

      // --- req.subdomains
      // array of subdomains in the domain name of the request
      // Host: "tobi.ferrets.example.com"
      console.dir(req.subdomains) // => ['ferrets', 'tobi']
      // application property "subdomain offset", which defaults to 2,
      // is used for determining the beginning of the subdomain segments

      // --- req.xhr
      // true, if X-Requested-With header field is “XMLHttpRequest”
      console.dir(req.xhr) // => true
    

      // --- req.accepts(types)
      // https://github.com/expressjs/accepts
      // checks if the specified content types are acceptable,
      // based on the request Accept HTTP header field
      // returns the best match, or if none of the specified content types is acceptable, false
      // (in which case, the application should respond with 406 "Not Acceptable")
      // type value may be a single MIME type string (such as "application/json"),
      // an extension name such as "json", a comma-delimited list, or an array
      // Accept: text/html
      req.accepts('html') // => "html"
      // Accept: text/*, application/json
      req.accepts('html') // => "html"
      req.accepts('text/html') // => "text/html"
      req.accepts(['json', 'text']) // => "json"
      req.accepts('application/json') // => "application/json"
      // Accept: text/*, application/json
      req.accepts('image/png')
      req.accepts('png') // => undefined
      // Accept: text/*;q=.5, application/json
      req.accepts(['html', 'json']) // => "json"
      // --- req.acceptsCharsets(charset [, ...])
      // --- req.acceptsEncodings(encoding [, ...])
      // --- req.acceptsLanguages(lang [, ...])
      // first accepted charset/encoding/language of the specified character sets,
      // based on the request Accept-Charset/Encoding/Language HTTP header field
      // if none of the specified charsets is accepted, returns false

      // --- req.get(field)
      // specified HTTP request header field (case-insensitive match)
      // Referrer and Referer fields are interchangeable
      req.get('Content-Type') // => "text/plain"
      req.get('content-type') // => "text/plain"
      req.get('Something') // => undefined
      // aliased as req.header(field)

      // --- req.is(type)
      // https://github.com/expressjs/type-is
      // matching content type
      // if "Content-Type" HTTP header matches the MIME type specified by the type parameter
      // if the request has no body, returns null, returns false otherwise
      // with Content-Type: text/html; charset=utf-8
      req.is('html') // => 'html'
      req.is('text/html') // => 'text/html'
      req.is('text/*') // => 'text/*'
      // when Content-Type is application/json
      req.is('json') // => 'json'
      req.is('application/json') // => 'application/json'
      req.is('application/*') // => 'application/*'
      req.is('html') // => false

      // --- req.range(size[, options])
      // range header parser
      // size parameter is the maximum size of the resource
      // options parameter is an object that can have the following properties
      // property "combine" - Boolean, specify if overlapping & adjacent ranges should be combined
      //   defaults to false, when true, ranges will be combined and returned
      // array of ranges will be returned or negative numbers indicating an error parsing
      // -2 signals a malformed header string
      // -1 signals an unsatisfiable range
      // parse header from request
      var range = req.range(1000)
      // the type of the range
      if (range.type === 'bytes') {
        range.forEach(function (r) { // the ranges
          // do something with r.start and r.end
        })
      }
    

      // --- res.app
      // holds a reference to the instance of the Express application
      // res.app is identical to the req.app property in the request object

      // --- res.headersSent
      // if the app sent HTTP headers for the response
      app.get('/', function (req, res) {
        console.dir(res.headersSent) // false
        res.send('OK')
        console.dir(res.headersSent) // true
      })

      // --- res.locals
      // object that contains response local variables scoped to the request,
      // available only to the view(s) rendered during that request/response cycle (if any)
      // otherwise, this property is identical to app.locals
      // useful for exposing request-level information such as the request path name,
      // authenticated user, user settings, and so on
      app.use(function (req, res, next) {
        res.locals.user = req.user
        res.locals.authenticated = !req.user.anonymous
        next()
      })
    

      // --- res.append(field [, value])
      // appends the specified value to the HTTP response header field
      // if header is not set, creates header with specified value (string or an array)
      // calling res.set() after res.append() will reset the previously-set header value
      res.append('Link', ['<http://localhost/>', ''<http://localhost:3000/>'])
      res.append('Set-Cookie', 'foo=bar; Path=/; HttpOnly')
      res.append('Warning', '199 Miscellaneous warning')

      // --- res.attachment([filename])
      // sets the HTTP response Content-Disposition header field to "attachment"
      // if a filename is given, then it sets the Content-Type based on the extension name
      // via res.type(), and sets the Content-Disposition "filename=" parameter
      // Content-Disposition: attachment
      res.attachment()
      // Content-Disposition: attachment; filename="logo.png" Content-Type: image/png
      res.attachment('path/to/logo.png')

      // --- res.cookie(name, value [, options])
      // sets cookie name to value, may be a string or object converted to JSON
      // options parameter is an object that can have the following properties:
      //   domain - domain name for the cookie, default: domain name of the app
      //   encode - synchronous function used for cookie value encoding, default: encodeURIComponent
      //   expires - expiry date of the cookie in GMT, if not specified or 0, creates a session cookie
      //   httpOnly - flags the cookie to be accessible only by the web server
      //   maxAge - setting the expiry time relative to the current time in milliseconds
      //   path - path for the cookie, default: "/"
      //   secure - marks the cookie to be used with HTTPS only
      //   signed - indicates if the cookie should be signed
      //   sameSite - value of the "SameSite" Set-Cookie attribute
      // sets the HTTP Set-Cookie header with the options provided.
      // any option not specified defaults to the value stated in RFC 6265
      res.cookie('name', 'tobi', { domain: '.example.com', path: '/admin', secure: true })
      res.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true })
      // multiple cookies in a single response by calling res.cookie multiple times
      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')
      // encode - choose the function used for cookie value encoding
      // does not support asynchronous functions.
      // set a domain-wide cookie for another site in your organization
      // this other site (not under your administrative control) does not use URI-encoded cookie values
      // Default encoding
      res.cookie(
        'some_cross_domain_cookie',
        'http://mysubdomain.example.com',
        { domain: 'example.com' }
      )
      // Result:
      // 'some_cross_domain_cookie=http%3A%2F%2Fmysubdomain.example.com; Domain=example.com; Path=/'
      // Custom encoding
      res.cookie(
        'some_cross_domain_cookie',
        'http://mysubdomain.example.com',
        { domain: 'example.com', encode: String }
      )
      // Result: 'some_cross_domain_cookie=http://mysubdomain.example.com; Domain=example.com; Path=/;'
      // maxAge - setting "expires" relative to the current time in milliseconds
      // equivalent to the second example above
      res.cookie('rememberme', '1', { maxAge: 900000, httpOnly: true })
      // pass an object as the value parameter;
      // it is then serialized as JSON and parsed by bodyParser() middleware
      res.cookie('cart', { items: [1, 2, 3] })
      res.cookie('cart', { items: [1, 2, 3] }, { maxAge: 900000 })
      // when using cookie-parser middleware, this method also supports signed cookies
      // include the signed option set to true
      // then res.cookie() will use the secret passed to cookieParser(secret) to sign the value
      res.cookie('name', 'tobi', { signed: true })
      // later you may access this value through the req.signedCookie object

      // --- res.clearCookie(name [, options])
      // clears the cookie specified by name
      // web browsers and other compliant clients will only clear the cookie if given options is identical
      // to those given to res.cookie(), excluding expires and maxAge
      res.cookie('name', 'tobi', { path: '/admin' })
      res.clearCookie('name', { path: '/admin' })

      // --- res.download(path [, filename] [, options] [, fn])
      // transfers the file at path as an "attachment"
      // browsers will prompt the user for download
      // by default, the Content-Disposition header "filename=" parameter is path
      // (this typically appears in the browser dialog), override this default with the filename parameter
      // when an error occurs or transfer is complete, method calls the optional callback function fn.
      // uses res.sendFile() to transfer the file
      // optional options argument passes to the underlying res.sendFile() call, takes the same parameters
      res.download('/report-12345.pdf')
      res.download('/report-12345.pdf', 'report.pdf')
      res.download('/report-12345.pdf', 'report.pdf', function (err) {
        if (err) {
          // Handle error, but keep in mind the response may be partially-sent
          // so check res.headersSent
        } else {
          // decrement a download credit, etc.
        }
      })

      // --- res.end([data] [, encoding])
      // ends the response process, from Node core, response.end() of http.ServerResponse
      // end the response without any data
      // use methods such as res.send() and res.json() to respond with data
      res.end()
      res.status(404).end()

      // --- res.format(object)
      // content-negotiation on the Accept HTTP header on the request object,
      // when present uses req.accepts() to select a handler for the request,
      // based on the acceptable types ordered by their quality values
      // if the header is not specified, the first callback is invoked
      // when no match is found, server responds with 406 "Not Acceptable", or invokes the default
      // Content-Type response header is set when a callback is selected
      // alter this within the callback using methods such as res.set() or res.type().
      // respond with { "message": "hey" } when the Accept header field is set to "application/json"
      // or "*/json" (however if it is "*/*", then the response will be "hey")
      res.format({
        'text/plain': function () { res.send('hey') },
        'text/html': function () { res.send('hey') },
        'application/json': function () { res.send({ message: 'hey' }) },
        'default': function () {
          res.status(406).send('Not Acceptable') // log the request and respond with 406
        }
      })
      // also use extension names mapped to these types for a slightly less verbose implementation
      // in addition to canonicalized MIME types
      res.format({
        text: function () { res.send('hey') },
        html: function () { res.send('hey') },
        json: function () { res.send({ message: 'hey' }) }
      })

      // --- res.get(field)
      // HTTP response header specified by field, match is case-insensitive
      res.get('Content-Type') // => "text/plain"

      // --- res.json([body])
      // sends a JSON response (with the correct content-type)
      // that is the parameter converted to a JSON string using JSON.stringify()
      // parameter can be any JSON type: object, array, string, Boolean, number, or null
      // use it to convert other values to JSON
      res.json(null)
      res.json({ user: 'tobi' })
      res.status(500).json({ error: 'message' })

      // --- res.jsonp([body])
      // sends a JSON response with JSONP support, identical to res.json()
      // except that it opts-in to JSONP callback support
      res.jsonp(null) // => callback(null)
      res.jsonp({ user: 'tobi' }) // => callback({ "user": "tobi" })
      res.status(500).jsonp({ error: 'message' }) // => callback({ "error": "message" })
      // default JSONP callback name is simply callback, override with jsonp callback name setting
      // ?callback=foo
      res.jsonp({ user: 'tobi' }) // => foo({ "user": "tobi" })
      app.set('jsonp callback name', 'cb')
      // ?cb=foo
      res.status(500).jsonp({ error: 'message' }) // => foo({ "error": "message" })

      // --- res.links(links)
      // joins the links provided as properties of the parameter
      // to populate the response Link HTTP header field
      res.links({
        next: 'http://api.example.com/users?page=2',
        last: 'http://api.example.com/users?page=5'
      })
      // yields the following results
      // Link: http://api.example.com/users?page=2; rel="next",
      //       http://api.example.com/users?page=5; rel="last"

      // --- res.location(path)
      // sets response Location HTTP header to the specified path parameter
      res.location('/foo/bar')
      res.location('http://example.com')
      res.location('back')
      // "back" refers to the URL specified in the Referer header or "/".
      // after encoding the URL, if not encoded already,
      // specified URL is passed to the browser in the Location header, with no validation.
      // browsers take the responsibility of deriving the intended URL from the current URL
      // or the referring URL, and the URL specified in the Location header;
      // and redirect the user accordingly

      // --- res.redirect([status,] path)
      // redirects to the URL derived from the specified path, with specified status,
      // HTTP status code, if not specified, status defaults to "302 Found"
      res.redirect('/foo/bar')
      res.redirect('http://example.com')
      res.redirect(301, 'http://example.com')
      res.redirect('../login')
      // be a fully-qualified URL for redirecting to a different site
      res.redirect('http://google.com')
      // can be relative to the root of the host name
      // if the application is on http://example.com/admin/post/new,
      // following would redirect to the URL http://example.com/admin
      res.redirect('/admin')
      // relative to the current URL.
      // from http://example.com/blog/admin/ (notice the trailing slash),
      // following would redirect to the URL http://example.com/blog/admin/post/new
      res.redirect('post/new')
      // redirecting to post/new from http://example.com/blog/admin (no trailing slash),
      // will redirect to http://example.com/blog/post/new.
      // think of path segments as directories (with trailing slashes) and files.
      // path-relative redirects are also possible
      // from http://example.com/admin/post/new, redirect to http://example.com/admin/post
      res.redirect('..')
      // back redirection redirects the request back to the referer,
      // defaulting to / when the referer is missing
      res.redirect('back')

      // --- res.render(view [, locals] [, callback])
      // renders a view and sends the rendered HTML string to client
      //    locals - object whose properties define local variables for the view
      //    callback - function, method returns both the possible error and rendered string,
      //               but does not perform an automated response
      //               when an error occurs, the method invokes next(err) internally
      //    view - string, file path of the view file to render,
      //    can be an absolute path, or a path relative to the views setting
      //    view engine setting determines file extension (and load module), if not defined in path.
      //    should not contain input from the end-user
      res.render('index')
      // if a callback is specified, the rendered HTML string has to be sent explicitly
      res.render('index', function (err, html) {
        res.send(html)
      })
      // pass a local variable to the view
      res.render('user', { name: 'Tobi' }, function (err, html) {
        // ...
      })

      // --- res.send([body])
      // sends the HTTP response
      // body parameter can be a Buffer object, String, object, Array
      res.send(Buffer.from('whoop'))
      res.send({ some: 'json' })
      res.send('<p>some html</p>')
      res.status(404).send('Sorry, we cannot find that!')
      res.status(500).send({ error: 'something blew up' })
      // method performs many useful tasks for simple non-streaming responses.
      // it automatically assigns Content-Length HTTP response header (unless previously defined)
      // and provides automatic HEAD and HTTP cache freshness support
      // when the parameter is a Buffer object, method sets the Content-Type response header field
      // to "application/octet-stream", unless previously defined as shown below
      res.set('Content-Type', 'text/html')
      res.send(Buffer.from('<p>some html</p>'))
      // when the parameter is a String, the method sets the Content-Type to "text/html"
      res.send('<p>some html</p>')
      // when the parameter is an Array or Object, Express responds with the JSON representation
      res.send({ user: 'tobi' })
      res.send([1, 2, 3])

      // --- res.sendFile(path [, options] [, fn])
      // https://github.com/pillarjs/send
      // transfers the file at the given path
      // sets the Content-Type response HTTP header field based on the filename extension
      // unless the root option is set in the options object, path must be an absolute path to the file.
      // this API provides access to data on the running file system
      // ensure that either (a) the way in which the path argument was constructed into an absolute path
      // 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, the path argument is allowed to be a relative path,
      // including containing ..
      // Express will validate as path and will resolve within the given root option
      // options:
      //   maxAge (0) - sets max-age property of Cache-Control header in milliseconds, or in ms format
      //   root - root directory for relative filenames
      //   lastModified (Enabled) - sets Last-Modified header to last modified date of the file on the OS
      //                            set false to disable it
      //   headers - object containing HTTP headers to serve with the file
      //   dotfiles - option for serving dotfiles. Possible values are "allow", "deny", "ignore"
      //   acceptRanges (true) - enable or disable accepting ranged requests
      //   cacheControl (true) - enable or disable setting Cache-Control response header
      //   immutable (false) - enable/disable the immutable directive in the Cache-Control response header
      //             if enabled, maxAge option should also be specified to enable caching
      //             immutable directive will prevent supported clients from making conditional requests
      //             during the life of the maxAge option to check if the file has changed
      // invokes the callback fn(err) when the transfer is complete or when an error occurs
      // if the callback is specified and an error occurs,
      // callback must explicitly handle the response process either by ending the request-response cycle,
      // or by passing control to the next route.
      // using res.sendFile with all its arguments
      app.get('/file/:name', function (req, res, next) {
        var options = {
          root: path.join(__dirname, 'public'),
          dotfiles: 'deny',
          headers: {
            'x-timestamp': Date.now(),
            'x-sent': true
          }
        }
        var fileName = req.params.name
        res.sendFile(fileName, options, function (err) {
          if (err) { next(err) }
          else { console.log('Sent:', fileName) }
        })
      })
      // using res.sendFile to provide fine-grained support for serving files
      app.get('/user/:uid/photos/:file', function (req, res) {
        var uid = req.params.uid
        var file = req.params.file
        req.user.mayViewFilesFrom(uid, function (yes) {
          if (yes) { res.sendFile('/uploads/' + uid + '/' + file) }
          else { res.status(403).send("Sorry! You can't see that.") }
        })
      })

      // --- res.sendStatus(statusCode)
      // sets response HTTP status code and send its string representation body
      res.sendStatus(200) // equivalent to res.status(200).send('OK')
      res.sendStatus(403) // equivalent to res.status(403).send('Forbidden')
      res.sendStatus(404) // equivalent to res.status(404).send('Not Found')
      res.sendStatus(500) // equivalent to res.status(500).send('Internal Server Error')
      // if an unsupported status code is specified,
      // HTTP status is still set to statusCode and the string version of the code
      // some versions of Node.js will throw
      // when res.statusCode is set to an invalid HTTP status code (outside of the range 100 to 599)
      res.sendStatus(9999) // equivalent to res.status(9999).send('9999')

      // --- res.set(field [, value])
      // sets the response HTTP header field to value
      // to set multiple fields at once, pass an object as the parameter
      res.set('Content-Type', 'text/plain')
      res.set({
        'Content-Type': 'text/plain',
        'Content-Length': '123',
        'ETag': '12345'
      })
      // aliased as res.header(field [, value])

      // --- res.status(code)
      // sets the HTTP status for the response
      // chainable alias of Node response.statusCode
      res.status(403).end()
      res.status(400).send('Bad Request')
      res.status(404).sendFile('/absolute/path/to/404.png')

      // --- res.type(type)
      // sets the Content-Type HTTP header to the MIME type
      // as determined by mime.lookup() for the specified type
      // if type contains the "/" character, then it sets the Content-Type to type
      res.type('.html') // => 'text/html'
      res.type('html') // => 'text/html'
      res.type('json') // => 'application/json'
      res.type('application/json') // => 'application/json'
      res.type('png') // => 'image/png'

      // --- res.vary(field)
      // adds the field to the Vary response header, if it is not there already
      res.vary('User-Agent').render('docs')
    

      // mapping "global" logic for specific path prefixes or arbitrary matches
      // if you placed the following route at the top of all other route definitions,
      // it would require that all routes from that point on
      // would require authentication, and automatically load a user.
      // these callbacks do not have to act as end points;
      // loadUser can perform a task, then call next() to continue matching subsequent routes
      router.all('*', requireAuthentication, loadUser)
      // the equivalent
      router.all('*', requireAuthentication)
      router.all('*', loadUser)
      //  white-listed "global" functionality, only restrict paths prefixed with "/api"
      router.all('/api/*', requireAuthentication)
    

      // provide the routing functionality in Express,
      // METHOD is one of the HTTP methods, such as GET, POST, and so on, in lowercase
      // actual methods are router.get(), router.post(), router.put(), and so on.
      // router.get() automatically called for the HTTP HEAD method in addition
      // to the GET method if router.head() was not called for the path before router.get().
      // provide multiple callbacks, and all are treated equally,
      // and behave just like middleware, except that these callbacks may invoke next('route')
      // to bypass the remaining route callback(s)
      // use this mechanism to perform pre-conditions on a route then pass control
      // to subsequent routes when there is no reason to proceed with the route matched

      // most simple route definition possible
      // Express translates the path strings to regular expressions,
      // used internally to match incoming requests.
      // query strings are not considered when performing these matches,
      // for example "GET /" would match the following route, as would "GET /?name=tobi"
      router.get('/', function (req, res) {
        res.send('hello world')
      })
      // also use regular expressions
      // following would match "GET /commits/71dbb9c" and "GET /commits/71dbb9c..4c084f9"
      router.get(/^\/commits\/(\w+)(?:\.\.(\w+))?$/, function (req, res) {
        var from = req.params[0]
        var to = req.params[1] || 'HEAD'
        res.send('commit range ' + from + '..' + to)
      })
    

      // adds callback triggers to route parameters, where name
      // is the name of the parameter and callback is the callback function.
      // name is technically optional, using this method without it is deprecated since v4.11.0
      // parameters of the callback function are
      //   req, the request object
      //   res, the response object
      //   next, indicating the next middleware function
      //   value of the name parameter
      //   name of the parameter
      // does not accept an array of route parameters

      // when :user is present in a route path, map user loading logic
      // to automatically provide req.user to the route, or perform validations input
      router.param('user', function (req, res, next, id) {
        // try to get the user details from the User model and attach it to the request object
        User.find(id, function (err, user) {
          if (err) {
            next(err)
          } else if (user) {
            req.user = user
            next()
          } else {
            next(new Error('failed to load user'))
          }
        })
      })

      // param callback functions are local to the router on which they are defined
      // they are not inherited by mounted apps or routers
      // will be triggered only by route parameters defined on router routes
      // will be called only once in a request-response cycle,
      // even if the parameter is matched in multiple routes
      router.param('id', function (req, res, next, id) {
        console.log('CALLED ONLY ONCE')
        next()
      })
      router.get('/user/:id', function (req, res, next) {
        console.log('although this matches')
        next()
      })
      router.get('/user/:id', function (req, res) {
        console.log('and this matches too')
        res.end()
      })
      // GET /user/42
      //   CALLED ONLY ONCE
      //   although this matches
      //   and this matches too
    

      // returns an instance of a single route,
      // then use to handle HTTP verbs with optional middleware
      // use to avoid duplicate route naming and thus typing errors.
      // re-use single /users/:user_id path and add handlers for various HTTP methods
      var router = express.Router()
      router.param('user_id', function (req, res, next, id) {
        // sample user, would actually fetch from DB, etc...
        req.user = {
          id: id,
          name: 'TJ'
        }
        next()
      })
      router.route('/users/:user_id')
      .all(function (req, res, next) {
        // runs for all HTTP verbs first
        // think of it as route specific middleware!
        next()
      })
      .get(function (req, res, next) {
        res.json(req.user)
      })
      .put(function (req, res, next) {
        // just an example of maybe updating the user
        req.user.name = req.params.name
        // save user ... etc
        res.json(req.user)
      })
      .post(function (req, res, next) {
        next(new Error('not implemented'))
      })
      .delete(function (req, res, next) {
        next(new Error('not implemented'))
      })
      // when you use router.route(), middleware ordering is based on when the route is created,
      // not when method handlers are added to the route
      // consider method handlers to belong to the route to which they were added
    

      // uses the specified middleware function or functions,
      // with optional mount path path, that defaults to "/"
      // similar to app.use()
      // requests start at the first middleware function defined
      // and work their way "down" the middleware stack processing for each path they match
      var express = require('express')
      var app = express()
      var router = express.Router()
      // simple logger for this router requests
      // all requests to this router will first hit this middleware
      router.use(function (req, res, next) {
        console.log('%s %s %s', req.method, req.url, req.path)
        next()
      })
      // this will only be invoked if the path starts with /bar from the mount point
      router.use('/bar', function (req, res, next) {
        // ... maybe some additional /bar logging ...
        next()
      })
      // always invoked
      router.use(function (req, res, next) {
        res.send('Hello World')
      })
      app.use('/foo', router)
      app.listen(3000)

      // "mount" path is stripped and is not visible to the middleware function
      // main effect of this feature is that a mounted middleware function
      // may operate without code changes regardless of its "prefix" pathname.
      // order in which you define middleware with router.use() is very important
      // they are invoked sequentially, thus the order defines middleware precedence.
      // usually a logger is the very first middleware, so that every request gets logged
      var logger = require('morgan')
      var path = require('path')
      router.use(logger())
      router.use(express.static(path.join(__dirname, 'public')))
      router.use(function (req, res) {
        res.send('Hello')
      })

      // ignore logging requests for static files,
      // and continue logging routes and middleware defined after logger().
      // move the call to express.static() to the top, before adding the logger middleware:
      router.use(express.static(path.join(__dirname, 'public')))
      router.use(logger())
      router.use(function (req, res) {
        res.send('Hello')
      })

      // serving files from multiple directories, giving precedence to "./public"
      router.use(express.static(path.join(__dirname, 'public')))
      router.use(express.static(path.join(__dirname, 'files')))
      router.use(express.static(path.join(__dirname, 'uploads')))

      // use() method also supports named parameters
      // mount points for other routers can benefit from preloading using named parameters.
      // although these middleware functions are added via a particular router,
      // when they run is defined by the path they are attached to (not the router)
      // therefore, middleware added via one router may run for other routers if its routes match.
      // this code shows two different routers mounted on the same path:
      var authRouter = express.Router()
      var openRouter = express.Router()
      authRouter.use(require('./authenticate').basic(usersdb))
      authRouter.get('/:user_id/edit', function (req, res, next) {
        // ... Edit user UI ...
      })
      openRouter.get('/', function (req, res, next) {
        // ... List users ...
      })
      openRouter.get('/:user_id', function (req, res, next) {
        // ... View user ...
      })
      app.use('/users', authRouter)
      app.use('/users', openRouter)

      // even though the authentication middleware was added via the authRouter
      // it will run on the routes defined by the openRouter
      // as well since both routers were mounted on /users
      // to avoid this behavior, use different paths for each router