vnfmarket/src/main/webapp/vnfmarket/node_modules/send/README.md

   1 # send
   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 Send is a library for streaming files from the file system as a http response
  11 supporting partial responses (Ranges), conditional-GET negotiation, high test
  12 coverage, and granular events which may be leveraged to take appropriate actions
  13 in your application or framework.
  14
  15 Looking to serve up entire folders mapped to URLs? Try [serve-static](https://www.npmjs.org/package/serve-static).
  16
  17 ## Installation
  18
  19 ```bash
  20 $ npm install send
  21 ```
  22
  23 ## API
  24
  25 ```js
  26 var send = require('send')
  27 ```
  28
  29 ### send(req, path, [options])
  30
  31 Create a new `SendStream` for the given path to send to a `res`. The `req` is
  32 the Node.js HTTP request and the `path` is a urlencoded path to send (urlencoded,
  33 not the actual file-system path).
  34
  35 #### Options
  36
  37 ##### dotfiles
  38
  39 Set how "dotfiles" are treated when encountered. A dotfile is a file
  40 or directory that begins with a dot ("."). Note this check is done on
  41 the path itself without checking if the path actually exists on the
  42 disk. If `root` is specified, only the dotfiles above the root are
  43 checked (i.e. the root itself can be within a dotfile when when set
  44 to "deny").
  45
  46   - `'allow'` No special treatment for dotfiles.
  47   - `'deny'` Send a 403 for any request for a dotfile.
  48   - `'ignore'` Pretend like the dotfile does not exist and 404.
  49
  50 The default value is _similar_ to `'ignore'`, with the exception that
  51 this default will not ignore the files within a directory that begins
  52 with a dot, for backward-compatibility.
  53
  54 ##### end
  55
  56 Byte offset at which the stream ends, defaults to the length of the file
  57 minus 1. The end is inclusive in the stream, meaning `end: 3` will include
  58 the 4th byte in the stream.
  59
  60 ##### etag
  61
  62 Enable or disable etag generation, defaults to true.
  63
  64 ##### extensions
  65
  66 If a given file doesn't exist, try appending one of the given extensions,
  67 in the given order. By default, this is disabled (set to `false`). An
  68 example value that will serve extension-less HTML files: `['html', 'htm']`.
  69 This is skipped if the requested file already has an extension.
  70
  71 ##### index
  72
  73 By default send supports "index.html" files, to disable this
  74 set `false` or to supply a new index pass a string or an array
  75 in preferred order.
  76
  77 ##### lastModified
  78
  79 Enable or disable `Last-Modified` header, defaults to true. Uses the file
  80 system's last modified value.
  81
  82 ##### maxAge
  83
  84 Provide a max-age in milliseconds for http caching, defaults to 0.
  85 This can also be a string accepted by the
  86 [ms](https://www.npmjs.org/package/ms#readme) module.
  87
  88 ##### root
  89
  90 Serve files relative to `path`.
  91
  92 ##### start
  93
  94 Byte offset at which the stream starts, defaults to 0. The start is inclusive,
  95 meaning `start: 2` will include the 3rd byte in the stream.
  96
  97 #### Events
  98
  99 The `SendStream` is an event emitter and will emit the following events:
 100
 101   - `error` an error occurred `(err)`
 102   - `directory` a directory was requested
 103   - `file` a file was requested `(path, stat)`
 104   - `headers` the headers are about to be set on a file `(res, path, stat)`
 105   - `stream` file streaming has started `(stream)`
 106   - `end` streaming has completed
 107
 108 #### .pipe
 109
 110 The `pipe` method is used to pipe the response into the Node.js HTTP response
 111 object, typically `send(req, path, options).pipe(res)`.
 112
 113 ### .mime
 114
 115 The `mime` export is the global instance of of the
 116 [`mime` npm module](https://www.npmjs.com/package/mime).
 117
 118 This is used to configure the MIME types that are associated with file extensions
 119 as well as other options for how to resolve the MIME type of a file (like the
 120 default type to use for an unknown file extension).
 121
 122 ## Error-handling
 123
 124 By default when no `error` listeners are present an automatic response will be
 125 made, otherwise you have full control over the response, aka you may show a 5xx
 126 page etc.
 127
 128 ## Caching
 129
 130 It does _not_ perform internal caching, you should use a reverse proxy cache
 131 such as Varnish for this, or those fancy things called CDNs. If your
 132 application is small enough that it would benefit from single-node memory
 133 caching, it's small enough that it does not need caching at all ;).
 134
 135 ## Debugging
 136
 137 To enable `debug()` instrumentation output export __DEBUG__:
 138
 139 ```
 140 $ DEBUG=send node app
 141 ```
 142
 143 ## Running tests
 144
 145 ```
 146 $ npm install
 147 $ npm test
 148 ```
 149
 150 ## Examples
 151
 152 ### Small example
 153
 154 ```js
 155 var http = require('http');
 156 var send = require('send');
 157
 158 var app = http.createServer(function(req, res){
 159   send(req, req.url).pipe(res);
 160 }).listen(3000);
 161 ```
 162
 163 ### Custom file types
 164
 165 ```js
 166 var http = require('http');
 167 var send = require('send');
 168
 169 // Default unknown types to text/plain
 170 send.mime.default_type = 'text/plain';
 171
 172 // Add a custom type
 173 send.mime.define({
 174   'application/x-my-type': ['x-mt', 'x-mtt']
 175 });
 176
 177 var app = http.createServer(function(req, res){
 178   send(req, req.url).pipe(res);
 179 }).listen(3000);
 180 ```
 181
 182 ### Serving from a root directory with custom error-handling
 183
 184 ```js
 185 var http = require('http');
 186 var send = require('send');
 187 var url = require('url');
 188
 189 var app = http.createServer(function(req, res){
 190   // your custom error-handling logic:
 191   function error(err) {
 192     res.statusCode = err.status || 500;
 193     res.end(err.message);
 194   }
 195
 196   // your custom headers
 197   function headers(res, path, stat) {
 198     // serve all files for download
 199     res.setHeader('Content-Disposition', 'attachment');
 200   }
 201
 202   // your custom directory handling logic:
 203   function redirect() {
 204     res.statusCode = 301;
 205     res.setHeader('Location', req.url + '/');
 206     res.end('Redirecting to ' + req.url + '/');
 207   }
 208
 209   // transfer arbitrary files from within
 210   // /www/example.com/public/*
 211   send(req, url.parse(req.url).pathname, {root: '/www/example.com/public'})
 212   .on('error', error)
 213   .on('directory', redirect)
 214   .on('headers', headers)
 215   .pipe(res);
 216 }).listen(3000);
 217 ```
 218
 219 ## License
 220
 221 [MIT](LICENSE)
 222
 223 [npm-image]: https://img.shields.io/npm/v/send.svg
 224 [npm-url]: https://npmjs.org/package/send
 225 [travis-image]: https://img.shields.io/travis/pillarjs/send/master.svg?label=linux
 226 [travis-url]: https://travis-ci.org/pillarjs/send
 227 [appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/send/master.svg?label=windows
 228 [appveyor-url]: https://ci.appveyor.com/project/dougwilson/send
 229 [coveralls-image]: https://img.shields.io/coveralls/pillarjs/send/master.svg
 230 [coveralls-url]: https://coveralls.io/r/pillarjs/send?branch=master
 231 [downloads-image]: https://img.shields.io/npm/dm/send.svg
 232 [downloads-url]: https://npmjs.org/package/send
 233 [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
 234 [gratipay-url]: https://www.gratipay.com/dougwilson/