Mycelium RPC Client

This is a V language client for the Mycelium mesh networking system, implementing the JSON-RPC API specification for administrative operations.

Overview

Mycelium is a mesh networking system that creates secure, encrypted connections between nodes. This client provides a comprehensive API to interact with Mycelium nodes via their JSON-RPC interface for administrative tasks such as:

• Node information retrieval
• Peer management
• Routing information
• Message operations
• Topic management

Features

• Complete implementation of all methods in the Mycelium JSON-RPC specification
• Type-safe API with proper error handling
• HTTP transport support
• Comprehensive documentation
• Example code for all operations

Usage

Basic Example

import freeflowuniverse.herolib.clients.mycelium_rpc

// Create a new client
mut client := mycelium_rpc.new_client(
    name: 'my_client'
    url: 'http://localhost:8990'
)!

// Get node information
info := client.get_info()!
println('Node Subnet: ${info.node_subnet}')
println('Node Public Key: ${info.node_pubkey}')

// List peers
peers := client.get_peers()!
for peer in peers {
    println('Peer: ${peer.endpoint.proto}://${peer.endpoint.socket_addr}')
    println('State: ${peer.connection_state}')
}

Configuration

The client can be configured with:

• name: Client instance name (default: 'default')
• url: Mycelium node API URL (default: 'http://localhost:8990')

Available Methods

Admin Methods

• get_info() - Get general information about the node
• get_peers() - List known peers
• add_peer(endpoint) - Add a new peer
• delete_peer(endpoint) - Remove an existing peer
• get_public_key_from_ip(ip) - Get public key from node IP

Routing Methods

• get_selected_routes() - List all selected routes
• get_fallback_routes() - List all active fallback routes
• get_queried_subnets() - List currently queried subnets
• get_no_route_entries() - List subnets marked as no route

Message Methods

• pop_message(peek, timeout, topic) - Get message from inbound queue
• push_message(message, reply_timeout) - Submit new message to system
• push_message_reply(id, message) - Reply to a message
• get_message_info(id) - Get status of an outbound message

Topic Management Methods

• get_default_topic_action() - Get default topic action
• set_default_topic_action(accept) - Set default topic action
• get_topics() - Get all configured topics
• add_topic(topic) - Add new topic to whitelist
• remove_topic(topic) - Remove topic from whitelist
• get_topic_sources(topic) - Get sources for a topic
• add_topic_source(topic, subnet) - Add source to topic
• remove_topic_source(topic, subnet) - Remove source from topic
• get_topic_forward_socket(topic) - Get forward socket for topic
• set_topic_forward_socket(topic, path) - Set forward socket for topic
• remove_topic_forward_socket(topic) - Remove forward socket for topic

Data Types

Info

struct Info {
    node_subnet string // The subnet owned by the node
    node_pubkey string // The public key of the node (hex encoded)
}

PeerStats

struct PeerStats {
    endpoint         Endpoint // Peer endpoint
    peer_type        string   // How we know about this peer
    connection_state string   // Current state of connection
    tx_bytes         i64      // Bytes transmitted to this peer
    rx_bytes         i64      // Bytes received from this peer
}

InboundMessage

struct InboundMessage {
    id      string // Message ID (hex encoded)
    src_ip  string // Sender overlay IP address
    src_pk  string // Sender public key (hex encoded)
    dst_ip  string // Receiver overlay IP address
    dst_pk  string // Receiver public key (hex encoded)
    topic   string // Optional message topic (base64 encoded)
    payload string // Message payload (base64 encoded)
}

Examples

See examples/clients/mycelium_rpc.vsh for a comprehensive example that demonstrates:

• Node information retrieval
• Peer listing and management
• Routing information
• Topic management
• Message operations
• Error handling

Requirements

• V language compiler
• Mycelium node running with API enabled
• Network connectivity to the Mycelium node

Running the Example

##v run examples/clients/mycelium_rpc.vsh

The example will:1. Install Mycelium if needed2. Start a Mycelium node with API enabled3. Demonstrate various RPC operations4. Clean up resources on exit

Error Handling

All methods return Result types and should be handled appropriately:

info := client.get_info() or {
    println('Error getting node info: ${err}')
    return
}

Notes

• The client uses HTTP transport to communicate with the Mycelium node
• All JSON field names are properly mapped using V's @[json: 'field_name'] attributes
• The client is thread-safe and can be used concurrently
• Message operations require multiple connected Mycelium nodes to be meaningful

License

This client follows the same license as the HeroLib project.

fn delete(args_ ArgsGet) !

fn exists(args_ ArgsGet) !bool

does the config exists?

