dgbuilder/dgeflows/node_modules/express/node_modules/send/Readme.md

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