Safe Haskell	Safe-Inferred
Language	GHC2021

Yesod.Session.Persist

Contents

Setup
Options
Timing
Timeout
Transport security
Session data model
Randomization
Storage
Key rotation
Freezing
Session map embedding
Comparison

Synopsis

makeSessionBackend :: SessionConfiguration persistentBackend persistentRecord -> IO SessionBackend
data SessionConfiguration persistentBackend persistentRecord = SessionConfiguration {
- persistence :: SessionPersistence persistentBackend persistentRecord IO
- options :: Options (ReaderT persistentBackend IO) IO
}
data Options (tx :: Type -> Type) (m :: Type -> Type) = Options {
- cookieName :: Text
- timing :: TimingOptions NominalDiffTime
- transportSecurity :: TransportSecurity
- embedding :: SessionEmbeddings
- clock :: m UTCTime
- randomization :: m (Randomization tx)
- keyRotationTrigger :: Comparison SessionMap -> Maybe KeyRotation
}
defaultOptions :: Options IO IO
hoistOptions :: Functor m2 => (forall a. tx1 a -> tx2 a) -> (forall a. m1 a -> m2 a) -> Options tx1 m1 -> Options tx2 m2
data TimingOptions a = TimingOptions {
- timeout :: Timeout a
- resolution :: Maybe a
}
defaultTimingOptions :: TimingOptions NominalDiffTime
data Timeout a = Timeout {
- idle :: Maybe a
- absolute :: Maybe a
}
defaultTimeout :: Timeout NominalDiffTime
data TransportSecurity
- = RequireSecureTransport
- | AllowPlaintextTranport
data Session = Session {
- key :: SessionKey
- map :: SessionMap
- time :: Time UTCTime
}
newtype SessionKey = SessionKey {
- text :: Text
}
data Time a = Time {
- created :: a
- accessed :: a
}
newtype Randomization (m :: Type -> Type) = Randomization {
- getRandomBytes :: Natural -> m ByteString
}
defaultRandomization :: IO (Randomization IO)
deterministicallyRandom :: DeterministicRandomization -> IO (Randomization IO)
newtype DeterministicRandomization = DeterministicRandomization {
- nextRandomBytes :: Natural -> (ByteString, DeterministicRandomization)
}
data SessionPersistence backend record (m :: Type -> Type) = (PersistRecordBackend record backend, PersistStoreWrite backend, SafeToInsert record) => SessionPersistence {
- databaseKey :: SessionKey -> Key record
- toDatabase :: Session -> record
- fromDatabase :: record -> Session
- runDB :: forall a. ReaderT backend IO a -> m a
}
data StorageException
- = SessionAlreadyExists
- | SessionDoesNotExist
rotateSessionKey :: (MonadHandler m, HasSessionEmbeddings (HandlerSite m)) => m ()
assignSessionKeyRotation :: (MonadHandler m, HasSessionEmbeddings (HandlerSite m)) => Maybe KeyRotation -> m ()
data KeyRotation = RotateSessionKey
disableSessionManagement :: (MonadHandler m, HasSessionEmbeddings (HandlerSite m)) => m ()
assignSessionFreeze :: (MonadHandler m, HasSessionEmbeddings (HandlerSite m)) => Maybe SessionFreeze -> m ()
data SessionFreeze = FreezeSessionForCurrentRequest
data SessionEmbeddings = SessionEmbeddings {
- keyRotation :: SessionMapEmbedding KeyRotation
- freeze :: SessionMapEmbedding SessionFreeze
}
class HasSessionEmbeddings a where
- getSessionEmbeddings :: a -> Maybe SessionEmbeddings
data Embedding (con :: (Type -> Type) -> Constraint) e a = Embedding {
- embed :: forall (m :: Type -> Type). con m => Maybe a -> m ()
- extract :: forall (m :: Type -> Type). (Functor m, con m) => m (Either e (Maybe a))
}
type SessionMapEmbedding a = Embedding (MapOperations Text ByteString) () a
class (Monad m, Ord k) => MapOperations k v (m :: Type -> Type) | m -> k v where
- lookup :: k -> m (Maybe v)
- assign :: k -> Maybe v -> m ()
bsKeyEmbedding :: k -> Embedding (MapOperations k a) e a
dimapEmbedding :: forall a e b (con :: (Type -> Type) -> Constraint). (a -> Either e b) -> (b -> a) -> Embedding con e a -> Embedding con e b
showReadKeyEmbedding :: (Read a, Show a) => k -> Embedding (MapOperations k ByteString) () a
data Comparison a = Comparison {
- old :: a
- new :: a
}
differsOn :: Eq b => (a -> b) -> Comparison a -> Bool

Setup

makeSessionBackend :: SessionConfiguration persistentBackend persistentRecord -> IO SessionBackend #

Use this to implement makeSessionBackend.

