Network.Wai

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 Source for the request body and Enumerator for the response bodies. The advantages of this approach over lazy IO have been debated elsewhere.

Nonetheless, many people find these data structures difficult to work with. For that reason, this library includes the Network.Wai.Enumerator module to provide more familiar abstractions, including lazy IO.

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.

A final note: 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.

Data types

Request method

type Method = ByteString

HTTP request method. Since the HTTP protocol allows arbitrary request methods, we leave this open as a ByteString. Please note the request methods are case-sensitive.

HTTP protocol versions

type HttpVersion = ByteString

Version of HTTP protocol used in current request. The value given here should be everything following the "HTTP/" line in a request. In other words, HTTP/1.1 -> "1.1", HTTP/1.0 -> "1.0".

http09 :: HttpVersion

HTTP/0.9

http10 :: HttpVersion

HTTP/1.0

http11 :: HttpVersion

HTTP/1.1

Case-insensitive byte strings

data CIByteString

A case insensitive bytestring, where the Eq and Ord instances do comparisons based on the lower-cased version of this string. For efficiency, this datatype contains both the original and lower-case version of the string; this means there is no need to lower-case the bytestring for every comparison.

Please note that this datatype has an IsString instance, which can allow for very concise code when using the OverloadedStrings language extension.

Constructors

CIByteString

Fields

ciOriginal :: !ByteString

ciLowerCase :: !ByteString

Instances

Eq CIByteString

Data CIByteString

Ord CIByteString

Read CIByteString

Show CIByteString

Typeable CIByteString

IsString CIByteString

mkCIByteString :: ByteString -> CIByteString

Convert a regular bytestring to a case-insensitive bytestring.

Request header names

type RequestHeader = CIByteString

Headers sent from the client to the server. Note that this is a case-insensitive string, as the HTTP spec specifies.

type RequestHeaders = [(RequestHeader, ByteString)]

Response header names

type ResponseHeader = CIByteString

Headers sent from the server to the client. Note that this is a case-insensitive string, as the HTTP spec specifies.

type ResponseHeaders = [(ResponseHeader, ByteString)]

Response status code

data Status

HTTP status code; a combination of the integral code and a status message. Equality is determined solely on the basis of the integral code.

Constructors

Status

Fields

statusCode :: Int

statusMessage :: ByteString

Instances

Eq Status

Show Status

status200 :: Status

OK

status301 :: Status

Moved Permanently

status302 :: Status

Found

status303 :: Status

See Other

status400 :: Status

Bad Request

status401 :: Status

Unauthorized

status403 :: Status

Forbidden

status404 :: Status

Not Found

status405 :: Status

Method Not Allowed

status500 :: Status

Internal Server Error

WAI interface

data Request

Information on the request sent by the client. This abstracts away the details of the underlying implementation.

Constructors

Request

Fields

requestMethod :: Method

httpVersion :: HttpVersion

pathInfo :: ByteString

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.

queryString :: ByteString

If no query string was specified, this should be empty.

serverName :: ByteString

serverPort :: Int

requestHeaders :: [(RequestHeader, ByteString)]

Was this request made over an SSL connection?

isSecure :: Bool

Log the given line in some method; how this is accomplished is server-dependant.

errorHandler :: String -> IO ()

remoteHost :: SockAddr

The client's host information.

Instances

Typeable Request

data Response

Constructors

ResponseFile Status ResponseHeaders FilePath

ResponseBuilder Status ResponseHeaders Builder

ResponseEnumerator (forall a. ResponseEnumerator a)

Instances

Typeable Response

type ResponseEnumerator a = (Status -> ResponseHeaders -> Iteratee Builder IO a) -> IO a

responseEnumerator :: Response -> ResponseEnumerator a

type Application = Request -> Iteratee ByteString IO Response

type Middleware = Application -> Application

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.

Response body smart constructors

responseLBS :: Status -> ResponseHeaders -> ByteString -> Response