OM.Legion

Legion is framework for building clusters of homogenous nodes that must maintain a shared, replicated state.

For instance, maybe in order to scale a service you are using a partitioning strategy to direct traffic for users A-H to node 1, users I-Q to node 2, and R-Z to node 3. The partition table itself is something all the nodes have to agree on and would make an excellent candidate for the "shared, replicated state" managed by this framework.

To update the shared state, whatever it is, use:

• applyFast
• or applyConsistent

Additionally, since Legion already has to understand about different nodes in the cluster, and how to talk to them, we provide a variety of tools to help facilitate inter-node communication:

• cast: We support sending arbitrary messages to other peers without waiting on a response.
• call: We support sending requests to other peers that block on a response.
• broadcast: We support sending a message to _every_ other peer without waiting on a response
• broadcall: We support sending a request to every other peer, and blocking until we recieve a response from them all.

Starting up the runtime.

forkLegionary

Arguments

:: (EventConstraints e, MonadConstraints m)

=> (ByteString -> IO ByteString)

Handle a user call request.

-> (ByteString -> IO ())

Handle a user cast message.

-> (Peer -> EventFold ClusterName Peer e -> IO ())

Callback when the cluster-wide eventfold changes.

-> Int

The propagation interval, in microseconds (for use with threadDelay).

-> StartupMode e

How to start the runtime, by creating new cluster or joining an existing cluster.

-> m (Runtime e)

Fork the Legion runtime system.

type EventConstraints e = (Binary (Output e), Binary (State e), Binary e, Default (State e), Eq (Output e), Eq e, Event Peer e, Show (Output e), Show (State e), Show e, ToJSON (Output e), ToJSON (State e), ToJSON e)

Shorthand for all the constraints needed for the event type. Mainly used so that documentation renders better.

type MonadConstraints m = (MonadCatch m, MonadFail m, MonadLoggerIO m, MonadTimeSpec m, MonadUnliftIO m, Race)

Shorthand for all the monad constraints, mainly use so that documentation renders better.

data StartupMode e

This defines the various ways a node can be spun up.

Constructors

NewCluster

Indicates that we should bootstrap a new cluster at startup.

Fields

• Peer

  The peer being launched.

• ClusterName

  The name of the cluster being launched.

JoinCluster

Indicates that the node should try to join an existing cluster.

Fields

• Peer

  The peer being launched.

• ClusterName

  The name of the cluster we are trying to join.

• Peer

  The existing peer we are attempting to join with.

Recover

Resume operation given the previously saved state.

Fields

• Peer

  The Peer being recovered.

• (EventFold ClusterName Peer e)

  The last acknowledged state we had before we crashed.

Instances

(Show e, Show (Output e), Show (State e)) => Show (StartupMode e)

Defined in OM.Legion.Runtime

Methods

showsPrec :: Int -> StartupMode e -> ShowS

show :: StartupMode e -> String

showList :: [StartupMode e] -> ShowS

data Runtime e

A handle on the Legion runtime.

Instances

Actor (Runtime e)

Defined in OM.Legion.Runtime

Associated Types

type Msg (Runtime e)

Methods

actorChan :: Runtime e -> Msg (Runtime e) -> IO ()

type Msg (Runtime e)

Defined in OM.Legion.Runtime

type Msg (Runtime e)

Applying state changes.

applyFast

Arguments

:: MonadIO m

=> Runtime e

The runtime handle.

-> e

The event to be applied.

-> m (Output e)

Returns the possibly inconsistent event output.

Update the distributed cluster state by applying an event. The event output will be returned immediately and may not reflect a totally consistent view of the cluster. The state update itself, however, is guaranteed to be applied atomically and consistently throughout the cluster.

applyConsistent

Arguments

:: MonadIO m

=> Runtime e

The runtime handle.

-> e

The event to be applied.

-> m (Output e)

Returns the strongly consistent event output.

Update the distributed cluster state by applying an event. Both the event output and resulting state will be totally consistent throughout the cluster.

Sending messages around the cluster.

cast :: MonadIO m => Runtime e -> Peer -> ByteString -> m ()

Send a user message to some other peer, without waiting on a response.

call :: MonadIO m => Runtime e -> Peer -> ByteString -> m ByteString

Send a user message to some other peer, and block until a response is received.

broadcast :: MonadIO m => Runtime e -> ByteString -> m ()

Send a user message to all peers, without wating on a response.

broadcall

Arguments

:: MonadIO m

=> Runtime e

-> DiffTime

The timeout.

-> ByteString

-> m (Map Peer (Maybe ByteString))

Send a user message to all peers, and block until a response is received from all of them.

Inspecting the current state.

readState :: MonadIO m => Runtime e -> m (EventFold ClusterName Peer e)

Read the current powerstate value.

getSelf :: Runtime e -> Peer

Get the identifier for the local peer.

getClusterName :: Runtime e -> ClusterName

Obtain the ClusterName.

Observability

getStats :: MonadIO m => Runtime e -> m Stats

Retrieve some basic stats that can be used to intuit the health of the cluster.

newtype Stats

Some basic stats that can be used to intuit the health of the cluster. We currently only report on how long it has been since some peer has made some progress.

Constructors

Stats

Fields

• timeWithoutProgress :: Map Peer DiffTime

  How long it has been since a Peer has made progress (if it is divergent). If the peer is completely up to date as far as we know, then it does not appear in the map at all. Only peers which we are expecting to make progress appear.

Instances

ToJSON Stats

Defined in OM.Legion.Runtime

Methods

toJSON :: Stats -> Value

toEncoding :: Stats -> Encoding

toJSONList :: [Stats] -> Value

toEncodingList :: [Stats] -> Encoding

Generic Stats

Defined in OM.Legion.Runtime

Associated Types

