Router

Overview

Purpose

The Router is responsible for forwarding both intra-node and inter-node messages between engine instances. It forwards intra-node messages directly between local engines, and sends and receives inter-node messages via the Transport engine. It makes routing decisions based on the DestinationIdentity in EngineMessage headers, and retrieves routing information for identities from the Network Identity Store engine.

State

RoutingTable

The router maintains a routing table that associates message destination identities with either a local engine address, a list of local engines subscribed to a pub/sub topic, a peer identity, a relay identity, or a domain identity.

The routing table is populated by lookups from the Network Identity Store (NIS) engine, and updated when the corresponding record changes in NIS, which the Router learns about by subscribing to IdentityUpdated notifications.

list<RoutingTableEntry>

Messages received

EngineMessage

A message sent between engine instances (both local & remote).

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:

EngineMessage

P2PMessage

RelayMessage

DomainRequest

P2PMessage

A signed message sent between peers.

Reception:

P2PMessageV1

Record with fields:

• src: NodeIdentity

Source peer

• dst: NodeIdentity

Destination peer

• msg: enum { EngineMessageV1, RelayMessageV1 }

Encapsulated message

• sig: Signature

Signature over the above fields by src

Triggers:

EngineMessage

RelayMessage

A RelayMessage is used to relay an encrypted EngineMessage via multiple routing hops. It is sent between two nodes and encapsulates either an EngineMessage or another RelayMessage.

Reception:

RelayMessageV1

Record with fields:

• src: NodeIdentity

Source Node ID

• dst: NodeIdentity

Destination Node ID

• tprefs: Option<TransportPrefs>

Transport preferences for outgoing messages

• expiry: Option

Expiry time for outgoing messages

• msg: Vec

Encrypted and padded EngineMessageV1 or RelayMessageV1

• sig: Signature

Signature over the above fields by src

Triggers:

EngineMessage

TopicCreateRequest

Create a pub/sub topic and start accepting subscriptions to it.

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:

TopicCreateResponseV1

Result

TopicDeleteRequest

Delete a pub/sub topic and remove all subscribers.

The request must come from the same engine that created the topic.

Reception:

TopicDeleteRequestV1

Record with fields:

• topic: TopicIdentity Pub/sub topic identity.

• scope: RoutingScope Whether the topic should be stopped being advertised on the network.

Triggers:

TopicDeleteResponseV1

Result

TopicSubRequest

Subscription request for a pub/sub topic.

Reception:

TopicSubRequestV1

Record with fields:

• topic: TopicIdentity

Pub/sub topic identity

• scope: RoutingScope

Whether the subscription request is local-only or should be also sent to the network

Triggers:

TopicSubResponseV1

Result

TopicUnsubRequest

Unsubscription request for a pub/sub topic.

Reception:

TopicUnsubRequestV1

Record with fields:

• topic: TopicIdentity

Pub/sub topic identity

• scope: RoutingScope

Whether the unsubscription request is local-only or should be also sent to the network

Triggers:

TopicUnsubResponseV1

Result

Message flow

sequenceDiagram

Transport -) Router: P2PMessage
Router -) Router: EngineMessage
Router -) Any Local Engine: EngineMessage
Any Local Engine -) Router: EngineMessage
Router -) Router: EngineMessage
Router -) Transport: P2PMessage
Router -) Router: RelayMessage
Router -) DomainRouting: DomainRequest

Transport -) Router: P2PMessage
Router -) Any Local Engine: EngineMessage

Router -) Router: RelayMessage
Router -) Router: EngineMessage

Any Local Engine ->>+ Router: TopicCreateRequest
Router ->>+ PubSub: StartAdvertRequest
PubSub -->>- Router: StartAdvertResponse
Router -->>- Any Local Engine: TopicCreateResponse

Any Local Engine ->>+ Router: TopicDeleteRequest
Router ->>+ PubSub: StopAdvertRequest
PubSub -->>- Router: StopAdvertResponse
Router -->>- Any Local Engine: TopicDeleteResponse

Any Local Engine ->>+ Router: TopicCreateRequest
Router ->>+ PubSub: SubscribeRequest
PubSub -->>- Router: SubscribeResponse
Router -->>- Any Local Engine: TopicCreateResponse

Any Local Engine ->>+ Router: TopicUnsubRequest
Router ->>+ PubSub: UnsubscribeRequest
PubSub -->>- Router: UnsubscribeResponse
Router -->>- Any Local Engine: TopicUnsubResponse