fn get(args_ ArgsGet) !&MyceliumRPC

fn heroscript_dumps(obj MyceliumRPC) !string

///////////NORMALLY NO NEED TO TOUCH

fn heroscript_loads(heroscript string) !MyceliumRPC

fn new_client(args NewClientArgs) !&MyceliumRPC

fn play(args_ PlayArgs) !

fn set(o MyceliumRPC) !

register the config for the future

fn switch(name string)

switch instance to be used for mycelium_rpc

struct ArgsGet {
pub mut:
	name string
}

///////FACTORY

struct DefaultConfigArgs {
	instance string = 'default'
}

helpers

struct Endpoint {
pub mut:
	proto       string @[json: 'proto']      // Protocol used (tcp, quic)
	socket_addr string @[json: 'socketAddr'] // The socket address used
}

Endpoint represents identification to connect to a peer

struct InboundMessage {
pub mut:
	id      string @[json: 'id']      // Id of the message, hex encoded (16 chars)
	src_ip  string @[json: 'srcIp']   // Sender overlay IP address (IPv6)
	src_pk  string @[json: 'srcPk']   // Sender public key, hex encoded (64 chars)
	dst_ip  string @[json: 'dstIp']   // Receiver overlay IP address (IPv6)
	dst_pk  string @[json: 'dstPk']   // Receiver public key, hex encoded (64 chars)
	topic   string @[json: 'topic']   // Optional message topic (base64 encoded, 0-340 chars)
	payload string @[json: 'payload'] // Message payload, base64 encoded
}

InboundMessage represents a message received by the system

struct Info {
pub mut:
	node_subnet string @[json: 'nodeSubnet'] // The subnet owned by the node and advertised to peers
	node_pubkey string @[json: 'nodePubkey'] // The public key of the node (hex encoded, 64 chars)
}

Info represents general information about a node

struct MessageDestination {
pub mut:
	ip string // Target IP of the message (IPv6)
	pk string // Hex encoded public key of the target node (64 chars)
}

MessageDestination represents the destination for a message

struct MessageStatusResponse {
pub mut:
	dst      string @[json: 'dst']      // IP address of the receiving node (IPv6)
	state    string @[json: 'state']    // Transmission state
	created  i64    @[json: 'created']  // Unix timestamp of when this message was created
	deadline i64    @[json: 'deadline'] // Unix timestamp of when this message will expire
	msg_len  int    @[json: 'msgLen']   // Length of the message in bytes
}

MessageStatusResponse represents information about an outbound message

struct MyceliumRPC {
pub mut:
	name       string = 'default'
	url        string = default_url // RPC server URL
	rpc_client ?&jsonrpc.Client @[skip]
}

THIS THE THE SOURCE OF THE INFORMATION OF THIS FILE, HERE WE HAVE THE CONFIG OBJECT CONFIGURED AND MODELLED

fn (mut c MyceliumRPC) add_peer(endpoint string) !bool

add_peer adds a new peer identified by the provided endpoint

fn (mut c MyceliumRPC) add_topic(topic string) !bool

add_topic adds a new topic to the system's whitelist

fn (mut c MyceliumRPC) add_topic_source(topic string, subnet string) !bool

add_topic_source adds a source (subnet) that is allowed to send messages for a specific topic

fn (mut c MyceliumRPC) delete_peer(endpoint string) !bool

delete_peer removes an existing peer identified by the provided endpoint

fn (mut c MyceliumRPC) get_default_topic_action() !bool

get_default_topic_action gets the default topic action

fn (mut c MyceliumRPC) get_fallback_routes() ![]Route

get_fallback_routes lists all active fallback routes

fn (mut c MyceliumRPC) get_info() !Info

get_info gets general info about the node

fn (mut c MyceliumRPC) get_message_info(id string) !MessageStatusResponse

get_message_info gets the status of an outbound message

fn (mut c MyceliumRPC) get_no_route_entries() ![]NoRouteSubnet

get_no_route_entries lists all subnets which are explicitly marked as no route

fn (mut c MyceliumRPC) get_peers() ![]PeerStats

get_peers lists known peers

fn (mut c MyceliumRPC) get_public_key_from_ip(mycelium_ip string) !PublicKeyResponse

get_public_key_from_ip gets the pubkey from node ip

fn (mut c MyceliumRPC) get_queried_subnets() ![]QueriedSubnet

get_queried_subnets lists all currently queried subnets

fn (mut c MyceliumRPC) get_selected_routes() ![]Route

get_selected_routes lists all selected routes

fn (mut c MyceliumRPC) get_topic_forward_socket(topic string) !string

