-- 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.5.0.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 :: 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

-- | 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 -> IO (Either Text ConnectionInfo)
instance GHC.Classes.Eq PostgresWebsockets.Claims.JWTAttempt


-- | This module encapsulates knowledge about the SQL commands and the
--   Hasql interface.
module PostgresWebsockets.Database

-- | Given a Hasql Pool, a channel and a message sends a notify command to
--   the database
notifyPool :: Pool -> ByteString -> ByteString -> IO (Either Error ())

-- | Given a Hasql Connection, a channel and a message sends a notify
--   command to the database
notify :: Connection -> PgIdentifier -> ByteString -> IO (Either Error ())

-- | Given a Hasql Connection and a channel sends a listen command to the
--   database
listen :: Connection -> PgIdentifier -> IO ()

-- | Given a Hasql Connection and a channel sends a unlisten command to the
--   database
unlisten :: Connection -> PgIdentifier -> IO ()

-- | Given a function that handles notifications and a Hasql connection
--   forks a thread that listens on the database connection and calls the
--   handler everytime a message arrives.
--   
--   The message handler passed as first argument needs two parameters
--   channel and payload.
waitForNotifications :: (ByteString -> ByteString -> IO ()) -> Connection -> IO ()

-- | A wrapped bytestring that represents a properly escaped and quoted
--   PostgreSQL identifier
data PgIdentifier

-- | Given a bytestring returns a properly quoted and escaped PgIdentifier
toPgIdentifier :: ByteString -> PgIdentifier
instance GHC.Show.Show PostgresWebsockets.Database.PgIdentifier


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


-- | PostgresWebsockets Middleware, composing this allows postgrest to
--   create websockets connections that will communicate with the database
--   through LISTEN/NOTIFY channels.
module PostgresWebsockets

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

-- | 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 :: ByteString -> 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 :: ByteString -> ByteString -> IO (Either ByteString Multiplexer)
instance GHC.Generics.Generic PostgresWebsockets.Message
instance GHC.Classes.Eq PostgresWebsockets.Message
instance GHC.Show.Show PostgresWebsockets.Message
instance Data.Aeson.Types.ToJSON.ToJSON PostgresWebsockets.Message