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


-- | Cookie-based session management for the Simple web framework
--   
@package simple-session
@version 0.10.0.0


-- | Adds cookie-based session management to simple <a>Controller</a>s. To
--   add to an application, declare the Controller setting's type an
--   instance of <a>HasSession</a>, and wrap routes with
--   <a>withSession</a>. For example:
--   
--   <pre>
--   data AppSettings = ...
--   
--   instance HasSession AppSettings where
--     ...
--   </pre>
--   
--   <pre>
--   controllerApp settings $ withSessions $ do
--     routeName \"posts\" $ ...
--   </pre>
module Web.Simple.Session

-- | Plaintext mapping of the session map. Both keys and values are
--   <a>ByteString</a>s.
type Session = Map ByteString ByteString

-- | Instances of this class can be used as states by a <a>Controller</a>
--   states to manage cookie-based user sessions. Instances must minimally
--   implement <a>getSession</a> and <a>setSession</a>. By default, the
--   secret session key is taken from the environment variable
--   "SESSION_KEY", or a default dummy key is used if the environment
--   variable "ENV" is set to "development". You can override this
--   behaviour by implementing the <a>sessionKey</a> method. If the
--   controller state contains a dedicated field of type 'Maybe Session', a
--   reasonable implementation would be:
--   
--   <pre>
--   data MyAppSettings = MyAppSettings { myAppSess :: Maybe Session, ...}
--   
--   instance HasSession MyAppSettings where
--      getSession = myAppSess &lt;$&gt; controllerState
--      setSession sess = do
--        cs &lt;- controllerState
--        putState $ cs { myAppSess = sess }
--   </pre>
class HasSession hs where sessionKey = liftIO $ do { env <- getEnvironment; case lookup "SESSION_KEY" env of { Just key -> return $ pack key Nothing -> case lookup "ENV" env of { Just e | e == "development" -> return "test-session-key" _ -> (error "SESSION_KEY environment variable not set") } } }
sessionKey :: HasSession hs => Controller hs ByteString
getSession :: HasSession hs => hs -> Maybe Session
setSession :: HasSession hs => Session -> Controller hs ()

-- | A middleware wrapper around a <a>Controller</a> that sets the
--   "Set-Cookie" header in the HTTP response if the Session is present,
--   i.e. if it was accessed/modified by the <a>Controller</a>.
withSession :: HasSession hs => Controller hs a -> Controller hs a

-- | Lookup a key from the current <tt>Request</tt>s session.
sessionLookup :: HasSession hs => ByteString -> Controller hs (Maybe ByteString)

-- | Insert or replace a key in the current <tt>Request</tt>s session.
sessionInsert :: HasSession hs => ByteString -> ByteString -> Controller hs ()

-- | Remove a key from the current <tt>Request</tt>s session.
sessionDelete :: HasSession hs => ByteString -> Controller hs ()

-- | Clear the entire <a>Session</a>.
sessionClear :: HasSession hs => Controller hs ()

-- | Returns the current <a>Session</a>, either from the <a>getSession</a>
--   cache or by parsing the cookie from the <tt>Request</tt> using
--   <a>sessionFromCookie</a>.
session :: HasSession hs => Controller hs Session

-- | Parses and validates a serialized <a>Session</a> given the secret. If
--   the <a>Session</a> is invalid (i.e. the hmac does not match), an empty
--   <a>Session</a> is returned.
parseSession :: ByteString -> ByteString -> Session

-- | Serializes a <a>Session</a> by applying a sha256 hmac with the given
--   secret key to the serialized <a>Session</a> (using
--   <a>renderSimpleQuery</a>), base64 encoding the result, and prepending
--   it to the serialized <a>Session</a>.
dumpSession :: ByteString -> Session -> ByteString

-- | Adds a "Set-Cookie" with the given key-value tuple to the
--   <a>Response</a>. The path set on the cookie is "/", meaning it applies
--   to all routes on the domain, and no expiration is set.
addCookie :: (ByteString, ByteString) -> Response -> Response
instance HasSession (Maybe Session)