Safe Haskell	None
Language	Haskell98

Web.ServerSession.Core.Internal

Description

Internal module exposing the guts of the package. Use at your own risk. No API stability guarantees apply.

UndecidableInstances is required in order to implement Eq, Ord, Show, etc. on data types that have Decomposed fields, and should be fairly safe.

Synopsis

Documentation

newtype SessionId sess #

The ID of a session. Always 18 bytes base64url-encoded as 24 characters. The sess type variable is a phantom type for the session data type this session ID points to.

Implementation notes:

Use fromPathPiece for parsing untrusted input.
Use generateSessionId for securely generating new session IDs.

Constructors

S
Fields unS :: Text

Instances

Eq (SessionId sess) #
Methods (==) :: SessionId sess -> SessionId sess -> Bool # (/=) :: SessionId sess -> SessionId sess -> Bool #
Ord (SessionId sess) #
Methods compare :: SessionId sess -> SessionId sess -> Ordering # (<) :: SessionId sess -> SessionId sess -> Bool # (<=) :: SessionId sess -> SessionId sess -> Bool # (>) :: SessionId sess -> SessionId sess -> Bool # (>=) :: SessionId sess -> SessionId sess -> Bool # max :: SessionId sess -> SessionId sess -> SessionId sess # min :: SessionId sess -> SessionId sess -> SessionId sess #
Read (SessionId sess) #
Methods readsPrec :: Int -> ReadS (SessionId sess) # readList :: ReadS [SessionId sess] # readPrec :: ReadPrec (SessionId sess) # readListPrec :: ReadPrec [SessionId sess] #
Show (SessionId sess) #
Methods showsPrec :: Int -> SessionId sess -> ShowS # show :: SessionId sess -> String # showList :: [SessionId sess] -> ShowS #
Hashable (SessionId sess) #
Methods hashWithSalt :: Int -> SessionId sess -> Int # hash :: SessionId sess -> Int #
ToJSON (SessionId sess) #
Methods toJSON :: SessionId sess -> Value # toEncoding :: SessionId sess -> Encoding # toJSONList :: [SessionId sess] -> Value # toEncodingList :: [SessionId sess] -> Encoding #
FromJSON (SessionId sess) #
Methods parseJSON :: Value -> Parser (SessionId sess) # parseJSONList :: Value -> Parser [SessionId sess] #
PathPiece (SessionId sess) #	Sanity checks input on `fromPathPiece` (untrusted input).
Methods fromPathPiece :: Text -> Maybe (SessionId sess) # toPathPiece :: SessionId sess -> Text #

checkSessionId :: Text -> Maybe (SessionId sess) #

(Internal) Check that the given text is a base64url-encoded representation of 18 bytes.

generateSessionId :: Generator -> IO (SessionId sess) #

Securely generate a new SessionId.

type AuthId = ByteString #

Value of the authKey session key.

data Session sess #

Representation of a saved session.

This representation is used by the serversession family of packages, transferring data between this core package and storage backend packages. The sess type variable describes the session data type.

Constructors

Session
Fields sessionKey :: SessionId sess Session ID, primary key. sessionAuthId :: Maybe AuthId Value of `authKey` session key, separate from the rest. sessionData :: Decomposed sess Rest of the session data. sessionCreatedAt :: UTCTime When this session was created. sessionAccessedAt :: UTCTime When this session was last accessed.

Instances

Eq (Decomposed sess) => Eq (Session sess) #
Methods (==) :: Session sess -> Session sess -> Bool # (/=) :: Session sess -> Session sess -> Bool #
Ord (Decomposed sess) => Ord (Session sess) #
Methods compare :: Session sess -> Session sess -> Ordering # (<) :: Session sess -> Session sess -> Bool # (<=) :: Session sess -> Session sess -> Bool # (>) :: Session sess -> Session sess -> Bool # (>=) :: Session sess -> Session sess -> Bool # max :: Session sess -> Session sess -> Session sess # min :: Session sess -> Session sess -> Session sess #
Show (Decomposed sess) => Show (Session sess) #
Methods showsPrec :: Int -> Session sess -> ShowS # show :: Session sess -> String # showList :: [Session sess] -> ShowS #

