Safe Haskell	None
Language	Haskell2010

Network.Zyre2

Contents

Context Lifecycle
Context information
Group membership
Peers
Sending and receiving messages
Constructing messages
Phantom tags for lifecycle state

Description

Zyre provides reliable group messaging over local area networks. It has these key characteristics:

Zyre needs no administration or configuration.
Peers may join and leave the network at any time.
Peers talk to each other without any central brokers or servers.
Peers can talk directly to each other.
Peers can join groups, and then talk to groups.
Zyre is reliable, and loses no messages even when the network is heavily loaded.
Zyre is fast and has low latency, requiring no consensus protocols.
Zyre is designed for WiFi networks, yet also works well on Ethernet networks.
Time for a new peer to join a network is about one second.

Typical use cases for Zyre are:

Local service discovery.
Clustering of a set of services on the same Ethernet network.
Controlling a network of smart devices (Internet of Things).
Multi-user mobile applications (like smart classrooms).

This package provides a haskell interface to the Zyre 2.0.1 API. The package requires the c libraries czmq and zyre to be installed on the system. See https://github.com/zeromq/zyre for specifics.

Synopsis

data ZyreContext state
new :: Maybe Text -> IO (ZyreContext ZCreated)
start :: ZyreContext ZCreated -> IO (ZyreContext ZRunning)
stop :: ZyreContext ZRunning -> IO (ZyreContext ZStopped)
destroy :: ZyreContext ZStopped -> IO (ZyreContext ZDestroyed)
uuid :: ZyreContext a -> IO Text
name :: ZyreContext a -> IO Text
version :: IO Word64
join :: ZyreContext ZRunning -> Text -> IO Int
leave :: ZyreContext ZRunning -> Text -> IO Int
ownGroups :: ZyreContext ZRunning -> IO [Text]
peerGroups :: ZyreContext ZRunning -> IO [Text]
peers :: ZyreContext ZRunning -> IO [Text]
peersByGroup :: ZyreContext ZRunning -> Text -> IO (Maybe [Text])
peerAddress :: ZyreContext ZRunning -> Text -> IO (Maybe Text)
peerName :: ZyreContext ZRunning -> Text -> IO (Maybe Text)
peerHeaderValue :: ZyreContext ZRunning -> Text -> Text -> IO (Maybe Text)
shout :: ZyreContext ZRunning -> Text -> ZMsg -> IO Int
shouts :: ZyreContext ZRunning -> Text -> Text -> IO Int
whisper :: ZyreContext ZRunning -> Text -> ZMsg -> IO Int
whispers :: ZyreContext ZRunning -> Text -> Text -> IO Int
recv :: ZyreContext ZRunning -> IO (Maybe ZMsg)
data ZMsg
- = Enter {
  - _zmsgFromNode :: Text
  - _zmsgName :: Text
  - _zmsgHeaders :: [(Text, Text)]
  - _zmsgIpPort :: Text
  }
- | Evasive {
  - _zmsgFromNode :: Text
  - _zmsgName :: Text
  }
- | Silent {
  - _zmsgFromNode :: Text
  - _zmsgName :: Text
  }
- | Exit {
  - _zmsgFromNode :: Text
  - _zmsgName :: Text
  }
- | Join {
  - _zmsgFromNode :: Text
  - _zmsgName :: Text
  - _zmsgGroupName :: Text
  }
- | Leave {
  - _zmsgFromNode :: Text
  - _zmsgName :: Text
  - _zmsgGroupName :: Text
  }
- | Whisper {
  - _zmsgFromNode :: Text
  - _zmsgName :: Text
  - _zmsgMessage :: [ZFrame]
  }
- | Shout {
  - _zmsgFromNode :: Text
  - _zmsgName :: Text
  - _zmsgGroupName :: Text
  - _zmsgMessage :: [ZFrame]
  }
- | Stop
msgShout :: ZMsg
msgWhisper :: ZMsg
pushMem :: ByteString -> ZMsg -> ZMsg
pushText :: Text -> ZMsg -> ZMsg
addMem :: ByteString -> ZMsg -> ZMsg
addText :: Text -> ZMsg -> ZMsg
data ZFrame
frameData :: ZFrame -> ByteString
popText :: ZMsg -> (Maybe Text, ZMsg)
popMem :: ZMsg -> (Maybe ByteString, ZMsg)
data ZCreated
data ZDestroyed
data ZRunning
data ZStopped

