| Safe Haskell | None |
|---|---|
| Language | Haskell98 |
Happstack.Server.ClientSession
Description
This module provides a simple session implementation which stores session data on the client as a cookie value.
The cookie values are stored in an encrypted 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 client-side 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 $ routesIn a real application you might want to use a newtype wrapper around
ClientSessionT to keep your type signatures sane. An alternative
version of this demo which does that can be found here:
- class SafeCopy st => ClientSession st where
- data SessionStatus sessionData
- class MonadClientSession sessionData m | m -> sessionData where
- data SessionConf = SessionConf {}
- mkSessionConf :: Key -> SessionConf
- newtype ClientSessionT sessionData m a = ClientSessionT {
- unClientSessionT :: ReaderT SessionConf (SessionStateT sessionData m) a
- mapClientSessionT :: (forall s. m (a, s) -> n (b, s)) -> ClientSessionT sessionData m a -> ClientSessionT sessionData n b
- runClientSessionT :: ClientSessionT sessionData m a -> SessionConf -> m (a, SessionStatus sessionData)
- withClientSessionT :: (Happstack m, Functor m, Monad m, FilterMonad Response m, ClientSession sessionData) => SessionConf -> ClientSessionT sessionData m a -> m a
- data SessionStateT s m a
- mapSessionStateT :: (forall s. m (a, s) -> n (b, s)) -> SessionStateT sessionData m a -> SessionStateT sessionData n b
- liftSessionStateT :: (Monad m, MonadTrans t, MonadClientSession sessionData (t m), Monad (t m)) => SessionStateT sessionData m a -> t m a
- data Key :: *
- getKey :: FilePath -> IO Key
- getDefaultKey :: IO Key
- randomKey :: IO (ByteString, Key)
Happstack.Server.ClientSession
class SafeCopy st => ClientSession st where Source #
Your session type must have an instance for this class.
Minimal complete definition
Methods
emptySession :: st Source #
An empty session, i.e. what you get when there is no existing session stored.
data SessionStatus sessionData Source #
Wrapper around the sessionData which tracks it state so we can avoid decoding or encoding/sending the cookie when not required
Instances
| Eq sessionData => Eq (SessionStatus sessionData) Source # | |
| Ord sessionData => Ord (SessionStatus sessionData) Source # | |
| Read sessionData => Read (SessionStatus sessionData) Source # | |
| Show sessionData => Show (SessionStatus sessionData) Source # | |
class MonadClientSession sessionData m | m -> sessionData where Source #
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.
Minimal complete definition
Methods
getSession :: m sessionData Source #
putSession :: sessionData -> m () Source #
expireSession :: m () Source #
Instances
| (Monad m, MonadClientSession sessionData m, Monoid w) => MonadClientSession sessionData (WriterT w m) Source # | |
| (Monad m, MonadClientSession sessionData m) => MonadClientSession sessionData (StateT s m) Source # | |
| (Monad m, MonadClientSession sessionData m, Error e) => MonadClientSession sessionData (ErrorT e m) Source # | |
| (Functor m, MonadPlus m, HasRqData m, ClientSession sessionData) => MonadClientSession sessionData (ClientSessionT sessionData m) Source # | |
| (Monad m, MonadClientSession sessionData m) => MonadClientSession sessionData (ReaderT * r m) Source # | |
| (Monad m, MonadClientSession sessionData m) => MonadClientSession sessionData (ContT * c m) Source # | |
| (Monad m, MonadClientSession sessionData m, Monoid w) => MonadClientSession sessionData (RWST r w s m) Source # | |
data SessionConf Source #
Configuration for the session cookie for passing to runClientSessionT or withClientSessionT.
Constructors
| SessionConf | |
Fields
| |
mkSessionConf :: Key -> SessionConf Source #
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 Source #
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
| |
Instances
mapClientSessionT :: (forall s. m (a, s) -> n (b, s)) -> ClientSessionT sessionData m a -> ClientSessionT sessionData n b Source #
transform the inner monad, but leave the session data alone.
runClientSessionT :: ClientSessionT sessionData m a -> SessionConf -> m (a, SessionStatus sessionData) Source #
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 Source #
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 Source #
SessionStateT is like StateT, except it records if put was ever called
Instances
mapSessionStateT :: (forall s. m (a, s) -> n (b, s)) -> SessionStateT sessionData m a -> SessionStateT sessionData n b Source #
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 Source #
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
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 must have exactly 32 bytes (256 bits) while Skein-MAC-512-256 must have 64 bytes (512 bits).
See also getDefaultKey and initKey.
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.
randomKey :: IO (ByteString, Key) #