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


-- | Middleware to map LISTEN/NOTIFY messages to Websockets
--   
--   Please see README.md
@package postgres-websockets
@version 0.9.0.0


-- | PostgresWebsockets functions to broadcast messages to several
--   listening clients This module provides a type called Multiplexer. The
--   multiplexer contains a map of channels and a producer thread.
--   
--   This module avoids any database implementation details, it is used by
--   HasqlBroadcast where the database logic is combined.
module PostgresWebsockets.Broadcast
data Multiplexer
data Message
Message :: ByteString -> ByteString -> Message
[channel] :: Message -> ByteString
[payload] :: Message -> ByteString
newMultiplexer :: (TQueue Message -> IO a) -> (Either SomeException a -> IO ()) -> IO Multiplexer

-- | Adds a listener to a certain multiplexer's channel. The listener must
--   be a function that takes a 'TChan Message' and perform any IO action.
--   All listeners run in their own thread. The first listener will open
--   the channel, when a listener dies it will check if there acquire any
--   others and close the channel when that's the case.
onMessage :: Multiplexer -> ByteString -> (Message -> IO ()) -> IO ()

-- | Reads the messages from the producer and relays them to the active
--   listeners in their respective channels.
relayMessages :: Multiplexer -> IO ()

-- | Opens a thread that relays messages from the producer thread to the
--   channels forever
relayMessagesForever :: Multiplexer -> IO ThreadId

-- | Read the next value from the <a>TQueue</a>.
readTQueue :: () => TQueue a -> STM a

-- | Write a value to a <a>TQueue</a>.
writeTQueue :: () => TQueue a -> a -> STM ()

-- | Read the next value from the <a>TChan</a>.
readTChan :: () => TChan a -> STM a
instance GHC.Show.Show PostgresWebsockets.Broadcast.Message
instance GHC.Classes.Eq PostgresWebsockets.Broadcast.Message
instance GHC.Show.Show PostgresWebsockets.Broadcast.Multiplexer


-- | This module provides the JWT claims validation. Since websockets and
--   listening connections in the database tend to be resource intensive
--   (not to mention stateful) we need claims authorizing a specific
--   channel and mode of operation.
module PostgresWebsockets.Claims
type ConnectionInfo = ([ByteString], ByteString, Claims)

-- | Given a secret, a token and a timestamp it validates the claims and
--   returns either an error message or a triple containing channel, mode
--   and claims hashmap.
validateClaims :: Maybe ByteString -> ByteString -> LByteString -> UTCTime -> IO (Either Text ConnectionInfo)
instance GHC.Classes.Eq PostgresWebsockets.Claims.JWTAttempt


-- | This module provides a helper function to read the command line
--   arguments using the AppConfig type to store them. It also can be used
--   to define other middleware configuration that may be delegated to some
--   sort of external configuration.
module PostgresWebsockets.Config

-- | User friendly version number
prettyVersion :: Text

-- | Load all postgres-websockets config from Environment variables. This
--   can be used to use just the middleware or to feed into warpSettings
loadConfig :: IO AppConfig

-- | Given a shutdown handler and an AppConfig builds a Warp Settings to
--   start a stand-alone server
warpSettings :: (IO () -> IO ()) -> AppConfig -> Settings

-- | Config file settings for the server
data AppConfig
AppConfig :: Text -> Maybe Text -> Text -> Int -> Text -> ByteString -> Bool -> Int -> Int -> AppConfig
[configDatabase] :: AppConfig -> Text
[configPath] :: AppConfig -> Maybe Text
[configHost] :: AppConfig -> Text
[configPort] :: AppConfig -> Int
[configListenChannel] :: AppConfig -> Text
[configJwtSecret] :: AppConfig -> ByteString
[configJwtSecretIsBase64] :: AppConfig -> Bool
[configPool] :: AppConfig -> Int
[configRetries] :: AppConfig -> Int


-- | Uses Broadcast module adding database as a source producer. This
--   module provides a function to produce a <a>Multiplexer</a> from a
--   Hasql <a>Connection</a>. The producer issues a LISTEN command upon
--   Open commands and UNLISTEN upon Close.
module PostgresWebsockets.HasqlBroadcast

-- | Returns a multiplexer from a connection URI, keeps trying to connect
--   in case there is any error. This function also spawns a thread that
--   keeps relaying the messages from the database to the multiplexer's
--   listeners
newHasqlBroadcaster :: IO () -> Text -> Int -> ByteString -> IO Multiplexer

-- | Returns a multiplexer from a connection URI or an error message on the
--   left case This function also spawns a thread that keeps relaying the
--   messages from the database to the multiplexer's listeners
newHasqlBroadcasterOrError :: IO () -> Text -> ByteString -> IO (Either ByteString Multiplexer)

-- | Acquire a connection using the provided settings encoded according to
--   the PostgreSQL format.
acquire :: Settings -> IO (Either ConnectionError Connection)

-- | Reads the messages from the producer and relays them to the active
--   listeners in their respective channels.
relayMessages :: Multiplexer -> IO ()

-- | Opens a thread that relays messages from the producer thread to the
--   channels forever
relayMessagesForever :: Multiplexer -> IO ThreadId


-- | These are all function necessary to configure and start the server.
module PostgresWebsockets

-- | User friendly version number
prettyVersion :: Text

-- | Load all postgres-websockets config from Environment variables. This
--   can be used to use just the middleware or to feed into warpSettings
loadConfig :: IO AppConfig

-- | Start a stand-alone warp server using the parameters from AppConfig
--   and a opening a database connection pool.
serve :: AppConfig -> IO ()

-- | Given a secret, a function to fetch the system time, a Hasql Pool and
--   a Multiplexer this will give you a WAI middleware.
postgresWsMiddleware :: IO UTCTime -> Text -> ByteString -> Pool -> Multiplexer -> Application -> Application