Cookies don't work quite right in HAppS out of the box. The most common problem + is that google analytics and HAppS session cookies are mutually incompatible. + (There is a thread about what went wrong in the initial implementation in the happs googlegroup.) + +
Hopefully the underlying problems will be fixed in the next HAppS hackathon. + +
Meanwhile, there is a workaround in the HAppSHelpers package on hackage, which is used by happstutorial. + So cookies do work in happstutorial: I use google analytics to track visitors, + along with normal HAppS session cookies. + And if you use happstutorial as your template for happs apps you should be fine. + +
The cookie fix is just a couple lines of code in Controller.hs: + +
import HAppS.Server.CookieFixer
+
controller allowStressTests = map cookieFixer \$ .....
+
+
+
+
Besides the cookies used by google analytics, which are obfuscated by javascript, happstutorial
+ uses cookies to track session state -- the data that corresponds to the current user's session in
+
+
data AppState = AppState {
+
appsessions :: Sessions SessionData,
+
appdatastore :: Users
+
} deriving (Show,Read,Typeable,Data)
+
+
+
When you log in, a cookie is created that expires in an hour + (3600 seconds). And every time a happs handler needs to check if a user is logged in (for example, + when it needs to decide whether to show the logged-in-user menubar) a check is made to see if a cookie + has been set. + +
The cookie code is in ControllerMisc.hs:
+
+
+
startsess' getLandingpage (RenderGlobals origRq ts _) user = do
+
let sd = SessionData user
+
key <- update \$ NewSession sd
+
addCookie (3600) (mkCookie "sid" (show key))
+
.....
+
+
getMbSessKey rq = runReaderT (readCookieValue "sid") (rqInputs rq,rqCookies rq)
+
diff --git a/templates/editconsultantprofile.st b/templates/editconsultantprofile.st
--- a/templates/editconsultantprofile.st
+++ b/templates/editconsultantprofile.st
@@ -7,7 +7,7 @@
Got feedback? + +
I created a + happs tutorial feedback thread + at happs googlegroup. + My preference would be for feedback on happs tutorial to go there, particularly if it fixes a problem + or describes things to watch out for. + +
For what it's worth, here are somthings people have said about happstutorial + in blogs, user groups, and private emails. + +
@tphyahoo Just wanted to thank you for your tutorial. I've used it to successfully create a blog-system (a pet project) in Haskell (http://gisli.hamstur.is/blog/). In the blog itself, which is in Icelandic, I'm going to explain the source code (http://gisli.hamstur.is/src/) to the Icelandic Haskell community (if one exists ;) + +
I was getting nowhere before finding your tutorial. There was however a slight feeling of set back when I realized that you hadn't written about HAppS-State. To my relief you were further along with the locally installed tutorial than happstutorial.com. Keep up the good work! + +
Best regards, Gísli (reddit) + +
Great work, thanks for the tutorials, they were definitely needed! + +
And the tutorial demo itself is awesome! + +
dons (reddit) +
Another annoyance: when I attempted to create dummy data with utf8 data (edited in kate)
-and save this to HAppS State, this did NOT display correctly. (See AppStateSetBased.hs) I got \123 type
+and save this to HAppS State, this did NOT display correctly. (See StateVersions.AppState1.hs) I got \123 type
character escape sequences. I think this is because Serialization is based on show instances of data,
and ... well...
@@ -37,3 +37,5 @@
end of the string as was more proper. I then got bitten by show as above, causing much misery.
But all that having been said, as the live demo shows, in general utf8 data does work as it should. + +
Next chapter is about using cron jobs to keep happs running if it quits on your mysterious reasons. diff --git a/templates/ghciflounderingaskdatastore.st b/templates/ghciflounderingaskdatastore.st --- a/templates/ghciflounderingaskdatastore.st +++ b/templates/ghciflounderingaskdatastore.st @@ -32,7 +32,7 @@
*Main> :i askDatastore
askDatastore :: Query AppState (Data.Set.Set User)
-
-- Defined at src/AppStateSetBased.hs:43:0-11
+
-- Defined at src/StateVersions/AppState1.hs
what's a Query? @@ -53,7 +53,7 @@ this mess typechecks. -
*AppStateSetBased Control.Monad.Reader GHC.Conc Data.Set> :t askDatastore :: Ev (ReaderT AppState STM) (Set User) +
*StateVersions.AppState1 Control.Monad.Reader GHC.Conc Data.Set> :t askDatastore :: Ev (ReaderT AppState STM) (Set User)
askDatastore :: Ev (ReaderT AppState STM) (Set User) :: Ev (ReaderT AppState STM) (Set User)
*Main>
diff --git a/templates/home.st b/templates/home.st
--- a/templates/home.st
+++ b/templates/home.st
@@ -1,11 +1,17 @@
Haskell is a great way to program.
+$!Haskell is a great way to program.
!$ -And HAppS is a great way to build -web applications. +
HAppS is a great way to build web applications. + Besides having a great feature set in its own right, it is probably the leading solution + for implementing web apps in haskell, + my favorite language. -
Especially if you believe, like I do, that as +$!
You also get all the goodness +that comes from programming in haskell, my favorite language.
+!$ + +HAppS is especially great if you believe, like I do, that as modern software systems tend toward ever increasing complexity, database usage is an unnecessary source of complication that should be factored out where possible. @@ -20,30 +26,17 @@ $!Or to put it another way, that sql is an ugly hack. !$ -
-HAppS is haskell's answer to rails and django (and perl's catalyst, and php). -$! , and every ORM ever written in the history of software) !$ -With HAppS, there is no wrangling data -structures into and out of the database, because there is no database. You use whatever data -structures are natural to your application, and serialize them -transparently using -powerful -machinery that's running behind the -scenes. And if there are existing databases that you need to connect to, you can do that too -- you're not locked in to using macid for everything. - -
The above description is a bit idealized. Keeping everything in macid limits you to how much RAM you can afford, - and even if you can afford a lot (16GB in the amazon cloud costs \$576/month) there's no guarantee that you won't - max that out if your application has a lot of data. - (See the stress test chapter for more caveats.) - The HAppS developers have promised a version of HAppS that will make it easy to share ram across computers - with a technique called sharding, but this hasn't been released in a way that inspires confidence in me - (on hackage, sufficient documentation), - and to be honest I don't really understand how it is supposed to work even in theory. - But what is realistic is to write an alpha version of an application without a database access layer, - and then add persistent hard drive storage (probably database, but could also be flat files or name your poison) - outside of macid when it becomes necessary. Most web projects do not get to a size where this is necessary, - so arguably coding in a database from a start is a form of insidious premature optimization, if you buy - the argument that using a database from the start introduces significant maintenance overhead. +
HAppS is haskell's answer to rails and django (and perl's catalyst, + and php). + $! , and every ORM ever written in the history of software) !$ + With HAppS, there is no wrangling data + structures into and out of the database, because there is no database. You use whatever data + structures are natural to your application, and serialize them + transparently using + powerful + machinery that's running behind the + scenes. And if there are existing databases that you need to connect to, you can do that too + -- you're not locked in to using macid for everything.
MACID, the HAppS storage mechanism, is no vanilla serialization layer that will @@ -53,12 +46,19 @@ you get the same ACID guarantees that normally only come with a database.
-You also get all the goodness -that comes from programming in haskell, my favorite language.
+There are some limitations to using macid + as a datastore that you should familiarize yourself with + if you are looking into using HAppS for heavy-usage transactional applications. + But long term, HAppS with macid looks promising enough that I've started + using it as a platform for building commercial web 2.0 type apps. (My first + commercial happs app will be public soon, so stay tuned on + techcrunch. :) ) +
In short, HAppS is awesome, and webmonkeys everywhere should use it. Except...
There is this one minor detail. + diff --git a/templates/introductiontomacid.st b/templates/introductiontomacid.st --- a/templates/introductiontomacid.st +++ b/templates/introductiontomacid.st @@ -21,7 +21,7 @@
thartman@thartman-laptop:~/happs-tutorial>grep -ra testuser _local
-
_local/happs-tutorial_state/events-0000000000:ß\$6¡·¢:1525374391 696985193?AppStateSetBased.AddUsertestuser e1
+
_local/happs-tutorial_state/events-0000000000:ß\$6¡·¢:1525374391 696985193?AppState1.AddUsertestuser e1
... (and lots more lines of binary data)
Hm... let's see, can we be sneaky and grep for the password? diff --git a/templates/maciddatasafety.st b/templates/maciddatasafety.st --- a/templates/maciddatasafety.st +++ b/templates/maciddatasafety.st @@ -91,7 +91,7 @@
Q: What if my hard drive dies and I can't get my data back?
A: Like with any other data storage system, if there's valuable data, you need to be making backups. - In the case of HAppS data stored under _local, I would probably be rsyncing + In the case of HAppS data stored under _local, I would probably be rsyncing the _local directory to a remote server, or maybe multiple remote servers for extra safety. For now I am not worried about securing data, but when that day comes I'm pretty confident I'll be ok. diff --git a/templates/macidlimits.st b/templates/macidlimits.st new file mode 100644 --- /dev/null +++ b/templates/macidlimits.st @@ -0,0 +1,60 @@ +
Keeping everything in macid limits you to how much RAM you can afford. + Even if you have a business model where you can afford a lot (16GB in the amazon cloud costs \$576/month) + there's no guarantee that you won't + max that out if your application has a lot of data, if you are limited to one computer. + +
(See the stress test chapter for more caveats.) + The HAppS core developers have promised HAppS features + that will make it easy to share application state + across many computers, making scaling to ebay-sized proportions relatively straightforward: you + just add more computers to your amazon EC2 cloud. This hasn't happened yet, and I have a feeling that + when (if?) it does happen it won't be a panacea for every scaling problem. But for reference, + the features are replication and sharding. You can search the happs googlegroup to learn more + about this. + + +
My take is that, as currently implemented, Macid may be impractical for an app with tens of thousands of + concurrent sessions, especially if real acid transactionality is required. (EG, an accounting application.) + The situation improves if you have large numbers of users but don't require transactionality. + (E.G, facebook, reddit, message boards.) + This is true for web apps with a database backend as well, for more or less similar reasons. + +
A realistic way to use HAppS with macid is to write an alpha version of an application + using macid (no database), + and then add some other type of persistent hard drive storage (probably database) + outside of macid only if it becomes necessary. + +
This raises the question: if you are eventually going to have to put in a database back end, why use + macid at all? + + +
The -- perhaps slightly depressing answer -- is that you probably won't have to put in a database back end, + because your app won't be so successful that this is required. If your state needs transcend what + macid can deliver with reasonable performance, you will have + to rewrite a lot of your state code, but it will be worth it, because venture capitalists will be + knocking down your door. (You're the next facebook, ebay, etc.) + +
In the best case scenario, the HAppS core team will deliver on their promise of easy scaling + via ec2 and similar cloud solutions, in which case you won't even have to deal with a state rewrite. + + +
Since macid is available and macid is more straightforward to use than a database layer, + coding in a database from a start is a form of insidious premature optimization, if you buy + the argument that using a database from the start introduces significant maintenance overhead. + +
Having made this lengthy argument for macid... I can see myself rewriting a future tutorial chapter + that describes using HAppS with takusen and postresql as a backend rather than macid. But that hasn't + happened yet. If it needs to, it will. :) + +
Well folks, that more or less wraps up the happs tutorial. + +
You can now go out and use happs, using happstutorial as a template to get you started if appropriate. + +
The remaining chapters are of an appendix nature. Nice to have, but not fundamental. + +
If you want to keep reading, the next chapter is about using utf8 in happs. diff --git a/templates/macidmigration.st b/templates/macidmigration.st --- a/templates/macidmigration.st +++ b/templates/macidmigration.st @@ -1,1 +1,222 @@
What happens when your data model changes? + +
People who have been following this tutorial for a while may have noticed that every time I come out with + a new version, the existing users and jobs disappear and we start out with a blank slate again. + +
That's because changing the data schema of a happs-with-macid web app (aka migrating) is a chore. + +
It's a chore with traditional web apps too. But it's probably more difficult with macid, especially + given the sparse documentation. + +
This isn't a problem for happstutorial.com, because typically there are only a + few dozen users and jobs, plus whatever dummy data I've entered myself. Who cares? + So far, rather than migrating, I've just wiped the slate clean. + +
However, that isn't going to work for your latest facebook-killer. + +
The good news is, there is a way to migrate HAppS state through various iterations, it's sufficiently + documented if you know where to look, and it's not too painful once you've gotten used to it. + +
The main challenge is finding documentation. + +
The best documentation I have found is two threads in the happs googlegroup, along with the migration example + that was produced by eelco lempsink during the thread. I have taken this migration example example and + included it in the happstutorial distribution, with some improvements of my own. + +
The googlegroup migration threads are + here + and follow-up here. + +
The migration example I've included with the tutorial is at migrationexample. + +
My advice is to try the demo in migrationexample first, + following the directions in the README file, + read through the source files to understand how the demo works, + and then refer to the googlegroups thread if necessary. + +
Possibly this is sufficient documentation for you to start doing migrations yourself. If so, great, + ignore what follows. + +
If you feel like you could use more guidance, read on for some notes I put together on my own + migration experience. + +
Though I haven't started migration for the toy job board in happs-tutorial, I am using it for my + commercial project that is under development. This will be the basis of the notes that follow. + +
I almost didn't include these notes, because I wanted to provide an + easy step by step example that referenced the toy job board as I have done for other tutorial topics. + However, doing this will be quite a bit of work, I haven't gotten around to doing this after many weeks. + I want to get the information out, so I decided to just share what I have. + +
I apologize in advance if some of this seems confusing or fragmentary. I did my best, and I will + try to clean things up and integrate the example into the tutorial rather than snipping from an external app. + +
Ok... General migration notes: + +
Old state module names should not change, nor be shifted around in + directory structure (which is really just another kind of name + change). Therefore it's a good idea to start out with a sane + directory hierarchy for schema versions before you start doing + migrations. I recommend keeping App state in one monolithic file, in + a directory devoted to state versions. It makes schema migrations + much easier, as all references to the old state can then be handle + via import Qualified StateLast.hs as Old, then referenced via + Old.whatever, when bits of logic that remain consistent between the + old monolithic state file and the new monolithic state file. Resist + the temptation to split state into multiple files. Bear in mind that due to template haskell the order of + data structures declarations becomes significant, which is usually not + the case with haskell. (I seem to reall this annoyance was part of the + reason why I started splitting things into multiple files to begin + with, which I later regretted because it made migration that much harder.) + +
Don't call HAppS State "State", as this conflicts with the + State datatype in Control.Monad.State. I usually call my state + datatype AppState. + +
There will be code duplication, for the functions that get + transformed to state modifiers in template haskell. This is a bad + code smell, but I think it's unavoidable for the mkMethods directive with + all the methods template haskell needs. + +
In the old state file (being migrated from), make sure it exports + everything via module OldState ( ... everything gets exported here + ...) where.... My way to do this is load the state module, :browse + in ghci, copy the output, and clean it up using emacs regexen. In + emacs, dired-mark-files-regexp and dired-do-query-replace-regexp are + your friends. + +
Then, (my way), cd StateVersions, cp AppState1.hs AppState2.hs (or whatever version number we're on.) + +
Seems almost too obvious to say, but if you have live customer + you're not going to want to migrate this without having tested the + migration in a sandbox first. Create your sandbox, which should + include a snapshot of live customer data. Good way to create a + snapshot is tar -czvf _local on your live data. Test thoroughly on this + snapshot before doing the live migration. And even if you think you've tested enough, + tar snapshot your live data before the migration again, just in case. + +
Make a live data snapshot and copy it to your migration sandbox: _local.tar.gz. (If there is an unwieldy large + amount of data, create a smaller data set by setting up a server identical with the live server and doing some + actions manually.) + +
cd StateVersions; cp AppState1.hs AppState2.hs (or whatever version we're on) + For now, we just want a placeholder that will have AppState2 behaving exactly like AppState1. + change references from AppState1.hs to AppState2.hs in app code. + try running server, the result should be that it compiles, runs, but all data is all lost. (because we haven't written migration yet.) + +
roll back from backup taken earlier: rm -rf _local and tar -xzvf _local.tar.gz (an explicit reminder to + rollback the live data tar may be omitted from future steps, but basically you keep rolling back until + you get a successful migration.) + +
modify AppState (or whatever your main State datastructure is), say, adding a field. Don't write a Migrate instance + yet. Try running. You'll probably get an error like "Exception: Non-exhaustive patterns in case." + Kind of a crappy error message if you ask me, but ok. What's happening is the pre-existing data in the + _local directory isn't compatible with your modified AppState. If you rm -rf _local and try running again, it should + work now. But of course you have lost all your data, and need to rollback the live data again for the next step. + +
Now make necessary changes in code for migration. + See eelco's and my uploads to happs google group (tk happs tutorial). Summary is: + modify the version instance for AppState and add a migrate instance, allong the following lines. First, + +
import qualified StateVersions.AppState1 as Old
+
...
+
-- we'll say 2 because this is StateVersions/AppState2.hs
+
-- I don't think it matters what number you use as long as it's higher than the last version,
+
-- but I'd like to have a core dev confirm that intuition.
+
-- I wonder too what happens if you screw up this version number somehow. EG, what if you specify a version number
+
-- identical to the version you're migrating from?
+
instance Version AppState where
+
mode = extension 2 (Proxy :: Proxy Old.AppState)
+
+
This won't compile, you'll get an error about a missing (Migrate Old.AppState AppState) + instance arising from use of extension. So we supply the instance + +
instance Migrate Old.AppState AppState where
+
migrate (Old.AppState s d) = AppState (migrates s) (migrated d)
+
migrates s = undefined
+
migrated (us, aus, rs, rus) = undefined
+
+
We use undefined just to get it to compile and have something to darcs commit, and then write sensible code later.
+
+
*Main> :! grep -irn AppState1 *.hs
+
Controller.hs:27:import StateVersions.AppState1
+
ControllerAppMigration.hs:18:import StateVersions.AppState1
+
......
+
View.hs:29:import StateVersions.AppState1
+
+
These are the places in the code that need to be switched to use AppState2 instead.
+
+
Let's test this by adding an emails field to UserInfos
+
Actually, first let's try adding an email field to Macid1 and see if we get an error.
+
We do get an error, and it's a weird error:
+
*** Exception: src/Macid1/Repos.hs:45:2-24: Non-exhaustive patterns in case
+
at \$(deriveSerialize ''Repos)
+
+
Is non-exhaustive pattern because somewhere behind the scenes there has been a macid version bump + when it detected that the schema changed? + +
Dunno, but let's try now by switching state to AppState2.hs +
Let's also note the latest checkpoint in the _local directory. It is: ...
+
ls -lth _local/patch-shack_state/ | head -n2
+
... checkpoints-0000000014
+
+
and back it up:
+
tar -czvf _loacl.beforemigration.tar.gz _local
+
+
Step1, cd StateVersions; cp AppState1.hs AppState2.hs. Ok, that works. (Haven't actually used migration machinery yet.) + +
Now, let's try using the migration machinery, but the migrate is actually just id (so no data structure actually changes). + +
The following is a snip from a working migration instance, where one field in an interior data structure +has been added. (Specifically, UserProfile has gone from a 3 argument constructor to a 4 argument constructor). + +
You might think this looks like a lot of boilerplate for adding a single field, and I would agree. The good news +is that your migration code will look similar if you are making more than just that one change, and the problem +is still tractable. + +
And of course, migrations with a database back-end are no picnic either. + +
Migrate instance example (add a field to UserProfile):
+
+
+ instance Migrate Old.AppState AppState where
+
migrate (Old.AppState s d) = AppState (migrates s) (migrated d)
+
+
-- Nothing changed in sessions -- it's the second arg to appstate (AppDatastore users) that had a field added
+
-- We could have avoided writing migrates by using type synonyms to exactly copy the types from AppState1,
+
-- as is done in eelco's example.
+
-- I prefer to write out the migration explicitly rather than use type synonyms, because then after a successful
+
-- migration the Migrate instance and the old state code can be removed, and you wind up with just a monolithic
+
-- state file evolving over time rather than a sequence of states each with a module dependency on the previous state
+
-- . (I think this is the case -- still have to prove this works.)
+
migrates :: Old.Sessions Old.SessionData -> Sessions SessionData
+
migrates (Old.Sessions s) = Sessions . M.map f \$ s
+
where f :: Old.SessionData -> SessionData
+
f (Old.UserSession (Old.UserName u) ) = UserSession (UserName u)
+
f (Old.AdminSession (Old.AdminUserName u) ) = AdminSession (AdminUserName u)
+
+
migrated (Old.Users us, Old.AdminUsers aus, Old.Repos rs, Old.RepoUsers rus) =
+
( (Users . M.map ui . M.mapKeys uk \$ us),
+
(AdminUsers . M.map auv . M.mapKeys auk \$ aus),
+
(Repos . M.map rv . M.mapKeys rk \$ rs),
+
(RepoUsers . IXS.fromSet . S.map ru . IXS.toSet \$ rus )
+
)
+
where ui (Old.UserInfos p (Old.UserProfile c bl av ) ) = UserInfos p (UserProfile S.empty c bl av)
+
uk (Old.UserName u) = UserName u
+
auk (Old.AdminUserName u) = AdminUserName u
+
auv (Old.AdminUserInfos p) = AdminUserInfos p
+
rv (Old.Repo (Old.UserName u) bud blu isp) = Repo (UserName u) bud blu isp
+
rk (Old.RepoName n) = RepoName n
+
ru (Old.RepoUser (Old.RepoName n) (Old.UserName u) ) = RepoUser (RepoName n) (UserName u)
+
The most important lesson I learned is that putting all application state into macid won't work if you +
Sidenote: as (I think) 37 Signals said, "you don't have a scaling problem." I certainly don't have a scaling problem, + and if I did I would probably be jumping for joy even while I was tearing my hair out trying to figure out + how to accomodate more users. My current plans are for a membership site with paying user count, optimistically, + in the high thousands -- so I'm okay using macid even with all the caveats. I'm mainly working on the + user scaling problem because I find it interesting and am learning a lot; secondarily because I have ideas + in the works that might actually run into the RAM limit. + +
That said, the most important lesson I learned is that putting all application state into macid won't work if you have a lot of data -- not even if you have one of those heavy iron boxen from amazon web services, or for that matter a whole virtual data center full of them. 16GB of RAM gets used up surprisingly fast if you are using ram for everything. @@ -89,39 +96,7 @@ 20,000 users (4 million jobs) before performance degraded because of the amount of data being kept in ram. (With 10,000 users it ran without breaking a sweat, 20,000 was doable but went into swap.) - -$!
To be honest, maybe not. !$ - -$! -
I have done some preliminary testing to answer this question, and so far the results have been disappointing. - -
I am hoping that I am doing something wrong, and that there is a way of using macid effectively - for more than just toy applications. I also asked the HAppS googlegroup for help, and if there is a - solution for the problems I found I will definitely be sharing it in the tutorial, so stay tuned. - -
I am seeking feedback from HAppS experts and educated users on the following questions: -
Thanks in advance for anybody who can help me push HAppS to 11! - -$! - -
Still chugging... At 1:03, about 15 minutes after we started, the 200th - user is inserted. The jobs page loads slowly, but that's to be expected with - a 20000 jobs long pagination. I ctrk-c out, and restart. The state file for the last experiment - is 542M large. The jobs app gives the startup message ("exit :q ghci completely...") - but it seems to be starting very slowly, and gives no feedback why. - Also emacs is sluggish. I restarted at 1:10, it's 1:14 and localhost:5001 still doesn't show anything. - At 1:20 http://localhost:5001 loads normally. - - - -!$ - +
Obviously this chapter of the happs tutorial is in progress and, to some extent, in flux. There is a + thread about the stress tests in the haspps googlegroup that you can have a look at + for even more information. I also say a few more words about what macid isn't good for in + macid limits. diff --git a/templates/macidupdatesandqueries.st b/templates/macidupdatesandqueries.st --- a/templates/macidupdatesandqueries.st +++ b/templates/macidupdatesandqueries.st @@ -18,12 +18,12 @@ If it's the empty set, there is no existing data and the dummy data can be added safely, and then a "dummy data success" page gets displayed. Otherwise no update happens and you get an error page. -
The macid state of our job board is defined in AppStateSetBased, +
The macid state of our job board is defined in StateVersions.AppState1, in the AppState data declaration. As you may recall, we have seen AppState before, in runserver, in our lesson on the main module. AppState's use in startSystemState, in Main.hs, is what makes it the primary state component of our web app. -
From AppStateSetBased.hs +
From StateVersions.AppState1.hs
(for optimal learning, open this file in another window):
@@ -43,7 +43,7 @@
One thing to watch out for in mind is that because template haskell is being generated, the order that functions
+ appear in the AppStaten.hs modules matters (which is generally not the case in haskell). If TH can't find
+ generated code it needs, the module won't compile. (Perhaps this is something that could be fixed in TH
+ in the future.)
+
+
Because AppState is the top-level component, in addition to Read / Show / Serializeable / Version,
it is also an instance of Method and Component.
@@ -70,11 +76,11 @@
query AskDatastore and update InitializeDummyData.
AskDatastore and InitializeDummyData are generated with template haskell, based on the definitions of
- askDatastore and initializeDummyData, in AppStateSetBased.
+ askDatastore and initializeDummyData, in AppState1.
If you do
- *Main> :browse AppStateSetBased
+ *Main> :browse StateVersions.AppState1
you'll see a number of function/datatype pairs defined via template haskell, where the datatype has the
same name as the function, except it is upper-cased. askDatastore / AskDatastore, getUser / GetUser,
@@ -97,11 +103,11 @@
*Main> :i AskDatastore
However, if you ask ghci about askDatastore, upon which you know AskDatastore is based --
because of the lowercase -- you can confirm that it is a query.
@@ -126,8 +132,8 @@
To get comfortable with macid
Have a look at Main.hs module at the core of this web application. Have a look at the Main.hs module which is at the core of this web application. Two bits of code that should jump out at you as being important are
+ In particular, notice the line
- smartserver (Conf p Nothing) "happs-tutorial" (controller allowStressTests) stateProxy
- We'll pospone learning about the HAppS state system (the first line) for later. This is a library function, which can be looked up via the ghci info directive (or i for short):
+ Each of these arguments is important enough to say something brief about.
+
+ In this case, the configuration argument just specifies the port the server runs on.
+
+ The second string argument controls where serialized app state will
+ be stored: in this case, under "_local/happs-tutorial". This is mainly for convenience, so the state
+ directory is the same whether we are running in ghci or ghc. (HAppS out of the box just looks
+ at the executable name, which in the case of ghci is something weird.)
+
+ The third argument tells HAppS what to use as a controller, in the MVC sense.
+ Basically, how to handle http requests.
+
+ The fourth argument tells happs what data structure to use for application state.
+ We'll cover about the HAppS state system in depth, but later. To learn more about what the controller function is doing,
, open this file in ghci: cd src; ghci Main.hs and have a look at these functions using ghci :info . *Main> :i controller
-
+ The controller function is a list of ServerPartTs, which are basically handlers that
-accept an HTTP request and return a response.
-Well, ok... this is a bit obfuscated by the many types involved in the construction,
-and if you want to be pedantic it's probably a bit more complicated than that, but you don't need to understand all
+ The controller function is a list of ServerPartTs, which are handlers that
+accept an HTTP request and return a response. (The boolean argument determines whether or not we
+enable a certain handler -- "stress tests" -- which is discussed later; don't worry about it for now.)
+This is a bit obfuscated by the many types involved in the construction,
+and if you want to be pedantic it's actually a bit more complicated than that, but you don't need to understand all
the details at this point. So, for the moment, just think about a ServerPartT as a wrapper
over a function that takes an HTTP request and returns a response.
diff --git a/templates/menubar.st b/templates/menubar.st
--- a/templates/menubar.st
+++ b/templates/menubar.st
@@ -2,7 +2,7 @@
data AskDatastore = AskDatastore
-
-- Defined at src/AppStateSetBased.hs:(178,2)-(191,27)
+
-- Defined at src/StateVersions/AppState1.hs
instance Serialize AskDatastore
-
-- Defined at src/AppStateSetBased.hs:(178,2)-(191,27)
+
-- Defined at src/StateVersions/AppState1.hs
instance Version AskDatastore
-
-- Defined at src/AppStateSetBased.hs:(178,2)-(191,27)
+
-- Defined at src/StateVersions/AppState1.hs
-
Where it all begins: the function main
-
-
+
+
*Main> :i smartserver
+
smartserver ::
+
(Methods st, Component st, ToMessage a) =>
+
Conf -> String -> [ServerPartT IO a] -> Proxy st -> IO ()
+
-- Defined in HAppS.Server.Helpers
+
controller :: [ServerPartT IO Response]
+
*Main> :i controller
+
controller :: Bool -> [ServerPartT IO Response]
-- Defined at Controller.hs...
+
*Main> :i ServerPartT
-
newtype ServerPartT m a
-
= ServerPartT {unServerPartT :: Request -> WebT m a}
+
newtype ServerPartT m a = ServerPartT {unServerPartT :: Request -> WebT m a}
-- Defined in HAppS.Server.SimpleHTTP
instance [overlap ok] (Monad m) => Monad (ServerPartT m)
-- Defined in HAppS.Server.SimpleHTTP
+
*Main> :i WebT
newtype WebT m a = WebT {unWebT :: m (Result a)}
-- Defined in HAppS.Server.SimpleHTTP
instance [overlap ok] (Monad m) => Monad (WebT m)
-- Defined in HAppS.Server.SimpleHTTP
+
*Main> :i Result
data Result a
= NoHandle | Ok (Response -> Response) a | Escape Response
-- Defined in HAppS.Server.SimpleHTTP
instance [overlap ok] (Show a) => Show (Result a)
-- Defined in HAppS.Server.SimpleHTTP
-
$ menubarMenu $
- $! td is for alignment only, an ugly hack, and it renders bad if you resize the window.
+ $! td is for alignment only, an ugly hack, and it renders bad if you resize the window.
how can I do this better? !$
$ userMenu $
Justin Bailey contributed a patch for displaying haskell files colorized. + +
Lemmih, who is -- I think -- the main happs core developer at the present time, + helped me think through the macid stress test chapter, and numerous other issues. + +
Eelco Lempsink, and Jeremy Shaw (nhepthanlabs) provided valuable assistance + via code contributed and questions answered in the happs googlegroup. + +
Did I forget someone? Drop me a line and I'll add you to the list. + +
Oh, thanks for everyone who encouraged me to keep working on this. + It's been a long slog, but I think it's been worth it. + +
Hey, that makes it sound like I'm done. But a tutorial is never done :) diff --git a/templates/toc.st b/templates/toc.st --- a/templates/toc.st +++ b/templates/toc.st @@ -10,12 +10,14 @@ , ("/tutorial/debugging","debugging") , ("/tutorial/get-and-post","form data: get and post") , ("/tutorial/file-uploads","form data: file uploads") + , ("/tutorial/cookies","cookies") , ("/tutorial/introductiontomacid","introduction to macid") , ("/tutorial/macid-data-safety","using macid safely") , ("/tutorial/macid-dummy-data","macid dummy data") , ("/tutorial/macid-updates-and-queries","macid updates and queries") , ("/tutorial/macid-migration","changing the data model") , ("/tutorial/macid-stress-test","macid stress test") + , ("/tutorial/macid-limits","limitations of macid") , ("/tutorial/foreignchars","foreign characters") , ("/tutorial/start-happs-on-boot","cron jobs") , ("/tutorial/thanks","thanks")