sal/src/mycelium/README.md

SAL Mycelium Module (sal::mycelium)

Overview

The sal::mycelium module provides a client interface for interacting with a Mycelium node's HTTP API. Mycelium is a decentralized networking project, and this SAL module allows Rust applications and herodo Rhai scripts to manage and communicate over a Mycelium network.

The module enables operations such as:

• Querying node status and information.
• Managing peer connections (listing, adding, removing).
• Inspecting routing tables (selected and fallback routes).
• Sending messages to other Mycelium nodes.
• Receiving messages from subscribed topics.

All interactions with the Mycelium API are performed asynchronously.

Key Design Points

• Async HTTP Client: Leverages reqwest for asynchronous HTTP requests to the Mycelium node's API, ensuring non-blocking operations suitable for concurrent applications.
• JSON Interaction: Expects and processes JSON-formatted data from the Mycelium API, using serde_json::Value for flexible data handling.
• Base64 Encoding: Message payloads and topics are Base64 encoded/decoded when communicating with the Mycelium API, as per its expected format.
• Rhai Scriptability: All core functionalities are exposed to Rhai scripts via herodo through the sal::rhai::mycelium bridge. This allows for easy automation of Mycelium network tasks.
• Error Handling: Provides clear error messages, converting HTTP and parsing errors into String results in Rust, which are then translated to EvalAltResult for Rhai.
• Tokio Runtime Management: For Rhai script execution, a Tokio runtime is managed internally by the wrapper functions to bridge Rhai's synchronous world with the asynchronous Rust client.

Rhai Scripting with herodo

The sal::mycelium module can be scripted using herodo. The following functions are available in Rhai, typically prefixed with mycelium_:

All functions take api_url (String) as their first argument, which is the base URL of the Mycelium node's HTTP API (e.g., "http://localhost:7777").

• mycelium_get_node_info(api_url: String) -> Dynamic

  • Retrieves general information about the Mycelium node.
  • Returns a dynamic object (map) representing the JSON response.

• mycelium_list_peers(api_url: String) -> Dynamic

  • Lists all peers currently connected to the node.
  • Returns a dynamic array of peer information objects.

• mycelium_add_peer(api_url: String, peer_address: String) -> Dynamic

  • Adds a new peer to the node.
  • peer_address: The endpoint address of the peer to add (e.g., "tcp://192.168.1.10:7778").
  • Returns a success status or an error.

• mycelium_remove_peer(api_url: String, peer_id: String) -> Dynamic

  • Removes a peer from the node.
  • peer_id: The ID of the peer to remove.
  • Returns a success status or an error.

• mycelium_list_selected_routes(api_url: String) -> Dynamic

  • Lists the currently selected (active) routes in the node's routing table.
  • Returns a dynamic array of route objects.

• mycelium_list_fallback_routes(api_url: String) -> Dynamic

  • Lists the fallback routes in the node's routing table.
  • Returns a dynamic array of route objects.

• mycelium_send_message(api_url: String, destination: String, topic: String, message: String, reply_deadline_secs: Int) -> Dynamic

  • Sends a message to a specific destination over the Mycelium network.
  • destination: The Mycelium address of the recipient node.
  • topic: The topic for the message (will be Base64 encoded).
  • message: The content of the message (will be Base64 encoded).
  • reply_deadline_secs: An integer specifying the timeout in seconds to wait for a reply. If negative, no reply is waited for.
  • Returns a response from the Mycelium API, potentially including a reply if waited for.

• mycelium_receive_messages(api_url: String, topic: String, wait_deadline_secs: Int) -> Dynamic

  • Subscribes to a topic and waits for messages.
  • topic: The topic to subscribe to (will be Base64 encoded).
  • wait_deadline_secs: An integer specifying the maximum time in seconds to wait for a message. If negative, waits indefinitely (or until the API's default timeout).
  • Returns an array of received messages, or an empty array if the deadline is met before messages arrive.

Rhai Example

// Assuming a Mycelium node is running and accessible at http://localhost:7777
let api_url = "http://localhost:7777";

// Get Node Info
print("Fetching node info...");
let node_info = mycelium_get_node_info(api_url);
if node_info.is_ok() {
    print(`Node Info: ${node_info}`);
} else {
    print(`Error fetching node info: ${node_info}`);
}

// List Peers
print("\nListing peers...");
let peers = mycelium_list_peers(api_url);
if peers.is_ok() {
    print(`Peers: ${peers}`);
} else {
    print(`Error listing peers: ${peers}`);
}

// Example: Send a message (destination and topic are illustrative)
let dest_addr = "some_mycelium_destination_address"; // Replace with actual address
let msg_topic = "sal/test_topic";
let msg_content = "Hello from SAL Mycelium via Rhai!";

print(`\nSending message to '${dest_addr}' on topic '${msg_topic}'...`);
// No reply wait (deadline = -1)
let send_result = mycelium_send_message(api_url, dest_addr, msg_topic, msg_content, -1);
if send_result.is_ok() {
    print(`Send Result: ${send_result}`);
} else {
    print(`Error sending message: ${send_result}`);
}

// Example: Receive messages (topic is illustrative)
// This will block for up to 10 seconds, or until a message arrives.
print(`\nAttempting to receive messages on topic '${msg_topic}' for 10 seconds...`);
let received = mycelium_receive_messages(api_url, msg_topic, 10);
if received.is_ok() {
    if received.len() > 0 {
        print(`Received Messages: ${received}`);
    } else {
        print("No messages received within the deadline.");
    }
} else {
    print(`Error receiving messages: ${received}`);
}

print("\nMycelium Rhai script finished.");

This module facilitates integration with Mycelium networks, enabling automation of peer management, message exchange, and network monitoring through herodo scripts or direct Rust integration.