dgbuilder/dgeflows/node_modules/serve-static/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 ##### etag
  55
  56 Enable or disable etag generation, defaults to true.
  57
  58 ##### extensions
  59
  60 If a given file doesn't exist, try appending one of the given extensions,
  61 in the given order. By default, this is disabled (set to `false`). An
  62 example value that will serve extension-less HTML files: `['html', 'htm']`.
  63 This is skipped if the requested file already has an extension.
  64
  65 ##### index
  66
  67 By default send supports "index.html" files, to disable this
  68 set `false` or to supply a new index pass a string or an array
  69 in preferred order.
  70
  71 ##### lastModified
  72
  73 Enable or disable `Last-Modified` header, defaults to true. Uses the file
  74 system's last modified value.
  75
  76 ##### maxAge
  77
  78 Provide a max-age in milliseconds for http caching, defaults to 0.
  79 This can also be a string accepted by the
  80 [ms](https://www.npmjs.org/package/ms#readme) module.
  81
  82 ##### root
  83
  84 Serve files relative to `path`.
  85
  86 ### Events
  87
  88 The `SendStream` is an event emitter and will emit the following events:
  89
  90   - `error` an error occurred `(err)`
  91   - `directory` a directory was requested
  92   - `file` a file was requested `(path, stat)`
  93   - `headers` the headers are about to be set on a file `(res, path, stat)`
  94   - `stream` file streaming has started `(stream)`
  95   - `end` streaming has completed
  96
  97 ### .pipe
  98
  99 The `pipe` method is used to pipe the response into the Node.js HTTP response
 100 object, typically `send(req, path, options).pipe(res)`.
 101
 102 ## Error-handling
 103
 104 By default when no `error` listeners are present an automatic response will be
 105 made, otherwise you have full control over the response, aka you may show a 5xx
 106 page etc.
 107
 108 ## Caching
 109
 110 It does _not_ perform internal caching, you should use a reverse proxy cache
 111 such as Varnish for this, or those fancy things called CDNs. If your
 112 application is small enough that it would benefit from single-node memory
 113 caching, it's small enough that it does not need caching at all ;).
 114
 115 ## Debugging
 116
 117 To enable `debug()` instrumentation output export __DEBUG__:
 118
 119 ```
 120 $ DEBUG=send node app
 121 ```
 122
 123 ## Running tests
 124
 125 ```
 126 $ npm install
 127 $ npm test
 128 ```
 129
 130 ## Examples
 131
 132 ### Small example
 133
 134 ```js
 135 var http = require('http');
 136 var send = require('send');
 137
 138 var app = http.createServer(function(req, res){
 139   send(req, req.url).pipe(res);
 140 }).listen(3000);
 141 ```
 142
 143 Serving from a root directory with custom error-handling:
 144
 145 ```js
 146 var http = require('http');
 147 var send = require('send');
 148 var url = require('url');
 149
 150 var app = http.createServer(function(req, res){
 151   // your custom error-handling logic:
 152   function error(err) {
 153     res.statusCode = err.status || 500;
 154     res.end(err.message);
 155   }
 156
 157   // your custom headers
 158   function headers(res, path, stat) {
 159     // serve all files for download
 160     res.setHeader('Content-Disposition', 'attachment');
 161   }
 162
 163   // your custom directory handling logic:
 164   function redirect() {
 165     res.statusCode = 301;
 166     res.setHeader('Location', req.url + '/');
 167     res.end('Redirecting to ' + req.url + '/');
 168   }
 169
 170   // transfer arbitrary files from within
 171   // /www/example.com/public/*
 172   send(req, url.parse(req.url).pathname, {root: '/www/example.com/public'})
 173   .on('error', error)
 174   .on('directory', redirect)
 175   .on('headers', headers)
 176   .pipe(res);
 177 }).listen(3000);
 178 ```
 179
 180 ## License
 181
 182 [MIT](LICENSE)
 183
 184 [npm-image]: https://img.shields.io/npm/v/send.svg
 185 [npm-url]: https://npmjs.org/package/send
 186 [travis-image]: https://img.shields.io/travis/pillarjs/send/master.svg?label=linux
 187 [travis-url]: https://travis-ci.org/pillarjs/send
 188 [appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/send/master.svg?label=windows
 189 [appveyor-url]: https://ci.appveyor.com/project/dougwilson/send
 190 [coveralls-image]: https://img.shields.io/coveralls/pillarjs/send/master.svg
 191 [coveralls-url]: https://coveralls.io/r/pillarjs/send?branch=master
 192 [downloads-image]: https://img.shields.io/npm/dm/send.svg
 193 [downloads-url]: https://npmjs.org/package/send
 194 [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
 195 [gratipay-url]: https://www.gratipay.com/dougwilson/