Network.Wai

wai-3.2.0.1: Web Application Interface.

Safe Haskell | None
Language | Haskell98

Network.Wai

Contents

- Types
- Request
  - Request accessors
- Response
  - Response composers
  - Response accessors
  - Response modifiers
- Middleware composition

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 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:

warp
  http://hackage.haskell.org/package/warp
wai-extra
  http://hackage.haskell.org/package/wai-extra
wai-test
  http://hackage.haskell.org/package/wai-test

Synopsis

- type Application = Request -> (Response -> IO ResponseReceived) -> IO ResponseReceived
- type Middleware = Application -> Application
- data ResponseReceived
- data Request
- defaultRequest :: Request
- data RequestBodyLength
  - = ChunkedBody
  - | KnownLength Word64
- requestMethod :: Request -> Method
- httpVersion :: Request -> HttpVersion
- rawPathInfo :: Request -> ByteString
- rawQueryString :: Request -> ByteString
- requestHeaders :: Request -> RequestHeaders
- isSecure :: Request -> Bool
- remoteHost :: Request -> SockAddr
- pathInfo :: Request -> [Text]
- queryString :: Request -> Query
- requestBody :: Request -> IO ByteString
- vault :: Request -> Vault
- requestBodyLength :: Request -> RequestBodyLength
- requestHeaderHost :: Request -> Maybe ByteString
- requestHeaderRange :: Request -> Maybe ByteString
- requestHeaderReferer :: Request -> Maybe ByteString
- requestHeaderUserAgent :: Request -> Maybe ByteString
- strictRequestBody :: Request -> IO ByteString
- lazyRequestBody :: Request -> IO ByteString
- data Response
- type StreamingBody = (Builder -> IO ()) -> IO () -> IO ()
- data FilePart = FilePart {
  - filePartOffset :: Integer
  - filePartByteCount :: Integer
  - filePartFileSize :: Integer
  }
- responseFile :: Status -> ResponseHeaders -> FilePath -> Maybe FilePart -> Response
- responseBuilder :: Status -> ResponseHeaders -> Builder -> Response
- responseLBS :: Status -> ResponseHeaders -> ByteString -> Response
- responseStream :: Status -> ResponseHeaders -> StreamingBody -> Response
- responseRaw :: (IO ByteString -> (ByteString -> IO ()) -> IO ()) -> Response -> Response
- responseStatus :: Response -> Status
- responseHeaders :: Response -> ResponseHeaders
- responseToStream :: Response -> (Status, ResponseHeaders, (StreamingBody -> IO a) -> IO a)
- mapResponseHeaders :: (ResponseHeaders -> ResponseHeaders) -> Response -> Response
- ifRequest :: (Request -> Bool) -> Middleware -> Middleware
- modifyResponse :: (Response -> Response) -> Middleware

# Types

type Application = Request -> (Response -> IO ResponseReceived) -> IO ResponseReceived

The WAI application.

Note that, since WAI 3.0, this type is structured in continuation passing style to allow for proper safe resource handling. This was handled in the past via other means (e.g., `ResourceT`). As a demonstration:

    app :: Application
    app req respond = bracket_
        (putStrLn "Allocating scarce resource")
        (putStrLn "Cleaning up")
        (respond $ responseLBS status200 [] "Hello World")

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 signature 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.

data ResponseReceived

A special datatype to indicate that the WAI handler has received the response. This is to avoid the need for Rank2Types in the definition of Application.

It is highly advised that only WAI handlers import and use the data constructor for this data type.

Since 3.0.0

# Request

data Request

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

Instances

Show Request |

defaultRequest :: Request

A default, blank request.

Since 2.0.0

data RequestBodyLength

The size of the request body. In the case of chunked bodies, the size will not be known.

Since 1.4.0

Constructors

ChunkedBody |
KnownLength Word64 |

Instances

Show RequestBodyLength |

## Request accessors

requestMethod :: Request -> Method

Request method such as GET.

httpVersion :: Request -> HttpVersion

HTTP version such as 1.1.

rawPathInfo :: Request -> 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.

Middlewares and routing tools should not modify this raw value, as it may be used for such things as creating redirect destinations by applications. Instead, if you are writing a middleware or routing framework, modify the `pathInfo` instead. This is the approach taken by systems like Yesod subsites.

Note: At the time of writing this documentation, there is at least one system (`Network.Wai.UrlMap` from `wai-extra`) that does not follow the above recommendation. Therefore, it is recommended that you test the behavior of your application when using `rawPathInfo` and any form of library that might modify the `Request`.

rawQueryString :: Request -> ByteString

If no query string was specified, this should be empty. This value will include the leading question mark. Do not modify this raw value - modify queryString instead.

requestHeaders :: Request -> RequestHeaders

