More docs.

CHANGES

@@ -2,6 +2,9 @@
 
   * Added requestTime environment variable.
 
+  * Added manual chapters on serving static files, rewriting URL's, and gzip
+    compression.
+
 = 0.5.3 / 2011-09-20
 
   * Removed multipart.File#unlink

doc/02_applications.js

@@ -10,8 +10,9 @@ The environment is simply a plain object with several CGI-like properties that
 pertain to the environment the app is operating in. This object is not the same
 as `process.env`. Whereas `process.env` contains information about the machine
 environment the node process is running in, the Strata environment includes
-information about the request, HTTP headers, the server, etc. This object is
-unique to the current request.
+information about the request, HTTP headers, the server, etc., similar to PHP's
+special [$_SERVER](http://php.net/manual/en/reserved.variables.server.php)
+variable. This object is unique to the current request.
 
 The callback is a function that is used to send the response when the app is
 ready to do so. It must be called with three arguments: the HTTP status code,

doc/08_static_files.js

@@ -0,0 +1,53 @@
+/*
+# 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.static` middleware serves static files efficiently thanks to node's
+excellent I/O handling. You use it like this:
+
+    strata.static(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.static`
+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 simply serves any file in the current working
+directory (or any of its subdirectories).
+*/
+
+var path = require("path"),
+    strata = require("strata"),
+    Builder = strata.Builder;
+
+// For the sake of this example, the root directory where we store static files
+// is the current working directory (i.e. $PWD).
+var root = path.resolve(".");
+
+var app = new Builder;
+
+app.use(strata.commonLogger);
+app.use(strata.static, root);
+
+module.exports = app;
+
+/*
+As in previous chapters, you can save the above code to a file named `app.js`
+and run it with:
+
+    $ strata 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).
+*/

doc/11_rewriting_urls.js

@@ -0,0 +1,84 @@
+/*
+# Rewriting URL's
+
+Occasionally your app may need to rewrite an incoming URL to be something else.
+For example, you may want to rewrite all requests for `/oldpage.html` to
+`newpage.html` without sending the client a full-blown redirect to the new
+content.
+
+The `strata.rewrite` middleware can perform this function for you. Given the
+scenario above, you might use it like this:
+
+    strata.rewrite(app, "/oldpage.html", "/newpage.html");
+
+Similar to Apache's [mod_rewrite](http://httpd.apache.org/docs/current/mod/mod_rewrite.html),
+`strata.rewrite` simply takes a regular expression (or a string) to match
+against the value of the environment's `pathInfo` and a replacement string. If
+the expression matches, the `pathInfo` is rewritten for all downstream apps with
+the replacement value using a simple [String#replace](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String/replace).
+
+## NGINX Rewrite Example
+
+If you've used the [NGINX](http://nginx.net/) web server before as a reverse
+proxy, you may have used a rewrite directive similar the following in your
+`nginx.conf`:
+
+    if (-f $request_filename.html) {
+      rewrite (.*) $1.html break;
+    }
+
+Basically, what this directive is saying is that if there is a file that exists
+on disk with the same name as the file name that was given in the request URL
+plus ".html", then rewrite the request to serve that file. This is a very common
+type of rewrite to perform that lets clients leave off the ".html" suffix when
+requesting HTML files. It also has other uses that are outside the scope of this
+chapter.
+
+The example app below performs the same function in Strata.
+*/
+
+var path = require("path"),
+    strata = require("strata"),
+    Builder = strata.Builder;
+
+// For the sake of this example, the root directory where we store static files
+// is the current working directory (i.e. $PWD).
+var root = path.resolve(".");
+
+// This middleware checks for a file in the given `root` directory that has an
+// ".html" suffix but otherwise corresponds to the path given in the URL.
+function checkHtml(app, root) {
+    return function (env, callback) {
+        var pathInfo = env.pathInfo;
+
+        // Check to see if a .html version of the requested file exists.
+        if (path.existsSync(path.join(root, pathInfo) + ".html")) {
+            // Rewrite the pathInfo for downstream apps.
+            env.pathInfo = pathInfo + ".html";
+        }
+
+        app(env, function (status, headers, body) {
+            // Reset the value of pathInfo for upstream apps.
+            env.pathInfo = pathInfo;
+            callback(status, headers, body);
+        });
+    }
+}
+
+var app = new Builder;
+
+app.use(strata.commonLogger);
+app.use(checkHtml, root); // Check for .html in front of a static file server.
+app.use(strata.static, root);
+
+module.exports = app;
+
+/*
+As in previous chapters, you can save the above code to a file named `app.js`
+and run it with:
+
+    $ strata app.js
+
+Make sure you run that command from a directory where you also have another file
+named `index.html`. Then view that file at [http://localhost:1982/index](http://localhost:1982/index).
+*/

doc/13_gzip_compression.js

@@ -0,0 +1,65 @@
+/*
+# Gzip Encoding
+
+Strata ships with a gzip module similar to Apache's [mod_deflate](http://httpd.apache.org/docs/2.0/mod/mod_deflate.html)
+that allows you to compress content that you send over the network on the fly.
+The main benefit of compressing content before you send it over the network is
+that it can be transferred more quickly since there is less data to send,
+resulting in a significant drop in overall response time.
+
+In Strata, gzip compression is implemented as a piece of middleware. You use it
+like this:
+
+    strata.gzip(app, /text|javascript/);
+
+As with all other Strata middleware, the `app` argument is the downstream app
+whose response will be compressed. The second argument is a regular expression
+that will be used to match the value of the `Content-Type` header from the
+downstream app. If the expression matches, the content is compressed. Otherwise
+it is passed through untouched.
+
+The default regular expression used in Strata's gzip middleware is
+`/text|javascript|json/i`. This is designed to match all text types (i.e.
+`text/html`, `text/css`, etc.) as well as responses that contain JavaScript or
+[JSON](http://www.json.org/). You only need to use your own regular expression
+if the default doesn't suit your needs.
+
+Since `strata.gzip` depends on reading the value of the `Content-Type` header,
+it is a good idea to insert it into the middleware pipeline *upstream* from
+`strata.contentType` if it's being used.
+
+It is important to note that, thanks to Strata's excellent content negotiation
+abilities, compressed responses will never be sent to clients that are not able
+to accept them.
+
+The app below demonstrates how gzip compression should be configured in front
+of an app that serves static files.
+*/
+
+var strata = require("strata"),
+    Builder = strata.Builder;
+
+var app = new Builder;
+
+app.use(strata.commonLogger);
+app.use(strata.gzip);
+app.use(strata.static, __dirname);
+
+module.exports = app;
+
+/*
+As in previous chapters, you can save the above code to a file named `app.js`
+and run it with:
+
+    $ strata app.js
+
+The app will serve any static files that are in the same directory on disk. To
+observe the gzip compression, use a client that is capable of accepting gzip
+encoding (i.e. sends an "Accept-Encoding: gzip" header in the request) and
+request a text or JavaScript file from the app.
+
+For example, to request the app file itself you could paste the following URL
+into your browser:
+
+    http://localhost:1982/app.js
+*/