Crate wapc

wapc

The wapc crate provides a WebAssembly host runtime that conforms to an RPC mechanism called waPC. waPC is designed specifically to prevent either side of the call from having to know anything about how or when memory is allocated or freed. The interface may at first appear more "chatty" than other protocols, but the cleanliness, ease of use, and simplified developer experience is worth the few extra nanoseconds of latency.

To use wapc, first you'll need a waPC-compliant WebAssembly module (referred to as the guest) to load and interpret. You can find a number of these samples available in the GitHub repository, and anything compiled with the wascc actor SDK can also be invoked via waPC as it is 100% waPC compliant.

To make function calls, first set your host_callback function, a function invoked by the guest. Then execute call on the WapcHost instance.

Example

extern crate wapc;
use wapc::prelude::*;

pub fn main() -> Result<(), Box<dyn std::error::Error>> {
    let module_bytes = load_file();
    let mut host = WapcHost::new(host_callback, &module_bytes, None)?;

    let res = host.call("wapc:sample!Hello", b"this is a test")?;
    assert_eq!(res, b"hello world!");

    Ok(())
}

fn host_callback(id: u64, bd: &str, ns: &str, op: &str, payload: &[u8]) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    println!("Guest {} invoked '{}->{}:{}' with payload of {} bytes", id, bd, ns, op, payload.len());
    Ok(vec![])
}

Notes

waPC is reactive. Guest modules cannot initiate host calls without first handling a call initiated by the host. waPC will not automatically invoke any start functions--that decision is up to the waPC library consumer. Guest modules can synchronously make as many host calls as they like, but keep in mind that if a host call takes too long or fails, it'll cause the original guest call to also fail.

In summary, keep host_callback functions fast and resilient, and do not spawn new threads within host_callback unless you must (and can synchronize memory access) because waPC assumes a single-threaded execution environment. The host_callback function intentionally has no references to the WebAssembly module bytes or the running instance.

Modules

errors	Library-specific error types and utility functions
prelude	Standard types typically used by consumers

Structs

WapcHost	A WebAssembly host runtime for waPC-compliant WebAssembly modules
WasiParams	Stores the parameters required to create a WASI instance

Type Definitions

Result

A result type for errors that occur within the wapc library