This module defines a generic web application interface. It is a common
protocol between web servers and web applications.

The overriding design principles here are performance and generality . To
address performance, this library is built on top of the conduit and
blaze-builder packages. The advantages of conduits over lazy IO have been
debated elsewhere and so will not be addressed here. However, helper functions
like responseLBS allow you to continue using lazy IO if you so desire.

Generality is achieved by removing many variables commonly found in similar
projects that are not universal to all servers. The goal is that the Request
object contains only data which is meaningful in all circumstances.

Please remember when using this package that, while your application may
compile without a hitch against many different servers, there are other
considerations to be taken when moving to a new backend. For example, if you
transfer from a CGI application to a FastCGI one, you might suddenly find you
have a memory leak. Conversely, a FastCGI application would be well served to
preload all templates from disk when first starting; this would kill the
performance of a CGI application.

This package purposely provides very little functionality. You can find various
middlewares, backends and utilities on Hackage. Some of the most commonly used
include:

Extra path information sent by the client. The meaning varies slightly
depending on backend; in a standalone server setting, this is most likely
all information after the domain name. In a CGI application, this would be
the information following the path to the CGI executable itself.
Do not modify this raw value- modify pathInfo instead.

The listening port that the server received this request on. It is
possible for a server to listen on a non-numeric port (i.e., Unix named
socket), in which case this value will be arbitrary. Like serverName,
this value should not be used in URL construction.

This value should not be used, and will be removed in future revisions
of WAI. There is no meaningful way that a backend can indicate whether the
request is actually over a secure channel, due to issues of reverse
proxying.

Q1. Shouldn't it be at the user's discretion to use Builders internally and
then create a stream of ByteStrings?

A1. That would be less efficient, as we wouldn't get cheap concatenation
with the response headers.

Q2. Isn't it really inefficient to convert from ByteString to Builder, and
then right back to ByteString?

A2. No. If the ByteStrings are small, then they will be copied into a larger
buffer, which should be a performance gain overall (less system calls). If
they are already large, then blaze-builder uses an InsertByteString
instruction to avoid copying.

Q3. Doesn't this prevent us from creating comet-style servers, since data
will be cached?

A3. You can force blaze-builder to output a ByteString before it is an
optimal size by sending a flush command.

Middleware is a component that sits between the server and application. It
can do such tasks as GZIP encoding or response caching. What follows is the
general definition of middleware, though a middleware author should feel
free to modify this.

As an example of an alternate type for middleware, suppose you write a
function to load up session information. The session information is simply a
string map [(String, String)]. A logical type signatures for this middleware
might be:

loadSession :: ([(String, String)] -> Application) -> Application

Here, instead of taking a standard Application as its first argument, the
middleware takes a function which consumes the session information as well.