-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | PostgreSQL backed Wai session store
--   
--   Provides a PostgreSQL backed session store for the Network.Wai.Session
--   interface.
@package wai-session-postgresql
@version 0.1.1.0

module Network.Wai.Session.PostgreSQL

-- | Create a new postgresql backed wai session store.
dbStore :: (WithPostgreSQLConn a, Serialize k, Eq k, Serialize v, MonadIO m) => a -> StoreSettings -> IO (SessionStore m k v)

-- | Create default settings using a session timeout of one hour, a
--   cryptographically secure session id generator using 24 bytes of
--   entropy and putStrLn to log events to stdout.
defaultSettings :: StoreSettings

-- | This function can be called to invalidate a session and enforce
--   creating a new one with a new session ID. It should be called *before*
--   and calls to sessionStore are made. It needs to be passed a request
--   and the cookie name explicitly due to the limited nature of the
--   Network.Wai.Session interface. Sessions should be cleared when a login
--   is performed, to prevent certain kinds of session hijacking attacks.
clearSession :: (WithPostgreSQLConn a) => a -> ByteString -> Request -> IO ()

-- | Delete expired sessions from the database.
purgeOldSessions :: WithPostgreSQLConn a => a -> StoreSettings -> IO Int64

-- | Run a thread using forkIO that runs periodically to purge old
--   sessions.
purger :: WithPostgreSQLConn a => a -> StoreSettings -> IO ThreadId

-- | Generate a session ID with n bytes of entropy
ratherSecureGen :: Int -> IO ByteString

-- | By default, you pass a postgresql connection to the session store when
--   creating it. The passed connection will have to stay open for the
--   (possibly very long) existence of the session and it should not be
--   used for any other purpose during that time. You can implement an
--   instance of this class for a connection pool instead, so that the
--   session manager will not require a permanent open PostgreSQL
--   connection.
class WithPostgreSQLConn a

-- | Call the function (Connection -> IO b) with a valid and open
--   PostgreSQL connection.
withPostgreSQLConn :: WithPostgreSQLConn a => a -> (Connection -> IO b) -> IO b

-- | These settings control how the session store is behaving
data StoreSettings
StoreSettings :: Int64 -> IO ByteString -> Bool -> (String -> IO ()) -> Int -> StoreSettings

-- | The number of seconds a session is valid Seconds are counted since the
--   session is last accessed (read or written), not since it was created.
[storeSettingsSessionTimeout] :: StoreSettings -> Int64

-- | A random session key generator. The session ID should provide
--   sufficient entropy, and must not be predictable. It is recommended to
--   use a cryptographically secure random number generator.
[storeSettingsKeyGen] :: StoreSettings -> IO ByteString

-- | Whether to create the database table if it does not exist upon
--   creating the session store. If set to false, the database table must
--   exist or be created by some other means.
[storeSettingsCreateTable] :: StoreSettings -> Bool

-- | A function that is called by to log events such as session purges or
--   the table creation.
[storeSettingsLog] :: StoreSettings -> String -> IO ()

-- | The number of microseconds to sleep between two runs of the old
--   session purge worker.
[storeSettingsPurgeInterval] :: StoreSettings -> Int
instance Network.Wai.Session.PostgreSQL.WithPostgreSQLConn Database.PostgreSQL.Simple.Internal.Connection