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


-- | Sessions and continuations for Snap web apps
--   
--   This package provides two Snap extensions, implementing sessions as
--   either memory-backed arbitrary types, or as client-side cookie-backed
--   serializable types. The latter uses the <tt>clientsession</tt> package
--   to encrypt the cookie for security. In both extensions, sessions are
--   protected from session stealing by checking the source IP address, and
--   have a configurable timeout (optional for the cookie- backed back
--   end). The session type is user-defined.
--   
--   In addition, a library is provided for a continuation- based
--   programming model called dialogues, which allows natural specification
--   of stateful interactions with the client that span multiple requests.
--   Because the session type is not serializable, this requires the
--   memory-backed implementation.
@package mysnapsession
@version 0.4

module Snap.SessionUtil

-- | Sets a cookie in both the request and the response. This modifies the
--   list of cookies in the request, so that later attempts to get cookies
--   will find this one even within the same request.
setCookie :: MonadSnap m => Cookie -> m ()

-- | Retrieves a cookie, looking first in the response map, and if not
--   there, then in the request. This ensures that the most recently set
--   cookie is retrieved.
lookupCookie :: MonadSnap m => ByteString -> m (Maybe Cookie)

-- | Clears a cookie. This involves setting the cookie to the empty string,
--   with an expiration time in the past.
clearCookie :: MonadSnap m => ByteString -> m ()

-- | If there is another path component in the request path, pop it off,
--   and pass it as a parameter to the handler.
popPathTo :: MonadSnap m => (ByteString -> m a) -> m a

-- | Ensure that we're at the top level of a request, and expect that it be
--   a directory. As with standard HTTP behavior, if a path to a directory
--   is given and the request URI doesn't end in a slash, then the user is
--   redirected to a path ending in a slash.
ifTopDir :: MonadSnap m => m a -> m a

-- | Ensure that we're at the top level of a request, and expect that it be
--   a file. If a trailing slash is given, we pass on the request.
ifTopFile :: MonadSnap m => m a -> m a

-- | Session keys are 64-bit integers with standard numeric type classes.
newtype SessionKey
K :: Word64 -> SessionKey

-- | Generates a random key that is not already used in the given map.
--   Though not technically speaking guaranteed to terminate, this should
--   be fast in practice.
uniqueKey :: (Random k, Ord k) => Map k a -> IO k
instance Eq SessionKey
instance Ord SessionKey
instance Enum SessionKey
instance Bounded SessionKey
instance Num SessionKey
instance Real SessionKey
instance Integral SessionKey
instance Read SessionKey
instance Show SessionKey
instance Random SessionKey


-- | <tt>Snap.Extension.Session</tt> exports the <a>MonadSession</a> type
--   class, which allows you to keep a session object for each client
--   session of a web application. Convenience functions are provided for
--   those cases where the session type is a <a>Map</a>.
module Snap.Extension.Session

-- | This type class captures all Snap-related monads that contain a
--   session.
class MonadSnap m => MonadSession m where { type family Session m; }
getSession :: MonadSession m => m (Session m)
setSession :: MonadSession m => Session m -> m ()
clearSession :: MonadSession m => m ()
touchSession :: MonadSession m => m ()

-- | Insert this into your routes to renew sessions on each request.
inSession :: MonadSession m => m a -> m a
withSession :: MonadSession m => (Session m -> m a) -> m a
getFromSession :: (Ord k, MonadSession m, (Session m) ~ (Map k a)) => k -> m (Maybe a)
deleteFromSession :: (Ord k, MonadSession m, (Session m) ~ (Map k a)) => k -> m ()
setInSession :: (Ord k, MonadSession m, (Session m) ~ (Map k a)) => k -> a -> m ()


-- | <tt>Snap.Extension.Session.Memory</tt> exports the
--   <tt>MonadSessionMemory</tt> interface which allows you to keep an
--   in-memory session object for each client session of a web application.
module Snap.Extension.Session.Memory
class HasMemorySessionManager a where { type family MemorySession a; }
memorySessionMgr :: HasMemorySessionManager a => a -> MemorySessionManager (MemorySession a)
data MemorySessionManager obj
memorySessionInitializer :: NominalDiffTime -> IO t -> Initializer (MemorySessionManager t)
instance HasMemorySessionManager s => MonadSession (SnapExtend s)
instance InitializerState (MemorySessionManager t)

module Snap.Extension.Session.Client
class HasClientSessionManager a where { type family ClientSession a; }
clientSessionMgr :: HasClientSessionManager a => a -> ClientSessionManager (ClientSession a)
data ClientSessionManager t
clientSessionInitializer :: Key -> Maybe NominalDiffTime -> IO t -> Initializer (ClientSessionManager t)
instance (HasClientSessionManager s, Serialize (ClientSession s)) => MonadSession (SnapExtend s)
instance Serialize UTCTime
instance InitializerState (ClientSessionManager t)

module Snap.Dialogues
data DlgManager m
makeDlgManager :: IO (DlgManager m)
class HasDlgManager m a | a -> m
getDlgManager :: HasDlgManager m a => a -> DlgManager m

-- | A value of a <a>Dlg</a> type represents a dialogue between the user
--   and the application, after which the application builds a value of
--   type <tt>a</tt>. The trivial case is that the value is already known.
--   Alternatively, it may be that there is some action to be performed, or
--   else that the user needs to be asked or told something.
data Dlg m a

-- | A value of <a>Page</a> type represents a way of rendering a page,
--   given a request URI that should be used for subsequent requests in
--   order to reassociate them with the current dialogue.
type Page m = ByteString -> m ()

-- | Converts methods for rendering and parsing the result of a page into a
--   <a>Dlg</a> step.
showPage :: Monad m => Page m -> m a -> Dlg m a
dialogue :: (MonadSession m, HasDlgManager m t, t ~ (Session m)) => ByteString -> Dlg m () -> m ()
instance MonadIO m => MonadIO (Dlg m)
instance MonadTrans Dlg
instance Monad m => Monad (Dlg m)