newtype SessionMap #

A newtype for a common session map.

This is a common representation of a session. Although serversession has generalized session data types, you can use this one if you don't want to worry about it. We strive to support this session data type on all frontends and storage backends.

Constructors

SessionMap
Fields unSessionMap :: HashMap Text ByteString

Instances

Eq SessionMap #
Methods (==) :: SessionMap -> SessionMap -> Bool # (/=) :: SessionMap -> SessionMap -> Bool #
Read SessionMap #
Methods readsPrec :: Int -> ReadS SessionMap # readList :: ReadS [SessionMap] # readPrec :: ReadPrec SessionMap # readListPrec :: ReadPrec [SessionMap] #
Show SessionMap #
Methods showsPrec :: Int -> SessionMap -> ShowS # show :: SessionMap -> String # showList :: [SessionMap] -> ShowS #
IsSessionData SessionMap #	A `SessionMap` decomposes into a `SessionMap` minus the keys that were removed. The auth key is added back when recomposing.
Associated Types type Decomposed SessionMap :: * # Methods emptySession :: SessionMap # decomposeSession :: Text -> SessionMap -> DecomposedSession SessionMap # recomposeSession :: Text -> Maybe AuthId -> Decomposed SessionMap -> SessionMap # isSameDecomposed :: proxy SessionMap -> Decomposed SessionMap -> Decomposed SessionMap -> Bool # isDecomposedEmpty :: proxy SessionMap -> Decomposed SessionMap -> Bool #
type Decomposed SessionMap #
type Decomposed SessionMap = SessionMap

class (Show (Decomposed sess), Typeable (Decomposed sess), Typeable sess) => IsSessionData sess where #

Class for data types to be used as session data (cf. sessionData, SessionData).

The Show constrain is needed for StorageException.

Minimal complete definition

emptySession, decomposeSession, recomposeSession, isSameDecomposed, isDecomposedEmpty

Associated Types

type Decomposed sess :: * #

The type of the session data after being decomposed. This may be the same as sess.

Methods

emptySession :: sess #

Empty session data.

decomposeSession :: Text -> sess -> DecomposedSession sess #

Decompose session data into:

The auth ID of the logged in user (cf. setAuthKey, dsAuthId).
If the session is being forced to be invalidated (cf. forceInvalidateKey, ForceInvalidate).
The rest of the session data (cf. Decomposed).

recomposeSession :: Text -> Maybe AuthId -> Decomposed sess -> sess #

Recompose a decomposed session again into a proper sess.

isSameDecomposed :: proxy sess -> Decomposed sess -> Decomposed sess -> Bool #

Returns True when both session datas are to be considered the same.

This is used to optimize storage calls (cf. setTimeoutResolution). Always returning False will disable the optimization but won't have any other adverse effects.

For data types implementing Eq, this is usually a good implementation:

isSameDecomposed _ = (==)

isDecomposedEmpty :: proxy sess -> Decomposed sess -> Bool #

Returns True if the decomposed session data is to be considered empty.

This is used to avoid storing empty session data if at all possible. Always returning False will disable the optimization but won't have any other adverse effects.

Instances

IsSessionData SessionMap #

A SessionMap decomposes into a SessionMap minus the keys that were removed. The auth key is added back when recomposing.

data DecomposedSession sess #

A session data type sess with its special variables taken apart.

Constructors

DecomposedSession
Fields dsAuthId :: !(Maybe ByteString) dsForceInvalidate :: !ForceInvalidate dsDecomposed :: !(Decomposed sess)

Instances

Eq (Decomposed sess) => Eq (DecomposedSession sess) #
Methods (==) :: DecomposedSession sess -> DecomposedSession sess -> Bool # (/=) :: DecomposedSession sess -> DecomposedSession sess -> Bool #
Ord (Decomposed sess) => Ord (DecomposedSession sess) #
Methods compare :: DecomposedSession sess -> DecomposedSession sess -> Ordering # (<) :: DecomposedSession sess -> DecomposedSession sess -> Bool # (<=) :: DecomposedSession sess -> DecomposedSession sess -> Bool # (>) :: DecomposedSession sess -> DecomposedSession sess -> Bool # (>=) :: DecomposedSession sess -> DecomposedSession sess -> Bool # max :: DecomposedSession sess -> DecomposedSession sess -> DecomposedSession sess # min :: DecomposedSession sess -> DecomposedSession sess -> DecomposedSession sess #
Show (Decomposed sess) => Show (DecomposedSession sess) #
Methods showsPrec :: Int -> DecomposedSession sess -> ShowS # show :: DecomposedSession sess -> String # showList :: [DecomposedSession sess] -> ShowS #

