Safe Haskell	Trustworthy
Language	Haskell2010

Web.Simple.Session

Contents

Class and Middleware
Accessors
Utilities

Description

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

Synopsis

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.
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.