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


-- | Interact with Serf via Haskell.
--   
@package serf
@version 0.1.1.0


-- | This module provides basic support for implementing Serf event handler
--   programs using Haskell. Serf calls event handlers by executing the
--   specified handler program with information relevant to the handler set
--   in environment variables.
module System.Serf.Handler

-- | A union of all possible event types that Serf supports.
data Event

-- | An event indicating that members have joined the cluster.
MemberJoin :: Event

-- | An event indicating that members have left the cluster.
MemberLeave :: Event

-- | An event indicating that members have failed out of the cluster.
MemberFailed :: Event

-- | A custom event triggered by an agent in the cluster.
User :: String -> Event

-- | All data set in the environment for the event handler. This is the
--   primary way that Serf communicates relevant information to the
--   executing handler.
data SerfEnv
SerfEnv :: Event -> String -> String -> SerfEnv

-- | The event that caused the handling program to be executed.
event :: SerfEnv -> Event

-- | The name of the node that is executing the event handler.
selfName :: SerfEnv -> String

-- | The role of the node that is executing the event handler.
selfRole :: SerfEnv -> String

-- | Retrieve all environment info set by Serf, returning Nothing if any
--   Serf environment data is missing.
getSerfEnv :: IO (Maybe SerfEnv)
instance Read Event
instance Show Event
instance Read SerfEnv
instance Show SerfEnv


-- | "Serf is a service discovery and orchestration tool that is
--   decentralized, highly available, and fault tolerant. Serf runs on
--   every major platform: Linux, Mac OS X, and Windows. It is extremely
--   lightweight: it uses 5 to 10 MB of resident memory and primarily
--   communicates using infrequent UDP messages."
--   
--   <a>www.serfdom.io/intro</a>
--   
--   This module provides facilities for interacting with a serf agent
--   running on a machine. This module aims to expose all functionality
--   provided by the serf command-line tool in a programmatic way.
module System.Serf

-- | An alias for the operational monad created with the <a>Serf</a> data
--   type.
type SerfM = Program Serf

-- | Commands supported by the serf executable (serf protocol v1).
data Serf a
SendEvent :: SendOptions -> String -> Maybe String -> Serf Bool
ForceLeave :: String -> Serf Bool
JoinNodes :: JoinOptions -> String -> [String] -> Serf Bool
Members :: Serf [MemberStatus]

-- | A convenience class for lifting serf action evaluation into monad
--   transformer stacks.
class Monad m => MonadSerf m
evalSerf :: MonadSerf m => SerfM a -> m a

-- | Run serf actions locally on the default port.
serf :: SerfM a -> IO a

-- | Run serf actions at a specified RPC address.
serfAt :: String -> SerfM a -> IO a

-- | Run serf actions with a list of arbitrary command line arguments.
serfWithOpts :: [String] -> SerfM a -> IO a

-- | Dispatch a custom user event into a Serf cluster.
--   
--   Nodes in the cluster listen for these custom events and react to them.
sendEvent :: String -> Maybe String -> SerfM Bool

-- | Dispatch a custom user event into a Serf cluster with additional flags
--   set.
sendEvent' :: SendOptions -> String -> Maybe String -> SerfM Bool
data SendOptions
SendOptions :: Maybe Bool -> SendOptions
coalesceEvents :: SendOptions -> Maybe Bool

-- | Force a specific node to leave a cluster. Note that the node will
--   rejoin unless the serf agent for that node has exited.
forceLeave :: String -> SerfM Bool

-- | Join the node to a cluster using the specified address(es).
--   
--   At least one node address must be specified.
joinNodes :: String -> [String] -> SerfM Bool

-- | Join the node to a cluster with non-standard options.
joinNodes' :: JoinOptions -> String -> [String] -> SerfM Bool

-- | Options specific to joining a cluster
data JoinOptions
JoinOptions :: Maybe Bool -> JoinOptions

-- | Whether to replay all events that have occurred in the cluster.
_jsReplay :: JoinOptions -> Maybe Bool

-- | List known members in the cluster
members :: SerfM [MemberStatus]
data MemberStatus
MemberStatus :: Text -> Text -> LastKnownStatus -> MemberStatus
memberStatusName :: MemberStatus -> Text
memberStatusAddress :: MemberStatus -> Text
memberStatus :: MemberStatus -> LastKnownStatus

-- | The last known status of listed nodes.
data LastKnownStatus
Alive :: LastKnownStatus
Failed :: LastKnownStatus

-- | The minimum log level to log with the "monitor" command.
data LogLevel
Trace :: LogLevel
Debug :: LogLevel
Info :: LogLevel
Warn :: LogLevel
Error :: LogLevel

-- | Options for monitoring serf agent events. It is recommended that the
--   log level is cranked up to either <a>Warn</a> or <a>Error</a>, as the
--   default currently seems to be <a>Debug</a>, and is not generally
--   useful in production environments.
data MonitorOptions
MonitorOptions :: Maybe LogLevel -> MonitorOptions
monitorLogLevel :: MonitorOptions -> Maybe LogLevel
instance Read LastKnownStatus
instance Show LastKnownStatus
instance Read MemberStatus
instance Show MemberStatus