Skip to content

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 ID

  • tags: list

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

PubSub engine ID of publisher

  • created: Time

Creation time

  • sig: Signature

Signature over the above fields by topic

Triggers:

TopicAdvert

TopicAdvertReceived

Subscribe

Subscribe to a topic at another peer.

Reception:

TopicRequestV1

Record with fields:

Triggers:

SubscribeAck

Unsubscribe

Unsubscribe from a topic at other peers.

Reception:

TopicRequestV1

Record with fields:

Triggers:

UnsubscribeAck

Event

An event sent to a topic.

Reception:

EventV1

Record with fields:

Topic the event is published to

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:

Source engine identity

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.

Routing preferences

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:

Triggers:

TopicResponseV1

Result

UnsubscribeRequest

Unsubscription request.

Reception:

TopicRequestV1

Record with fields:

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:

Triggers:

TopicResponseV1

Result

Notifications sent

TopicSubscribed

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

TopicRequestV1

Record with fields:

TopicUnsubscribed

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

TopicRequestV1

Record with fields:

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
(Wiki) links on this page