node-staticp

node-staticp
===========

> a simple, rfc 2616 compliant file streaming module for node plus postscript support

node-staticp has an in-memory file cache, making it highly efficient.
node-staticp understands and supports conditional GET and HEAD requests.
node-staticp was inspired by some of the other static-file serving modules out there,
such as node-paperboy and antinode.

The postscript feature will append a common include file to every html document response body.
Both a postscript in the dictionary sense, and a feature well-suited to postload content with a script.

Synopsis
--------

var static = require('node-staticp');

//
// Create a node-staticp server instance to serve the './public' folder
//
var file = new(static.Server)('./public');

require('http').createServer(function (request, response) {
request.addListener('end', function () {
//
// Serve files!
//
file.serve(request, response);
});
}).listen(8080);

API
---

$3

Creating a file server instance is as simple as:

new static.Server();

This will serve files in the current directory. If you want to serve files in a specific
directory, pass it as the first argument:

new static.Server('./public');

You can also specify how long the client is supposed to cache the files node-staticp serves:

new static.Server('./public', { cache: 3600 });

This will set the Cache-Control header, telling clients to cache the file for an hour.
This is the default setting.

$3

To serve files under a directory, simply call the serve method on a Server instance, passing it
the HTTP request and response object:

var fileServer = new static.Server('./public');

require('http').createServer(function (request, response) {
request.addListener('end', function () {
fileServer.serve(request, response);
});
}).listen(8080);

$3

If you want to serve a specific file, like an error page for example, use the serveFile method:

fileServer.serveFile('/error.html', 500, {}, request, response);

This will serve the error.html file, from under the file root directory, with a 500 status code.
For example, you could serve an error page, when the initial request wasn't found:

require('http').createServer(function (request, response) {
request.addListener('end', function () {
fileServer.serve(request, response, function (e, res) {
if (e && (e.status === 404)) { // If the file wasn't found
fileServer.serveFile('/not-found.html', 404, {}, request, response);
}
});
});
}).listen(8080);

More on intercepting errors bellow.

$3

An optional callback can be passed as last argument, it will be called every time a file
has been served successfully, or if there was an error serving the file:

var fileServer = new static.Server('./public');

require('http').createServer(function (request, response) {
request.addListener('end', function () {
fileServer.serve(request, response, function (err, result) {
if (err) { // There was an error serving the file
sys.error("Error serving " + request.url + " - " + err.message);

// Respond to the client
response.writeHead(err.status, err.headers);
response.end();
}
});
});
}).listen(8080);

Note that if you pass a callback, and there is an error serving the file, node-staticp
will not respond to the client. This gives you the opportunity to re-route the request,
or handle it differently.

For example, you may want to interpret a request as a static request, but if the file isn't found,
send it to an application.

If you only want to listen for errors, you can use event listeners:

fileServer.serve(request, response).addListener('error', function (err) {
sys.error("Error serving " + request.url + " - " + err.message);
});

With this method, you don't have to explicitly send the response back, in case of an error.

$3

#### cache #

Sets the Cache-Control header.

example: { cache: 7200 }

Passing a number will set the cache duration to that number of seconds.
Passing false will disable the Cache-Control header.

> Defaults to 3600

#### postscript #

Relative path of a file to append to every HTML response body.

example: { postscript: "inc/postscript.html" }

> Defaults to false (disabled)

#### serverInfo #

Sets the Server header.

example: { serverInfo: "myserver" }

> Defaults to node-staticp/{version}

#### headers #

Sets response headers.

example: { 'X-Hello': 'World!' }

> defaults to {}

Command Line Interface
----------------------

node-staticp also provides a CLI.

$3

$ npm install -g node-staticp

$3

# serve up the current directory
$ static
serving "." at http://127.0.0.1:8080

# serve up a different directory
$ static public
serving "public" at http://127.0.0.1:8080

# specify additional headers (this one is useful for development)
$ static -H '{"Cache-Control": "no-cache, must-revalidate"}'
serving "." at http://127.0.0.1:8080

# set cache control max age
$ static -c 7200
serving "." at http://127.0.0.1:8080

# show help message, including all options
$ static -h