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


-- | A library for client-server applications based on custom protocols
--   
--   An API abstracting over the typical tasks of client-server
--   communication. It automates the authentication process, failure
--   management and the task of keeping the connections alive. It allows
--   the user to implement protocols of any form. Useful for writing all
--   kinds of services.
@package remotion
@version 0.2.0

module Remotion.Client

-- | A monad transformer for performing actions on client-side.
--   
--   Supports custom protocols with <tt>i</tt> being the type of the client
--   request and <tt>o</tt> - the server's response.
data Client i o m r

-- | Run <a>Client</a> in the base monad.
--   
--   Requires the base monad to have a <a>MonadBaseControl</a> instance for
--   <a>IO</a>.
run :: (Serializable IO i, Serializable IO o, MonadIO m, Applicative m, MonadBaseControl IO m) => Settings -> Client i o m r -> m (Either Failure r)

-- | Send a request <tt>i</tt> and receive a response <tt>o</tt>.
request :: (Serializable IO i, Serializable IO o, MonadIO m, Applicative m) => i -> Client i o m o

-- | Settings of <a>Client</a>.
type Settings = (UserProtocolSignature, URL)

-- | A unique identification of user's protocol version used for checking
--   of protocol versions mismatch between client and server. It can be
--   simply a user-supplied version number or a hash or a serialization of
--   the representation of a type used for protocol, which can be generated
--   using such library as <a>type-structure</a>.
type UserProtocolSignature = ByteString

-- | Location of the server.
data URL

-- | Path to the socket-file.
Socket :: FilePath -> URL

-- | Host name, port and credentials.
Host :: Text -> Int -> Credentials -> URL

-- | Either a plain ASCII password or an encoding of some data, e.g. an MD5
--   hash of a username-password pair or just a password. In more involved
--   scenarios you can mix in serialization, e.g. a serialized pair of
--   username and a hash of just the password.
--   
--   <tt>Nothing</tt> means anonymous.
type Credentials = Maybe ByteString
data Failure

-- | Unable to connect to the provided url.
UnreachableURL :: Failure

-- | Server has too many connections already. It's suggested to retry
--   later.
ServerIsBusy :: Failure

-- | Incorrect credentials.
Unauthenticated :: Failure

-- | Connection got interrupted for some reason.
ConnectionInterrupted :: Failure

-- | A timeout of communication with server reached.
TimeoutReached :: Int -> Failure

-- | A mismatch of the internal protocol versions on client and server.
--   First is the version on the client, second is the version on the
--   server.
ProtocolVersionMismatch :: Int -> Int -> Failure

-- | A mismatch of the user-supplied versions of custom protocol on client
--   and server. First is the version on the client, second is the version
--   on the server.
UserProtocolSignatureMismatch :: ByteString -> ByteString -> Failure

-- | Server reports that it was unable to deserialize the request. This is
--   only expected to happen in case of user's protocol mismatch.
CorruptRequest :: Text -> Failure
instance Typeable Failure
instance Show Failure
instance Read Failure
instance Ord Failure
instance Eq Failure
instance Generic Failure
instance Data Failure
instance Monad m => Functor (Client i o m)
instance Monad m => Applicative (Client i o m)
instance Monad m => Monad (Client i o m)
instance MonadIO m => MonadIO (Client i o m)
instance Monad m => MonadError Failure (Client i o m)
instance Datatype D1Failure
instance Constructor C1_0Failure
instance Constructor C1_1Failure
instance Constructor C1_2Failure
instance Constructor C1_3Failure
instance Constructor C1_4Failure
instance Constructor C1_5Failure
instance Constructor C1_6Failure
instance Constructor C1_7Failure
instance MonadBaseControl IO m => MonadBaseControl IO (Client i o m)
instance MonadTransControl (Client i o)
instance MonadBase IO m => MonadBase IO (Client i o m)
instance MonadTrans (Client i o)

module Remotion.Server

-- | A monad transformer, which runs the server in the background.
data Server m a

-- | Run the server, while automatically managing all related resources.
run :: (Serializable IO i, Serializable IO o, MonadIO m) => Settings i o s -> Server m a -> m (Either Failure a)

-- | Block until the server stops (which should never happen).
wait :: MonadIO m => Server m ()

-- | Count the currently available slots for new connections.
countSlots :: MonadIO m => Server m Int

-- | Run the server, while blocking the calling thread.
runAndWait :: (Serializable IO i, Serializable IO o) => Settings i o s -> IO (Either Failure ())

-- | Settings of how to run the server.
type Settings i o s = (UserProtocolSignature, ListeningMode, Timeout, MaxClients, Log, ProcessUserRequest i o s)

-- | A unique identification of user's protocol version used for checking
--   of protocol versions mismatch between client and server. It can be
--   simply a user-supplied version number or a hash or a serialization of
--   the representation of a type used for protocol, which can be generated
--   using such library as <a>type-structure</a>.
type UserProtocolSignature = ByteString

-- | Defines how to listen for connections.
data ListeningMode

-- | Listen on a port with an authentication function.
Host :: Port -> Authenticate -> ListeningMode

-- | Listen on a socket file. Since sockets are local no authentication is
--   needed. Works only on UNIX systems.
Socket :: FilePath -> ListeningMode

-- | A port to run the server on.
type Port = Int

-- | A function, which checks the authentication data. If you want to
--   provide access to anybody, use <tt>(const $ return True)</tt>.
type Authenticate = Credentials -> IO Bool

-- | Either a plain ASCII password or an encoding of some data, e.g. an MD5
--   hash of a username-password pair or just a password. In more involved
--   scenarios you can mix in serialization, e.g. a serialized pair of
--   username and a hash of just the password.
--   
--   <tt>Nothing</tt> means anonymous.
type Credentials = Maybe ByteString

-- | A session timeout in microseconds. The period of keepalive signaling
--   depends on that parameter. If you don't want excessive requests, just
--   make it a couple of minutes.
type Timeout = Int

-- | A maximum amount of clients. When this amount is reached the server
--   rejects all the further connections.
type MaxClients = Int

-- | A logging function. If you want no logging, use <tt>(const $ return
--   ())</tt>. If you want to output to console use
--   <tt>Data.Text.IO.<a>putStrLn</a></tt>. If you want to somehow reformat
--   the output, you're welcome: <tt>(Data.Text.IO.<a>putStrLn</a> .
--   ("Remotion.Server: " <a>&lt;&gt;</a>))</tt>.
type Log = Text -> IO ()

-- | A function which processes requests of type <tt>i</tt> from client and
--   produces a response of type <tt>o</tt>, while maintaining a
--   user-defined session state of type <tt>s</tt> per each client.
--   
--   This function essentially is what defines what the server actually
--   does.
type ProcessUserRequest i o s = State s -> i -> IO o

-- | A mutable state associated with particular client's connection. Since
--   we're in <a>IO</a> anyway, we use a mutable state with <a>IORef</a>
--   wrapper. You're free to extend it with whatever the data structure you
--   want.
type State s = IORef (Maybe s)

-- | A Server failure.
data Failure
ListeningSocketIsBusy :: Failure
instance Typeable Failure
instance Functor m => Functor (Server m)
instance Applicative m => Applicative (Server m)
instance Monad m => Monad (Server m)
instance MonadIO m => MonadIO (Server m)
instance MonadTrans Server
instance Show Failure
instance Eq Failure
instance Generic Failure
instance Datatype D1Failure
instance Constructor C1_0Failure
instance MonadBaseControl IO m => MonadBaseControl IO (Server m)
instance MonadTransControl Server
instance MonadBase IO m => MonadBase IO (Server m)