Context Lifecycle

data ZyreContext state Source #

A context handle for zyre contexts. Holds relevant state for the context, and is tagged with the state of the context. E.g. ZCreated, ZRunning, ZStopped, ZDestroyed.

new :: Maybe Text -> IO (ZyreContext ZCreated) Source #

Create a new Zyre instance/context. All created contexts must be manually cleaned up with destroy to avoid leaks. Takes a node name, or if Nothing will auto-generate a name from the node UUID.

start :: ZyreContext ZCreated -> IO (ZyreContext ZRunning) Source #

Start the zyre instance. Starts UDP beaconing and joins the peer network. Generates an Enter message for other participants.

stop :: ZyreContext ZRunning -> IO (ZyreContext ZStopped) Source #

Stop the zyre instance, leaving the peer network. Generates a Exit message for the other participants.

destroy :: ZyreContext ZStopped -> IO (ZyreContext ZDestroyed) Source #

Destroy the given zyre context, freeing its resources. Once it has been destroyed, it can no longer be used. Returns a ZyreContext tagged as destroyed to maintain an API similar to the rest of the interface.

Context information

uuid :: ZyreContext a -> IO Text Source #

Retrieve the UUID generated for the context.

name :: ZyreContext a -> IO Text Source #

Retrieve the name of our node after initialization. Either set by new or automatically generated by zyre from the nodes UUID.

version :: IO Word64 Source #

Retrieve the version of underlying zyre library.

Group membership

join :: ZyreContext ZRunning -> Text -> IO Int Source #

Join a peer group, to start receiving and be able to send messages from that group. Generates a Join message for the other participants in the group.

leave :: ZyreContext ZRunning -> Text -> IO Int Source #

Leave a peer group, and stop receiving updates from that group. Generates a Leave message for the other participants in the group network.

ownGroups :: ZyreContext ZRunning -> IO [Text] Source #

List the groups that you are a part of.

peerGroups :: ZyreContext ZRunning -> IO [Text] Source #

List groups that are known through connected peers.

Peers

peers :: ZyreContext ZRunning -> IO [Text] Source #

List the id of the peers in the peer network.

peersByGroup :: ZyreContext ZRunning -> Text -> IO (Maybe [Text]) Source #

List the id of the peers in a specific group in the peer network.

peerAddress :: ZyreContext ZRunning -> Text -> IO (Maybe Text) Source #

Retrieve the endpoint of a connected peer. Returns Nothing if peer does not exist.

peerName :: ZyreContext ZRunning -> Text -> IO (Maybe Text) Source #

peerHeaderValue :: ZyreContext ZRunning -> Text -> Text -> IO (Maybe Text) Source #

Retrieve the value of a header of a connected peer. Returns Nothing if peer or key doesn't exist.

Sending and receiving messages

shout :: ZyreContext ZRunning -> Text -> ZMsg -> IO Int Source #

Shout a Shout to a group. Sends data frames.

ctx <- new "my-node"
ctx <- start ctx
join ctx "my-group"
let msg = addString "My message" msgShout
shout ctx "my-group" msg

You can also send multiple frames in the same message.

let msg = addString "Frame2" . addString "Frame1" $ msgShout

shouts :: ZyreContext ZRunning -> Text -> Text -> IO Int Source #

Shout a Shout to a group. Sends some Text value encoded as a ByteString.

ctx <- new "my-node"
ctx <- start ctx
join ctx "my-group"
shout ctx "my-group" "My message"

whisper :: ZyreContext ZRunning -> Text -> ZMsg -> IO Int Source #

Whisper a Whisper to a specific peer. Takes a node id and a ZMsg. Sends data frames.

whispers :: ZyreContext ZRunning -> Text -> Text -> IO Int Source #

Whisper a Whisper to a specific peer. Sends some Text value encoded as a ByteString.

recv :: ZyreContext ZRunning -> IO (Maybe ZMsg) Source #

Block and await a message from the peer network. Returns Nothing if it times out or is interruped.

Constructing messages

data ZMsg Source #

