1
  2# send
  3
  4  Send is Connect's `static()` extracted for generalized use, a streaming static file
  5  server supporting partial responses (Ranges), conditional-GET negotiation, high test coverage, and granular events which may be leveraged to take appropriate actions in your application or framework.
  6
  7## Installation
  8
  9    $ npm install send
 10
 11## Examples
 12
 13  Small:
 14
 15```js
 16var http = require('http');
 17var send = require('send');
 18
 19var app = http.createServer(function(req, res){
 20  send(req, req.url).pipe(res);
 21});
 22```
 23
 24  Serving from a root directory with custom error-handling:
 25
 26```js
 27var http = require('http');
 28var send = require('send');
 29
 30var app = http.createServer(function(req, res){
 31  // your custom error-handling logic:
 32  function error(err) {
 33    res.statusCode = err.status || 500;
 34    res.end(err.message);
 35  }
 36
 37  // your custom directory handling logic:
 38  function redirect() {
 39    res.statusCode = 301;
 40    res.setHeader('Location', req.url + '/');
 41    res.end('Redirecting to ' + req.url + '/');
 42  }
 43
 44  // transfer arbitrary files from within
 45  // /www/example.com/public/*
 46  send(req, url.parse(req.url).pathname)
 47  .root('/www/example.com/public')
 48  .on('error', error)
 49  .on('directory', redirect)
 50  .pipe(res);
 51});
 52```
 53
 54## API
 55
 56### Events
 57
 58  - `error` an error occurred `(err)`
 59  - `directory` a directory was requested
 60  - `stream` file streaming has started `(stream)`
 61  - `end` streaming has completed
 62
 63### .root(dir)
 64
 65  Serve files relative to `path`. Aliased as `.from(dir)`.
 66
 67### .index(path)
 68
 69  By default send supports "index.html" files, to disable this
 70  invoke `.index(false)` or to supply a new index pass a string.
 71
 72### .maxage(ms)
 73
 74  Provide a max-age in milliseconds for http caching, defaults to 0.
 75
 76## Error-handling
 77
 78  By default when no `error` listeners are present an automatic response will be made, otherwise you have full control over the response, aka you may show a 5xx page etc.
 79
 80## Caching
 81
 82  It does _not_ perform internal caching, you should use a reverse proxy cache such
 83  as Varnish for this, or those fancy things called CDNs. If your application is small enough that it would benefit from single-node memory caching, it's small enough that it does not need caching at all ;).
 84
 85## Debugging
 86
 87 To enable `debug()` instrumentation output export __DEBUG__:
 88
 89```
 90$ DEBUG=send node app
 91```
 92
 93## Running tests
 94
 95```
 96$ npm install
 97$ make test
 98```
 99
100## License 
101
102(The MIT License)
103
104Copyright (c) 2012 TJ Holowaychuk <tj@vision-media.ca>
105
106Permission is hereby granted, free of charge, to any person obtaining
107a copy of this software and associated documentation files (the
108'Software'), to deal in the Software without restriction, including
109without limitation the rights to use, copy, modify, merge, publish,
110distribute, sublicense, and/or sell copies of the Software, and to
111permit persons to whom the Software is furnished to do so, subject to
112the following conditions:
113
114The above copyright notice and this permission notice shall be
115included in all copies or substantial portions of the Software.
116
117THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
118EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
119MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
120IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
121CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
122TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
123SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.