vnfmarket/src/main/webapp/vnfmarket/node_modules/serve-static/README.md

   1 # serve-static
   2
   3 [![NPM Version][npm-image]][npm-url]
   4 [![NPM Downloads][downloads-image]][downloads-url]
   5 [![Linux Build][travis-image]][travis-url]
   6 [![Windows Build][appveyor-image]][appveyor-url]
   7 [![Test Coverage][coveralls-image]][coveralls-url]
   8 [![Gratipay][gratipay-image]][gratipay-url]
   9
  10 ## Install
  11
  12 ```sh
  13 $ npm install serve-static
  14 ```
  15
  16 ## API
  17
  18 ```js
  19 var serveStatic = require('serve-static')
  20 ```
  21
  22 ### serveStatic(root, options)
  23
  24 Create a new middleware function to serve files from within a given root
  25 directory. The file to serve will be determined by combining `req.url`
  26 with the provided root directory. When a file is not found, instead of
  27 sending a 404 response, this module will instead call `next()` to move on
  28 to the next middleware, allowing for stacking and fall-backs.
  29
  30 #### Options
  31
  32 ##### dotfiles
  33
  34  Set how "dotfiles" are treated when encountered. A dotfile is a file
  35 or directory that begins with a dot ("."). Note this check is done on
  36 the path itself without checking if the path actually exists on the
  37 disk. If `root` is specified, only the dotfiles above the root are
  38 checked (i.e. the root itself can be within a dotfile when set
  39 to "deny").
  40
  41   - `'allow'` No special treatment for dotfiles.
  42   - `'deny'` Deny a request for a dotfile and 403/`next()`.
  43   - `'ignore'` Pretend like the dotfile does not exist and 404/`next()`.
  44
  45 The default value is similar to `'ignore'`, with the exception that this
  46 default will not ignore the files within a directory that begins with a dot.
  47
  48 ##### etag
  49
  50 Enable or disable etag generation, defaults to true.
  51
  52 ##### extensions
  53
  54 Set file extension fallbacks. When set, if a file is not found, the given
  55 extensions will be added to the file name and search for. The first that
  56 exists will be served. Example: `['html', 'htm']`.
  57
  58 The default value is `false`.
  59
  60 ##### fallthrough
  61
  62 Set the middleware to have client errors fall-through as just unhandled
  63 requests, otherwise forward a client error. The difference is that client
  64 errors like a bad request or a request to a non-existent file will cause
  65 this middleware to simply `next()` to your next middleware when this value
  66 is `true`. When this value is `false`, these errors (even 404s), will invoke
  67 `next(err)`.
  68
  69 Typically `true` is desired such that multiple physical directories can be
  70 mapped to the same web address or for routes to fill in non-existent files.
  71
  72 The value `false` can be used if this middleware is mounted at a path that
  73 is designed to be strictly a single file system directory, which allows for
  74 short-circuiting 404s for less overhead. This middleware will also reply to
  75 all methods.
  76
  77 The default value is `true`.
  78
  79 ##### index
  80
  81 By default this module will send "index.html" files in response to a request
  82 on a directory. To disable this set `false` or to supply a new index pass a
  83 string or an array in preferred order.
  84
  85 ##### lastModified
  86
  87 Enable or disable `Last-Modified` header, defaults to true. Uses the file
  88 system's last modified value.
  89
  90 ##### maxAge
  91
  92 Provide a max-age in milliseconds for http caching, defaults to 0. This
  93 can also be a string accepted by the [ms](https://www.npmjs.org/package/ms#readme)
  94 module.
  95
  96 ##### redirect
  97
  98 Redirect to trailing "/" when the pathname is a dir. Defaults to `true`.
  99
 100 ##### setHeaders
 101
 102 Function to set custom headers on response. Alterations to the headers need to
 103 occur synchronously. The function is called as `fn(res, path, stat)`, where
 104 the arguments are:
 105
 106   - `res` the response object
 107   - `path` the file path that is being sent
 108   - `stat` the stat object of the file that is being sent
 109
 110 ## Examples
 111
 112 ### Serve files with vanilla node.js http server
 113
 114 ```js
 115 var finalhandler = require('finalhandler')
 116 var http = require('http')
 117 var serveStatic = require('serve-static')
 118
 119 // Serve up public/ftp folder
 120 var serve = serveStatic('public/ftp', {'index': ['index.html', 'index.htm']})
 121
 122 // Create server
 123 var server = http.createServer(function(req, res){
 124   var done = finalhandler(req, res)
 125   serve(req, res, done)
 126 })
 127
 128 // Listen
 129 server.listen(3000)
 130 ```
 131
 132 ### Serve all files as downloads
 133
 134 ```js
 135 var contentDisposition = require('content-disposition')
 136 var finalhandler = require('finalhandler')
 137 var http = require('http')
 138 var serveStatic = require('serve-static')
 139
 140 // Serve up public/ftp folder
 141 var serve = serveStatic('public/ftp', {
 142   'index': false,
 143   'setHeaders': setHeaders
 144 })
 145
 146 // Set header to force download
 147 function setHeaders(res, path) {
 148   res.setHeader('Content-Disposition', contentDisposition(path))
 149 }
 150
 151 // Create server
 152 var server = http.createServer(function(req, res){
 153   var done = finalhandler(req, res)
 154   serve(req, res, done)
 155 })
 156
 157 // Listen
 158 server.listen(3000)
 159 ```
 160
 161 ### Serving using express
 162
 163 #### Simple
 164
 165 This is a simple example of using Express.
 166
 167 ```js
 168 var express = require('express')
 169 var serveStatic = require('serve-static')
 170
 171 var app = express()
 172
 173 app.use(serveStatic('public/ftp', {'index': ['default.html', 'default.htm']}))
 174 app.listen(3000)
 175 ```
 176
 177 #### Multiple roots
 178
 179 This example shows a simple way to search through multiple directories.
 180 Files are look for in `public-optimized/` first, then `public/` second as
 181 a fallback.
 182
 183 ```js
 184 var express = require('express')
 185 var serveStatic = require('serve-static')
 186
 187 var app = express()
 188
 189 app.use(serveStatic(__dirname + '/public-optimized'))
 190 app.use(serveStatic(__dirname + '/public'))
 191 app.listen(3000)
 192 ```
 193
 194 #### Different settings for paths
 195
 196 This example shows how to set a different max age depending on the served
 197 file type. In this example, HTML files are not cached, while everything else
 198 is for 1 day.
 199
 200 ```js
 201 var express = require('express')
 202 var serveStatic = require('serve-static')
 203
 204 var app = express()
 205
 206 app.use(serveStatic(__dirname + '/public', {
 207   maxAge: '1d',
 208   setHeaders: setCustomCacheControl
 209 }))
 210
 211 app.listen(3000)
 212
 213 function setCustomCacheControl(res, path) {
 214   if (serveStatic.mime.lookup(path) === 'text/html') {
 215     // Custom Cache-Control for HTML files
 216     res.setHeader('Cache-Control', 'public, max-age=0')
 217   }
 218 }
 219 ```
 220
 221 ## License
 222
 223 [MIT](LICENSE)
 224
 225 [npm-image]: https://img.shields.io/npm/v/serve-static.svg
 226 [npm-url]: https://npmjs.org/package/serve-static
 227 [travis-image]: https://img.shields.io/travis/expressjs/serve-static/master.svg?label=linux
 228 [travis-url]: https://travis-ci.org/expressjs/serve-static
 229 [appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/serve-static/master.svg?label=windows
 230 [appveyor-url]: https://ci.appveyor.com/project/dougwilson/serve-static
 231 [coveralls-image]: https://img.shields.io/coveralls/expressjs/serve-static/master.svg
 232 [coveralls-url]: https://coveralls.io/r/expressjs/serve-static
 233 [downloads-image]: https://img.shields.io/npm/dm/serve-static.svg
 234 [downloads-url]: https://npmjs.org/package/serve-static
 235 [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
 236 [gratipay-url]: https://gratipay.com/dougwilson/