Message-types supported and published by zyre.

Constructors

Enter	A peer has joined the peer network.
Fields _zmsgFromNode :: Text The UUID of the sending node. _zmsgName :: Text The name of the sending node. _zmsgHeaders :: [(Text, Text)] Dictionary containing the headers. _zmsgIpPort :: Text The ip and port of the sending node. E.g. tcp://127.0.0.1:8344
Evasive	A peer has not sent a message within the `evasive` interval period. The peer will be pinged.
Fields _zmsgFromNode :: Text The UUID of the sending node. _zmsgName :: Text The name of the sending node.
Silent	A peer has been silent and not responded to PING messages for the `silent` interval period.
Fields _zmsgFromNode :: Text The UUID of the sending node. _zmsgName :: Text The name of the sending node.
Exit	A peer has exited the peer network.
Fields _zmsgFromNode :: Text The UUID of the sending node. _zmsgName :: Text The name of the sending node.
Join	A peer has joined a group.
Fields _zmsgFromNode :: Text The UUID of the sending node. _zmsgName :: Text The name of the sending node. _zmsgGroupName :: Text The name of the group which the message concerns.
Leave	A peer has left a group.
Fields _zmsgFromNode :: Text The UUID of the sending node. _zmsgName :: Text The name of the sending node. _zmsgGroupName :: Text The name of the group which the message concerns.
Whisper	A peer has whispered to this node.
Fields _zmsgFromNode :: Text The UUID of the sending node. _zmsgName :: Text The name of the sending node. _zmsgMessage :: [ZFrame] The message content, coded as `ZFrame`s. A message may hold 0 or more frames. Note: a ZMsg with 0 frames supplied to `shout` or `whisper` will be ignored and not sent.
Shout	A peer has shouted in a group.
Fields _zmsgFromNode :: Text The UUID of the sending node. _zmsgName :: Text The name of the sending node. _zmsgGroupName :: Text The name of the group which the message concerns. _zmsgMessage :: [ZFrame] The message content, coded as `ZFrame`s. A message may hold 0 or more frames. Note: a ZMsg with 0 frames supplied to `shout` or `whisper` will be ignored and not sent.
Stop	The zyre context which is being listened to has been stopped.

Instances

Instances details

Show ZMsg Source #
Instance details Defined in Network.Zyre2.ZMsg Methods showsPrec :: Int -> ZMsg -> ShowS # show :: ZMsg -> String # showList :: [ZMsg] -> ShowS #

msgShout :: ZMsg Source #

Empty Shout message. Combine with addText, pushText, addMem, and pushMem to construct a shout to send.

msgWhisper :: ZMsg Source #

Empty Whisper message. Combine with addText, pushText, addMem, and pushMem to construct a whisper to send.

Adding data

pushMem :: ByteString -> ZMsg -> ZMsg Source #

Push binary data to the front of a ZMsg as a frame.

pushText :: Text -> ZMsg -> ZMsg Source #

Push a text frame to the front of a ZMsg.

addMem :: ByteString -> ZMsg -> ZMsg Source #

Add binary data to the end of a ZMsg as a frame.

addText :: Text -> ZMsg -> ZMsg Source #

Add a text frame to the end of a ZMsg.

Frames

data ZFrame Source #

A frame of binary data. See mkFrame and frameData.

Instances

Instances details

Show ZFrame Source #
Instance details Defined in Network.Zyre2.ZMsg Methods showsPrec :: Int -> ZFrame -> ShowS # show :: ZFrame -> String # showList :: [ZFrame] -> ShowS #

frameData :: ZFrame -> ByteString Source #

Retrieve the data stored in a ZFrame.

Deconstructing messages

popText :: ZMsg -> (Maybe Text, ZMsg) Source #

Remove the first frame of the ZMsg, and interpret it as Text.

popMem :: ZMsg -> (Maybe ByteString, ZMsg) Source #

Remove the first frame of the ZMsg as a ByteString.

Phantom tags for lifecycle state

data ZCreated Source #

Phantom tag for a created context.

data ZDestroyed Source #

Phantom tag for a destroyed context.

data ZRunning Source #

Phantom tag for a running context.

data ZStopped Source #

Phantom tag for a stopped context.