Editing WebApplicationInterface (section)

== Specification Overview ==

The WAI interface has two sides: the "server" side, and the "application" or "framework" side.  The server calls a function that is provided by the application side.  How the server is configured with this function is not a part of this specification.

=== The Application/Framework Side ===

An application is simply a function from an environment (described later) to a response.  We use the word "application" here in a very general sense.  WAI is not intended for writing applications directly.  Rather it is an interface for writing frameworks upon.  However, we will continue to use the word application to refer both to applications and frameworks.  A simple application might look like this:

<haskell>
import Data.ByteString.Char8 (pack)

simpleApp _ = return (status, responseHeaders, enumerator) 
    where
      status = 200
      responseHeaders = [(pack "Content-type", pack "text/plain")]
      enumerator f z =
        case f z (pack "Hello world!\n") of
          Left z'  -> z'
          Right z' -> z'
</haskell>

This simple application completely ignores the environment given to it.  A real application would use the environment to examine the request URL, etc.

=== The Server Side ===

The server calls the application function once for each request it receives from an HTTP client, that is directed at the application.  Here is a simple CGI web server:

<haskell>
{-# LANGUAGE OverloadedStrings #-}

module Wai.CgiAdapter
    ( serveWithCgi
    ) where

import Control.Arrow ((***))
import Control.Exception (catch)
import Control.Monad (forM_)
import Data.ByteString (hGet, putStr, null)
import Data.ByteString.Char8 (pack)
import Data.List (partition, isPrefixOf)
import Data.Maybe (fromJust)
import Network.Wai (Application, Environment(..), Method(..))
import Prelude hiding (catch, null, putStr)
import System.Environment (getEnv, getEnvironment)
import System.IO (hFlush, hPutStr, stderr, stdin, stdout)

serveWithCgi :: Application -> IO ()
serveWithCgi application = do
  method <- getEnv "REQUEST_METHOD"
  script <- getEnv "SCRIPT_NAME"
  path <- getEnv "PATH_INFO"
  query <- catch (Just `fmap` getEnv "QUERY_STRING") (const $ return Nothing)
  protocolStr <- getEnv "SERVER_PROTOCOL"
  (hdrs, _) <- partition (isPrefixOf "HTTP_" . fst) `fmap` getEnvironment
  let input' f z = do
        chunk <- hGet stdin 1024
        if null chunk
           then return z
           else do z' <- f z chunk
                   case z' of
                     Left z''  -> return z''
                     Right z'' -> input' f z''
      protocol = read *** read . drop 1 $ break (== '.') $ protocolStr
      environ =
          Environment
          { requestMethod   = fromJust $ lookup method methods
          , scriptName      = pack script
          , pathInfo        = pack path
          , queryString     = pack `fmap` query
          , requestProtocol = protocol
          , headers         = map (\(k, v) -> (pack k, pack v)) hdrs
          , input           = input'
          , errors          = \s -> hPutStr stderr s >> hFlush stderr
          }
  (status, reason, respHeaders, output) <- application environ
  putStr "Status: " >> putStr (pack $ show status) >> putStr " "
  putStr reason >> putStr "\r\n"
  forM_ respHeaders $ \(k, v) ->
      do putStr k >> putStr ": " >> putStr v
         putStr "\r\n"
  putStr "\r\n"
  flip output () $ \_ bs -> putStr bs >> return (Right ())
  hFlush stdout

methods :: [(String, Method)]
methods =
    [("OPTIONS", Options)
    ,("GET", Get)
    ,("HEAD", Head)
    ,("POST", Post)
    ,("PUT", Put)
    ,("DELETE", Delete)
    ,("TRACE", Trace)
    ,("CONNECT", Connect)]
</haskell>

Note: This implementation is simplistic and is only used to illustrate what the server side of the interface might look like.

=== Middleware: Components that Play Both Sides ===

Note that a function ''may'' play both the role of a server with respect to some application(s), while also acting as an application with respect to some server(s).  Such "middleware" components can perform such functions as:

* Routing requests to different applications based on the request URL.  This can be used to have several application or frameworks run side-by-side in the same server.
* Perform content postprocessing.
* Load an application dynamically (using for example the GHC API) on every request removing the manual recompilation step while developing.

<haskell>
-- TODO: Add example.
</haskell>