geofmureithi / plugy

plugy empowers you to construct agnostic dynamic plugin systems using Rust and WebAssembly.

plugy

plugy is a plugin system designed to enable the seamless integration of Rust-based plugins into your application. It provides a runtime environment for loading and executing plugins written in WebAssembly (Wasm), enabling dynamic extensibility and modularity in your Rust projects.

Features

• Load and execute plugins compiled to WASM.
• Flexible runtime management of plugins.
• Calls to plugin functions are async.
• Easy-to-use macros for generating plugin interfaces.

Getting Started

To use plugy in your Rust project, follow these steps:

1. Write your plugin trait:

#[plugy::plugin]
trait Greeter {
    fn greet(&self) -> String;
}

2. Write your first plugin implementation

#[derive(Debug, Deserialize)]
struct FooPlugin;

#[plugin_impl]
impl Greeter for FooPlugin {
    fn greet(&self) -> String {
        "Hello From Foo Plugin".to_owned()
    }
}

Compile it!

cargo build --target wasm32-unknown-unknown

3. Import and run

#[plugin_import(file = "target/wasm32-unknown-unknown/debug/foo_plugin.wasm")]
struct FooPlugin;

#[tokio::main]
async fn main() {
    let runtime = Runtime::<Box<dyn Greeter>>::new().unwrap();
    let handle = runtime.load(FooPlugin).await.unwrap();
    let res = handle.greet().await;
    assert_eq!(res, "Hello From Foo Plugin")
}

And you are set!

Examples

Check out the examples directory for sample usage of plugy.

Milestones

Status	Goal	Labels
✅	accept multiple arity (n-ary) in plugin functions	complete
✅	pass down context between host and guest	complete

Functionality

Plugy comprises three fundamental crates, each serving a distinct role in crafting dynamic plugin systems with Rust and WebAssembly:

• core: This crate houses essential components such as bitwise utilities and the guest module, forming the foundation of Plugy's functionality.

• runtime: The runtime crate orchestrates the execution of your plugin system, allowing seamless integration of plugins into your applications.

• macros: The macros crate offers a collection of macros that simplify the generation of bindings and interfaces, streamlining the process of working with dynamic plugins.

Contributing

Contributions to plugy are welcome! If you find a bug or want to propose a new feature, feel free to create an issue or submit a pull request.

Thanks to

• Wasmtime
• Bincode
• Serde
• Wasmtime-Serde inspired alot of the inner working of this project

License

This project is licensed under the MIT OR Apache-2.0 License.

plugy's Issues

Pass down context between host and guest

Imagine doing this:

let context = Context::new(); // Context shared by plugins
let runtime = Runtime::new(context);

Then on guest:

#[plugy::plugin]
trait Greeter {
    fn greet(&self, ctx:Context) -> String;
}

Context can expose methods like fetch etc which would have external access for guests.

example to use diverse plugins

there are dog.wasm, cat.wasm and much more plugins, these are provided by community, and keep growing. the host app is fixed, so it's impossible to define struct for each plugin in host app code, like current example in repo.

the host app needs to use plugin based on user input. i tried a bit but fail.

Ability to do generics

Is generics a worthy cause?
Currently they can work on guest but the warpper code generated doesn't

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• fix(deps): update rust crate async-lock to 3.3.0
• fix(deps): update rust crate wasmtime to v16

Detected dependencies

cargo

Cargo.toml

crates/plugy-core/Cargo.toml

• serde 1
• bincode 1.3.3
• anyhow 1

crates/plugy-macros/Cargo.toml

• quote 1.0
• syn 2.0
• proc-macro2 1
• darling 0.20.3
• convert_case 0.6.0

crates/plugy-runtime/Cargo.toml

• anyhow 1
• bincode 1.3.3
• dashmap 5.5.3
• serde 1
• wasmtime 15.0.1
• async-lock 3.2.0

github-actions

.github/workflows/build.yml

• actions/checkout v4
• actions/checkout v4

---

• Check this box to trigger a request for Renovate to run again on this repository

Enforce structure of the plugin.

Currently we dont have any way of differentiating between plugins that are rightly done eg have all methods defined and a junk wasm file.
This causes a panic at calltime and rightly so.

Is there a way to add some signature or check to prevent loading a wasm file that doesn't conform.

Accept multiple arity in plugin functions.

Currently this works:

#[plugy::plugin]
trait Greeter {
    fn greet(&self) -> String;
}

This may not:

#[plugy::plugin]
trait Greeter {
    fn greet(&self, name:String) -> String;
}

WASI support

Add optional wasi support.

Invalid context call

plugy/crates/plugy-macros/src/lib.rs

Line 345 in d5fac7a

bincode::serialize(&ctx.fetch(&caller, message.0).await)

consider calling `.as_ref()` or `.as_mut()` to borrow the type's contents

plugy/crates/plugy-macros/src/lib.rs

Line 330 in 0e106ad

let store = caller.data().clone().unwrap();