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
   9 Send is a library for streaming files from the file system as a http response
  10 supporting partial responses (Ranges), conditional-GET negotiation (If-Match,
  11 If-Unmodified-Since, If-None-Match, If-Modified-Since), high test coverage,
  12 and granular events which may be leveraged to take appropriate actions in your
  13 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 This is a [Node.js](https://nodejs.org/en/) module available through the
  20 [npm registry](https://www.npmjs.com/). Installation is done using the
  21 [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
  22
  23 ```bash
  24 $ npm install send
  25 ```
  26
  27 ## API
  28
  29 <!-- eslint-disable no-unused-vars -->
  30
  31 ```js
  32 var send = require('send')
  33 ```
  34
  35 ### send(req, path, [options])
  36
  37 Create a new `SendStream` for the given path to send to a `res`. The `req` is
  38 the Node.js HTTP request and the `path` is a urlencoded path to send (urlencoded,
  39 not the actual file-system path).
  40
  41 #### Options
  42
  43 ##### acceptRanges
  44
  45 Enable or disable accepting ranged requests, defaults to true.
  46 Disabling this will not send `Accept-Ranges` and ignore the contents
  47 of the `Range` request header.
  48
  49 ##### cacheControl
  50
  51 Enable or disable setting `Cache-Control` response header, defaults to
  52 true. Disabling this will ignore the `immutable` and `maxAge` options.
  53
  54 ##### dotfiles
  55
  56 Set how "dotfiles" are treated when encountered. A dotfile is a file
  57 or directory that begins with a dot ("."). Note this check is done on
  58 the path itself without checking if the path actually exists on the
  59 disk. If `root` is specified, only the dotfiles above the root are
  60 checked (i.e. the root itself can be within a dotfile when when set
  61 to "deny").
  62
  63   - `'allow'` No special treatment for dotfiles.
  64   - `'deny'` Send a 403 for any request for a dotfile.
  65   - `'ignore'` Pretend like the dotfile does not exist and 404.
  66
  67 The default value is _similar_ to `'ignore'`, with the exception that
  68 this default will not ignore the files within a directory that begins
  69 with a dot, for backward-compatibility.
  70
  71 ##### end
  72
  73 Byte offset at which the stream ends, defaults to the length of the file
  74 minus 1. The end is inclusive in the stream, meaning `end: 3` will include
  75 the 4th byte in the stream.
  76
  77 ##### etag
  78
  79 Enable or disable etag generation, defaults to true.
  80
  81 ##### extensions
  82
  83 If a given file doesn't exist, try appending one of the given extensions,
  84 in the given order. By default, this is disabled (set to `false`). An
  85 example value that will serve extension-less HTML files: `['html', 'htm']`.
  86 This is skipped if the requested file already has an extension.
  87
  88 ##### immutable
  89
  90 Enable or diable the `immutable` directive in the `Cache-Control` response
  91 header, defaults to `false`. If set to `true`, the `maxAge` option should
  92 also be specified to enable caching. The `immutable` directive will prevent
  93 supported clients from making conditional requests during the life of the
  94 `maxAge` option to check if the file has changed.
  95
  96 ##### index
  97
  98 By default send supports "index.html" files, to disable this
  99 set `false` or to supply a new index pass a string or an array
 100 in preferred order.
 101
 102 ##### lastModified
 103
 104 Enable or disable `Last-Modified` header, defaults to true. Uses the file
 105 system's last modified value.
 106
 107 ##### maxAge
 108
 109 Provide a max-age in milliseconds for http caching, defaults to 0.
 110 This can also be a string accepted by the
 111 [ms](https://www.npmjs.org/package/ms#readme) module.
 112
 113 ##### root
 114
 115 Serve files relative to `path`.
 116
 117 ##### start
 118
 119 Byte offset at which the stream starts, defaults to 0. The start is inclusive,
 120 meaning `start: 2` will include the 3rd byte in the stream.
 121
 122 #### Events
 123
 124 The `SendStream` is an event emitter and will emit the following events:
 125
 126   - `error` an error occurred `(err)`
 127   - `directory` a directory was requested `(res, path)`
 128   - `file` a file was requested `(path, stat)`
 129   - `headers` the headers are about to be set on a file `(res, path, stat)`
 130   - `stream` file streaming has started `(stream)`
 131   - `end` streaming has completed
 132
 133 #### .pipe
 134
 135 The `pipe` method is used to pipe the response into the Node.js HTTP response
 136 object, typically `send(req, path, options).pipe(res)`.
 137
 138 ### .mime
 139
 140 The `mime` export is the global instance of of the
 141 [`mime` npm module](https://www.npmjs.com/package/mime).
 142
 143 This is used to configure the MIME types that are associated with file extensions
 144 as well as other options for how to resolve the MIME type of a file (like the
 145 default type to use for an unknown file extension).
 146
 147 ## Error-handling
 148
 149 By default when no `error` listeners are present an automatic response will be
 150 made, otherwise you have full control over the response, aka you may show a 5xx
 151 page etc.
 152
 153 ## Caching
 154
 155 It does _not_ perform internal caching, you should use a reverse proxy cache
 156 such as Varnish for this, or those fancy things called CDNs. If your
 157 application is small enough that it would benefit from single-node memory
 158 caching, it's small enough that it does not need caching at all ;).
 159
 160 ## Debugging
 161
 162 To enable `debug()` instrumentation output export __DEBUG__:
 163
 164 ```
 165 $ DEBUG=send node app
 166 ```
 167
 168 ## Running tests
 169
 170 ```
 171 $ npm install
 172 $ npm test
 173 ```
 174
 175 ## Examples
 176
 177 ### Small example
 178
 179 ```js
 180 var http = require('http')
 181 var parseUrl = require('parseurl')
 182 var send = require('send')
 183
 184 var server = http.createServer(function onRequest (req, res) {
 185   send(req, parseUrl(req).pathname).pipe(res)
 186 })
 187
 188 server.listen(3000)
 189 ```
 190
 191 ### Custom file types
 192
 193 ```js
 194 var http = require('http')
 195 var parseUrl = require('parseurl')
 196 var send = require('send')
 197
 198 // Default unknown types to text/plain
 199 send.mime.default_type = 'text/plain'
 200
 201 // Add a custom type
 202 send.mime.define({
 203   'application/x-my-type': ['x-mt', 'x-mtt']
 204 })
 205
 206 var server = http.createServer(function onRequest (req, res) {
 207   send(req, parseUrl(req).pathname).pipe(res)
 208 })
 209
 210 server.listen(3000)
 211 ```
 212
 213 ### Custom directory index view
 214
 215 This is a example of serving up a structure of directories with a
 216 custom function to render a listing of a directory.
 217
 218 ```js
 219 var http = require('http')
 220 var fs = require('fs')
 221 var parseUrl = require('parseurl')
 222 var send = require('send')
 223
 224 // Transfer arbitrary files from within /www/example.com/public/*
 225 // with a custom handler for directory listing
 226 var server = http.createServer(function onRequest (req, res) {
 227   send(req, parseUrl(req).pathname, {index: false, root: '/www/example.com/public'})
 228   .once('directory', directory)
 229   .pipe(res)
 230 })
 231
 232 server.listen(3000)
 233
 234 // Custom directory handler
 235 function directory (res, path) {
 236   var stream = this
 237
 238   // redirect to trailing slash for consistent url
 239   if (!stream.hasTrailingSlash()) {
 240     return stream.redirect(path)
 241   }
 242
 243   // get directory list
 244   fs.readdir(path, function onReaddir (err, list) {
 245     if (err) return stream.error(err)
 246
 247     // render an index for the directory
 248     res.setHeader('Content-Type', 'text/plain; charset=UTF-8')
 249     res.end(list.join('\n') + '\n')
 250   })
 251 }
 252 ```
 253
 254 ### Serving from a root directory with custom error-handling
 255
 256 ```js
 257 var http = require('http')
 258 var parseUrl = require('parseurl')
 259 var send = require('send')
 260
 261 var server = http.createServer(function onRequest (req, res) {
 262   // your custom error-handling logic:
 263   function error (err) {
 264     res.statusCode = err.status || 500
 265     res.end(err.message)
 266   }
 267
 268   // your custom headers
 269   function headers (res, path, stat) {
 270     // serve all files for download
 271     res.setHeader('Content-Disposition', 'attachment')
 272   }
 273
 274   // your custom directory handling logic:
 275   function redirect () {
 276     res.statusCode = 301
 277     res.setHeader('Location', req.url + '/')
 278     res.end('Redirecting to ' + req.url + '/')
 279   }
 280
 281   // transfer arbitrary files from within
 282   // /www/example.com/public/*
 283   send(req, parseUrl(req).pathname, {root: '/www/example.com/public'})
 284   .on('error', error)
 285   .on('directory', redirect)
 286   .on('headers', headers)
 287   .pipe(res)
 288 })
 289
 290 server.listen(3000)
 291 ```
 292
 293 ## License
 294
 295 [MIT](LICENSE)
 296
 297 [npm-image]: https://img.shields.io/npm/v/send.svg
 298 [npm-url]: https://npmjs.org/package/send
 299 [travis-image]: https://img.shields.io/travis/pillarjs/send/master.svg?label=linux
 300 [travis-url]: https://travis-ci.org/pillarjs/send
 301 [appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/send/master.svg?label=windows
 302 [appveyor-url]: https://ci.appveyor.com/project/dougwilson/send
 303 [coveralls-image]: https://img.shields.io/coveralls/pillarjs/send/master.svg
 304 [coveralls-url]: https://coveralls.io/r/pillarjs/send?branch=master
 305 [downloads-image]: https://img.shields.io/npm/dm/send.svg
 306 [downloads-url]: https://npmjs.org/package/send