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


-- | Cookie-based session management for the Simple web framework
--   
--   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>
--   
--   Then, in your controllers you can seemlessly get and set keys from the
--   session:
--   
--   <pre>
--   get "/profile" $ do
--     muserId &lt;- sessionLookup "current_user_id"
--     case muserIf of
--       Nothing -&gt; respond $ redirectTo "/login"
--       Just userId -&gt; [handle request]
--   </pre>
@package simple-session
@version 2.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>
--   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.
--   
--   The default generated cookie always uses the <tt>httponly</tt> option,
--   and the <tt>secure</tt> option if the request is over HTTPS. You can
--   override this behavior, as well as other cookie options (e.g. the
--   path, expiration and domain) by implementing the
--   <a>sessionBaseCookie</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

-- | Returns the secret session key. The default implementation uses the
--   "SESSION_KEY" environment variable. If it is not present, and the
--   "ENV" environment variable is set to "development", a dummy, hardcoded
--   key is used.
sessionKey :: HasSession hs => Controller hs ByteString

-- | Returns the cached session for the current request, or nothing if the
--   session has not been set yet for this request.
getSession :: HasSession hs => hs -> Maybe Session

-- | Stores a parsed or changed session for the remainder of the
--   request.This is used both for cached a parsed session cookie as well
--   as for serializing to the "Set-Cookie" header when responding.
setSession :: HasSession hs => Session -> Controller hs ()
sessionBaseCookie :: HasSession hs => Controller hs SetCookie

-- | 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) -> SetCookie -> Response -> Response
instance Web.Simple.Session.HasSession (GHC.Maybe.Maybe Web.Simple.Session.Session)