EngineMessage¶
Purpose¶
A message sent between engine instances (both local & remote).
Type¶
Reception:
Record with fields:
-
src
: EngineIdentitySource engine identity
-
dst
: DestinationIdentityDestination identity
-
id
: u64Message ID: unique per
src
-dst
pairs
-
reply_to
: Optionid
of a previous message this message is in reply to
-
expiry
OptionExpiry time for outgoing messages. See P2PMessage & TransportMessage.
-
rprefs
: Option<RoutingPrefs>Routing preferences
-
tprefs
: Option<TransportPrefs>Transport preferences
-
protocol
: ProtocolProtocol & version used in
body
-
body
: VecSerialized message body
-
sig
: OptionSignature over the above fields by
src
Triggers:
DomainRequest
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 not found, it sends a LookupIdentityRequest
with the destination address to the Network Identity Store engine.
-
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]