class (Typeable sto, MonadIO (TransactionM sto), IsSessionData (SessionData sto)) => Storage sto where #

A storage backend sto for server-side sessions. The sess session data type and/or its Decomposed version may be constrained depending on the storage backend capabilities.

Minimal complete definition

runTransactionM, getSession, deleteSession, deleteAllSessionsOfAuthId, insertSession, replaceSession

Associated Types

type SessionData sto :: * #

The session data type used by this storage.

type TransactionM sto :: * -> * #

Monad where transactions happen for this backend. We do not require transactions to be ACID.

Methods

runTransactionM :: sto -> TransactionM sto a -> IO a #

Run a transaction on the IO monad.

getSession :: sto -> SessionId (SessionData sto) -> TransactionM sto (Maybe (Session (SessionData sto))) #

Get the session for the given session ID. Returns Nothing if the session is not found.

deleteSession :: sto -> SessionId (SessionData sto) -> TransactionM sto () #

Delete the session with given session ID. Does not do anything if the session is not found.

deleteAllSessionsOfAuthId :: sto -> AuthId -> TransactionM sto () #

Delete all sessions of the given auth ID. Does not do anything if there are no sessions of the given auth ID.

insertSession :: sto -> Session (SessionData sto) -> TransactionM sto () #

Insert a new session. Throws SessionAlreadyExists if there already exists a session with the same session ID (we only call this method after generating a fresh session ID).

replaceSession :: sto -> Session (SessionData sto) -> TransactionM sto () #

Replace the contents of a session. Throws SessionDoesNotExist if there is no session with the given session ID (we only call this method when updating a session that is known to exist).

It is possible to have concurrent requests using the same session ID such that:

request 1: loadSession
                       request 2: loadSession
                       request 2: forceInvalidate
                       request 2: saveSession
request 1: saveSession

The request 2's call to saveSession will have called deleteSession as invalidation was forced. However, request 1 has no idea and will try to replaceSession. The following behaviors are possible:

Make replaceSession insert the session again. However, this will undo the invalidation of request 2. As invalidations are done for security reasons, this is a bad idea.
Make replaceSession silently discard the session. The reasoning is that, as the session was going to be invalidated if request 2 came after request 1, we can discard its contents. However, we can't be sure that request 2 would have had the same effect if it had seen the session changes made by request 1 (and vice versa).
Make replaceSession throw an error. This error is going to be unrecoverable since usually the session processing is done at the end of the request processing by the web framework, thus leading to a 500 Internal Server Error. However, this signals to the caller that something went wrong, which is correct.

Most of the time this discussion does not matter. Invalidations usually occur at times where only one request is flying.

data StorageException sto #

Common exceptions that may be thrown by any storage.

Constructors

SessionAlreadyExists	Exception thrown by `insertSession` whenever a session with same ID already exists.
Fields seExistingSession :: Session (SessionData sto) seNewSession :: Session (SessionData sto)
SessionDoesNotExist	Exception thrown by `replaceSession` whenever trying to replace a session that is not present on the storage.
Fields seNewSession :: Session (SessionData sto)

Instances

