The Interface

The interface itself is very straight-forward: an application takes a request and returns a response. A response is an HTTP status, a list of headers and a response body. A request contains various information: the requested path, query string, request body, HTTP version, and so on.

In order to handle resource management in an exception-safe manner, we use continuation passing style for returning the response, similar to how the bracket function works. This makes our definition of an application look like:

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

The first argument is a Request, which shouldn’t be too surprising. The second argument is the continuation, or what we should do with a Response. Generally speaking, this will just be sending it to the client. We use the special ResponseReceived type to ensure that the application does in fact call the continuation.

This may seem a little strange, but usage is pretty straight-forward, as we’ll demonstrate below.

Hello World

To demonstrate the simplicity of WAI, let’s look at a hello world example. In this example, we’re going to use the OverloadedStrings language extension to avoid explicitly packing string values into bytestrings.

{-# LANGUAGE OverloadedStrings #-}
import Network.Wai
import Network.HTTP.Types (status200)
import Network.Wai.Handler.Warp (run)

application _ respond = respond $
  responseLBS status200 [("Content-Type", "text/plain")] "Hello World"

main = run 3000 application

Lines 2 through 4 perform our imports. Warp is provided by the warp package, and is the premiere WAI backend. WAI is also built on top of the http-types package, which provides a number of datatypes and convenience values, including status200.

First we define our application. Since we don’t care about the specific request parameters, we ignore the first argument to the function, which contains the request value. The second argument is our "send a response" function, which we immediately use. The response value we send is built from a lazy ByteString (thus responseLBS), with status code 200 ("OK"), a text/plain content type, and a body containing the words "Hello World". Pretty straight-forward.

Resource allocation

Let’s make this a little more interesting, and try to allocate a resource for our response. We’ll create an MVar in our main function to track the number of requests, and then hold that MVar while sending each response.

{-# LANGUAGE OverloadedStrings #-}
import           Blaze.ByteString.Builder           (fromByteString)
import           Blaze.ByteString.Builder.Char.Utf8 (fromShow)
import           Control.Concurrent.MVar
import           Data.Monoid                        ((<>))
import           Network.HTTP.Types                 (status200)
import           Network.Wai
import           Network.Wai.Handler.Warp           (run)

application countRef _ respond = do
    modifyMVar countRef $ \count -> do
        let count' = count + 1
            msg = fromByteString "You are visitor number: " <>
                  fromShow count'
        responseReceived <- respond $ responseBuilder
            status200
            [("Content-Type", "text/plain")]
            msg
        return (count', responseReceived)

main = do
    visitorCount <- newMVar 0
    run 3000 $ application visitorCount

This is where WAI’s continuation interface shines. We’re able to use the standard modifyMVar function to acquire the MVar lock and send our response. Note how we thread the responseReceived value through, though we never actually use the value for anything. It is merely witness to the fact that we have, in fact, sent a response.

Notice also how we take advantage of Builders in constructing our msg value. Instead of concatenating two ByteStrings together directly, we monoidally append two different Builder values. The advantage to this is that the results will end up being copied directly into the final output buffer, instead of first being copied into a temporary ByteString buffer to only later be copied into the final buffer.

Streaming response

Let’s give our streaming interface a test as well:

{-# LANGUAGE OverloadedStrings #-}
import           Blaze.ByteString.Builder (fromByteString)
import           Control.Concurrent       (threadDelay)
import           Network.HTTP.Types       (status200)
import           Network.Wai
import           Network.Wai.Handler.Warp (run)

application _ respond = respond $ responseStream status200 [("Content-Type", "text/plain")]
    $ \send flush -> do
        send $ fromByteString "Starting the response...\n"
        flush
        threadDelay 1000000
        send $ fromByteString "All done!\n"

main = run 3000 application

We use responseStream, and our third argument is a function which takes our "send a builder" and "flush the buffer" functions. Notice how we flush after our first chunk of data, to make sure the client sees the data immediately. However, there’s no need to flush at the end of a response. WAI requires that the handler automatically flush at the end of a stream.

Middleware

In addition to allowing our applications to run on multiple backends without code changes, the WAI allows us another benefits: middleware. Middleware is essentially an application transformer, taking one application and returning another one.

Middleware components can be used to provide lots of services: cleaning up URLs, authentication, caching, JSON-P requests. But perhaps the most useful and most intuitive middleware is gzip compression. The middleware works very simply: it parses the request headers to determine if a client supports compression, and if so compresses the response body and adds the appropriate response header.

The great thing about middlewares is that they are unobtrusive. Let’s see how we would apply the gzip middleware to our hello world application.

{-# LANGUAGE OverloadedStrings #-}
import Network.Wai
import Network.Wai.Handler.Warp (run)
import Network.Wai.Middleware.Gzip (gzip, def)
import Network.HTTP.Types (status200)

application _ respond = respond $ responseLBS status200 [("Content-Type", "text/plain")]
                       "Hello World"

main = run 3000 $ gzip def application

We added an import line to actually have access to the middleware, and then simply applied gzip to our application. You can also chain together multiple middlewares: a line such as gzip False $ jsonp $ othermiddleware $ myapplication is perfectly valid. One word of warning: the order the middleware is applied can be important. For example, jsonp needs to work on uncompressed data, so if you apply it after you apply gzip, you’ll have trouble.