Web.Simple.Session

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\" $ ...

Documentation

type Session = Map ByteString ByteString

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

Class and Middleware

class HasSession hs where

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

Methods

sessionKey :: Controller hs ByteString

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

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 ()

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

Instances

HasSession (Maybe Session)

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

Defined in Web.Simple.Session

Methods

sessionKey :: Controller (Maybe Session) ByteString

getSession :: Maybe Session -> Maybe Session

setSession :: Session -> Controller (Maybe Session) ()

sessionBaseCookie :: Controller (Maybe Session) SetCookie

withSession :: HasSession hs => Controller hs a -> Controller hs a

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)

Lookup a key from the current Requests session.

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

Insert or replace a key in the current Requests session.

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

Remove a key from the current Requests session.

sessionClear :: HasSession hs => Controller hs ()

Clear the entire Session.

Utilities

session :: HasSession hs => Controller hs Session

Returns the current Session, either from the getSession cache or by parsing the cookie from the Request using sessionFromCookie.

parseSession :: ByteString -> ByteString -> Session

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

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

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.