wai-0.3.2: Web Application Interface.Source codeContentsIndex
Network.Wai
Contents
Data types
Request method
HTTP protocol versions
Case-insensitive byte strings
Request header names
Response header names
Response status code
WAI interface
Response body smart constructors
Description

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 enumerator package. The advantages of this approach over lazy IO have been debated elsewhere. 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.

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.

Synopsis
type Method = ByteString
type HttpVersion = ByteString
http09 :: HttpVersion
http10 :: HttpVersion
http11 :: HttpVersion
data CIByteString = CIByteString {
ciOriginal :: !ByteString
ciLowerCase :: !ByteString
}
mkCIByteString :: ByteString -> CIByteString
type RequestHeader = CIByteString
type RequestHeaders = [(RequestHeader, ByteString)]
type ResponseHeader = CIByteString
type ResponseHeaders = [(ResponseHeader, ByteString)]
data Status = Status {
statusCode :: Int
statusMessage :: ByteString
}
status200 :: Status
statusOK :: Status
status201 :: Status
statusCreated :: Status
status206 :: Status
statusPartialContent :: Status
status301 :: Status
statusMovedPermanently :: Status
status302 :: Status
statusFound :: Status
status303 :: Status
statusSeeOther :: Status
status400 :: Status
statusBadRequest :: Status
status401 :: Status
statusUnauthorized :: Status
status403 :: Status
statusForbidden :: Status
status404 :: Status
statusNotFound :: Status
status405 :: Status
statusNotAllowed :: Status
status500 :: Status
statusServerError :: Status
data Request = Request {
requestMethod :: Method
httpVersion :: HttpVersion
pathInfo :: ByteString
queryString :: ByteString
serverName :: ByteString
serverPort :: Int
requestHeaders :: [(RequestHeader, ByteString)]
isSecure :: Bool
errorHandler :: String -> IO ()
remoteHost :: SockAddr
}
data Response
= ResponseFile Status ResponseHeaders FilePath
| ResponseBuilder Status ResponseHeaders Builder
| ResponseEnumerator (forall a. ResponseEnumerator a)
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
responseLBS :: Status -> ResponseHeaders -> ByteString -> Response
Data types
Request method
type Method = ByteStringSource
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 = ByteStringSource
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 :: HttpVersionSource
HTTP/0.9
http10 :: HttpVersionSource
HTTP/1.0
http11 :: HttpVersionSource
HTTP/1.1
Case-insensitive byte strings
data CIByteString Source

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
ciOriginal :: !ByteString
ciLowerCase :: !ByteString
show/hide Instances
mkCIByteString :: ByteString -> CIByteStringSource
Convert a regular bytestring to a case-insensitive bytestring.
Request header names
type RequestHeader = CIByteStringSource
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)]Source
Response header names
type ResponseHeader = CIByteStringSource
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)]Source
Response status code
data Status Source
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
statusCode :: Int
statusMessage :: ByteString
show/hide Instances
status200 :: StatusSource
statusOK :: StatusSource
OK
status201 :: StatusSource
statusCreated :: StatusSource
Created
status206 :: StatusSource
statusPartialContent :: StatusSource
Partial Content
status301 :: StatusSource
statusMovedPermanently :: StatusSource
Moved Permanently
status302 :: StatusSource
statusFound :: StatusSource
Found
status303 :: StatusSource
statusSeeOther :: StatusSource
See Other
status400 :: StatusSource
statusBadRequest :: StatusSource
Bad Request
status401 :: StatusSource
statusUnauthorized :: StatusSource
Unauthorized
status403 :: StatusSource
statusForbidden :: StatusSource
Forbidden
status404 :: StatusSource
statusNotFound :: StatusSource
Not Found
status405 :: StatusSource
statusNotAllowed :: StatusSource
Method Not Allowed
status500 :: StatusSource
statusServerError :: StatusSource
Internal Server Error
WAI interface
data Request Source
Information on the request sent by the client. This abstracts away the details of the underlying implementation.
Constructors
Request
requestMethod :: Method
httpVersion :: HttpVersion
pathInfo :: ByteStringExtra 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 :: ByteStringIf 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 :: BoolLog the given line in some method; how this is accomplished is server-dependant.
errorHandler :: String -> IO ()
remoteHost :: SockAddrThe client's host information.
show/hide Instances
data Response Source
Constructors
ResponseFile Status ResponseHeaders FilePath
ResponseBuilder Status ResponseHeaders Builder
ResponseEnumerator (forall a. ResponseEnumerator a)
show/hide Instances
type ResponseEnumerator a = (Status -> ResponseHeaders -> Iteratee Builder IO a) -> IO aSource
responseEnumerator :: Response -> ResponseEnumerator aSource
type Application = Request -> Iteratee ByteString IO ResponseSource
type Middleware = Application -> ApplicationSource

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 -> ResponseSource
Produced by Haddock version 2.6.1