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 ```