1 | # send
|
2 |
|
3 | Send is Connect's `static()` extracted for generalized use, a streaming static file
|
4 | 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.
|
5 |
|
6 | ## Installation
|
7 |
|
8 | $ npm install send
|
9 |
|
10 | ## Examples
|
11 |
|
12 | Small:
|
13 |
|
14 | ```js
|
15 | var http = require('http');
|
16 | var send = require('send');
|
17 |
|
18 | var app = http.createServer(function(req, res){
|
19 | send(req, req.url).pipe(res);
|
20 | }).listen(3000);
|
21 | ```
|
22 |
|
23 | Serving from a root directory with custom error-handling:
|
24 |
|
25 | ```js
|
26 | var http = require('http');
|
27 | var send = require('send');
|
28 | var url = require('url');
|
29 |
|
30 | var 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 | }).listen(3000);
|
52 | ```
|
53 |
|
54 | ## API
|
55 |
|
56 | ### Events
|
57 |
|
58 | - `error` an error occurred `(err)`
|
59 | - `directory` a directory was requested
|
60 | - `file` a file was requested `(path, stat)`
|
61 | - `stream` file streaming has started `(stream)`
|
62 | - `end` streaming has completed
|
63 |
|
64 | ### .root(dir)
|
65 |
|
66 | Serve files relative to `path`. Aliased as `.from(dir)`.
|
67 |
|
68 | ### .index(path)
|
69 |
|
70 | By default send supports "index.html" files, to disable this
|
71 | invoke `.index(false)` or to supply a new index pass a string.
|
72 |
|
73 | ### .maxage(ms)
|
74 |
|
75 | Provide a max-age in milliseconds for http caching, defaults to 0.
|
76 |
|
77 | ### .hidden(bool)
|
78 |
|
79 | Enable or disable transfer of hidden files, defaults to false.
|
80 |
|
81 | ## Error-handling
|
82 |
|
83 | 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.
|
84 |
|
85 | ## Caching
|
86 |
|
87 | It does _not_ perform internal caching, you should use a reverse proxy cache such
|
88 | 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 ;).
|
89 |
|
90 | ## Debugging
|
91 |
|
92 | To enable `debug()` instrumentation output export __DEBUG__:
|
93 |
|
94 | ```
|
95 | $ DEBUG=send node app
|
96 | ```
|
97 |
|
98 | ## Running tests
|
99 |
|
100 | ```
|
101 | $ npm install
|
102 | $ make test
|
103 | ```
|
104 |
|
105 | ## License
|
106 |
|
107 | (The MIT License)
|
108 |
|
109 | Copyright (c) 2012 TJ Holowaychuk <tj@vision-media.ca>
|
110 |
|
111 | Permission is hereby granted, free of charge, to any person obtaining
|
112 | a copy of this software and associated documentation files (the
|
113 | 'Software'), to deal in the Software without restriction, including
|
114 | without limitation the rights to use, copy, modify, merge, publish,
|
115 | distribute, sublicense, and/or sell copies of the Software, and to
|
116 | permit persons to whom the Software is furnished to do so, subject to
|
117 | the following conditions:
|
118 |
|
119 | The above copyright notice and this permission notice shall be
|
120 | included in all copies or substantial portions of the Software.
|
121 |
|
122 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
123 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
124 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
125 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
126 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
127 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
128 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|