-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | client-side session data
--   
--   uses the clientsession library to store session data in an HTTP cookie
@package happstack-clientsession
@version 7.3.2


-- | 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 <i>only</i> 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 <a>sessionPath</a> and <a>sessionDomain</a> parameters
--   of <a>SessionConf</a> 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 <tt>LANGUAGE</tt> pragma at the top of your app:
--   
--   {-# LANGUAGE DeriveDataTypeable, TemplateHaskell #-}
--   
--   Then you will need some imports:
--   
--   <pre>
--   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)
--   </pre>
--   
--   Next you will want to create a type to hold your session data. Here we
--   use a simple record which we will update using <tt>data-lens-fd</tt>.
--   But, you could also store a, <tt>Map Text Text</tt>, or whatever suits
--   your fancy as long as it can be serialized. (So no data types that
--   include functions, existential types, etc).
--   
--   <pre>
--   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)
--   </pre>
--   
--   We use the <tt>safecopy</tt> library to serialize the data so we can
--   encrypt it and store it in a cookie. <tt>safecopy</tt> 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
--   <a>SafeCopy</a> instance is with <tt>deriveSafeCopy</tt>:
--   
--   <pre>
--   $(deriveSafeCopy 0 'base ''SessionData)
--   </pre>
--   
--   We also need to define what an <a>emptySession</a> looks like. This
--   will be used for creating new sessions when the client does not
--   already have one:
--   
--   <pre>
--   instance ClientSession SessionData where
--       emptySession = SessionData { _count = 0 }
--   </pre>
--   
--   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, <a>liftSessionStateT</a> to lift the
--   <tt>+=</tt> lens function into <a>ClientSessionT</a> to increment and
--   return the value stored in the client session.
--   
--   Alternatively, we could have used the <a>getSession</a> and
--   <a>putSession</a> functions from <a>MonadClientSession</a>. Those
--   functions do not require the use of <a>liftSessionStateT</a>.
--   
--   <pre>
--   routes :: ClientSessionT SessionData (ServerPartT IO) Response
--   routes =
--       do nullDir
--          c &lt;- liftSessionStateT $ count += 1
--          ok $ toResponse $ "you have viewed this page " ++ (show c) ++ " time(s)."
--   </pre>
--   
--   Finally, we unwrap the <a>ClientSessionT</a> monad transformer using
--   <a>withClientSessionT</a>.
--   
--   The <a>SessionConf</a> type requires an encryption key. You can
--   generate the key using <a>getDefaultKey</a> uses a default filename.
--   Alternatively, you can specific the name you want to use explicitly
--   using <a>getKey</a>. The key will be created automatically if it does
--   not already exist.
--   
--   If you change the key, all existing client sessions will be
--   invalidated.
--   
--   <pre>
--   main :: IO ()
--   main =
--       do key &lt;- getDefaultKey
--          let sessionConf = mkSessionConf key
--          simpleHTTP nullConf $ withClientSessionT sessionConf $ routes
--   </pre>
--   
--   In a real application you might want to use a <tt>newtype</tt> wrapper
--   around <a>ClientSessionT</a> to keep your type signatures sane. An
--   alternative version of this demo which does that can be found here:
--   
--   
--   <a>http://patch-tag.com/r/mae/happstack/snapshot/current/content/pretty/happstack-clientsession/demo/demo.hs</a>
module Happstack.Server.ClientSession

-- | Your session type must have an instance for this class.
class SafeCopy st => ClientSession st

-- | An empty session, i.e. what you get when there is no existing session
--   stored.
emptySession :: ClientSession st => st

-- | Wrapper around the sessionData which tracks it state so we can avoid
--   decoding or encoding/sending the cookie when not required
data SessionStatus sessionData
Unread :: SessionStatus sessionData
NoChange :: sessionData -> SessionStatus sessionData
Modified :: sessionData -> SessionStatus sessionData
Expired :: SessionStatus sessionData

-- | <a>MonadClientSession</a> provides the primary interface to get
--   <tt>sessionData</tt>, put <tt>sessionData</tt> or expire
--   <tt>sessionData</tt>.
--   
--   This is a class so you can use newtype deriving to make the functions
--   available in your custom server monad.
class MonadClientSession sessionData m | m -> sessionData
getSession :: MonadClientSession sessionData m => m sessionData
putSession :: MonadClientSession sessionData m => sessionData -> m ()
expireSession :: MonadClientSession sessionData m => m ()

-- | Configuration for the session cookie for passing to
--   <a>runClientSessionT</a> or <a>withClientSessionT</a>.
data SessionConf
SessionConf :: String -> CookieLife -> Key -> String -> String -> Bool -> Bool -> SessionConf

-- | Name of the cookie to hold your session data.
[sessionCookieName] :: SessionConf -> String

-- | Lifetime of that cookie.
[sessionCookieLife] :: SessionConf -> CookieLife

-- | Encryption key, usually from one of <a>getKey</a>,
--   <a>getDefaultKey</a> and <a>randomKey</a>.
[sessionKey] :: SessionConf -> Key

-- | cookie domain
[sessionDomain] :: SessionConf -> String

-- | cookie path
[sessionPath] :: SessionConf -> String

-- | Only use a session over secure transports.
[sessionSecure] :: SessionConf -> Bool

-- | Only use session over HTTP (to prevent it from being stolen via
--   cross-site scripting)
[sessionHttpOnly] :: SessionConf -> Bool

-- | Create a <a>SessionConf</a> using defaults for everything except
--   <a>sessionKey</a>. You can use record update syntax to override
--   individual fields.
--   
--   <pre>
--   main = do key &lt;- getDefaultKey
--             let sessConf = (mkSessionConf key) { sessionCookieLife = oneWeek }
--             simpleHTTP nullConf $ withClientSessionT sessConf handlers
--     where
--       oneWeek  = MaxAge $ 60 * 60 * 24 * 7
--       handlers = msum [...]
--   </pre>
--   
--   <a>mkSessionConf</a> is currently defined as:
--   
--   <pre>
--   mkSessionConf :: Key -&gt; SessionConf
--   mkSessionConf key = SessionConf
--      { sessionCookieName = "Happstack.ClientSession"
--      , sessionCookieLife = Session
--      , sessionKey        = key
--      , sessionDomain     = ""
--      , sessionPath       = "/"
--      , sessionSecure     = False
--      , sessionHttpOnly   = True
--      }
--   </pre>
--   
--   see also: <a>getKey</a>, <a>getDefaultKey</a>
mkSessionConf :: Key -> SessionConf

-- | <a>ClientSessionT</a> provides an environment in which we can access
--   and update the client-side session state
--   
--   The inner monad needs to provide an instance of <a>Happstack</a> so
--   that the cookie value can be read and set. According
--   <a>ClientSessionT</a> must appear outside <tt>ServerPartT</tt> not
--   inside it.
newtype ClientSessionT sessionData m a
ClientSessionT :: ReaderT SessionConf (SessionStateT sessionData m) a -> ClientSessionT sessionData m a
[unClientSessionT] :: ClientSessionT sessionData m a -> ReaderT SessionConf (SessionStateT sessionData m) a

-- | transform the inner monad, but leave the session data alone.
mapClientSessionT :: (forall s. m (a, s) -> n (b, s)) -> ClientSessionT sessionData m a -> ClientSessionT sessionData n b

-- | run the <a>ClientSessionT</a> monad and get the result plus the final
--   <tt>SessionStatus sessionData</tt>
--   
--   This function does <i>not</i> automatically update the cookie if the
--   session has been modified. It is up to you to do that. You probably
--   want to use <a>withClientSessionT</a> instead.
--   
--   see also: <a>withClientSessionT</a>, <a>mkSessionConf</a>
runClientSessionT :: ClientSessionT sessionData m a -> SessionConf -> m (a, SessionStatus sessionData)

-- | Wrapper around your handlers that use the session.
--   
--   This function automatically takes care of expiring or updating the
--   cookie if the <a>expireSession</a> or <tt>modifySession</tt> is
--   called.
--   
--   If no changes are made to the session, then the cookie will not be
--   resent (because there is no need to).
withClientSessionT :: (Happstack m, Functor m, Monad m, FilterMonad Response m, ClientSession sessionData) => SessionConf -> ClientSessionT sessionData m a -> m a

-- | <a>SessionStateT</a> is like <a>StateT</a>, except it records if
--   <a>put</a> was ever called
data SessionStateT s m a

-- | Transform the inner monad. (similar to <a>mapStateT</a>)
--   
--   The <tt>forall s.</tt> is to prevent you from modifying the session
--   state.
--   
--   In theory we want this function to have the type:
--   
--   <pre>
--   mapSessionStateT :: (m a -&gt; n b) -&gt; SessionStateT s m a -&gt; SessionStateT s n b
--   </pre>
--   
--   But that can not be done, so this is the next best thing.
mapSessionStateT :: (forall s. m (a, s) -> n (b, s)) -> SessionStateT sessionData m a -> SessionStateT sessionData n b

-- | lift a computation from the <a>SessionStateT</a> monad
--   
--   The primary purpose of this function is to make it possible to use the
--   <a>MonadState</a> functions such as <a>get</a> and <tt>set</tt> to get
--   and set the current session data.
--   
--   That makes it possible to use the <a>MonadState</a> based functions
--   provided by <a>Lens</a>, e.g.:
--   
--   <pre>
--   do c &lt;- liftSessionStateT $ count += 1
--   </pre>
liftSessionStateT :: (Monad m, MonadTrans t, MonadClientSession sessionData (t m), Monad (t m)) => SessionStateT sessionData m a -> t m a

-- | 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 <a>getDefaultKey</a> and <a>initKey</a>.
data 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.
getKey :: FilePath -> IO Key

-- | Simply calls <a>getKey</a> <a>defaultKeyFile</a>.
getDefaultKey :: IO Key

-- | Generate a random <a>Key</a>. Besides the <a>Key</a>, the
--   <tt>ByteString</tt> passed to <a>initKey</a> is returned so that it
--   can be saved for later use.
randomKey :: IO (ByteString, Key)
instance GHC.Show.Show sessionData => GHC.Show.Show (Happstack.Server.ClientSession.SessionStatus sessionData)
instance GHC.Read.Read sessionData => GHC.Read.Read (Happstack.Server.ClientSession.SessionStatus sessionData)
instance GHC.Classes.Ord sessionData => GHC.Classes.Ord (Happstack.Server.ClientSession.SessionStatus sessionData)
instance GHC.Classes.Eq sessionData => GHC.Classes.Eq (Happstack.Server.ClientSession.SessionStatus sessionData)
instance Happstack.Server.Internal.Monads.ServerMonad m => Happstack.Server.Internal.Monads.ServerMonad (Happstack.Server.ClientSession.SessionStateT s m)
instance Happstack.Server.Internal.Monads.WebMonad r m => Happstack.Server.Internal.Monads.WebMonad r (Happstack.Server.ClientSession.SessionStateT s m)
instance Happstack.Server.Internal.Monads.FilterMonad r m => Happstack.Server.Internal.Monads.FilterMonad r (Happstack.Server.ClientSession.SessionStateT s m)
instance (GHC.Base.Monad m, Happstack.Server.RqData.HasRqData m) => Happstack.Server.RqData.HasRqData (Happstack.Server.ClientSession.SessionStateT s m)
instance Control.Monad.Trans.Class.MonadTrans (Happstack.Server.ClientSession.SessionStateT s)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Happstack.Server.ClientSession.SessionStateT s m)
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Happstack.Server.ClientSession.SessionStateT s m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Happstack.Server.ClientSession.SessionStateT s m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Happstack.Server.ClientSession.SessionStateT s m)
instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Happstack.Server.ClientSession.SessionStateT s m)
instance GHC.Base.MonadPlus m => GHC.Base.MonadPlus (Happstack.Server.ClientSession.SessionStateT s m)
instance GHC.Base.Monad m => GHC.Base.Monad (Happstack.Server.ClientSession.SessionStateT s m)
instance GHC.Base.MonadPlus m => GHC.Base.Alternative (Happstack.Server.ClientSession.SessionStateT s m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Happstack.Server.ClientSession.SessionStateT s m)
instance GHC.Base.Functor m => GHC.Base.Functor (Happstack.Server.ClientSession.SessionStateT s m)
instance Happstack.Server.Internal.Monads.ServerMonad m => Happstack.Server.Internal.Monads.ServerMonad (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance Happstack.Server.Internal.Monads.WebMonad r m => Happstack.Server.Internal.Monads.WebMonad r (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance Happstack.Server.Internal.Monads.FilterMonad r m => Happstack.Server.Internal.Monads.FilterMonad r (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance (GHC.Base.Monad m, Happstack.Server.RqData.HasRqData m) => Happstack.Server.RqData.HasRqData (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance GHC.Base.MonadPlus m => GHC.Base.MonadPlus (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance Control.Monad.Base.MonadBase b m => Control.Monad.Base.MonadBase b (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance GHC.Base.Monad m => GHC.Base.Monad (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance GHC.Base.MonadPlus m => GHC.Base.Alternative (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance GHC.Base.Functor m => GHC.Base.Functor (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance (GHC.Base.Functor m, GHC.Base.MonadPlus m, Happstack.Server.RqData.HasRqData m, Happstack.Server.ClientSession.ClientSession sessionData) => Happstack.Server.ClientSession.MonadClientSession sessionData (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance (GHC.Base.Monad m, Happstack.Server.ClientSession.MonadClientSession sessionData m) => Happstack.Server.ClientSession.MonadClientSession sessionData (Control.Monad.Trans.Cont.ContT c m)
instance (GHC.Base.Monad m, Happstack.Server.ClientSession.MonadClientSession sessionData m, Control.Monad.Trans.Error.Error e) => Happstack.Server.ClientSession.MonadClientSession sessionData (Control.Monad.Trans.Error.ErrorT e m)
instance (GHC.Base.Monad m, Happstack.Server.ClientSession.MonadClientSession sessionData m) => Happstack.Server.ClientSession.MonadClientSession sessionData (Control.Monad.Trans.Reader.ReaderT r m)
instance (GHC.Base.Monad m, Happstack.Server.ClientSession.MonadClientSession sessionData m) => Happstack.Server.ClientSession.MonadClientSession sessionData (Control.Monad.Trans.State.Lazy.StateT s m)
instance (GHC.Base.Monad m, Happstack.Server.ClientSession.MonadClientSession sessionData m, GHC.Base.Monoid w) => Happstack.Server.ClientSession.MonadClientSession sessionData (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monad m, Happstack.Server.ClientSession.MonadClientSession sessionData m, GHC.Base.Monoid w) => Happstack.Server.ClientSession.MonadClientSession sessionData (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance Happstack.Server.Monads.Happstack m => Happstack.Server.Monads.Happstack (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance GHC.Base.MonadPlus m => GHC.Base.Semigroup (Happstack.Server.ClientSession.ClientSessionT sessionData m a)
instance GHC.Base.MonadPlus m => GHC.Base.Monoid (Happstack.Server.ClientSession.ClientSessionT sessionData m a)
instance Control.Monad.Trans.Class.MonadTrans (Happstack.Server.ClientSession.ClientSessionT sessionData)
instance Control.Monad.Trans.Control.MonadTransControl (Happstack.Server.ClientSession.ClientSessionT s)
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Happstack.Server.ClientSession.ClientSessionT s m)
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance Control.Monad.RWS.Class.MonadRWS r w s m => Control.Monad.RWS.Class.MonadRWS r w s (Happstack.Server.ClientSession.ClientSessionT sessionData m)
instance Happstack.Server.Monads.Happstack m => Happstack.Server.Monads.Happstack (Happstack.Server.ClientSession.SessionStateT sessionData m)
instance GHC.Base.MonadPlus m => GHC.Base.Semigroup (Happstack.Server.ClientSession.SessionStateT sessionData m a)
instance GHC.Base.MonadPlus m => GHC.Base.Monoid (Happstack.Server.ClientSession.SessionStateT sessionData m a)
instance (GHC.Base.Monad m, Happstack.Server.ClientSession.ClientSession sessionData) => Control.Monad.State.Class.MonadState sessionData (Happstack.Server.ClientSession.SessionStateT sessionData m)
instance Control.Monad.Trans.Control.MonadTransControl (Happstack.Server.ClientSession.SessionStateT s)
instance Control.Monad.Trans.Control.MonadBaseControl b m => Control.Monad.Trans.Control.MonadBaseControl b (Happstack.Server.ClientSession.SessionStateT s m)
instance Data.SafeCopy.SafeCopy.SafeCopy Web.ClientSession.Key