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


-- | Apache Pulsar client for Haskell
--   
--   Supernova is an Apache Pulsar client that implements the specified TCP
--   protocol.
@package supernova
@version 0.0.2


-- | Consider the following imports (needs the <a>async</a> library).
--   
--   <pre>
--   import           Control.Concurrent             ( threadDelay )
--   import           Control.Concurrent.Async       ( concurrently_ )
--   import           Control.Monad                  ( forever )
--   import           Pulsar
--   </pre>
--   
--   A quick example of a consumer and producer running concurrently.
--   
--   <pre>
--   resources :: Pulsar (Consumer IO, Producer IO)
--   resources = do
--     ctx      &lt;- connect defaultConnectData
--     consumer &lt;- newConsumer ctx topic "test-sub"
--     producer &lt;- newProducer ctx topic
--     return (consumer, producer)
--   </pre>
--   
--   A Pulsar connection, consumers, and producers are long-lived resources
--   that are managed accordingly for you. Once the program exits, the
--   resources will be released in the respective order (always opposite to
--   the order of acquisition).
--   
--   <pre>
--   main :: IO ()
--   main = runPulsar resources $ (Consumer {..}, Producer {..}) -&gt;
--     let c = forever $ fetch &gt;&gt;= (Message i m) -&gt; print m &gt;&gt; ack i
--         p = forever $ threadDelay (5 * 1000000) &gt;&gt; produce "hello world"
--     in  concurrently_ c p
--   </pre>
module Pulsar

-- | Starts a Pulsar connection with the supplied <a>ConnectData</a>
connect :: (MonadThrow m, MonadIO m, MonadManaged m) => ConnectData -> m PulsarCtx

-- | Default connection data: "127.0.0.1:6650"
defaultConnectData :: ConnectData

-- | Create a new <a>Consumer</a> by supplying a <a>PulsarCtx</a> (returned
--   by <a>connect</a>), a <a>Topic</a> and a <a>SubscriptionName</a>.
newConsumer :: (MonadManaged m, MonadIO f) => PulsarCtx -> Topic -> SubscriptionName -> m (Consumer f)

-- | Create a new <a>Producer</a> by supplying a <a>PulsarCtx</a> (returned
--   by <a>connect</a>) and a <a>Topic</a>.
newProducer :: (MonadManaged m, MonadIO f) => PulsarCtx -> Topic -> m (Producer f)

-- | Runs a Pulsar computation with default logging to standard output
runPulsar :: forall a b. Pulsar a -> (a -> IO b) -> IO b

-- | Runs a Pulsar computation with the supplied logging options
runPulsar' :: forall a b. LogOptions -> Pulsar a -> (a -> IO b) -> IO b

-- | An abstract <a>Consumer</a> able to <a>fetch</a> messages and
--   <a>ack</a>nowledge them.
data Consumer m
Consumer :: m Message -> (MsgId -> m ()) -> Consumer m

-- | Fetches a single message. Blocks if no messages are available.
[fetch] :: Consumer m -> m Message

-- | Acknowledges a single message.
[ack] :: Consumer m -> MsgId -> m ()

-- | An abstract <a>Producer</a> able to <a>produce</a> messages of type
--   <a>PulsarMessage</a>.
newtype Producer m
Producer :: (PulsarMessage -> m ()) -> Producer m

-- | Produces a single message.
[produce] :: Producer m -> PulsarMessage -> m ()

-- | The main Pulsar monad, which abstracts over a <a>Managed</a> monad.
data Pulsar a

-- | Internal Pulsar context. You will never need to access its content
--   (not exported) but might need to take it as argument.
data PulsarCtx

-- | Connection details: host and port.
data ConnectData

-- | Internal logging level, part of <a>LogOptions</a>. Can be used
--   together with <a>runPulsar</a>`.
data LogLevel
Error :: LogLevel
Warn :: LogLevel
Info :: LogLevel
Debug :: LogLevel

-- | Internal logging options. Can be used together with <a>runPulsar</a>`.
data LogOptions
LogOptions :: LogLevel -> LogOutput -> LogOptions
[logLevel] :: LogOptions -> LogLevel
[logOutput] :: LogOptions -> LogOutput

-- | Internal logging output, part of <a>LogOptions</a>. Can be used
--   together with <a>runPulsar</a>`.
data LogOutput
StdOut :: LogOutput
File :: FilePath -> LogOutput

-- | A Topic is in the form "type://tenant/namespace/topic-name", which is
--   what the <a>Show</a> instance does.
data Topic
Topic :: TopicType -> Tenant -> NameSpace -> TopicName -> Topic
[type'] :: Topic -> TopicType
[tenant] :: Topic -> Tenant
[namespace] :: Topic -> NameSpace
[name] :: Topic -> TopicName

-- | A default <a>Topic</a>: "non-persistent://public/default/my-topic".
defaultTopic :: String -> Topic

-- | A topic can be either <a>Persistent</a> or <a>NonPersistent</a>.
data TopicType
Persistent :: TopicType
NonPersistent :: TopicType

-- | A tenant can be any string value. Default value is "public".
newtype Tenant
Tenant :: String -> Tenant

-- | A namespace can be any string value. Default value is "default".
newtype NameSpace
NameSpace :: String -> NameSpace

-- | A topic name can be any string value.
newtype TopicName
TopicName :: String -> TopicName

-- | A message id, needed for acknowledging messages. See <a>ack</a>.
newtype MsgId
MsgId :: MessageIdData -> MsgId

-- | A consumed message, containing both <a>MsgId</a> and payload as
--   bytestring.
data Message
Message :: MsgId -> ByteString -> Message

-- | A produced message, containing just a payload as bytestring.
newtype PulsarMessage
PulsarMessage :: ByteString -> PulsarMessage

-- | A subscription name can be any string value.
newtype SubscriptionName
SubscriptionName :: Text -> SubscriptionName