get_topic_forward_socket gets the forward socket for a topic

fn (mut c MyceliumRPC) get_topic_sources(topic string) ![]string

get_topic_sources gets all sources (subnets) that are allowed to send messages for a specific topic

fn (mut c MyceliumRPC) get_topics() ![]string

get_topics gets all configured topics

fn (mut c MyceliumRPC) pop_message(peek bool, timeout i64, topic string) !InboundMessage

pop_message gets a message from the inbound message queue

fn (mut c MyceliumRPC) push_message(message PushMessageBody, reply_timeout i64) !string

push_message submits a new message to the system

fn (mut c MyceliumRPC) push_message_reply(id string, message PushMessageBody) !bool

push_message_reply replies to a message with the given ID

fn (mut c MyceliumRPC) remove_topic(topic string) !bool

remove_topic removes a topic from the system's whitelist

fn (mut c MyceliumRPC) remove_topic_forward_socket(topic string) !bool

remove_topic_forward_socket removes the socket path where messages for a specific topic are forwarded to

fn (mut c MyceliumRPC) remove_topic_source(topic string, subnet string) !bool

remove_topic_source removes a source (subnet) that is allowed to send messages for a specific topic

fn (mut c MyceliumRPC) set_default_topic_action(accept bool) !bool

set_default_topic_action sets the default topic action

fn (mut c MyceliumRPC) set_topic_forward_socket(topic string, socket_path string) !bool

set_topic_forward_socket sets the socket path where messages for a specific topic should be forwarded to

struct NewClientArgs {
pub mut:
	name string = 'default'
	url  string = default_url
}

Factory function to create a new MyceliumRPC client instance

struct NoRouteSubnet {
pub mut:
	subnet     string // The overlay subnet which is marked
	expiration string // Amount of seconds until the entry expires
}

NoRouteSubnet represents information about a subnet marked as no route

struct PeerStats {
pub mut:
	endpoint         Endpoint @[json: 'endpoint']        // Peer endpoint
	peer_type        string   @[json: 'type']            // How we know about this peer (static, inbound, linkLocalDiscovery)
	connection_state string   @[json: 'connectionState'] // Current state of connection (alive, connecting, dead)
	tx_bytes         i64      @[json: 'txBytes']         // Bytes transmitted to this peer
	rx_bytes         i64      @[json: 'rxBytes']         // Bytes received from this peer
}

PeerStats represents info about a peer

struct PlayArgs {
pub mut:
	heroscript string // if filled in then plbook will be made out of it
	plbook     ?playbook.PlayBook
	reset      bool
}

struct PopMessageParams {
pub mut:
	peek    ?bool   // Whether to peek the message or not
	timeout ?i64    // Amount of seconds to wait for a message
	topic   ?string // Optional filter for loading messages
}

PopMessageParams represents parameters for pop_message method

struct PublicKeyResponse {
pub mut:
	node_pub_key string @[json: 'NodePubKey'] // Public key (hex encoded, 64 chars)
}

PublicKeyResponse represents public key requested based on a node's IP

struct PushMessageBody {
pub mut:
	dst     MessageDestination // Message destination
	topic   string             // Optional message topic (base64 encoded, 0-340 chars)
	payload string             // Message to send, base64 encoded
}

PushMessageBody represents a message to send to a given receiver

struct PushMessageParams {
pub mut:
	message       PushMessageBody // The message to send
	reply_timeout ?i64            // Amount of seconds to wait for a reply
}

PushMessageParams represents parameters for push_message method

struct PushMessageReplyParams {
pub mut:
	id      string          // The ID of the message to reply to
	message PushMessageBody // The reply message
}

PushMessageReplyParams represents parameters for push_message_reply method

struct PushMessageResponseId {
pub mut:
	id string // Id of the message, hex encoded (16 chars)
}

PushMessageResponseId represents the ID generated for a message after pushing

struct QueriedSubnet {
pub mut:
	subnet     string // The overlay subnet which we are currently querying
	expiration string // Amount of seconds until the query expires
}

QueriedSubnet represents information about a subnet currently being queried

struct Route {
pub mut:
	subnet   string @[json: 'subnet']  // The overlay subnet for which this is the route
	next_hop string @[json: 'nextHop'] // Way to identify the next hop of the route
	metric   string @[json: 'metric']  // The metric of the route (can be int or "infinite")
	seqno    int    @[json: 'seqno']   // Sequence number advertised with this route
}

Route represents information about a route

struct SetDefaultTopicActionParams {
pub mut:
	accept bool // Whether to accept unconfigured topics by default
}

SetDefaultTopicActionParams represents parameters for set_default_topic_action method