Eq (Decomposed (SessionData sto)) => Eq (StorageException sto) #
Methods (==) :: StorageException sto -> StorageException sto -> Bool # (/=) :: StorageException sto -> StorageException sto -> Bool #
Ord (Decomposed (SessionData sto)) => Ord (StorageException sto) #
Methods compare :: StorageException sto -> StorageException sto -> Ordering # (<) :: StorageException sto -> StorageException sto -> Bool # (<=) :: StorageException sto -> StorageException sto -> Bool # (>) :: StorageException sto -> StorageException sto -> Bool # (>=) :: StorageException sto -> StorageException sto -> Bool # max :: StorageException sto -> StorageException sto -> StorageException sto # min :: StorageException sto -> StorageException sto -> StorageException sto #
Show (Decomposed (SessionData sto)) => Show (StorageException sto) #
Methods showsPrec :: Int -> StorageException sto -> ShowS # show :: StorageException sto -> String # showList :: [StorageException sto] -> ShowS #
Storage sto => Exception (StorageException sto) #
Methods toException :: StorageException sto -> SomeException # fromException :: SomeException -> Maybe (StorageException sto) # displayException :: StorageException sto -> String #

data State sto #

The server-side session backend needs to maintain some state in order to work:

A nonce generator for the session IDs.
A reference to the storage backend.
The name of cookie where the session ID will be saved (setCookieName).
Authentication session variable (setAuthKey).
Idle and absolute timeouts (setIdleTimeout and setAbsoluteTimeout).
Timeout resolution (setTimeoutResolution).
Whether cookies should be persistent (setPersistentCookies), HTTP-only (setHTTPOnlyCookies) and/or secure (setSecureCookies).

Create a new State using createState.

Constructors

State
Fields generator :: !Generator storage :: !sto cookieName :: !Text authKey :: !Text idleTimeout :: !(Maybe NominalDiffTime) absoluteTimeout :: !(Maybe NominalDiffTime) timeoutResolution :: !(Maybe NominalDiffTime) persistentCookies :: !Bool httpOnlyCookies :: !Bool secureCookies :: !Bool

createState :: MonadIO m => sto -> m (State sto) #

Create a new State for the server-side session backend using the given storage backend.

setCookieName :: Text -> State sto -> State sto #

Set the name of cookie where the session ID will be saved. Defaults to "JSESSIONID", which is a generic cookie name used by many frameworks thus making it harder to fingerprint this implementation.

setAuthKey :: Text -> State sto -> State sto #

Set the name of the session variable that keeps track of the logged user.

This setting is used by session data types that are Map-alike, using a lookup function. However, the IsSessionData instance of a session data type may choose not to use it. For example, if you implemented a custom data type, you could return the AuthId without needing a lookup.

Defaults to "_ID" (used by yesod-auth).

setIdleTimeout :: Maybe NominalDiffTime -> State sto -> State sto #

Set the idle timeout for all sessions. This is used both on the client side (by setting the cookie expires fields) and on the server side (the idle timeout is enforced even if the cookie expiration is ignored). Setting to Nothing removes the idle timeout entirely.

"[The idle timemout] defines the amount of time a session will remain active in case there is no activity in the session, closing and invalidating the session upon the defined idle period since the last HTTP request received by the web application for a given session ID." (Source)

Defaults to 7 days.

setAbsoluteTimeout :: Maybe NominalDiffTime -> State sto -> State sto #

Set the absolute timeout for all sessions. This is used both on the client side (by setting the cookie expires fields) and on the server side (the absolute timeout is enforced even if the cookie expiration is ignored). Setting to Nothing removes the absolute timeout entirely.

"[The absolute timeout] defines the maximum amount of time a session can be active, closing and invalidating the session upon the defined absolute period since the given session was initially created by the web application. After invalidating the session, the user is forced to (re)authenticate again in the web application and establish a new session." (Source)

Defaults to 60 days.

setTimeoutResolution :: Maybe NominalDiffTime -> State sto -> State sto #

Set the timeout resolution.

We need to save both the creation and last access times on sessions in order to implement idle and absolute timeouts. This means that we have to save the updated session on the storage backend even if the request didn't change any session variable, if only to update the last access time.

This setting provides an optimization where the session is not updated on the storage backend provided that:

No session variables were changed.
The difference between the current time and the last saved access time is less than the timeout resolution.

For example, with a timeout resolution of 1 minute, every request that does not change the session variables within 1 minute of the last update will not generate any updates on the storage backend.

If the timeout resolution is Nothing, then this optimization becomes disabled and the session will always be updated.

Defaults to 10 minutes.

setPersistentCookies :: Bool -> State sto -> State sto #