type Rep Stats :: Type -> Type

Methods

from :: Stats -> Rep Stats x

to :: Rep Stats x -> Stats

Show Stats

Defined in OM.Legion.Runtime

Methods

showsPrec :: Int -> Stats -> ShowS

show :: Stats -> String

showList :: [Stats] -> ShowS

Binary Stats

Defined in OM.Legion.Runtime

Methods

put :: Stats -> Put

get :: Get Stats

putList :: [Stats] -> Put

Eq Stats

Defined in OM.Legion.Runtime

Methods

(==) :: Stats -> Stats -> Bool

(/=) :: Stats -> Stats -> Bool

type Rep Stats

Defined in OM.Legion.Runtime

type Rep Stats = D1 ('MetaData "Stats" "OM.Legion.Runtime" "om-legion-6.9.0.3-inplace" 'True) (C1 ('MetaCons "Stats" 'PrefixI 'True) (S1 ('MetaSel ('Just "timeWithoutProgress") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Map Peer DiffTime))))

Cluster Topology

eject :: MonadIO m => Runtime e -> Peer -> m ()

Eject a peer from the cluster.

newtype Peer

The identification of a node within the legion cluster.

Constructors

Peer

Fields

• unPeer :: Text

Instances

FromJSON Peer

Defined in OM.Legion.MsgChan

Methods

parseJSON :: Value -> Parser Peer

parseJSONList :: Value -> Parser [Peer]

FromJSONKey Peer

Defined in OM.Legion.MsgChan

Methods

fromJSONKey :: FromJSONKeyFunction Peer

fromJSONKeyList :: FromJSONKeyFunction [Peer]

ToJSON Peer

Defined in OM.Legion.MsgChan

Methods

toJSON :: Peer -> Value

toEncoding :: Peer -> Encoding

toJSONList :: [Peer] -> Value

toEncodingList :: [Peer] -> Encoding

ToJSONKey Peer

Defined in OM.Legion.MsgChan

Methods

toJSONKey :: ToJSONKeyFunction Peer

toJSONKeyList :: ToJSONKeyFunction [Peer]

Show Peer

Defined in OM.Legion.MsgChan

Methods

showsPrec :: Int -> Peer -> ShowS

show :: Peer -> String

showList :: [Peer] -> ShowS

Binary Peer

Defined in OM.Legion.MsgChan

Methods

put :: Peer -> Put

get :: Get Peer

putList :: [Peer] -> Put

Eq Peer

Defined in OM.Legion.MsgChan

Methods

(==) :: Peer -> Peer -> Bool

(/=) :: Peer -> Peer -> Bool

Ord Peer

Defined in OM.Legion.MsgChan

Methods

compare :: Peer -> Peer -> Ordering

(<) :: Peer -> Peer -> Bool

(<=) :: Peer -> Peer -> Bool

(>) :: Peer -> Peer -> Bool

(>=) :: Peer -> Peer -> Bool

max :: Peer -> Peer -> Peer

min :: Peer -> Peer -> Peer

FromHttpApiData Peer

Defined in OM.Legion.MsgChan

Methods

parseUrlPiece :: Text -> Either Text Peer

parseHeader :: ByteString -> Either Text Peer

parseQueryParam :: Text -> Either Text Peer

ToHttpApiData Peer

Defined in OM.Legion.MsgChan

Methods

toUrlPiece :: Peer -> Text

toEncodedUrlPiece :: Peer -> Builder

toHeader :: Peer -> ByteString

toQueryParam :: Peer -> Text

newtype ClusterName

The name of a cluster.

Constructors

ClusterName

Fields

• unClusterName :: Text

Instances

FromJSON ClusterName

Defined in OM.Legion.MsgChan

Methods

parseJSON :: Value -> Parser ClusterName

parseJSONList :: Value -> Parser [ClusterName]

ToJSON ClusterName

Defined in OM.Legion.MsgChan

Methods

toJSON :: ClusterName -> Value

toEncoding :: ClusterName -> Encoding

toJSONList :: [ClusterName] -> Value

toEncodingList :: [ClusterName] -> Encoding

IsString ClusterName

Defined in OM.Legion.MsgChan

Methods

fromString :: String -> ClusterName

Show ClusterName

Defined in OM.Legion.MsgChan

Methods

showsPrec :: Int -> ClusterName -> ShowS

show :: ClusterName -> String

showList :: [ClusterName] -> ShowS

Binary ClusterName

Defined in OM.Legion.MsgChan

Methods

put :: ClusterName -> Put

get :: Get ClusterName

putList :: [ClusterName] -> Put

Eq ClusterName

Defined in OM.Legion.MsgChan

Methods

(==) :: ClusterName -> ClusterName -> Bool

(/=) :: ClusterName -> ClusterName -> Bool

Ord ClusterName

Defined in OM.Legion.MsgChan

Methods

compare :: ClusterName -> ClusterName -> Ordering

(<) :: ClusterName -> ClusterName -> Bool

(<=) :: ClusterName -> ClusterName -> Bool

(>) :: ClusterName -> ClusterName -> Bool

(>=) :: ClusterName -> ClusterName -> Bool

max :: ClusterName -> ClusterName -> ClusterName

min :: ClusterName -> ClusterName -> ClusterName

FromHttpApiData ClusterName

Defined in OM.Legion.MsgChan

Methods

parseUrlPiece :: Text -> Either Text ClusterName

parseHeader :: ByteString -> Either Text ClusterName

parseQueryParam :: Text -> Either Text ClusterName

ToHttpApiData ClusterName

Defined in OM.Legion.MsgChan

Methods

toUrlPiece :: ClusterName -> Text

toEncodedUrlPiece :: ClusterName -> Builder

toHeader :: ClusterName -> ByteString

toQueryParam :: ClusterName -> Text