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


-- | Simple PostgreSQL backed wai-session backend. This module allows you
--   to store session data of wai-sessions in a PostgreSQL database. Two
--   tables are kept, one to store the session's metadata and one to store
--   key,value pairs for each session. All keys and values are stored as
--   bytea values in the postgresql database using haskell's cereal module
--   to serialize and deserialize them.
--   
--   Please note that the module does not let you configure the names of
--   the database tables. It is recommended to use this module with its own
--   database schema.
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)

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

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

-- | Prepare a simple postgresql connection for use by the postgresql
--   session store. This basically wraps the connection along with a mutex
--   to ensure transactions work correctly. Connections used this way must
--   not be used anywhere else for the duration of the session store! It is
--   recommended to use a connection pool instead. To use a connection
--   pool, you simply need to implement the WithPostgreSQLConn type class.
fromSimpleConnection :: Connection -> IO SimpleConnection

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

-- | A simple PostgreSQL connection stored together with a mutex that
--   prevents from running more than one postgresql transaction at the same
--   time. It is recommended to use a connection pool instead for larger
--   sites.
data SimpleConnection

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

-- | 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
instance Data.Default.Class.Default Network.Wai.Session.PostgreSQL.StoreSettings
instance Network.Wai.Session.PostgreSQL.WithPostgreSQLConn Network.Wai.Session.PostgreSQL.SimpleConnection
instance Network.Wai.Session.PostgreSQL.WithPostgreSQLConn (Data.Pool.Pool Database.PostgreSQL.Simple.Internal.Connection)