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


-- | Middleware to map LISTEN/NOTIFY messages to Websockets
--   
--   WAI middleware that adds websockets capabilites on top of PostgreSQL's
--   asynchronous notifications using LISTEN and NOTIFY commands. Fully
--   functioning server included.
@package postgres-websockets
@version 0.11.2.2


-- | 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 :: Text -> Text -> Message
[channel] :: Message -> Text
[payload] :: Message -> Text
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 -> Text -> (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

-- | Given a multiplexer, a number of milliseconds and an IO computation
--   that returns a boolean Runs the IO computation at every interval of
--   milliseconds interval and reopens the multiplexer producer if the
--   resulting boolean is true When interval is 0 this is NOOP, so the
--   minimum interval is 1ms Call this in case you want to ensure the
--   producer thread is killed and restarted under a certain condition
superviseMultiplexer :: Multiplexer -> Int -> IO Bool -> IO ()

-- | 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.Generics.Generic PostgresWebsockets.Broadcast.MultiplexerSnapshot
instance Data.Aeson.Types.ToJSON.ToJSON PostgresWebsockets.Broadcast.MultiplexerSnapshot


-- | 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 = ([Text], Text, 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 KeyMap.
validateClaims :: Maybe Text -> 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 -> Maybe Text -> ByteString -> Bool -> Int -> Int -> Maybe Int -> Maybe Text -> Maybe Text -> AppConfig
[configDatabase] :: AppConfig -> Text
[configPath] :: AppConfig -> Maybe Text
[configHost] :: AppConfig -> Text
[configPort] :: AppConfig -> Int
[configListenChannel] :: AppConfig -> Text
[configMetaChannel] :: AppConfig -> Maybe Text
[configJwtSecret] :: AppConfig -> ByteString
[configJwtSecretIsBase64] :: AppConfig -> Bool
[configPool] :: AppConfig -> Int
[configRetries] :: AppConfig -> Int
[configReconnectInterval] :: AppConfig -> Maybe Int
[configCertificateFile] :: AppConfig -> Maybe Text
[configKeyFile] :: AppConfig -> Maybe Text
instance GHC.Show.Show PostgresWebsockets.Config.AppConfig


-- | 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 -> Maybe 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 :: Context -> Middleware