A list of headers (a pair of key and value) in an HTTP request.

isSecure :: Request -> Bool

Was this request made over an SSL connection?

Note that this value will not tell you if the client originally made this request over SSL, but rather whether the current connection is SSL. The distinction lies with reverse proxies. In many cases, the client will connect to a load balancer over SSL, but connect to the WAI handler without SSL. In such a case, `isSecure` will be `False`, but from a user perspective, there is a secure connection.

remoteHost :: Request -> SockAddr

The client's host information.

pathInfo :: Request -> [Text]

Path info in individual pieces - the URL without a hostname/port and without a query string, split on forward slashes.

queryString :: Request -> Query

Parsed query string information.

requestBody :: Request -> IO ByteString

Get the next chunk of the body. Returns `empty` when the body is fully consumed.

vault :: Request -> Vault

A location for arbitrary data to be shared by applications and middleware.

requestBodyLength :: Request -> RequestBodyLength

The size of the request body. In the case of a chunked request body, this may be unknown.

Since 1.4.0

requestHeaderHost :: Request -> Maybe ByteString

The value of the Host header in a HTTP request.

Since 2.0.0

requestHeaderRange :: Request -> Maybe ByteString

The value of the Range header in a HTTP request.

Since 2.0.0

requestHeaderReferer :: Request -> Maybe ByteString

The value of the Referer header in a HTTP request.

Since 3.2.0

requestHeaderUserAgent :: Request -> Maybe ByteString

The value of the User-Agent header in a HTTP request.

Since 3.2.0

strictRequestBody :: Request -> IO ByteString

Get the request body as a lazy ByteString. However, do not use any lazy I/O, instead reading the entire body into memory strictly.

Since 3.0.1

lazyRequestBody :: Request -> IO ByteString

Get the request body as a lazy ByteString. This uses lazy I/O under the surface, and therefore all typical warnings regarding lazy I/O apply.

Since 1.4.1

# Response

data Response

type StreamingBody = (Builder -> IO ()) -> IO () -> IO ()

Represents a streaming HTTP response body. It's a function of two parameters; the first parameter provides a means of sending another chunk of data, and the second parameter provides a means of flushing the data to the client.

Since 3.0.0

data FilePart

Information on which part to be sent. Sophisticated application handles Range (and If-Range) then create `FilePart`.

Constructors

FilePart |
Fields filePartOffset :: Integer filePartByteCount :: Integer filePartFileSize :: Integer

Instances

Show FilePart |

## Response composers

responseFile :: Status -> ResponseHeaders -> FilePath -> Maybe FilePart -> Response

Creating `Response` from a file.

responseBuilder :: Status -> ResponseHeaders -> Builder -> Response

Creating `Response` from `Builder`.

Some questions and answers about the usage of `Builder` here:

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.

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

Creating `Response` from `ByteString`. This is a wrapper for `responseBuilder`.

responseStream :: Status -> ResponseHeaders -> StreamingBody -> Response

Creating `Response` from a stream of values.

In order to allocate resources in an exception-safe manner, you can use the `bracket` pattern outside of the call to `responseStream`. As a trivial example:

    app :: Application
    app req respond = bracket_
        (putStrLn "Allocating scarce resource")
        (putStrLn "Cleaning up")
        $ respond $ responseStream status200 [] $ \write flush -> do
            write $ fromByteString "Hello\n"
            flush
            write $ fromByteString "World\n"

Note that in some cases you can use `bracket` from inside `responseStream` as well. However, placing the call on the outside allows your status value and response headers to depend on the scarce resource.

Since 3.0.0

responseRaw :: (IO ByteString -> (ByteString -> IO ()) -> IO ()) -> Response -> Response

Create a response for a raw application. This is useful for "upgrade" situations such as WebSockets, where an application requests for the server to grant it raw network access.

This function requires a backup response to be provided, for the case where the handler in question does not support such upgrading (e.g., CGI apps).

In the event that you read from the request body before returning a `responseRaw`, behavior is undefined.

Since 2.1.0

## Response accessors

responseStatus :: Response -> Status

Accessing `Status` in `Response`.

responseHeaders :: Response -> ResponseHeaders

Accessing `ResponseHeaders` in `Response`.

## Response modifiers

responseToStream :: Response -> (Status, ResponseHeaders, (StreamingBody -> IO a) -> IO a)

Converting the body information in `Response` to a `StreamingBody`.

mapResponseHeaders :: (ResponseHeaders -> ResponseHeaders) -> Response -> Response

Apply the provided function to the response header list of the Response.

# Middleware composition

ifRequest :: (Request -> Bool) -> Middleware -> Middleware

conditionally apply a `Middleware`

modifyResponse :: (Response -> Response) -> Middleware

apply a function that modifies a response as a `Middleware`