PubSub¶

Purpose¶

The Publish-Subscribe (PubSub) engine implements a peer-to-peer topic-based publish-subscribe protocol. It is responsible for handling P2P protocol messages and managing subscriptions. Local engines send and receive pub/sub messages via the Router.

~Usage~¶

The Router engine interfaces with the PubSub engine directly, while other local engines use the Router to subscribe to topics and send messages destined to the multicast address of a pub/sub topic, which the Router then forwards to PubSub for delivery.

State¶

PubSubRoutingTable ¶

Todo

Pending a proper description.

Messages received¶

TopicAdvert ¶

Topic advertisement by a publisher.

Reception:

TopicAdvertV1

Record with fields:

topic: TopicIdentity

Topic ID

tags: list

List of optional tags to facilitate subscribing to new topics with relevant tags

publisher: EngineIdentity

PubSub engine ID of publisher

created: Time

Creation time

sig: Signature

Signature over the above fields by topic

Triggers:

TopicAdvert

TopicAdvertReceived

Subscribe to a topic at another peer.

Reception:

TopicRequestV1

Record with fields:

topic: TopicIdentity Pub/sub topic identity.

Triggers:

SubscribeAck

Unsubscribe ¶

Unsubscribe from a topic at other peers.

Reception:

TopicRequestV1

Record with fields:

topic: TopicIdentity Pub/sub topic identity.

Triggers:

UnsubscribeAck

Event ¶

An event sent to a topic.

Reception:

EventV1

Record with fields:

topic: TopicIdentity

Topic the event is published to

publisher: EngineIdentity

PubSub engine identity of pulisher

seq: u32

Sequence number of publisher

deps: Vec

Events this event depends on

seen: Vec

Independent events recently seen

body: Vec

Encapsulated EngineMessage

sig: Signature

Signature by publisher over the above fields

Triggers:

Event

EngineMessage

EngineMessage ¶

A message sent to a pub/sub topic by an engine.

Reception:

EngineMessageV1

Record with fields:

src: EngineIdentity

Source engine identity

dst: DestinationIdentity

Destination identity

id: u64

Message ID: unique per src-dst pairs

reply_to: Option

id of a previous message this message is in reply to

expiry Option

Expiry time for outgoing messages. See P2PMessage & TransportMessage.

rprefs: Option<RoutingPrefs>

Routing preferences

tprefs: Option<TransportPrefs>

Transport preferences

protocol: Protocol

Protocol & version used in body

body: Vec

Serialized message body

sig: Option

Signature over the above fields by src

Triggers:

Event

SubscribeRequest ¶

Subscription request.

Reception:

TopicRequestV1

Record with fields:

topic: TopicIdentity Pub/sub topic identity.

Triggers:

TopicResponseV1

Result

UnsubscribeRequest ¶

Unsubscription request.

Reception:

TopicRequestV1

Record with fields:

topic: TopicIdentity Pub/sub topic identity.

Triggers:

TopicResponseV1

Result

StartAdvertRequest ¶

Start advertising a topic in the network.

Reception:

TopicCreateRequestV1

Record with fields:

topic: TopicIdentity Pub/sub topic identity.
scope: RoutingScope Whether the topic should be advertised over the network.
advert: Option<TopicAdvertV1> Topic advertisement to send to the network, when the scope allows.

Triggers:

TopicResponseV1

Result

StopAdvertRequest ¶

Stop advertising a topic in the network.

Reception:

TopicRequestV1

Record with fields:

topic: TopicIdentity Pub/sub topic identity.

Triggers:

TopicResponseV1

Result

Notifications sent¶

TopicSubscribed ¶

Notification about a topic that was successfully subscribed at another peer.

TopicRequestV1

Record with fields:

topic: TopicIdentity Pub/sub topic identity.

TopicUnsubscribed ¶

Notification about a topic that was successfully unsubscribed at another peer.

TopicRequestV1

Record with fields:

topic: TopicIdentity Pub/sub topic identity.

TopicAdvertReceived ¶

A TopicAdvert has been received from another peer.

TopicCreateRequestV1

Record with fields:

topic: TopicIdentity Pub/sub topic identity.
scope: RoutingScope Whether the topic should be advertised over the network.
advert: Option<TopicAdvertV1> Topic advertisement to send to the network, when the scope allows.

Message flow¶

sequenceDiagram

%% TODO

Router -) PubSub: EngineMessage
PubSub -) PubSub: Event
PubSub -) Router: EngineMessage
Router -) Any Local Engine: EngineMessage

Any Local Engine -) Router: EngineMessage
Router -) PubSub: EngineMessage
PubSub -) PubSub: Event

PubSub ->>+ PubSub_R: Subscribe
PubSub_R -->>- PubSub: SubscribeAck

PubSub ->>+ PubSub_R: Unsubscribe
PubSub_R -->>- PubSub: UnsubscribeAck

Router ->>+ PubSub: SubscribeRequest
PubSub -->>- Router: SubscribeResponse

Router ->>+ PubSub: UnsubscribeRequest
PubSub -->>- Router: UnsubscribeResponse

Router ->>+ PubSub: StartAdvertRequest
PubSub -->>- Router: StartAdvertResponse

Router ->>+ PubSub: StopAdvertRequest
PubSub -->>- Router: StopAdvertResponse

PubSub -) Any Local Engine: TopicSubscribed

PubSub -) Any Local Engine: TopicUnsubscribed

PubSub -) Any Local Engine: TopicAdvertReceived