Set whether by default cookies should be persistent (True) or non-persistent (False). Persistent cookies are saved across browser sessions. Non-persistent cookies are discarded when the browser is closed.

If you set cookies to be persistent and do not define any timeouts (setIdleTimeout or setAbsoluteTimeout), then the cookie is set to expire in 10 years.

Defaults to True.

setHttpOnlyCookies :: Bool -> State sto -> State sto #

Set whether cookies should be HTTP-only (True) or not (False). Cookies marked as HTTP-only ("HttpOnly") are not accessible from client-side scripting languages such as JavaScript, thus preventing a large class of XSS attacks. It's highly recommended to set this attribute to True.

Defaults to True.

setSecureCookies :: Bool -> State sto -> State sto #

Set whether cookies should be mared "Secure" (True) or not (False). Cookies marked as "Secure" are not sent via plain HTTP connections, only via HTTPS connections. It's highly recommended to set this attribute to True. However, since many sites do not operate over HTTPS, the default is False.

Defaults to False.

getCookieName :: State sto -> Text #

Cf. setCookieName.

getHttpOnlyCookies :: State sto -> Bool #

Cf. setHttpOnlyCookies.

getSecureCookies :: State sto -> Bool #

Cf. setSecureCookies.

loadSession :: Storage sto => State sto -> Maybe ByteString -> IO (SessionData sto, SaveSessionToken sto) #

Load the session map from the storage backend. The value of the session cookie should be given as argument if present.

Returns:

The session data sess to be used by the frontend as the current session's value.
Information to be passed back to saveSession on the end of the request in order to save the session.

checkExpired #

Arguments

:: UTCTime	Now.
-> State sto
-> Session sess
-> Maybe (Session sess)

Check if a session s has expired. Returns the Just s if not expired, or Nothing if expired.

nextExpires :: State sto -> Session sess -> Maybe UTCTime #

Calculate the next point in time where the given session will expire assuming that it sees no activity until then. Returns Nothing iff the state does not have any expirations set to Just.

cookieExpires :: State sto -> Session sess -> Maybe UTCTime #

Calculate the date that should be used for the cookie's "Expires" field.

saveSession :: Storage sto => State sto -> SaveSessionToken sto -> SessionData sto -> IO (Maybe (Session (SessionData sto))) #

Save the session on the storage backend. A SaveSessionToken given by loadSession is expected besides the new contents of the session.

Returns Nothing if the session was empty and didn't need to be saved. Note that this does not necessarily means that nothing was done. If you ask for a session to be invalidated and clear every other sesssion variable, then saveSession will invalidate the older session but will avoid creating a new, empty one.

data SaveSessionToken sto #

Opaque token containing the necessary information for saveSession to save the session.

Constructors

SaveSessionToken (Maybe (Session (SessionData sto))) UTCTime

Instances

Eq (Decomposed (SessionData sto)) => Eq (SaveSessionToken sto) #
Methods (==) :: SaveSessionToken sto -> SaveSessionToken sto -> Bool # (/=) :: SaveSessionToken sto -> SaveSessionToken sto -> Bool #
Ord (Decomposed (SessionData sto)) => Ord (SaveSessionToken sto) #
Methods compare :: SaveSessionToken sto -> SaveSessionToken sto -> Ordering # (<) :: SaveSessionToken sto -> SaveSessionToken sto -> Bool # (<=) :: SaveSessionToken sto -> SaveSessionToken sto -> Bool # (>) :: SaveSessionToken sto -> SaveSessionToken sto -> Bool # (>=) :: SaveSessionToken sto -> SaveSessionToken sto -> Bool # max :: SaveSessionToken sto -> SaveSessionToken sto -> SaveSessionToken sto # min :: SaveSessionToken sto -> SaveSessionToken sto -> SaveSessionToken sto #
Show (Decomposed (SessionData sto)) => Show (SaveSessionToken sto) #
Methods showsPrec :: Int -> SaveSessionToken sto -> ShowS # show :: SaveSessionToken sto -> String # showList :: [SaveSessionToken sto] -> ShowS #

