Overview

ADAPT uses message passing for communication between ADAPT nodes. Messages are requests sent by one node to another node to execute a specific transaction.

For more information about transactions, refer to the packet interface.

The function of the ADAPT message broker is to pass messages between ADAPT nodes on the specific network.

The broker maps each packet ID to an ADAPT node IP address and enables MUFL code to designate addressee nodes by packet IDs. MUFL code sends transaction requests (each containing the packet ID of the destination packet) to the message broker. In turn, the message broker translates the application layer routing (unique packet IDs) to the internet layer routing addresses (IP addresses of the ADAPT nodes) and routes the transaction to the node containing the packet. The MUFL language and your MUFL code are unaware of the actual methods used to transmit messages within the network.

The typical communication process between two ADAPT nodes is:

  1. The node containing packet A sends a registration request to the ADAPT message broker. The request contains the information about packet A running inside the node.
  2. The message broker registers packet A and stores its packet ID and the IP address of the ADAPT node where packet A is running.
  3. The node containing packet B sends a registration request to the message broker.
  4. The message broker registers packet B and stores its packet ID and the IP address of the ADAPT node where packet B is running.
  5. From your code’s perspective, packet A sends a transaction request to destination packet B using packet B’s packet ID.
  6. In actuality, ADAPT routes the transaction request through the message broker.
  7. The message broker redirects the transaction request to the corresponding node’s IP address.
  8. The node receives the transaction request from the broker and directs the transaction to destination packet B.
  9. Packet B processes the transaction request and invokes the requested transaction. The transaction request contains the packet ID of the sender (packet A), enabling the application logic of packet B to know where the request came from.

When the source and destination packets are hosted by the same node (the same wrapper), the transaction is delivered locally within the node and does not pass through the message broker. The broker is involved only when packets are in different nodes. See the ADAPT wrapper page for details.

For a more detailed overview of the process, refer to the ADAPT messaging protocol.

The message broker is not designed to be a secure component. It does not provide additional security. All transaction request messages passed to the message broker are end-to-end encrypted (depending on the application logic, but generally, MUFL provides developers with a simple way to encrypt and sign messages). Thus, even if the message broker is compromised, it does not reveal any sensitive information to an attacker.

By default the message broker holds pending messages in memory only and does not guarantee delivery, so each packet’s application logic should still include timeout requests and ensure idempotency of messages.

Persistent Pending Messages

A message addressed to a packet that is not currently connected is held by the broker as a pending message and delivered when that packet (re)registers. By default this pending queue is kept in memory and is lost if the broker restarts.

Starting the broker with the --db_path <path> option enables a persistent pending-message store backed by an on-disk SQLite database at the given path. With persistence enabled, pending messages survive a broker restart and are delivered once the destination packet registers again, and a pending message is removed from the store only after it has been successfully sent. Use this option when delivery needs to survive broker restarts.

The message broker is implemented as a TypeScript module on top of the native N-API backend (@adapt-toolkit/sdk-native).

The broker script’s TypeScript source lives at typescript/sdk/src/utilities/executables/broker.ts in the adapt-toolkit/adapt repository, and ships as broker.js inside @adapt-toolkit/sdk (dist/utilities/executables/broker.js).