The session type parameter represents the Persistent entity you're using to store sessions (see the SessionPersistence field of the configuration).

data SessionConfiguration persistentBackend persistentRecord #

Constructors

SessionConfiguration
Fields persistence :: SessionPersistence persistentBackend persistentRecord IO Mapping between `Session` and your Persistent entity options :: Options (ReaderT persistentBackend IO) IO Various options that have defaults; see `defaultOptions`

Options

data Options (tx :: Type -> Type) (m :: Type -> Type) #

Settings that have defaults

See defaultOptions.

Constructors

Options

Fields

cookieName :: Text
The name of cookie where the session key will be saved
timing :: TimingOptions NominalDiffTime
Various time duration settings
transportSecurity :: TransportSecurity
Whether cookies require HTTPS
embedding :: SessionEmbeddings
How special session management indicators get smuggled through a SessionMap
clock :: m UTCTime
How to determine the current time; you can change this to a fake for testing
randomization :: m (Randomization tx)
Generator of random byte strings, used to contrive session keys
keyRotationTrigger :: Comparison SessionMap -> Maybe KeyRotation
At the end of request handling, compare old session data to new session data to determine whether a key rotation should be performed

defaultOptions :: Options IO IO #

Default options

cookieName = "session-key"
timing = defaultTimingOptions
transportSecurity = AllowPlaintextTranport (change this in production)
embedding.keyRotation = showReadKeyEmbedding "session-key-rotation"
embedding.freeze = showReadKeyEmbedding "session-freeze"
clock = getCurrentTime
randomization = defaultRandomization
keyRotationTrigger = const Nothing

hoistOptions :: Functor m2 => (forall a. tx1 a -> tx2 a) -> (forall a. m1 a -> m2 a) -> Options tx1 m1 -> Options tx2 m2 #

Timing

data TimingOptions a #

Time duration settings

See defaultTimingOptions.

Constructors

TimingOptions
Fields timeout :: Timeout a How long sessions are allowed to live resolution :: Maybe a If `Just resolution`, this setting provides an optimization that can prevent excessive database writes. If the only thing that needs to be updated is the session's last access time, the write will be skipped if the previously recorded access time is within `resolution` long ago.

Instances

Instances details

Show a => Show (TimingOptions a)
Instance details Defined in Session.Timing.Options Methods showsPrec :: Int -> TimingOptions a -> ShowS # show :: TimingOptions a -> String # showList :: [TimingOptions a] -> ShowS #
Eq a => Eq (TimingOptions a)
Instance details Defined in Session.Timing.Options Methods (==) :: TimingOptions a -> TimingOptions a -> Bool # (/=) :: TimingOptions a -> TimingOptions a -> Bool #

defaultTimingOptions :: TimingOptions NominalDiffTime #

Default timing options

timeout = defaultTimeout
resolution = 10 minutes

Timeout

data Timeout a #

How long sessions are allowed to live

See defaultTimeout.

Constructors

Timeout

Fields

idle :: Maybe a
The amount of time a session will remain active in case there is no activity in the session
This is used both on the client side (by setting the cookie expires fields) and on the server.
Setting to Nothing removes the idle timeout.
absolute :: Maybe a
The maximum amount of time a session can be active
This is used both on the client side (by setting the cookie expires fields) and on the server side.
Setting to Nothing removes the absolute timeout.

Instances

Instances details

