Happstack.Server.ClientSession

This module provides a simple session implementation which stores session data on the client as a cookie value.

The cookie values stored in an encryted cookie to make it more difficult for users to tamper with the values. However, this does not prevent replay attacks, and should not be seen as a substitute for using HTTPS. Additionally, the cryptography libraries used to encrypt the cookie have never been audited. Hence you are encouraged to think carefully about what data you put in the session data.

Another important thing to realize is clientside sessions do not provide Isolation. Imagine if the browser makes multiple simultaneous requests, which each modify the session data. The browser will submit the same cookie for each the requests, and each request handling thread will get their own copy of the session data. The threads will then modify their local copies independently and send their modified values back to the browser, overwriting each other. The final value will be determined by which ever request is sent last, and any changes made by the other request will be entirely lost.

This means that clientsessions would not be suitable for implementing a request counter, because if overlapping requests are made, the count will be off. The count will only be accurate if the requests are processed sequentially. That said, the demo code implements a request counter anyway, because it is short and sweet. Also, this caveat was forgotten when the example code was being written.

If you only modify the session data for POST requests, but not GET requests you are less likely to run into situations where you are losing changes, because there are not a lot of cases where a client will be submitting multiple POST requests in parallel. Though there is no guarantee.

Alternatively, you can choose to only store data where it is ok if modifications are lost. For example, if the session data contains only a userid and the time of the last request they made, then there is no great loss if some of the modifications are lost, because the access times are going to all be about the same anyway.

By default the client will need to submit the cookie that contains the client session data for every request (including images, and other static assets). So, storing a large amount of data in the client session will make requests slower and is not recommended. If you have assets which can be served with out examining the client session data you can use the sessionPath and sessionDomain parameters of SessionConf to limit when the browser sends the session data cookie.

The first thing you need to do is enable some extensions which can be done via a LANGUAGE pragma at the top of your app:

