herocode/herolib_rust
12
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add mycelium package to workspace
Some checks are pending
Rhai Tests / Run Rhai Tests (push) Waiting to run
Details

Browse Source 
- Add the `mycelium` package to the workspace members.
- Add `sal-mycelium` dependency to `Cargo.toml`.
- Update MONOREPO_CONVERSION_PLAN.md to reflect the addition
  and completion of the mycelium package.
This commit is contained in:
Mahmoud-Emad
2025-06-19 12:11:55 +03:00
parent 3e617c2489
commit 4a8d3bfd24
13 changed files with 1226 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/lib.rs
View File

@@ -38,7 +38,7 @@ pub type Result<T> = std::result::Result<T, Error>;
// Re-export modules
pub mod cmd;
pub mod mycelium;
pub use sal_mycelium as mycelium;
pub mod net;
pub mod os;
pub mod postgresclient;

126
src/mycelium/README.md
View File

@@ -1,126 +0,0 @@
# SAL Mycelium Module (`sal::mycelium`)
## Overview
The `sal::mycelium` module provides a client interface for interacting with a [Mycelium](https://mycelium.com/) 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
```rhai
// 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.

313
src/mycelium/mod.rs
View File

@@ -1,313 +0,0 @@
use base64::{
engine::general_purpose,
Engine as _,
};
use reqwest::Client;
use serde_json::Value;
use std::time::Duration;
/// Get information about the Mycelium node
///
/// # Arguments
///
/// * `api_url` - The URL of the Mycelium API
///
/// # Returns
///
/// * `Result<Value, String>` - The node information as a JSON value, or an error message
pub async fn get_node_info(api_url: &str) -> Result<Value, String> {
let client = Client::new();
let url = format!("{}/api/v1/admin", api_url);
let response = client
.get(&url)
.send()
.await
.map_err(|e| format!("Failed to send request: {}", e))?;
let status = response.status();
if !status.is_success() {
return Err(format!("Request failed with status: {}", status));
}
let result: Value = response
.json()
.await
.map_err(|e| format!("Failed to parse response: {}", e))?;
Ok(result)
}
/// List all peers connected to the Mycelium node
///
/// # Arguments
///
/// * `api_url` - The URL of the Mycelium API
///
/// # Returns
///
/// * `Result<Value, String>` - The list of peers as a JSON value, or an error message
pub async fn list_peers(api_url: &str) -> Result<Value, String> {
let client = Client::new();
let url = format!("{}/api/v1/admin/peers", api_url);
let response = client
.get(&url)
.send()
.await
.map_err(|e| format!("Failed to send request: {}", e))?;
let status = response.status();
if !status.is_success() {
return Err(format!("Request failed with status: {}", status));
}
let result: Value = response
.json()
.await
.map_err(|e| format!("Failed to parse response: {}", e))?;
Ok(result)
}
/// Add a new peer to the Mycelium node
///
/// # Arguments
///
/// * `api_url` - The URL of the Mycelium API
/// * `peer_address` - The address of the peer to add
///
/// # Returns
///
/// * `Result<Value, String>` - The result of the operation as a JSON value, or an error message
pub async fn add_peer(api_url: &str, peer_address: &str) -> Result<Value, String> {
let client = Client::new();
let url = format!("{}/api/v1/admin/peers", api_url);
let response = client
.post(&url)
.json(&serde_json::json!({
"endpoint": peer_address
}))
.send()
.await
.map_err(|e| format!("Failed to send request: {}", e))?;
let status = response.status();
if status == reqwest::StatusCode::NO_CONTENT {
// Successfully added, but no content to parse
return Ok(serde_json::json!({"success": true}));
}
if !status.is_success() {
return Err(format!("Request failed with status: {}", status));
}
// For other success statuses that might have a body
let result: Value = response
.json()
.await
.map_err(|e| format!("Failed to parse response: {}", e))?;
Ok(result)
}
/// Remove a peer from the Mycelium node
///
/// # Arguments
///
/// * `api_url` - The URL of the Mycelium API
/// * `peer_id` - The ID of the peer to remove
///
/// # Returns
///
/// * `Result<Value, String>` - The result of the operation as a JSON value, or an error message
pub async fn remove_peer(api_url: &str, peer_id: &str) -> Result<Value, String> {
let client = Client::new();
let peer_id_url_encoded = urlencoding::encode(peer_id);
let url = format!("{}/api/v1/admin/peers/{}", api_url, peer_id_url_encoded);
let response = client
.delete(&url)
.send()
.await
.map_err(|e| format!("Failed to send request: {}", e))?;
let status = response.status();
if status == reqwest::StatusCode::NO_CONTENT {
// Successfully removed, but no content to parse
return Ok(serde_json::json!({"success": true}));
}
if !status.is_success() {
return Err(format!("Request failed with status: {}", status));
}
let result: Value = response
.json()
.await
.map_err(|e| format!("Failed to parse response: {}", e))?;
Ok(result)
}
/// List all selected routes in the Mycelium node
///
/// # Arguments
///
/// * `api_url` - The URL of the Mycelium API
///
/// # Returns
///
/// * `Result<Value, String>` - The list of selected routes as a JSON value, or an error message
pub async fn list_selected_routes(api_url: &str) -> Result<Value, String> {
let client = Client::new();
let url = format!("{}/api/v1/admin/routes/selected", api_url);
let response = client
.get(&url)
.send()
.await
.map_err(|e| format!("Failed to send request: {}", e))?;
let status = response.status();
if !status.is_success() {
return Err(format!("Request failed with status: {}", status));
}
let result: Value = response
.json()
.await
.map_err(|e| format!("Failed to parse response: {}", e))?;
Ok(result)
}
/// List all fallback routes in the Mycelium node
///
/// # Arguments
///
/// * `api_url` - The URL of the Mycelium API
///
/// # Returns
///
/// * `Result<Value, String>` - The list of fallback routes as a JSON value, or an error message
pub async fn list_fallback_routes(api_url: &str) -> Result<Value, String> {
let client = Client::new();
let url = format!("{}/api/v1/admin/routes/fallback", api_url);
let response = client
.get(&url)
.send()
.await
.map_err(|e| format!("Failed to send request: {}", e))?;
let status = response.status();
if !status.is_success() {
return Err(format!("Request failed with status: {}", status));
}
let result: Value = response
.json()
.await
.map_err(|e| format!("Failed to parse response: {}", e))?;
Ok(result)
}
/// Send a message to a destination via the Mycelium node
///
/// # Arguments
///
/// * `api_url` - The URL of the Mycelium API
/// * `destination` - The destination address
/// * `topic` - The message topic
/// * `message` - The message content
/// * `reply_deadline` - The deadline in seconds; pass `-1` to indicate we do not want to wait on a reply
///
/// # Returns
///
/// * `Result<Value, String>` - The result of the operation as a JSON value, or an error message
pub async fn send_message(
api_url: &str,
destination: &str,
topic: &str,
message: &str,
reply_deadline: Option<Duration>, // This is passed in URL query
) -> Result<Value, String> {
let client = Client::new();
let url = format!("{}/api/v1/messages", api_url);
let mut request = client.post(&url);
if let Some(deadline) = reply_deadline {
request = request.query(&[("reply_timeout", deadline.as_secs())]);
}
let response = request
.json(&serde_json::json!({
"dst": { "ip": destination },
"topic": general_purpose::STANDARD.encode(topic),
"payload": general_purpose::STANDARD.encode(message)
}))
.send()
.await
.map_err(|e| format!("Failed to send request: {}", e))?;
let status = response.status();
if !status.is_success() {
return Err(format!("Request failed with status: {}", status));
}
let result: Value = response
.json()
.await
.map_err(|e| format!("Failed to parse response: {}", e))?;
Ok(result)
}
/// Receive messages from a topic via the Mycelium node
///
/// # Arguments
///
/// * `api_url` - The URL of the Mycelium API
/// * `topic` - The message topic
/// * `wait_deadline` - Time we wait for receiving a message
///
/// # Returns
///
/// * `Result<Value, String>` - The received messages as a JSON value, or an error message
pub async fn receive_messages(
api_url: &str,
topic: &str,
wait_deadline: Option<Duration>,
) -> Result<Value, String> {
let client = Client::new();
let url = format!("{}/api/v1/messages", api_url);
let mut request = client.get(&url);
if let Some(deadline) = wait_deadline {
request = request.query(&[
("topic", general_purpose::STANDARD.encode(topic)),
("timeout", deadline.as_secs().to_string()),
])
} else {
request = request.query(&[("topic", general_purpose::STANDARD.encode(topic))])
};
let response = request
.send()
.await
.map_err(|e| format!("Failed to send request: {}", e))?;
let status = response.status();
if !status.is_success() {
return Err(format!("Request failed with status: {}", status));
}
let result: Value = response
.json()
.await
.map_err(|e| format!("Failed to parse response: {}", e))?;
Ok(result)
}

5
src/rhai/mod.rs
View File

@@ -6,7 +6,6 @@
mod buildah;
mod core;
pub mod error;
mod mycelium;
mod nerdctl;
mod os;
mod platform;
@@ -99,7 +98,7 @@ pub use sal_git::{GitRepo, GitTree};
pub use zinit::register_zinit_module;
// Re-export mycelium module
pub use mycelium::register_mycelium_module;
pub use sal_mycelium::rhai::register_mycelium_module;
// Re-export text module
pub use text::register_text_module;
@@ -164,7 +163,7 @@ pub fn register(engine: &mut Engine) -> Result<(), Box<rhai::EvalAltResult>> {
zinit::register_zinit_module(engine)?;
// Register Mycelium module functions
mycelium::register_mycelium_module(engine)?;
sal_mycelium::rhai::register_mycelium_module(engine)?;
// Register Text module functions
text::register_text_module(engine)?;

248
src/rhai/mycelium.rs
View File

@@ -1,248 +0,0 @@
//! Rhai wrappers for Mycelium client module functions
//!
//! This module provides Rhai wrappers for the functions in the Mycelium client module.
use std::time::Duration;
use rhai::{Engine, EvalAltResult, Array, Dynamic, Map};
use crate::mycelium as client;
use tokio::runtime::Runtime;
use serde_json::Value;
use rhai::Position;
/// Register Mycelium module functions with the Rhai engine
///
/// # Arguments
///
/// * `engine` - The Rhai engine to register the functions with
///
/// # Returns
///
/// * `Result<(), Box<EvalAltResult>>` - Ok if registration was successful, Err otherwise
pub fn register_mycelium_module(engine: &mut Engine) -> Result<(), Box<EvalAltResult>> {
// Register Mycelium client functions
engine.register_fn("mycelium_get_node_info", mycelium_get_node_info);
engine.register_fn("mycelium_list_peers", mycelium_list_peers);
engine.register_fn("mycelium_add_peer", mycelium_add_peer);
engine.register_fn("mycelium_remove_peer", mycelium_remove_peer);
engine.register_fn("mycelium_list_selected_routes", mycelium_list_selected_routes);
engine.register_fn("mycelium_list_fallback_routes", mycelium_list_fallback_routes);
engine.register_fn("mycelium_send_message", mycelium_send_message);
engine.register_fn("mycelium_receive_messages", mycelium_receive_messages);
Ok(())
}
// Helper function to get a runtime
fn get_runtime() -> Result<Runtime, Box<EvalAltResult>> {
tokio::runtime::Runtime::new().map_err(|e| {
Box::new(EvalAltResult::ErrorRuntime(
format!("Failed to create Tokio runtime: {}", e).into(),
rhai::Position::NONE
))
})
}
// Helper function to convert serde_json::Value to rhai::Dynamic
fn value_to_dynamic(value: Value) -> Dynamic {
match value {
Value::Null => Dynamic::UNIT,
Value::Bool(b) => Dynamic::from(b),
Value::Number(n) => {
if let Some(i) = n.as_i64() {
Dynamic::from(i)
} else if let Some(f) = n.as_f64() {
Dynamic::from(f)
} else {
Dynamic::from(n.to_string())
}
},
Value::String(s) => Dynamic::from(s),
Value::Array(arr) => {
let mut rhai_arr = Array::new();
for item in arr {
rhai_arr.push(value_to_dynamic(item));
}
Dynamic::from(rhai_arr)
},
Value::Object(map) => {
let mut rhai_map = Map::new();
for (k, v) in map {
rhai_map.insert(k.into(), value_to_dynamic(v));
}
Dynamic::from_map(rhai_map)
}
}
}
//
// Mycelium Client Function Wrappers
//
/// Wrapper for mycelium::get_node_info
///
/// Gets information about the Mycelium node.
pub fn mycelium_get_node_info(api_url: &str) -> Result<Dynamic, Box<EvalAltResult>> {
let rt = get_runtime()?;
let result = rt.block_on(async { client::get_node_info(api_url).await });
let node_info = result.map_err(|e| {
Box::new(EvalAltResult::ErrorRuntime(
format!("Mycelium error: {}", e).into(),
Position::NONE,
))
})?;
Ok(value_to_dynamic(node_info))
}
/// Wrapper for mycelium::list_peers
///
/// Lists all peers connected to the Mycelium node.
pub fn mycelium_list_peers(api_url: &str) -> Result<Dynamic, Box<EvalAltResult>> {
let rt = get_runtime()?;
let result = rt.block_on(async { client::list_peers(api_url).await });
let peers = result.map_err(|e| {
Box::new(EvalAltResult::ErrorRuntime(
format!("Mycelium error: {}", e).into(),
Position::NONE,
))
})?;
Ok(value_to_dynamic(peers))
}
/// Wrapper for mycelium::add_peer
///
/// Adds a new peer to the Mycelium node.
pub fn mycelium_add_peer(api_url: &str, peer_address: &str) -> Result<Dynamic, Box<EvalAltResult>> {
let rt = get_runtime()?;
let result = rt.block_on(async { client::add_peer(api_url, peer_address).await });
let response = result.map_err(|e| {
Box::new(EvalAltResult::ErrorRuntime(
format!("Mycelium error: {}", e).into(),
Position::NONE,
))
})?;
Ok(value_to_dynamic(response))
}
/// Wrapper for mycelium::remove_peer
///
/// Removes a peer from the Mycelium node.
pub fn mycelium_remove_peer(api_url: &str, peer_id: &str) -> Result<Dynamic, Box<EvalAltResult>> {
let rt = get_runtime()?;
let result = rt.block_on(async { client::remove_peer(api_url, peer_id).await });
let response = result.map_err(|e| {
Box::new(EvalAltResult::ErrorRuntime(
format!("Mycelium error: {}", e).into(),
Position::NONE,
))
})?;
Ok(value_to_dynamic(response))
}
/// Wrapper for mycelium::list_selected_routes
///
/// Lists all selected routes in the Mycelium node.
pub fn mycelium_list_selected_routes(api_url: &str) -> Result<Dynamic, Box<EvalAltResult>> {
let rt = get_runtime()?;
let result = rt.block_on(async { client::list_selected_routes(api_url).await });
let routes = result.map_err(|e| {
Box::new(EvalAltResult::ErrorRuntime(
format!("Mycelium error: {}", e).into(),
Position::NONE,
))
})?;
Ok(value_to_dynamic(routes))
}
/// Wrapper for mycelium::list_fallback_routes
///
/// Lists all fallback routes in the Mycelium node.
pub fn mycelium_list_fallback_routes(api_url: &str) -> Result<Dynamic, Box<EvalAltResult>> {
let rt = get_runtime()?;
let result = rt.block_on(async { client::list_fallback_routes(api_url).await });
let routes = result.map_err(|e| {
Box::new(EvalAltResult::ErrorRuntime(
format!("Mycelium error: {}", e).into(),
Position::NONE,
))
})?;
Ok(value_to_dynamic(routes))
}
/// Wrapper for mycelium::send_message
///
/// Sends a message to a destination via the Mycelium node.
pub fn mycelium_send_message(
api_url: &str,
destination: &str,
topic: &str,
message: &str,
reply_deadline_secs: i64,
) -> Result<Dynamic, Box<EvalAltResult>> {
let rt = get_runtime()?;
let deadline = if reply_deadline_secs < 0 {
None
} else {
Some(Duration::from_secs(reply_deadline_secs as u64))
};
let result =
rt.block_on(async { client::send_message(api_url, destination, topic, message, deadline).await });
let response = result.map_err(|e| {
Box::new(EvalAltResult::ErrorRuntime(
format!("Mycelium error: {}", e).into(),
Position::NONE,
))
})?;
Ok(value_to_dynamic(response))
}
/// Wrapper for mycelium::receive_messages
///
/// Receives messages from a topic via the Mycelium node.
pub fn mycelium_receive_messages(
api_url: &str,
topic: &str,
wait_deadline_secs: i64,
) -> Result<Dynamic, Box<EvalAltResult>> {
let rt = get_runtime()?;
let deadline = if wait_deadline_secs < 0 {
None
} else {
Some(Duration::from_secs(wait_deadline_secs as u64))
};
let result = rt.block_on(async { client::receive_messages(api_url, topic, deadline).await });
let messages = result.map_err(|e| {
Box::new(EvalAltResult::ErrorRuntime(
format!("Mycelium error: {}", e).into(),
Position::NONE,
))
})?;
Ok(value_to_dynamic(messages))
}