Personal tools

HAppS tutorial2

From HaskellWiki

Revision as of 21:10, 23 February 2008 by Aycanirican (Talk | contribs)

Jump to: navigation, search


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

Contents

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


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

1.1.1 WebT

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

A WebT is a computation that generates a result.

1.1.2 ServerPartT

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

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

1.2 Basic ServerPart Functions

1.2.1 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

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

module Main where
 
import HAppS.Server
 
impl = [ dir "test" [ dir "me" [ anyRequest $ ok $ toResponse "/test/me matched." ]
                    , anyRequest $ ok $ toResponse "/test matched."] ]
 
main = simpleHTTP nullConf { port = 8080 } impl

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

1.2.4 multi

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

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

1.2.5 method

method :: (MatchMethod method, Monad m) => method -> WebT m a -> ServerPartT m a

Filters for a specific request method.

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

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

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

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

1.3 Error Codes

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

2 Working with State

NOTE: This section is in progress.

 * startSystemState - call this function to select an entry point
 * query - get the state
 * update - change the state

The query and update functions provide all the mechanisms needed to work with state.

HAppS works with state by working with functions that manipulate the state. Lemmih has described it as follows, "[Google's] BigTable pushes data on several machines in a parallel manner. HAppS pushes functions around on several machines in a parallel manner." On a single machine, HAppS keeps a transaction log by storing the functions that modified the state. In order to do this, those functions must be serialized.

Because of this, the query and update functions take QueryEvents and UpdateEvents as a parameter. These functions are typically generated by the TemplateHaskell mkMethods function to eliminate the need to write the above mentioned serialization code. Calls to mkMethods look like the following (taken from AllIn.hs):

$(mkMethods ''UserComponent ['getComponent,'setComponent])
$(mkMethods ''SingletonComponent ['setSingleton,'getSingleton])

The lists in the second arguments are lists of the names of functions for which QueryEvents and UpdateEvents are to be created. QueryEvents and UpdateEvents are created from functions that return a MonadReader and MonadState respectively.