SimpleHTTP provides a back-end independent API for handling HTTP requests.

By default, the built-in HTTP server will be used. However, other back-ends like CGI/FastCGI can used if so desired.

So the general nature of simpleHTTP is no different than what you'd expect from a web application container. First you figure out which function is going to process your request, process the request to generate a response, then return that response to the client. The web application container is started with simpleHTTP, which takes a configuration and a response-building structure (ServerPartT which I'll return too in a moment), and picks the first handler that is willing to accept the request, passes the request into the handler. A simple hello world style HAppS simpleHTTP server looks like:

   main = simpleHTTP nullConf $ return "Hello World!"

simpleHTTP nullConf creates a HTTP server on port 8000. return "Hello World!" creates a serverPartT that just returns that text.

ServerPartT is the basic response builder. As you might expect, it's a container for a function that takes a Request and converts it a response suitable for sending back to the server. Most of the time though you don't even need to worry about that as ServerPartT hides almost all the machinery for building your response by exposing a few type classes.

ServerPartT is a pretty rich monad. You can interact with your request, your response, do IO, etc. Here is a do block that validates basic authentication It takes a realm name as a string, a Map of username to password and a server part to run if authentication fails.

basicAuth' acts like a guard, and only produces a response when authentication fails. So put it before any ServerPartT you want to demand authentication for in any collection of ServerPartTs.

main = simpleHTTP nullConf $ myAuth, return "Hello World!"
     where
         myAuth = basicAuth' "Test"
             (M.fromList [("hello", "world")]) (return "Login Failed")

basicAuth' realmName authMap unauthorizedPart =
    do
        let validLogin name pass = M.lookup name authMap == Just pass
        let parseHeader = break (':'==) . Base64.decode . B.unpack . B.drop 6
        authHeader <- getHeaderM "authorization"
        case authHeader of
            Nothing -> err
            Just x  -> case parseHeader x of
                (name, ':':pass) | validLogin name pass -> mzero
                                   | otherwise -> err
                _                                       -> err
    where
        err = do
            unauthorized ()
            setHeaderM headerName headerValue
            unauthorizedPart
        headerValue = "Basic realm=\"" ++ realmName ++ "\""
        headerName  = "WWW-Authenticate"

Here is another example that uses liftIO to embed IO in a request process

   main = simpleHTTP nullConf $ myPart
   myPart = do
     line <- liftIO $ do -- IO
         putStr "return? "
         getLine
     when (take 2 line /= "ok") $ (notfound () >> return "refused")
     return "Hello World!"

This example will ask in the console "return? " if you type "ok" it will show "Hello World!" and if you type anything else it will return a 404.

Run simpleHTTP with a previously bound socket. Useful if you want to run happstack as user on port 80. Use something like this:

 import System.Posix.User (setUserID, UserEntry(..), getUserEntryForName)

 main = do
     let conf = nullConf { port = 80 }
     socket <- bindPort conf
     -- do other stuff as root here
     getUserEntryForName "www" >>= setUserID . userID
     -- finally start handling incoming requests
     tid <- forkIO $ socketSimpleHTTP socket conf impl

Note: It's important to use the same conf (or at least the same port) for bindPort and simpleHTTPWithSocket.

Used to manipulate the containing monad. Very useful when embedding a monad into a ServerPartT, since simpleHTTP requires a ServerPartT IO a. Refer to WebT for an explanation of the structure of the monad.

Here is an example. Suppose you want to embed an ErrorT into your ServerPartT to enable throwError and catchError in your Monad.

   type MyServerPartT e m a = ServerPartT (ErrorT e m) a

Now suppose you want to pass MyServerPartT into a function that demands a ServerPartT IO a (e.g. simpleHTTP). You can provide the function:

   unpackErrorT:: (Monad m, Show e) => UnWebT (ErrorT e m) a -> UnWebT m a
   unpackErrorT handler et = do
      eitherV <- runErrorT et
      case eitherV of
          Left err -> return $ Just (Left Catastrophic failure  ++ show e, Set $ Endo r -> r{rsCode = 500})
          Right x -> return x

With unpackErrorT you can now call simpleHTTP. Just wrap your ServerPartT list.

   simpleHTTP nullConf $ mapServerPartT unpackErrorT (myPart `catchError` myHandler)

Or alternatively:

   simpleHTTP' unpackErrorT nullConf (myPart `catchError` myHandler)

Also see spUnwrapErrorT for a more sophisticated version of this function

It is worth discussing the unpacked structure of WebT a bit as it's exposed in mapServerPartT and mapWebT.

A fully unpacked WebT has a structure that looks like:

    ununWebT $ WebT m a :: m (Maybe (Either Response a, FilterFun Response))

