1 | node-static
|
2 | ===========
|
3 |
|
4 | > a simple, *rfc 2616 compliant* file streaming module for [node](http://nodejs.org)
|
5 |
|
6 | node-static has an in-memory file cache, making it highly efficient.
|
7 | node-static understands and supports *conditional GET* and *HEAD* requests.
|
8 | node-static was inspired by some of the other static-file serving modules out there,
|
9 | such as node-paperboy and antinode.
|
10 |
|
11 | Synopsis
|
12 | --------
|
13 |
|
14 | var static = require('node-static');
|
15 |
|
16 | //
|
17 | // Create a node-static server instance to serve the './public' folder
|
18 | //
|
19 | var file = new static.Server('./public');
|
20 |
|
21 | require('http').createServer(function (request, response) {
|
22 | request.addListener('end', function () {
|
23 | //
|
24 | // Serve files!
|
25 | //
|
26 | file.serve(request, response);
|
27 | }).resume();
|
28 | }).listen(8080);
|
29 |
|
30 | API
|
31 | ---
|
32 |
|
33 | ### Creating a node-static Server #
|
34 |
|
35 | Creating a file server instance is as simple as:
|
36 |
|
37 | new static.Server();
|
38 |
|
39 | This will serve files in the current directory. If you want to serve files in a specific
|
40 | directory, pass it as the first argument:
|
41 |
|
42 | new static.Server('./public');
|
43 |
|
44 | You can also specify how long the client is supposed to cache the files node-static serves:
|
45 |
|
46 | new static.Server('./public', { cache: 3600 });
|
47 |
|
48 | This will set the `Cache-Control` header, telling clients to cache the file for an hour.
|
49 | This is the default setting.
|
50 |
|
51 | ### Serving files under a directory #
|
52 |
|
53 | To serve files under a directory, simply call the `serve` method on a `Server` instance, passing it
|
54 | the HTTP request and response object:
|
55 |
|
56 | var static = require('node-static');
|
57 |
|
58 | var fileServer = new static.Server('./public');
|
59 |
|
60 | require('http').createServer(function (request, response) {
|
61 | request.addListener('end', function () {
|
62 | fileServer.serve(request, response);
|
63 | }).resume();
|
64 | }).listen(8080);
|
65 |
|
66 | ### Serving specific files #
|
67 |
|
68 | If you want to serve a specific file, like an error page for example, use the `serveFile` method:
|
69 |
|
70 | fileServer.serveFile('/error.html', 500, {}, request, response);
|
71 |
|
72 | This will serve the `error.html` file, from under the file root directory, with a `500` status code.
|
73 | For example, you could serve an error page, when the initial request wasn't found:
|
74 |
|
75 | require('http').createServer(function (request, response) {
|
76 | request.addListener('end', function () {
|
77 | fileServer.serve(request, response, function (e, res) {
|
78 | if (e && (e.status === 404)) { // If the file wasn't found
|
79 | fileServer.serveFile('/not-found.html', 404, {}, request, response);
|
80 | }
|
81 | });
|
82 | }).resume();
|
83 | }).listen(8080);
|
84 |
|
85 | More on intercepting errors bellow.
|
86 |
|
87 | ### Intercepting errors & Listening #
|
88 |
|
89 | An optional callback can be passed as last argument, it will be called every time a file
|
90 | has been served successfully, or if there was an error serving the file:
|
91 |
|
92 | var static = require('node-static');
|
93 |
|
94 | var fileServer = new static.Server('./public');
|
95 |
|
96 | require('http').createServer(function (request, response) {
|
97 | request.addListener('end', function () {
|
98 | fileServer.serve(request, response, function (err, result) {
|
99 | if (err) { // There was an error serving the file
|
100 | sys.error("Error serving " + request.url + " - " + err.message);
|
101 |
|
102 | // Respond to the client
|
103 | response.writeHead(err.status, err.headers);
|
104 | response.end();
|
105 | }
|
106 | });
|
107 | }).resume();
|
108 | }).listen(8080);
|
109 |
|
110 | Note that if you pass a callback, and there is an error serving the file, node-static
|
111 | *will not* respond to the client. This gives you the opportunity to re-route the request,
|
112 | or handle it differently.
|
113 |
|
114 | For example, you may want to interpret a request as a static request, but if the file isn't found,
|
115 | send it to an application.
|
116 |
|
117 | If you only want to *listen* for errors, you can use *event listeners*:
|
118 |
|
119 | fileServer.serve(request, response).addListener('error', function (err) {
|
120 | sys.error("Error serving " + request.url + " - " + err.message);
|
121 | });
|
122 |
|
123 | With this method, you don't have to explicitly send the response back, in case of an error.
|
124 |
|
125 | ### Options when creating an instance of `Server` #
|
126 |
|
127 | #### `cache` #
|
128 |
|
129 | Sets the `Cache-Control` header.
|
130 |
|
131 | example: `{ cache: 7200 }`
|
132 |
|
133 | Passing a number will set the cache duration to that number of seconds.
|
134 | Passing `false` will disable the `Cache-Control` header.
|
135 |
|
136 | > Defaults to `3600`
|
137 |
|
138 |
|
139 | #### `serverInfo` #
|
140 |
|
141 | Sets the `Server` header.
|
142 |
|
143 | example: `{ serverInfo: "myserver" }`
|
144 |
|
145 | > Defaults to `node-static/{version}`
|
146 |
|
147 | #### `headers` #
|
148 |
|
149 | Sets response headers.
|
150 |
|
151 | example: `{ 'X-Hello': 'World!' }`
|
152 |
|
153 | > defaults to `{}`
|
154 |
|
155 | #### `gzip` #
|
156 |
|
157 | Enable support for sending compressed responses. This will enable a check for a
|
158 | file with the same name plus '.gz' in the same folder. If the compressed file is
|
159 | found and the client has indicated support for gzip file transfer, the contents
|
160 | of the .gz file will be sent in place of the uncompressed file along with a
|
161 | Content-Encoding: gzip header to inform the client the data has been compressed.
|
162 |
|
163 | example: `{ gzip: true }`
|
164 | example: `{ gzip: /^\/text/ }`
|
165 |
|
166 | Passing `true` will enable this check for all files.
|
167 | Passing a RegExp instance will only enable this check if the content-type of the
|
168 | respond would match that RegExp using its test() method.
|
169 |
|
170 | > Defaults to `false`
|
171 |
|
172 |
|
173 | Command Line Interface
|
174 | ----------------------
|
175 |
|
176 | `node-static` also provides a CLI.
|
177 |
|
178 | ### Installation #
|
179 |
|
180 | $ npm install -g node-static
|
181 |
|
182 | ### Example Usage #
|
183 |
|
184 | # serve up the current directory
|
185 | $ static
|
186 | serving "." at http://127.0.0.1:8080
|
187 |
|
188 | # serve up a different directory
|
189 | $ static public
|
190 | serving "public" at http://127.0.0.1:8080
|
191 |
|
192 | # specify additional headers (this one is useful for development)
|
193 | $ static -H '{"Cache-Control": "no-cache, must-revalidate"}'
|
194 | serving "." at http://127.0.0.1:8080
|
195 |
|
196 | # set cache control max age
|
197 | $ static -c 7200
|
198 | serving "." at http://127.0.0.1:8080
|
199 |
|
200 | # show help message, including all options
|
201 | $ static -h
|