Skip to content

EngineMessage

Purpose

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

Type

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:

EngineMessage

P2PMessage

RelayMessage

DomainRequest

Behavior

When the router receives an EngineMessage from a local engine instance, it processes it the following way:

  1. It looks up dst, the DestinationIdentity in the routing table:

  2. 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.

  3. If a route is found, the EngineMessage is processed the following way, depending on the type of DestinationIdentity:

  4. Engine (EngineIdentity): unicast message to a local engine

    • The Router forwards the EngineMessage directly to the destination engine

  5. 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.

  6. 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.

  1. (cont.)

  2. 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.

  3. 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.
  1. 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]