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.
Second Author's Note: This is by NO means a complete list. The best reference (that I've found so far) is, in the source, SimpleHTTP.hs - it has everything listed here, and more.
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.
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
compiling the "dir"-example
Suppose you have saved the "dir"-example in the file dir_test.hs. Then you can compile with
ghc --make dir_test.hs -o dir_test
run it with ./dir_test and watch the result on your browser through
http://localhost:8080/test/me
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.
module Main where
import HAppS.Server
handleProjectById :: Int -> [ServerPart Response]
handleProjectById id = [ anyRequest $ ok $ toResponse $ "Project num " ++ show id ++ " addressed."]
handleProjectByTag :: String -> [ServerPart Response]
handleProjectByTag tag = [ anyRequest $ ok $ toResponse $ "Project tag " ++ show tag ++ " addressed."]
impl = [ dir "projects"
[ path $ handleProjectById
, path $ handleProjectByTag ]
]
main = simpleHTTP nullConf { port = 8080 } impl
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
method :: (MatchMethod method, Monad m) => method -> WebT m a -> ServerPartT m a
Filters for a specific request method.
An important note: method also prevents further matching on the request URL. This means you must capture (using path, dir, etc) the entire url before using method. This is useful, however, as method GET alone will match "/" (which cannot be matched with dir).
Below example illustrates handling different kind of request methods.
module Main where
import HAppS.Server
import Control.Monad (mplus)
import Text.XHtml hiding (method, dir)
import qualified Text.XHtml as H
-- a page for gathering comments
commentPage :: Html
commentPage = body <<
(toHtml "Please give us your opinions:" +++
(form ! [H.method "POST"] <<
[ textarea ! [strAttr "name" "comment", strAttr "cols" "50", strAttr "rows" "12"] << ""
, br, input ! [strAttr "type" "submit"]]))
resultPage :: String -> Html
resultPage str = body <<
(toHtml "Thank you for your comments." +++
blockquote << (p << str))
processComment (Comment str) = [ anyRequest $ ok $ resultPage str ]
-- comment as a data type
newtype Comment = Comment String
instance FromData Comment where
fromData = do c <- look "comment" `mplus` return "No comment."
return (Comment c)
unauthMethods = (`elem` [CONNECT,TRACE,HEAD])
impl = [ dir "comment" [ method GET $ ok commentPage
, methodSP POST $ withData processComment
, method () $ ok $ toHtml "Service not implemented for this type of method."]
, method unauthMethods $ unauthorized $ toHtml "You're not authorized."]
main = simpleHTTP nullConf { port = 8080 } impl
We can see the behaviour from shell (note, html output omitted):
quad% curl -X CONNECT http://localhost:8080/comment You're not authorized. quad% curl -X OPTIONS http://localhost:8080/comment Service not implemented for this type of method.
methodSP
identical to method, except for it takes a ServerPart T instead of a WebPart T
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 { port = 8080 }
[ 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.
http://localhost:8080/?str=foo
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.
seeOther
seeOther :: (Monad m, ToSURI uri) => uri -> res -> WebT m res
preformes an http redirect to uri. returns res (a response).
Error Codes
* badRequest * unauthorizied * notFound * seeOther * found * movedPermanently * tempRedirect
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.
Other Things To Check Out
Blog series by the first author, detailing the creation of an application to handle users:
Blog post by second author, expanding upon what was in the first post series:
Building With HAppS - Part 1 - More User Functionality
Thomas Hartman took ideas from both authors, added some of his own, and created:
Real World HAppS: The Cabalized, Self-Demoing HAppS Tutorial