Mycelium Client

A V client library for interacting with the Mycelium messaging system. This client provides functionality for configuring and inspecting a Mycelium node.

Components

The Mycelium integration consists of two main components:

1. Mycelium Client (this package) - For interacting with a running Mycelium node
2. Mycelium Installer (in installers/net/mycelium/) - For installing and managing Mycelium nodes

Configuration

The client can be configured either through V code or using heroscript.

V Code Configuration

import freeflowuniverse.herolib.clients.mycelium

// Get default client instance
mut client := mycelium.get()!

// Get named client instance
mut client := mycelium.get(name: 'custom')!

Core Functions

Inspect Node

Get information about the local Mycelium node:

import freeflowuniverse.herolib.clients.mycelium

// Get node info including public key and address
result := mycelium.inspect()!
println('Public Key: ${result.public_key}')
println('Address: ${result.address}')

// Get just the IP address
addr := mycelium.ipaddr()
println('IP Address: ${addr}')

Check Node Status

Check if the Mycelium node is running and reachable:

import freeflowuniverse.herolib.clients.mycelium

is_running := mycelium.check()
if is_running {
    println('Mycelium node is running and reachable')
} else {
    println('Mycelium node is not running or unreachable')
}

Sending and Receiving Messages

The client provides several functions for sending and receiving messages between nodes:

import freeflowuniverse.herolib.clients.mycelium

mut client := mycelium.get()!

// Send a message to a node by public key
// Parameters: public_key, payload, topic, wait_for_reply
msg := client.send_msg(
    'abc123...', // destination public key
    'Hello World', // message payload
    'greetings', // optional topic
    true // wait for reply
)!
println('Sent message ID: ${msg.id}')

// Receive messages
// Parameters: wait_for_message, peek_only, topic_filter
received := client.receive_msg(true, false, 'greetings')!
println('Received message from: ${received.src_pk}')
println('Message payload: ${received.payload}')

// Reply to a message
client.reply_msg(
    received.id, // original message ID
    received.src_pk, // sender's public key
    'Got your message!', // reply payload
    'greetings' // topic
)!

// Check message status
status := client.get_msg_status(msg.id)!
println('Message status: ${status.state}')
println('Created at: ${status.created}')
println('Expires at: ${status.deadline}')

The messaging API supports:- Sending messages to nodes identified by public key

• Optional message topics for filtering
• Waiting for replies when sending messages
• Peeking at messages without removing them from the queue
• Tracking message delivery status
• Base64 encoded message payloads for binary data

Installation and Management

For installing and managing Mycelium nodes, use the Mycelium Installer package located in installers/net/mycelium/. The installer provides functionality for:

• Installing Mycelium nodes
• Starting/stopping nodes
• Managing node configuration
• Setting up TUN interfaces
• Configuring peer connections

fn check() bool

fn delete(args_ ArgsGet) !

fn exists(args_ ArgsGet) !bool

does the config exists?

fn get(args_ ArgsGet) !&Mycelium

fn heroscript_dumps(obj Mycelium) !string

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

fn heroscript_loads(heroscript string) !Mycelium

fn inspect(args MyceliumInspectArgs) !MyceliumInspectResult

fn ipaddr() string

if returns empty then probably mycelium is not installed

fn play(args_ PlayArgs) !

fn set(o Mycelium) !

register the config for the future

fn switch(name string)

switch instance to be used for mycelium

struct ArgsGet {
pub mut:
	name string
}

///////FACTORY

struct DefaultConfigArgs {
	instance string = 'default'
}

helpers

struct InboundMessage {
pub:
	id      string
	src_ip  string @[json: 'srcIp'] // Sender overlay IP address
	src_pk  string @[json: 'srcPk'] // Sender public key, hex encoded
	dst_ip  string @[json: 'dstIp'] // Receiver overlay IP address
	dst_pk  string @[json: 'dstPk'] // Receiver public key, hex encoded
	topic   string // Optional message topic
	payload string // Message payload, base64 encoded
}

A message received by the system

struct Info {
pub:
	node_subnet string @[json: 'nodeSubnet'] // subnet owned by node
}

General information about a node

struct MessageDestination {
pub:
	ip string @[omitempty] // IP in the subnet of the receiver node
	pk string @[omitempty] // hex encoded public key of the receiver node
}

Represents a destination for a message, can be either IP or public key

struct MessageStatusResponse {
pub:
	dst      string // IP address of receiving node
	state    string // pending, received, read, aborted or sending object
	created  i64    // Unix timestamp of creation
	deadline i64    // Unix timestamp of expiry
	msg_len  int @[json: 'msgLen'] // Length in bytes
}

Information about an outbound message

struct Mycelium {
pub mut:
	name       string = 'default'
	server_url string = 'http://localhost:8989'
	conn       ?&httpconnection.HTTPConnection @[skip; str: skip]
}

fn (mut self Mycelium) connection() !&httpconnection.HTTPConnection

Get connection to mycelium server

fn (mut self Mycelium) get_info() !Info

Get node info

fn (mut self Mycelium) get_msg_status(id string) !MessageStatusResponse

Get status of a message by ID

fn (mut self Mycelium) get_pubkey_from_ip(ip string) !PublicKeyResponse

Get public key for a node IP

fn (mut self Mycelium) receive_msg(args ReceiveMessageArgs) !InboundMessage

Receive a message from the queue

fn (mut self Mycelium) receive_msg_opt(args ReceiveMessageArgs) ?InboundMessage

Optional version of receive_msg that returns none on 204

fn (mut self Mycelium) reply_msg(args ReplyMessageArgs) !

Reply to a message

fn (mut self Mycelium) send_msg(args SendMessageArgs) !InboundMessage

Send a message to a node identified by public key

struct MyceliumInspectArgs {
pub:
	key_file_path string = '/root/hero/cfg/priv_key.bin'
}

struct MyceliumInspectResult {
pub:
	public_key string @[json: publicKey]
	address    string
}

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

struct PublicKeyResponse {
pub:
	node_pub_key string @[json: 'NodePubKey'] // hex encoded public key
}

Response containing public key for a node IP

struct PushMessageBody {
pub:
	dst     MessageDestination
	topic   ?string // optional message topic
	payload string  // base64 encoded message
}

Body of a message to be sent

struct PushMessageResponseId {
pub:
	id string // hex encoded message ID
}

Response containing message ID after pushing

struct ReceiveMessageArgs {
pub mut:
	topic ?string
	wait  bool
	peek  bool
}

struct ReplyMessageArgs {
pub mut:
	id         string @[required]
	public_key string @[required]
	payload    string @[required]
	topic      ?string
}

struct SendMessageArgs {
pub mut:
	public_key string @[required]
	payload    string @[required]
	topic      ?string
	wait       bool
}