So, ignoring m, as it is just the containing Monad, the outermost layer is a Maybe. This is Nothing if mzero was called or Just (Either Response a, SetAppend (Endo Response)) if mzero wasn't called. Inside the Maybe, there is a pair. The second element of the pair is our filter function FilterFun Response. FilterFun Response is a type alias for SetAppend (Dual (Endo Response)). This is just a wrapper for a Response->Response function with a particular Monoid behavior. The value

      Append (Dual (Endo f))

Causes f to be composed with the previous filter.

      Set (Dual (Endo f))

Causes f to not be composed with the previous filter.

Finally, the first element of the pair is either Left Response or Right a.

Another way of looking at all these pieces is from the behaviors they control. The Maybe controls the mzero behavior. Set (Endo f) comes from the setFilter behavior. Likewise, Append (Endo f) is from composeFilter. Left Response is what you get when you call finishWith and Right a is the normal exit.

An example case statement looks like: ex1 webt = do val <- ununWebT webt case val of Nothing -> Nothing -- this is the interior value when mzero was used Just (Left r, f) -> Just (Left r, f) -- r is the value that was passed into finishWith -- f is our filter function Just (Right a, f) -> Just (Right a, f) -- a is our normal monadic value -- f is still our filter function

pops any path element and ignores when chosing a ServerPartT to handle the

request.

used to read parse your request with a RqData (a ReaderT, basically) For example here is a simple GET or POST variable based authentication guard. It handles the request with errorHandler if authentication fails.

   myRqData = do
      username <- lookInput "username"
      password <- lookInput "password"
      return (username, password)
  checkAuth errorHandler = do
      d <- getData myRqDataA
      case d of
          Nothing -> errorHandler
          Just a | isValid a -> mzero
          Just a | otherwise -> errorHandler

An varient of getData that uses FromData to chose your RqData for you. The example from getData becomes:

   myRqData = do
      username <- lookInput "username"
      password <- lookInput "password"
      return (username, password)
   instance FromData (String,String) where
      fromData = myRqData
   checkAuth errorHandler = do
      d <- getData'
      case d of
          Nothing -> errorHandler
          Just a | isValid a -> mzero
          Just a | otherwise -> errorHandler

proxyServe is for creating ServerPartT's that proxy. The sole argument [String] is a list of allowed domains for proxying. This matches the domain part of the request and the wildcard * can be used. E.g.

• "*" to match anything.
• "*.example.com" to match anything under example.com
• "example.com" to match just example.com

TODO: annoyingly enough, this method eventually calls escape, so any headers you set won't be used, and the computation immediatly ends.

This ServerPart modifier enables the use of throwError and catchError inside the WebT actions, by adding the ErrorT monad transformer to the stack.

You can wrap the complete second argument to simpleHTTP in this function.

An example error Handler to be used with spUnWrapErrorT, which returns the error message as a plain text message to the browser.

Another possibility is to store the error message, e.g. as a FlashMsg, and then redirect the user somewhere.

This is a for use with mapServerPartT' It it unwraps the interior monad for use with simpleHTTP. If you have a ServerPartT (ErrorT e m) a, this will convert that monad into a ServerPartT m a. Used with mapServerPartT' to allow throwError and catchError inside your monad. Eg.

   simpleHTTP conf $ mapServerPartT' (spUnWrapErrorT failurePart)  $ myPart `catchError` errorPart

Note that failurePart will only be run if errorPart threw an error so it doesn't have to be very complex.

Set the validator which should be used for this particular Response when validation is enabled.

Calling this function does not enable validation. That can only be done by enabling the validation in the Conf that is passed to simpleHTTP.

You do not need to call this function if the validator set in Conf does what you want already.

Example: (use noopValidator instead of the default supplied by validateConf)

  simpleHTTP validateConf . anyRequest $ ok . setValidator noopValidator =<< htmlPage

See also: validateConf, wdgHTMLValidator, noopValidator, lazyProcValidator

ServerPart version of setValidator

Example: (Set validator to noopValidator)

   simpleHTTP validateConf $ setValidatorSP noopValidator (dir ajax ... )

See also: setValidator

This extends nullConf by enabling validation and setting wdgHTMLValidator as the default validator for text/html.

Example:

  simpleHTTP validateConf . anyRequest $ ok htmlPage

Actually perform the validation on a Response

Run the validator specified in the Response. If none is provide use the supplied default instead.

Note: This function will run validation unconditionally. You probably want setValidator or validateConf.

Validate text/html content with WDG HTML Validator.

This function expects the executable to be named validate and it must be in the default PATH.

See also: setValidator, validateConf, lazyProcValidator

A validator which always succeeds.

Useful for selectively disabling validation. For example, if you are sending down HTML fragments to an AJAX application and the default validator only understands complete documents.