simple-session- Cookie-based session management for the Simple web framework

Safe HaskellTrustworthy




Adds cookie-based session management to simple Controllers. 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 Source

Plaintext mapping of the session map. Both keys and values are ByteStrings.

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 }

Minimal complete definition

getSession, setSession


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.

sessionBaseCookie :: Controller hs SetCookie Source


HasSession (Maybe Session) Source

A trivial implementation if the Controller settings is just a Session store.

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.


sessionLookup :: HasSession hs => ByteString -> Controller hs (Maybe ByteString) Source

Lookup a key from the current Requests session.

sessionInsert :: HasSession hs => ByteString -> ByteString -> Controller hs () Source

Insert or replace a key in the current Requests session.

sessionDelete :: HasSession hs => ByteString -> Controller hs () Source

Remove a key from the current Requests session.

sessionClear :: HasSession hs => Controller hs () Source

Clear the entire Session.


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

Parses and validates a serialized Session given the secret. If the Session is invalid (i.e. the hmac does not match), an empty Session is returned.

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.