invalidateIfNeeded :: Storage sto => State sto -> Maybe (Session (SessionData sto)) -> DecomposedSession (SessionData sto) -> TransactionM sto (Maybe (Session (SessionData sto))) #

Invalidates an old session ID if needed. Returns the Session that should be replaced when saving the session, if any.

Currently we invalidate whenever the auth ID has changed (login, logout, different user) in order to prevent session fixation attacks. We also invalidate when asked to via forceInvalidate.

saveSessionOnDb #

Arguments

:: Storage sto
=> State sto
-> UTCTime	Now.
-> Maybe (Session (SessionData sto))	The old session, if any.
-> DecomposedSession (SessionData sto)	The session data to be saved.
-> TransactionM sto (Maybe (Session (SessionData sto)))	Copy of saved session.

Save a session on the database. If an old session is supplied, it is replaced, otherwise a new session is generated. If the session is empty, it is not saved and Nothing is returned. If the timeout resolution optimization is applied (cf. setTimeoutResolution), the old session is returned and no update is made.

forceInvalidateKey :: Text #

The session key used to signal that the session ID should be invalidated.

data ForceInvalidate #

Which session IDs should be invalidated.

Note that this is not the same concept of invalidation as used on J2EE. In this context, invalidation means creating a fresh session ID for this user's session and disabling the old ID. Its purpose is to avoid session fixation attacks.

Constructors

CurrentSessionId

Invalidate the current session ID. The current session ID is automatically invalidated on login and logout (cf. setAuthKey).

AllSessionIdsOfLoggedUser

Invalidate all session IDs beloging to the currently logged in user. Only the current session ID will be renewed (the only one for which a cookie can be set).

This is useful, for example, if the user asks to change their password. It's also useful to provide a button to clear all other sessions.

If the user is not logged in, this option behaves exactly as CurrentSessionId (i.e., it does not invalidate the sessions of all logged out users).

Note that, for the purposes of AllSessionIdsOfLoggedUser, we consider "logged user" the one that is logged in at the *end* of the handler processing. For example, if the user was logged in but the current handler logged him out, the session IDs of the user who was logged in will not be invalidated.

DoNotForceInvalidate

Do not force invalidate. Invalidate only if automatically. This is the default.

Instances

Bounded ForceInvalidate #
Methods minBound :: ForceInvalidate # maxBound :: ForceInvalidate #
Enum ForceInvalidate #
Methods succ :: ForceInvalidate -> ForceInvalidate # pred :: ForceInvalidate -> ForceInvalidate # toEnum :: Int -> ForceInvalidate # fromEnum :: ForceInvalidate -> Int # enumFrom :: ForceInvalidate -> [ForceInvalidate] # enumFromThen :: ForceInvalidate -> ForceInvalidate -> [ForceInvalidate] # enumFromTo :: ForceInvalidate -> ForceInvalidate -> [ForceInvalidate] # enumFromThenTo :: ForceInvalidate -> ForceInvalidate -> ForceInvalidate -> [ForceInvalidate] #
Eq ForceInvalidate #
Methods (==) :: ForceInvalidate -> ForceInvalidate -> Bool # (/=) :: ForceInvalidate -> ForceInvalidate -> Bool #
Ord ForceInvalidate #
Methods compare :: ForceInvalidate -> ForceInvalidate -> Ordering # (<) :: ForceInvalidate -> ForceInvalidate -> Bool # (<=) :: ForceInvalidate -> ForceInvalidate -> Bool # (>) :: ForceInvalidate -> ForceInvalidate -> Bool # (>=) :: ForceInvalidate -> ForceInvalidate -> Bool # max :: ForceInvalidate -> ForceInvalidate -> ForceInvalidate # min :: ForceInvalidate -> ForceInvalidate -> ForceInvalidate #
Read ForceInvalidate #
Methods readsPrec :: Int -> ReadS ForceInvalidate # readList :: ReadS [ForceInvalidate] # readPrec :: ReadPrec ForceInvalidate # readListPrec :: ReadPrec [ForceInvalidate] #
Show ForceInvalidate #
Methods showsPrec :: Int -> ForceInvalidate -> ShowS # show :: ForceInvalidate -> String # showList :: [ForceInvalidate] -> ShowS #