rc-web@69: node-static
rc-web@69: ===========
rc-web@69: 
rc-web@69: > a simple, *rfc 2616 compliant* file streaming module for [node](http://nodejs.org)
rc-web@69: 
rc-web@69: node-static has an in-memory file cache, making it highly efficient.
rc-web@69: node-static understands and supports *conditional GET* and *HEAD* requests.
rc-web@69: node-static was inspired by some of the other static-file serving modules out there,
rc-web@69: such as node-paperboy and antinode.
rc-web@69: 
rc-web@69: Synopsis
rc-web@69: --------
rc-web@69: 
rc-web@69:     var static = require('node-static');
rc-web@69: 
rc-web@69:     //
rc-web@69:     // Create a node-static server instance to serve the './public' folder
rc-web@69:     //
rc-web@69:     var file = new static.Server('./public');
rc-web@69: 
rc-web@69:     require('http').createServer(function (request, response) {
rc-web@69:         request.addListener('end', function () {
rc-web@69:             //
rc-web@69:             // Serve files!
rc-web@69:             //
rc-web@69:             file.serve(request, response);
rc-web@69:         }).resume();
rc-web@69:     }).listen(8080);
rc-web@69: 
rc-web@69: API
rc-web@69: ---
rc-web@69: 
rc-web@69: ### Creating a node-static Server #
rc-web@69: 
rc-web@69: Creating a file server instance is as simple as:
rc-web@69: 
rc-web@69:     new static.Server();
rc-web@69: 
rc-web@69: This will serve files in the current directory. If you want to serve files in a specific
rc-web@69: directory, pass it as the first argument:
rc-web@69: 
rc-web@69:     new static.Server('./public');
rc-web@69: 
rc-web@69: You can also specify how long the client is supposed to cache the files node-static serves:
rc-web@69: 
rc-web@69:     new static.Server('./public', { cache: 3600 });
rc-web@69: 
rc-web@69: This will set the `Cache-Control` header, telling clients to cache the file for an hour.
rc-web@69: This is the default setting.
rc-web@69: 
rc-web@69: ### Serving files under a directory #
rc-web@69: 
rc-web@69: To serve files under a directory, simply call the `serve` method on a `Server` instance, passing it
rc-web@69: the HTTP request and response object:
rc-web@69:  
rc-web@69:     var static = require('node-static');
rc-web@69: 
rc-web@69:     var fileServer = new static.Server('./public');
rc-web@69: 
rc-web@69:     require('http').createServer(function (request, response) {
rc-web@69:         request.addListener('end', function () {
rc-web@69:             fileServer.serve(request, response);
rc-web@69:         }).resume();
rc-web@69:     }).listen(8080);
rc-web@69: 
rc-web@69: ### Serving specific files #
rc-web@69: 
rc-web@69: If you want to serve a specific file, like an error page for example, use the `serveFile` method:
rc-web@69: 
rc-web@69:     fileServer.serveFile('/error.html', 500, {}, request, response);
rc-web@69: 
rc-web@69: This will serve the `error.html` file, from under the file root directory, with a `500` status code.
rc-web@69: For example, you could serve an error page, when the initial request wasn't found:
rc-web@69: 
rc-web@69:     require('http').createServer(function (request, response) {
rc-web@69:         request.addListener('end', function () {
rc-web@69:             fileServer.serve(request, response, function (e, res) {
rc-web@69:                 if (e && (e.status === 404)) { // If the file wasn't found
rc-web@69:                     fileServer.serveFile('/not-found.html', 404, {}, request, response);
rc-web@69:                 }
rc-web@69:             });
rc-web@69:         }).resume();
rc-web@69:     }).listen(8080);
rc-web@69: 
rc-web@69: More on intercepting errors bellow.
rc-web@69: 
rc-web@69: ### Intercepting errors & Listening #
rc-web@69: 
rc-web@69: An optional callback can be passed as last argument, it will be called every time a file
rc-web@69: has been served successfully, or if there was an error serving the file:
rc-web@69: 
rc-web@69:     var static = require('node-static');
rc-web@69:     
rc-web@69:     var fileServer = new static.Server('./public');
rc-web@69: 
rc-web@69:     require('http').createServer(function (request, response) {
rc-web@69:         request.addListener('end', function () {
rc-web@69:             fileServer.serve(request, response, function (err, result) {
rc-web@69:                 if (err) { // There was an error serving the file
rc-web@69:                     sys.error("Error serving " + request.url + " - " + err.message);
rc-web@69: 
rc-web@69:                     // Respond to the client
rc-web@69:                     response.writeHead(err.status, err.headers);
rc-web@69:                     response.end();
rc-web@69:                 }
rc-web@69:             });
rc-web@69:         }).resume();
rc-web@69:     }).listen(8080);
rc-web@69: 
rc-web@69: Note that if you pass a callback, and there is an error serving the file, node-static
rc-web@69: *will not* respond to the client. This gives you the opportunity to re-route the request,
rc-web@69: or handle it differently.
rc-web@69: 
rc-web@69: For example, you may want to interpret a request as a static request, but if the file isn't found,
rc-web@69: send it to an application.
rc-web@69: 
rc-web@69: If you only want to *listen* for errors, you can use *event listeners*:
rc-web@69: 
rc-web@69:     fileServer.serve(request, response).addListener('error', function (err) {
rc-web@69:         sys.error("Error serving " + request.url + " - " + err.message);
rc-web@69:     });
rc-web@69: 
rc-web@69: With this method, you don't have to explicitly send the response back, in case of an error.
rc-web@69: 
rc-web@69: ### Options when creating an instance of `Server` #
rc-web@69: 
rc-web@69: #### `cache` #
rc-web@69: 
rc-web@69: Sets the `Cache-Control` header.
rc-web@69: 
rc-web@69: example: `{ cache: 7200 }`
rc-web@69: 
rc-web@69: Passing a number will set the cache duration to that number of seconds.
rc-web@69: Passing `false` will disable the `Cache-Control` header.
rc-web@69: 
rc-web@69: > Defaults to `3600`
rc-web@69: 
rc-web@69: 
rc-web@69: #### `serverInfo` #
rc-web@69: 
rc-web@69: Sets the `Server` header.
rc-web@69: 
rc-web@69: example: `{ serverInfo: "myserver" }`
rc-web@69: 
rc-web@69: > Defaults to `node-static/{version}`
rc-web@69: 
rc-web@69: #### `headers` #
rc-web@69: 
rc-web@69: Sets response headers.
rc-web@69: 
rc-web@69: example: `{ 'X-Hello': 'World!' }`
rc-web@69: 
rc-web@69: > defaults to `{}`
rc-web@69: 
rc-web@69: #### `gzip` #
rc-web@69: 
rc-web@69: Enable support for sending compressed responses.  This will enable a check for a
rc-web@69: file with the same name plus '.gz' in the same folder.  If the compressed file is
rc-web@69: found and the client has indicated support for gzip file transfer, the contents
rc-web@69: of the .gz file will be sent in place of the uncompressed file along with a
rc-web@69: Content-Encoding: gzip header to inform the client the data has been compressed.
rc-web@69: 
rc-web@69: example: `{ gzip: true }`
rc-web@69: example: `{ gzip: /^\/text/ }`
rc-web@69: 
rc-web@69: Passing `true` will enable this check for all files.
rc-web@69: Passing a RegExp instance will only enable this check if the content-type of the
rc-web@69: respond would match that RegExp using its test() method.
rc-web@69: 
rc-web@69: > Defaults to `false`
rc-web@69: 
rc-web@69: 
rc-web@69: Command Line Interface
rc-web@69: ----------------------
rc-web@69: 
rc-web@69: `node-static` also provides a CLI.
rc-web@69: 
rc-web@69: ### Installation #
rc-web@69: 
rc-web@69:     $ npm install -g node-static
rc-web@69: 
rc-web@69: ### Example Usage #
rc-web@69: 
rc-web@69:     # serve up the current directory
rc-web@69:     $ static
rc-web@69:     serving "." at http://127.0.0.1:8080
rc-web@69: 
rc-web@69:     # serve up a different directory
rc-web@69:     $ static public
rc-web@69:     serving "public" at http://127.0.0.1:8080
rc-web@69: 
rc-web@69:     # specify additional headers (this one is useful for development)
rc-web@69:     $ static -H '{"Cache-Control": "no-cache, must-revalidate"}'
rc-web@69:     serving "." at http://127.0.0.1:8080
rc-web@69: 
rc-web@69:     # set cache control max age
rc-web@69:     $ static -c 7200
rc-web@69:     serving "." at http://127.0.0.1:8080
rc-web@69: 
rc-web@69:     # show help message, including all options
rc-web@69:     $ static -h