Binmod MDK for Rust

The Rust Module Development Kit (MDK) for Binmod - build WebAssembly-based plugins that run anywhere.

Overview

Binmod MDK for Rust provides macros and types to create WebAssembly modules that can be loaded and executed by any Binmod runtime. Write your plugin logic in Rust, compile to WASM, and run it in applications written in Python, Rust, or any other language with a Binmod runtime.

Basic Usage

Create a New Module

Create a new Rust library project:

cargo new --lib my_calculator
cd my_calculator

Installation

Add the binmod-mdk crate to your Cargo.toml:

[dependencies]
binmod-mdk = { git = "https://github.com/binmod-io/rust-mdk" }

Or, add the Binmod MDK dependency via cargo:

cargo add binmod-mdk

Install the WebAssembly target:

rustup target add wasm32-wasip1

Implement Your Module

Edit src/lib.rs:

use binmod_mdk::{mod_fn, host_fns, FnResult};

// Define host functions provided by the runtime
// The namespace must match the one used when instantiating the module
#[host_fns(namespace = "calculator")]
unsafe extern "host" {
    fn log(message: String);
    fn get_pi() -> f64;
}

// Implement module functions - your plugin's public API
// All parameters and return types must be JSON-serializable
#[mod_fn(name = "circle_area")]
fn circle_area(radius: f64) -> FnResult<f64> {
    let pi = unsafe { get_pi()? };
    let area = pi * radius * radius;
    unsafe { log(format!("Calculating area for radius {}", radius))? };
    Ok(area)
}

#[mod_fn(name = "add")]
fn add(a: i32, b: i32) -> FnResult<i32> {
    let result = a + b;
    unsafe { log(format!("Adding {} + {} = {}", a, b, result))? };
    Ok(result)
}

Key points:

• Module Functions (#[mod_fn]): Functions your plugin exposes that can be called by the host
• Host Functions (#[host_fns]): Functions provided by the runtime that your plugin can call
• FnResult: All module functions must return this type
• All parameters and return types must be JSON-serializable (primitives, strings, arrays, objects)

Compile Your Module

cargo build --target wasm32-wasip1

Your compiled module will be at:

target/wasm32-wasip1/debug/my_calculator.wasm

Use Your Module

Your compiled WebAssembly module can now be loaded by any Binmod runtime. Here's an example using the Python runtime:

from binmod import Module, ModuleEnv

mod = Module.from_file(
    "target/wasm32-wasip1/debug/my_calculator.wasm",
    name="my_calculator",
    environment=ModuleEnv.inherit(),
    namespace="calculator",
    host_fns={
        "log": lambda msg: print(f"[Module] {msg}"),
        "get_pi": lambda: 3.14159,
    }
)
mod.instantiate()

# Call module functions
area = mod.api.circle_area(5.0)
# Or alternatively using the call method
# area = mod.call("circle_area", (5.0,))
print(f"Circle area: {area}")

sum_result = mod.api.add(10, 20)
# Or alternatively using the call method
# sum_result = mod.call("add", (10, 20))
print(f"10 + 20 = {sum_result}")

License

MIT License

Support

If you encounter issues or have questions, please open an issue on GitHub.