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