EngineMessage¶
Purpose¶
A message sent between engine instances (both local & remote).
Type¶
Reception:
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:
Behaviour¶
When the router receives an EngineMessage from a local engine instance, it processes it the following way:
-
It looks up
dst
, the DestinationIdentity in the routing table: -
If not found, it sends a LookupIdentityRequest with the destination address to the Network Identity Store engine.
- If the LookupIdentityResponse returns a result, it is added to the routing table, and the process continues with the next step.
-
If a route is found, the EngineMessage is processed the following way, depending on the type of DestinationIdentity:
-
Engine (EngineIdentity): unicast message to a local engine
- The Router forwards the EngineMessage directly to the destination engine
-
Node (NodeIdentity): unicast message to a remote node
- The Router wraps the EngineMessage in a P2PMessage with the destination set to the remote node's identity, and the source set to the local node's identity (which equals to the engine instance identity of the Router), then signs the message with its identity key, and forwards it to the Transport engine for delivery over the network.
-
Topic (TopicIdentity): multicast message to a local pub/sub topic
- The Router forwards the Message to all local engines subscribed to the multicast group, which might include the PubSub engine that is responsible for remote delivery over a P2P publish-subscribe protocol.
-
(cont.)
-
Relay (NodeIdentity): relayed message via another node
- The Router wraps the EngineMessage in a RelayMessage with the destination set to the external identity from the routing table, the source set to the local node identity, and signs it with its identity key.
- The Router then wraps the RelayMessage in a P2PMessage and sends it to Transport for delivery over the network.
-
Domain (DomainIdentity): anycast message to a domain
- The Router wraps the EngineMessage in a DomainRequest with the destination set to the domain's identity and the source set to the local node identity.
- The Router then sends the DomainRequest to the Domain Routing engine.
- If no route is found, the message is dropped.
When processing the EngineMessage, the given RoutingPrefs and RoutingScope is respected.
Note
The router subscribes to IdentityUpdated notifications of the Network Identity Store engine, in order to keep addresses in the routing table up to date.
Message flow¶
sequenceDiagram
%% --8<-- [start:sequence]
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
%% --8<-- [end:sequence]
(Wiki) links on this page
- EngineMessageV1
- EngineIdentity
- DestinationIdentity
- P2PMessage to Transport
- TransportMessage
- RoutingPrefs
- TransportPrefs
- EngineMessage
- P2PMessage
- RelayMessage
- DestinationIdentity
- LookupIdentityRequest
- Network Identity Store
- LookupIdentityRequest
- DestinationIdentity
- EngineIdentity
- NodeIdentity
- P2PMessage
- Transport
- TopicIdentity
- PubSub
- NodeIdentity
- RelayMessage
- RelayMessage
- P2PMessage
- Transport
- DomainIdentity
- RoutingPrefs
- RoutingScope
- IdentityUpdated
- Network Identity Store