wasmex

Wasmex is a fast and secure WebAssembly and WASI runtime for Elixir. It enables lightweight WebAssembly containers to be run in your Elixir backend.

It uses wasmtime to execute Wasm binaries through a Rust NIF.

Documentation can be found at https://hexdocs.pm/wasmex.

Install

The package can be installed by adding wasmex to your list of dependencies in mix.exs:

def deps do
  [
    {:wasmex, "~> 0.15.1"}
  ]
end

Example

There is a toy Wasm program in test/fixture_projects/wasm_test/src/lib.rs, written in Rust (but could potentially be any other language that compiles to WebAssembly). It defines many functions we use for end-to-end testing, but also serves as example code. For example:

#[no_mangle]
pub extern fn sum(x: i32, y: i32) -> i32 {
    x + y
}

Once this program is compiled to WebAssembly (which happens whenever the tests run), we get a wasmex_test.wasm binary file.

This Wasm file can be executed in Elixir:

bytes =
  File.read!(
    "test/fixture_projects/wasm_test/target/wasm32-unknown-unknown/debug/wasmex_test.wasm"
  )
{:ok, pid} = Wasmex.start_link(%{bytes: bytes}) # starts a GenServer running a Wasm instance
{:ok, [42]} == Wasmex.call_function(pid, "sum", [50, -8])

What is WebAssembly?

Quoting the WebAssembly site:

WebAssembly (abbreviated Wasm) is a binary instruction format for a stack-based virtual machine. Wasm is designed as a portable target for compilation of high-level languages like C/C++/Rust, enabling deployment on the web for client and server applications.

About speed:

WebAssembly aims to execute at native speed by taking advantage of common hardware capabilities available on a wide range of platforms.

About safety:

WebAssembly describes a memory-safe, sandboxed execution environment […].

Using WebAssembly on an Elixir host is great not only, but especially for the following use cases:

• Running user-provided code safely
• Share business logic between systems written in different programming languages. E.g. a JS frontend and Elixir backend
• Run existing libraries/programs and easily interface them from Elixir

Development

To set up a development environment install the latest stable rust and rust-related tooling:

rustup component add rustfmt
rustup component add clippy
rustup target add wasm32-unknown-unknown # to compile our example Wasm files for testing
rustup target add wasm32-wasip1 # to compile our example Wasm/WASI files for testing
rustup target add wasm32-wasip2 # to compile component resource fixtures
cargo install --locked cargo-component # for Wasm component model files

Then install the erlang/elixir dependencies:

asdf install # assuming you install elixir, erlang with asdf. if not, make sure to install them your way
mix deps.get

If you plan to change something on the Rust part of this project, set the following ENV WASMEX_BUILD=true so that your changes will be picked up.

I´m looking forward to your contributions. Please open a PR containing the motivation of your change. If it is a bigger change or refactoring, consider creating an issue first. We can discuss changes there first which might safe us time down the road :)

Run WASMEX_BUILD=true mix test for the Elixir integration suite and cargo test --manifest-path native/wasmex/Cargo.toml --all-targets --all-features for the Rust unit tests. In addition to tests, we expect the formatters and linters (cargo fmt, cargo clippy, mix format, mix credo) to pass.

License

The entire project is under the MIT License. Please read the LICENSE file.

Licensing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, shall be licensed as above, without any additional terms or conditions.