HAppS tutorial2

Most of the stuff on this page refers to HAppS 0.9.1.2 or greater. This is the most recent development version at the time of this writing. There is another tutorial for HAppS 0.8.8 at HAppS tutorial. Start there to get a background. This page is dedicated to the things that have changed in the newer versions.

Author's Note: This page will be in various states of disrepair for awhile. I'm creating this document as I am learning HAppS, so it may reflect my inaccurate perceptions. Some of the information on this page MAY EVEN BE WRONG. If you know it's wrong, I would be grateful for your help in improving it.

HAppS is a framework for developing Internet services quickly, deploying them easily, scaling them massively, and managing them effortlessly. Web, persistence, mail, DNS and database servers are all built-in so you can focus on app development rather than integrating and babysitting lots of different servers/services (the Haskell type system keeps everything consistent).

Introduction

The basic web server framework in HAppS consists of a call to simpleHTTP that is passed a list of ServerParts that define the available pages. simpleHTTP searches through the ServerParts and returns the response generated by the first matching ServerPart. Typically ServerParts will match based on some part of the request URL.

The ServerPart is the workhorse of defining HAppS actions. The biggest goal of this document is to provide a useful guide to the ServerPart primitives that are available.

---

Fundamental Data Types

Need better explanations here.

Author's Note: Due to my inexperience with Monads, these explanations are probably lacking. Feel free to improve them.

These data types provide the framework for converting a Request into a Result in a structured way.

WebT

newtype WebT m a = WebT { unWebT :: m (Result a) }

A WebT is a computation that generates a result.

ServerPartT

newtype ServerPartT m a = ServerPartT { unServerPartT :: Request -> WebT m a }

A ServerPartT is a function that converts a Request into a WebT.

Basic ServerPart Functions

High-level description

Currently, these ServerPart primitives are defined in SimpleHTTP.hs. They were recently moved there from AlternativeHTTP.hs.

 * dir - match a directory at the front of the URL
 * path - another way to match a URL directory
 * multi - run a list of server parts
 * method - runs a server part if the request has the specified method
 * withRequest - builds a ServerPartT from a WebT
 * anyRequest - runs a ServerPartT no matter what the request was
 * withData - retrieve data from the input query or the cookies
 * withDataFn - retrieve data from the input query or the cookies
 * applyRequest
 * ok
 * toResponse
 * fileServe - a generic file server that returns files from the local file system as responses

dir

dir :: Monad m => String -> [ServerPartT m a] -> ServerPartT m a

The first argument is matched to the first directory element in the path URL. If it matches, then the ServerParts in the second argument are run.

path

path :: (FromReqURI a, Monad m) => (a -> [ServerPartT m r]) -> ServerPartT m r

Similar to dir except instead of passing a String and a list of ServerParts, you pass a function that returns a list of ServerParts.

FromReqURI is a type class that facilitates the conversion of data in the URI to Haskell types. The basic types are are already members of the class.

multi

multi :: Monad m => [ServerPartT m a] -> ServerPartT m a

Returns a ServerPart that runs the list of ServerParts supplied in the first argument.

method

withRequest

withRequest :: (Request -> WebT m a) -> ServerPartT m a

Since a ServerPartT is an encapsulation for a function (Request -> WebT), the withRequest function acts as a ServerPartT constructor.

anyRequest

anyRequest :: Monad m => WebT m a -> ServerPartT m a
anyRequest x = withRequest $ \_ -> x

anyRequest uses withRequest to construct a ServerPartT from the supplied WebT.

withData

withData provides a mechanism for retrieving structured data from a request. The first argument to withData is a function that takes a FromData instance in and returns [ServerPartT]. FromData is defined as follows.

class FromData a where
    fromData :: RqData a

So all you have to do to use withData is implement a fromData function for your data structure. fromData returns RqData which is a ReaderT that builds a computation that can get your type from the data in the request. HAppS provides several functions to use in constructing a fromData function for your data type. These functions are:

 * lookInput
 * lookBS
 * look
 * lookCookie
 * lookCookieValue
 * readCookieValue
 * lookRead
 * lookPairs

Here is an excerpt from one of the HAppS examples that illustrates the concept.

data MyStructure = MyStructure String
instance FromData MyStructure where
    fromData = do str <- look "str"
                  return $ MyStructure str

main = do simpleHTTP nullConf

              [ withData $ \(MyStructure str) ->

                    [ anyRequest $ ok $ "You entered: " ++ str ]

              , anyRequest $ ok "Sorry, I don't understand." ]

In this example, the look function gets the contents of the variable "str" passed in the request.

fileServe

fileServe :: MonadIO m => [FilePath] -> FilePath -> ServerPartT m Response

Creates a ServerPartT computation that serves files in the local filesystem. The first argument is a list of filenames to serve. The second argument is a path to the local directory where those files reside.

Error Codes

 * badRequest
 * unauthorizied
 * notFound
 * seeOther
 * found
 * movedPermanently
 * tempRedirect