{-# LANGUAGE DeriveDataTypeable, TemplateHaskell #-}

Then you will need some imports:

 module Main where

 import Happstack.Server   (ServerPartT, Response, simpleHTTP
                          , nullConf, nullDir, ok, toResponse
                          )
 import Happstack.Server.ClientSession
                           ( ClientSession(..), ClientSessionT(..)
                          , getDefaultKey, mkSessionConf
                          , liftSessionStateT, withClientSessionT
                          )
 import Data.Data          (Data, Typeable)
 import Data.Lens          ((+=))
 import Data.Lens.Template (makeLens)
 import Data.SafeCopy      (base, deriveSafeCopy)

Next you will want to create a type to hold your session data. Here we use a simple record which we will update using data-lens-fd. But, you could also store a, Map Text Text, or whatever suits your fancy as long as it can be serialized. (So no data types that include functions, existential types, etc).

 data SessionData = SessionData
     { _count    :: Integer
     }
    deriving (Eq, Ord, Read, Show, Data, Typeable)

 -- | here we make it a lens, but that is not required
 $(makeLens ''SessionData)

We use the safecopy library to serialize the data so we can encrypt it and store it in a cookie. safecopy provides version migration, which means that we will be able to read-in old session data if we change the data type. The easiest way to create a SafeCopy instance is with deriveSafeCopy:

 $(deriveSafeCopy 0 'base ''SessionData)

We also need to define what an emptySession looks like. This will be used for creating new sessions when the client does not already have one:

 instance ClientSession SessionData where
     emptySession = SessionData { _count = 0 }

Next we have a function which reads a client-specific page counter and returns the number of times the page has been reloaded.

In this function we use, liftSessionStateT to lift the += lens function into ClientSessionT to increment and return the value stored in the client session.

Alternatively, we could have used the getSession and putSession functions from MonadClientSession. Those functions do not require the use of liftSessionStateT.

 routes :: ClientSessionT SessionData (ServerPartT IO) Response
 routes =
     do nullDir
        c <- liftSessionStateT $ count += 1
        ok $ toResponse $ "you have viewed this page " ++ (show c) ++ " time(s)."

Finally, we unwrap the ClientSessionT monad transformer using withClientSessionT.

The SessionConf type requires an encryption key. You can generate the key using getDefaultKey uses a default filename. Alternatively, you can specific the name you want to use explicitly using getKey. The key will be created automatically if it does not already exist.

If you change the key, all existing client sessions will be invalidated.

 main :: IO ()
 main =
     do key <- getDefaultKey
        let sessionConf = mkSessionConf key
        simpleHTTP nullConf $ withClientSessionT sessionConf $ routes

In a real application you might want to use a newtype wrapper around ClientSessionT to keep your type sigantures sane. An alternative version of this demo which does that can be found here:

http://patch-tag.com/r/mae/happstack/snapshot/current/content/pretty/happstack-clientsession/demo/demo.hs

Happstack.Server.ClientSession

class SafeCopy st => ClientSession st where

Your session type must have an instance for this class.

Methods

emptySession :: st

An empty session, i.e. what you get when there is no existing session stored.

data SessionStatus sessionData

Wrapper around the sessionData which tracks it state so we can avoid decoding or encoding/sending the cookie when not required

Constructors

Unread

NoChange sessionData

Modified sessionData

Expired

Instances

Eq sessionData => Eq (SessionStatus sessionData)

Ord sessionData => Ord (SessionStatus sessionData)

Read sessionData => Read (SessionStatus sessionData)

Show sessionData => Show (SessionStatus sessionData)

class MonadClientSession sessionData m | m -> sessionData where

MonadClientSession provides the primary interface to get sessionData, put sessionData or expire sessionData.

This is a class so you can use newtype deriving to make the functions available in your custom server monad.

Methods

getSession

Arguments

:: m sessionData

get the current sessionData

putSession

Arguments

:: sessionData

-> m ()

set the sessionData

expireSession

Arguments

:: m ()

expire the session (deletes the cookie)

Instances

(Functor m, MonadPlus m, HasRqData m, ClientSession sessionData) => MonadClientSession sessionData (ClientSessionT sessionData m)

data SessionConf

Configuration for the session cookie for passing to runClientSessionT or withClientSessionT.

Constructors

SessionConf

Fields

sessionCookieName :: String

Name of the cookie to hold your session data.

sessionCookieLife :: CookieLife

Lifetime of that cookie.

sessionKey :: Key

Encryption key, usually from getKey or getDefaultKey.

sessionDomain :: String

cookie domain

sessionPath :: String

cookie path

sessionSecure :: Bool

Only use a session over secure transports.

sessionHttpOnly :: Bool

Only use session over HTTP (to prevent it from being stolen via cross-site scripting)

mkSessionConf :: Key -> SessionConf

Create a SessionConf using defaults for everything except sessionKey. You can use record update syntax to override individual fields.

 main = do key <- getDefaultKey
           let sessConf = (mkSessionConf key) { sessionCookieLife = oneWeek }
           simpleHTTP nullConf $ withClientSessionT sessConf handlers
   where
     oneWeek  = MaxAge $ 60 * 60 * 24 * 7
     handlers = msum [...]

mkSessionConf is currently defined as:

 mkSessionConf :: Key -> SessionConf
 mkSessionConf key = SessionConf
    { sessionCookieName = "Happstack.ClientSession"
    , sessionCookieLife = Session
    , sessionKey        = key
    , sessionDomain     = ""
    , sessionPath       = "/"
    , sessionSecure     = False
    , sessionHttpOnly   = True
    }

see also: getKey, getDefaultKey

newtype ClientSessionT sessionData m a

ClientSessionT provides an environment in which we can access and update the client-side session state

The inner monad needs to provide an instance of Happstack so that the cookie value can be read and set. According ClientSessionT must appear outside ServerPartT not inside it.

Constructors

ClientSessionT

Fields

unClientSessionT :: ReaderT SessionConf (SessionStateT sessionData m) a

Instances

MonadRWS r w s m => MonadRWS r w s (ClientSessionT sessionData m)

MonadReader r m => MonadReader r (ClientSessionT sessionData m)

FilterMonad r m => FilterMonad r (ClientSessionT sessionData m)

WebMonad r m => WebMonad r (ClientSessionT sessionData m)

MonadBase b m => MonadBase b (ClientSessionT sessionData m)

MonadBaseControl b m => MonadBaseControl b (ClientSessionT s m)

MonadError e m => MonadError e (ClientSessionT sessionData m)

MonadState s m => MonadState s (ClientSessionT sessionData m)

MonadWriter w m => MonadWriter w (ClientSessionT sessionData m)

(Functor m, MonadPlus m, HasRqData m, ClientSession sessionData) => MonadClientSession sessionData (ClientSessionT sessionData m)

MonadTrans (ClientSessionT sessionData)

MonadTransControl (ClientSessionT s)

Monad m => Monad (ClientSessionT sessionData m)

Functor m => Functor (ClientSessionT sessionData m)

MonadFix m => MonadFix (ClientSessionT sessionData m)

MonadPlus m => MonadPlus (ClientSessionT sessionData m)

(Monad m, Functor m) => Applicative (ClientSessionT sessionData m)

(Functor m, MonadPlus m) => Alternative (ClientSessionT sessionData m)

Happstack m => Happstack (ClientSessionT sessionData m)

(Monad m, HasRqData m) => HasRqData (ClientSessionT sessionData m)

ServerMonad m => ServerMonad (ClientSessionT sessionData m)

MonadIO m => MonadIO (ClientSessionT sessionData m)

MonadCont m => MonadCont (ClientSessionT sessionData m)

MonadPlus m => Monoid (ClientSessionT sessionData m a)

mapClientSessionT :: (forall s. m (a, s) -> n (b, s)) -> ClientSessionT sessionData m a -> ClientSessionT sessionData n b

transform the inner monad, but leave the session data alone.

runClientSessionT :: ClientSessionT sessionData m a -> SessionConf -> m (a, SessionStatus sessionData)

run the ClientSessionT monad and get the result plus the final SessionStatus sessionData

This function does not automatically update the cookie if the session has been modified. It is up to you to do that. You probably want to use withClientSessionT instead.

see also: withClientSessionT, mkSessionConf

withClientSessionT :: (Happstack m, Functor m, Monad m, FilterMonad Response m, ClientSession sessionData) => SessionConf -> ClientSessionT sessionData m a -> m a

Wrapper around your handlers that use the session.

This function automatically takes care of expiring or updating the cookie if the expireSession or modifySession is called.

If no changes are made to the session, then the cookie will not be resent (because there is no need to).

data SessionStateT s m a

SessionStateT is like StateT, except it records if put was ever called

Instances

FilterMonad r m => FilterMonad r (SessionStateT s m)

WebMonad r m => WebMonad r (SessionStateT s m)

MonadBase b m => MonadBase b (SessionStateT s m)

MonadBaseControl b m => MonadBaseControl b (SessionStateT s m)

MonadError e m => MonadError e (SessionStateT s m)

(Monad m, ClientSession sessionData) => MonadState sessionData (SessionStateT sessionData m)

MonadTrans (SessionStateT s)

MonadTransControl (SessionStateT s)

Monad m => Monad (SessionStateT s m)

Functor m => Functor (SessionStateT s m)

MonadFix m => MonadFix (SessionStateT s m)

MonadPlus m => MonadPlus (SessionStateT s m)

(Monad m, Functor m) => Applicative (SessionStateT s m)

(Functor m, MonadPlus m) => Alternative (SessionStateT s m)

Happstack m => Happstack (SessionStateT sessionData m)

(Monad m, HasRqData m) => HasRqData (SessionStateT s m)

ServerMonad m => ServerMonad (SessionStateT s m)

MonadIO m => MonadIO (SessionStateT s m)

MonadCont m => MonadCont (SessionStateT s m)

MonadPlus m => Monoid (SessionStateT sessionData m a)

mapSessionStateT :: (forall s. m (a, s) -> n (b, s)) -> SessionStateT sessionData m a -> SessionStateT sessionData n b

Transform the inner monad. (similar to mapStateT)

The forall s. is to prevent you from modifying the session state.

In theory we want this function to have the type:

 mapSessionStateT :: (m a -> n b) -> SessionStateT s m a -> SessionStateT s n b

But that can not be done, so this is the next best thing.

liftSessionStateT :: (Monad m, MonadTrans t, MonadClientSession sessionData (t m), Monad (t m)) => SessionStateT sessionData m a -> t m a

lift a computation from the SessionStateT monad

The primary purpose of this function is to make it possible to use the MonadState functions such as get and set to get and set the current session data.

That makes it possible to use the MonadState based functions provided by Lens, e.g.:

 do c <- liftSessionStateT $ count += 1

Exported from Web.ClientSession

data Key

The keys used to store the cookies. We have an AES key used to encrypt the cookie and a Skein-MAC-512-256 key used verify the authencity and integrity of the cookie. The AES key needs to have exactly 32 bytes (256 bits) while Skein-MAC-512-256 should have 64 bytes (512 bits).

See also getDefaultKey and initKey.

Instances

Show Key

Dummy Show instance.

getKey

Arguments

:: FilePath

File name where key is stored.

-> IO Key

The actual key.

Get a key from the given text file.

If the file does not exist or is corrupted a random key will be generated and stored in that file.

getDefaultKey :: IO Key

Simply calls getKey defaultKeyFile.