Functor Timeout
Instance details Defined in Session.Timing.Timeout Methods fmap :: (a -> b) -> Timeout a -> Timeout b # (<$) :: a -> Timeout b -> Timeout a #
Arbitrary a => Arbitrary (Timeout a)
Instance details Defined in Session.Timing.Timeout Methods arbitrary :: Gen (Timeout a) # shrink :: Timeout a -> [Timeout a] #
Generic (Timeout a)
Instance details Defined in Session.Timing.Timeout Associated Types type Rep (Timeout a) :: Type -> Type # Methods from :: Timeout a -> Rep (Timeout a) x # to :: Rep (Timeout a) x -> Timeout a #
Show a => Show (Timeout a)
Instance details Defined in Session.Timing.Timeout Methods showsPrec :: Int -> Timeout a -> ShowS # show :: Timeout a -> String # showList :: [Timeout a] -> ShowS #
Eq a => Eq (Timeout a)
Instance details Defined in Session.Timing.Timeout Methods (==) :: Timeout a -> Timeout a -> Bool # (/=) :: Timeout a -> Timeout a -> Bool #
type Rep (Timeout a)
Instance details Defined in Session.Timing.Timeout type Rep (Timeout a) = D1 ('MetaData "Timeout" "Session.Timing.Timeout" "yesod-session-persist-0.0.0.2-4wroKzVSNpLxsAaD7x2SU-internal" 'False) (C1 ('MetaCons "Timeout" 'PrefixI 'True) (S1 ('MetaSel ('Just "idle") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe a)) :*: S1 ('MetaSel ('Just "absolute") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe a))))

defaultTimeout :: Timeout NominalDiffTime #

Default timeouts

idle = 8 hours
absolute = 30 days

Transport security

data TransportSecurity #

Constructors

RequireSecureTransport

Only allow cookies on HTTPS connections

Set this in production.

AllowPlaintextTranport

Allow cookies over either HTTP or HTTPS

This is okay for development.

Session data model

data Session #

What a saved session looks like in the database

Constructors

Session
Fields key :: SessionKey Session key (primary key) map :: SessionMap Arbitrary session data time :: Time UTCTime Creation and access times, used to determine expiration

Instances

Instances details

Show Session
Instance details Defined in Yesod.Session.SessionType Methods showsPrec :: Int -> Session -> ShowS # show :: Session -> String # showList :: [Session] -> ShowS #
Eq Session
Instance details Defined in Yesod.Session.SessionType Methods (==) :: Session -> Session -> Bool # (/=) :: Session -> Session -> Bool #

newtype SessionKey #

Secret value that is sent to and subsequently furnished by the client to identify the session

Constructors

SessionKey
Fields text :: Text

Instances

Instances details

Show SessionKey
Instance details Defined in Session.Key Methods showsPrec :: Int -> SessionKey -> ShowS # show :: SessionKey -> String # showList :: [SessionKey] -> ShowS #
Eq SessionKey
Instance details Defined in Session.Key Methods (==) :: SessionKey -> SessionKey -> Bool # (/=) :: SessionKey -> SessionKey -> Bool #
Ord SessionKey
Instance details Defined in Session.Key Methods compare :: SessionKey -> SessionKey -> Ordering # (<) :: SessionKey -> SessionKey -> Bool # (<=) :: SessionKey -> SessionKey -> Bool # (>) :: SessionKey -> SessionKey -> Bool # (>=) :: SessionKey -> SessionKey -> Bool # max :: SessionKey -> SessionKey -> SessionKey # min :: SessionKey -> SessionKey -> SessionKey #

data Time a #

Creation and access times, used to determine session expiration

Constructors

Time
Fields created :: a When the session was created This is used to apply the absolute timeout. accessed :: a When the session was last accessed This is used to apply the idle timeout.

Instances

Instances details

Show a => Show (Time a)
Instance details Defined in Session.Timing.Time Methods showsPrec :: Int -> Time a -> ShowS # show :: Time a -> String # showList :: [Time a] -> ShowS #
Eq a => Eq (Time a)
Instance details Defined in Session.Timing.Time Methods (==) :: Time a -> Time a -> Bool # (/=) :: Time a -> Time a -> Bool #

Randomization

newtype Randomization (m :: Type -> Type) #

General means of obtaining randomness

Constructors

Randomization
Fields getRandomBytes :: Natural -> m ByteString Given a requested number of bytes, this action should produce a `ByteString` of that length.

defaultRandomization :: IO (Randomization IO) #

Cryptographically secure deterministic randomization seeded from system entropy using ChaChaDRG from the crypton package

deterministicallyRandom :: DeterministicRandomization -> IO (Randomization IO) #

Convert from a deterministic generator to an effectful one

newtype DeterministicRandomization #

A deterministic random generator

Constructors

DeterministicRandomization
Fields nextRandomBytes :: Natural -> (ByteString, DeterministicRandomization) Given a requested number of bytes, this function should give a `ByteString` of that length and a new deterministic generator.

Storage

data SessionPersistence backend record (m :: Type -> Type) #

Mapping between Session and a Persistent entity of your choice

Constructors

(PersistRecordBackend record backend, PersistStoreWrite backend, SafeToInsert record) => SessionPersistence
Fields databaseKey :: SessionKey -> Key record toDatabase :: Session -> record fromDatabase :: record -> Session runDB :: forall a. ReaderT backend IO a -> m a

data StorageException #

Common exceptions that may be thrown by any storage.

Constructors

SessionAlreadyExists	Thrown when attempting to insert a new session and another session with the same key already exists
SessionDoesNotExist	Thrown when attempting to replace an existing session but no session with the same key exists

Instances

Instances details

Exception StorageException
Instance details Defined in Yesod.Session.Storage.Exceptions Methods toException :: StorageException -> SomeException # fromException :: SomeException -> Maybe StorageException # displayException :: StorageException -> String #
Show StorageException
Instance details Defined in Yesod.Session.Storage.Exceptions Methods showsPrec :: Int -> StorageException -> ShowS # show :: StorageException -> String # showList :: [StorageException] -> ShowS #
Eq StorageException
Instance details Defined in Yesod.Session.Storage.Exceptions Methods (==) :: StorageException -> StorageException -> Bool # (/=) :: StorageException -> StorageException -> Bool #

Key rotation

rotateSessionKey :: (MonadHandler m, HasSessionEmbeddings (HandlerSite m)) => m () #

assignSessionKeyRotation #

Arguments

:: (MonadHandler m, HasSessionEmbeddings (HandlerSite m))
=> Maybe KeyRotation	`Just` to rotate, or `Nothing` to cancel any previous request for rotation and restore the default behavior
-> m ()

Indicate whether the current session key should be rotated

The key rotation does not occur immediately; this action only places a value into the session map.

Later calls to assignSessionKeyRotation on the same handler will override earlier calls.

At the end of the request handler, if the value is Just, the session key will be rotated.

The session variable set by this function is then discarded and is not persisted across requests.

data KeyRotation #

Key rotation means we delete the session on the server and copy the stored data into a new session with a different key.

Constructors

RotateSessionKey

Generate a new session key and invalidate the old one

Instances

Instances details

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

Freezing

disableSessionManagement :: (MonadHandler m, HasSessionEmbeddings (HandlerSite m)) => m () #

assignSessionFreeze #

Arguments

:: (MonadHandler m, HasSessionEmbeddings (HandlerSite m))
=> Maybe SessionFreeze	`Just` to freeze the session, or `Nothing` to cancel any previous request for session freezing and restore the default behavior
-> m ()

Indicate whether the session should be frozen for the handling of the current request

At the end of the request handler, if the value is Just, no database actions will be performed and no cookies will be set.

data SessionFreeze #

Constructors

FreezeSessionForCurrentRequest

Instances

Instances details

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

Session map embedding

data SessionEmbeddings #

Constructors

SessionEmbeddings
Fields keyRotation :: SessionMapEmbedding KeyRotation How to represent a key rotation instruction in the session data; see `assignSessionKeyRotation` freeze :: SessionMapEmbedding SessionFreeze How to represent a freeze instruction in the session data; see `assignSessionFreeze`

Instances

Instances details

HasSessionEmbeddings SessionEmbeddings
Instance details Defined in Yesod.Session.Embedding.Options Methods getSessionEmbeddings :: SessionEmbeddings -> Maybe SessionEmbeddings #

class HasSessionEmbeddings a where #

Methods

getSessionEmbeddings :: a -> Maybe SessionEmbeddings #

Instances

Instances details

HasSessionEmbeddings SessionEmbeddings
Instance details Defined in Yesod.Session.Embedding.Options Methods getSessionEmbeddings :: SessionEmbeddings -> Maybe SessionEmbeddings #

data Embedding (con :: (Type -> Type) -> Constraint) e a #

Targets a value that is optionally present in some stateful monadic context

Constructors

Embedding
Fields embed :: forall (m :: Type -> Type). con m => Maybe a -> m () Sets or clears the value extract :: forall (m :: Type -> Type). (Functor m, con m) => m (Either e (Maybe a)) Removes the value if present, returning what was removed

type SessionMapEmbedding a = Embedding (MapOperations Text ByteString) () a #

Specifies how we represent some value within a SessionMap

We use this to sort of abuse the session; key rotation and freezing are done by embedding special values among the session data. These special values are extracted from the map before persisting to storage and are never actually saved.

class (Monad m, Ord k) => MapOperations k v (m :: Type -> Type) | m -> k v where #

A monadic context with operations over some Map-like state

This allows us to generalize between pure operations over Map and the more limited session manipulation utilities afforded by Yesod. (See the instance list for this class.)

Methods

lookup :: k -> m (Maybe v) #

assign :: k -> Maybe v -> m () #

Instances

Instances details

MapOperations Text ByteString (HandlerFor site)
Instance details Defined in Yesod.Session.Embedding.Map Methods lookup :: Text -> HandlerFor site (Maybe ByteString) # assign :: Text -> Maybe ByteString -> HandlerFor site () #
(Monad m, Ord k) => MapOperations k v (StateT (Map k v) m)
Instance details Defined in Yesod.Session.Embedding.Map Methods lookup :: k -> StateT (Map k v) m (Maybe v) # assign :: k -> Maybe v -> StateT (Map k v) m () #

bsKeyEmbedding :: k -> Embedding (MapOperations k a) e a #

An embedding which stores a value at some particular key in a map-like structure

dimapEmbedding :: forall a e b (con :: (Type -> Type) -> Constraint). (a -> Either e b) -> (b -> a) -> Embedding con e a -> Embedding con e b #

showReadKeyEmbedding :: (Read a, Show a) => k -> Embedding (MapOperations k ByteString) () a #

Represents a value in a SessionMap by storing the UTF-8 encoding of its show representation at the given key

Comparison

data Comparison a #

Constructors

Comparison
Fields old :: a new :: a

differsOn :: Eq b => (a -> b) -> Comparison a -> Bool #