Safe Haskell | Trustworthy |
---|---|
Language | Haskell2010 |
Adds cookie-based session management to simple Controller
s. To add to an
application, declare the Controller setting's type an instance of
HasSession
, and wrap routes with withSession
. For example:
data AppSettings = ... instance HasSession AppSettings where ...
controllerApp settings $ withSessions $ do routeName \"posts\" $ ...
- type Session = Map ByteString ByteString
- class HasSession hs where
- sessionKey :: Controller hs ByteString
- getSession :: hs -> Maybe Session
- setSession :: Session -> Controller hs ()
- sessionBaseCookie :: Controller hs SetCookie
- withSession :: HasSession hs => Controller hs a -> Controller hs a
- sessionLookup :: HasSession hs => ByteString -> Controller hs (Maybe ByteString)
- sessionInsert :: HasSession hs => ByteString -> ByteString -> Controller hs ()
- sessionDelete :: HasSession hs => ByteString -> Controller hs ()
- sessionClear :: HasSession hs => Controller hs ()
- session :: HasSession hs => Controller hs Session
- parseSession :: ByteString -> ByteString -> Session
- dumpSession :: ByteString -> Session -> ByteString
- addCookie :: (ByteString, ByteString) -> SetCookie -> Response -> Response
Documentation
type Session = Map ByteString ByteString Source
Plaintext mapping of the session map. Both keys and values are
ByteString
s.
Class and Middleware
class HasSession hs where Source
Instances of this class can be used as states by a Controller
to manage
cookie-based user sessions. Instances must minimally implement getSession
and setSession
.
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 sessionKey
method.
The default generated cookie always uses the httponly
option, and the
secure
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 sessionBaseCookie
method.
If the controller state contains a dedicated field of type 'Maybe Session', a reasonable implementation would be:
data MyAppSettings = MyAppSettings { myAppSess :: Maybe Session, ...} instance HasSession MyAppSettings where getSession = myAppSess <$> controllerState setSession sess = do cs <- controllerState putState $ cs { myAppSess = sess }
sessionKey :: Controller hs ByteString Source
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.
getSession :: hs -> Maybe Session Source
Returns the cached session for the current request, or nothing if the session has not been set yet for this request.
setSession :: Session -> Controller hs () Source
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.
HasSession (Maybe Session) Source | A trivial implementation if the |
withSession :: HasSession hs => Controller hs a -> Controller hs a Source
A middleware wrapper around a Controller
that sets the "Set-Cookie"
header in the HTTP response if the Session is present, i.e. if it was
accessed/modified by the Controller
.
Accessors
sessionLookup :: HasSession hs => ByteString -> Controller hs (Maybe ByteString) Source
Lookup a key from the current Request
s session.
sessionInsert :: HasSession hs => ByteString -> ByteString -> Controller hs () Source
Insert or replace a key in the current Request
s session.
sessionDelete :: HasSession hs => ByteString -> Controller hs () Source
Remove a key from the current Request
s session.
sessionClear :: HasSession hs => Controller hs () Source
Clear the entire Session
.
Utilities
session :: HasSession hs => Controller hs Session Source
Returns the current Session
, either from the getSession
cache or by
parsing the cookie from the Request
using sessionFromCookie
.
parseSession :: ByteString -> ByteString -> Session Source
dumpSession :: ByteString -> Session -> ByteString Source
Serializes a Session
by applying a sha256 hmac with the given secret
key to the serialized Session
(using renderSimpleQuery
), base64 encoding
the result, and prepending it to the serialized Session
.
addCookie :: (ByteString, ByteString) -> SetCookie -> Response -> Response Source
Adds a "Set-Cookie" with the given key-value tuple to the Response
.
The path set on the cookie is "/", meaning it applies to all routes on the
domain, and no expiration is set.