PubSub

Defines a publish-subscribe protocol for sending and receiving messages to and from the Marlin network.

Operation

Channels

The publish-subscribe abstraction revolves around channels(alternatively known as topics) which serve as a group identifier for clients interested in a particular set of messages. Interested clients subscribe to a channel(or many) and receive all messages published to the channel by other clients.

Subscribing/Unsubscribing

Clients subscribe/unsubscribe to a channel by sending a SUBSCRIBE/UNSUBSCRIBE message with channel details. They receive a RESPONSE message indicating success or error.

ClientNodeClientNodeSubscribeSUBSCRIBE(some_channel)Add client to subscriptionlist of some_channelalt[success][failure]RESPONSE(ok, some_channel)RESPONSE(error, some_channel)UnsubscribeUNSUBSCRIBE(some_channel)Remove client from subscriptionlist of some_channelalt[success][failure]RESPONSE(ok, some_channel)RESPONSE(error, some_channel)

Publishing

Messages can be published to the channel by sending a MESSAGE message to the node. The node will automatically push the message to all subscribers.

PublisherNodeSubscriber1Subscriber2SubscriberNPublisherNodeSubscriber1Subscriber2SubscriberNMESSAGE(some_channel, payload)MESSAGE(some_channel, payload)MESSAGE(some_channel, payload)Send to all subscribersMESSAGE(some_channel, payload)

Wire format

Every message is prefixed with a version byte and a message type byte. The message type identifies the message and the version field enables protocol upgrades in the future.

 0               1               2               3
 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+++++++++++++++++++++++++++++++++
|    Version    |      Type     |
-----------------------------------------------------------------
|                            Payload                          ...
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

SUBSCRIBE (0x00)

Channel as payload.

 0               1               2               3
 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+++++++++++++++++++++++++++++++++
|      0x00     |      0x00     |
-----------------------------------------------------------------
|                         Channel Name                        ...
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

UNSUBSCRIBE (0x01)

Channel as payload.

 0               1               2               3
 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+++++++++++++++++++++++++++++++++
|      0x00     |      0x01     |
-----------------------------------------------------------------
|                         Channel Name                        ...
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

RESPONSE (0x02)

Payload contains a byte representing the reponse type(currently a OK/ERROR flag) followed by an arbitrary response message.

 0               1               2               3
 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+++++++++++++++++++++++++++++++++++++++++++++++++
|      0x00     |      0x02     |      Type     |
-----------------------------------------------------------------
|                            Message                          ...
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

MESSAGE (0x03)

Payload contains a 8 byte message length, a 8 byte message id, channel details and the message data.

 0               1               2               3
 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+++++++++++++++++++++++++++++++++
|      0x00     |      0x03     |
-----------------------------------------------------------------
|                                                               |
----                      Message Length                     ----
|                                                               |
-----------------------------------------------------------------
|                                                               |
----                        Message ID                       ----
|                                                               |
-----------------------------------------------------------------
|      Channel name length      |
-----------------------------------------------------------------
|                         Channel Name                        ...
-----------------------------------------------------------------
|                         Message Data                        ...
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++