strata/doc/09_static_files.js

A modular, streaming HTTP server

/*
# Static Files

Web applications typically contain a directory of static files that are publicly
accessible. These are usually image and other static asset files that do not
need to be dynamically generated by the application but are instead generated
at deploy time so that they can be served quickly and efficiently.

The `strata.file` middleware serves static files efficiently thanks to node's
excellent I/O handling. You use it like this:

    strata.file(app, "/path/to/public");

The first argument here is the downstream app, as is the case with all Strata
middleware. The second argument is the path to the directory where static files
are kept. When the request comes in, this middleware will check to see if the
request URL matches any of the files in the given directory. If it does, the
middleware streams back the file without passing the request to the downstream
app. If not, the request passes through like normal.

Because of the way this works, you'll normally want to put a `strata.file`
middleware *upstream* from any application logic. This prevents your app from
wasting time processing a request that is only meant to serve a static file
anyway.

The app below demonstrates how to serve any file in the current working
directory (or any of its subdirectories).

    var path = require("path");
    var strata = require("strata");

    // Use the current working directory as document root for this example.
    var root = path.resolve(".");

    strata.use(strata.commonLogger);
    strata.use(strata.file, root);

    strata.run();

## Indexes

The `strata.file` middleware accepts an optional 3rd argument, `index` that
allows you to specify the name of a file that should be served when a directory
is the target of the request. This is typically used to display an "index.html"
file, for example. Use it like this:

    strata.file(app, root, "index.html");
    strata.file(app, root, ["index.html", "index.htm"]);

As you can see, the `index` may be the name of a single file or an array of file
names to try. When searching for a file to return in response to a request for a
directory, each file name is tried in order. If a match is found it is served.
Otherwise the middleware passes the request downstream as usual.

## Automatically Generating Indexes

You can use the `strata.directory` middleware to automatically generate an HTML
listing of the files in a directory, with basic information about and a link to
each one. This middleware behaves similarly to
[Apache's mod_autoindex](http://httpd.apache.org/docs/2.0/mod/mod_autoindex.html)
and [nginx's autoindex module](http://wiki.nginx.org/HttpAutoindexModule).

For example, to create a simple file server with an auto-generated directory
listing of each directory's contents, you could modify the sample app provided
above and add a `strata.directory` middleware immediately after `strata.file`
in the middleware pipeline.
*/

var path = require("path");
var strata = require("strata");

// Use the current working directory as document root for this example.
var root = path.resolve(".");

strata.use(strata.commonLogger);
strata.use(strata.file, root);
strata.use(strata.directory, root);

strata.run();

/*
As in previous chapters, you can save the above code to a file named `app.js`
and run it with the `node` executable:

    $ node app.js

You can then view the app file (or, similarly, any other file in its same
directory) at [http://localhost:1982/app.js](http://localhost:1982/app.js).
*/