Struct wapc::WapcHost

pub struct WapcHost { /* fields omitted */ }

A WebAssembly host runtime for waPC-compliant WebAssembly modules

Use an instance of this struct to provide a means of invoking procedure calls by specifying an operation name and a set of bytes representing the opaque operation payload. WapcHost makes no assumptions about the contents or format of either the payload or the operation name.

Methods

impl WapcHost

pub fn new<F>(
    host_callback: F,
    buf: &[u8],
    wasi: Option<WasiParams>
) -> Result<Self> where
    F: Fn(u64, &str, &str, &str, &[u8]) -> Result<Vec<u8>, Box<dyn Error>> + Sync + Send + 'static, 

Creates a new instance of a waPC-compliant WebAssembly host runtime. The resulting WebAssembly module instance will not be allowed to utilize WASI host functions.

pub fn new_with_logger<F, G>(
    host_callback: F,
    buf: &[u8],
    logger: G,
    wasi: Option<WasiParams>
) -> Result<Self> where
    F: Fn(u64, &str, &str, &str, &[u8]) -> Result<Vec<u8>, Box<dyn Error>> + Sync + Send + 'static,
    G: Fn(u64, &str) -> Result<(), Box<dyn Error>> + Sync + Send + 'static, 

pub fn id(&self) -> u64

Returns a reference to the unique identifier of this module. If a parent process has instantiated multiple WapcHosts, then the single static host call function will be required to differentiate between modules. Use the unique ID as a differentiator

pub fn call(&mut self, op: &str, payload: &[u8]) -> Result<Vec<u8>>

Invokes the __guest_call function within the guest module as per the waPC specification. Provide an operation name and an opaque payload of bytes and the function returns a Result containing either an error or an opaque reply of bytes.

It is worth noting that the first time call is invoked, the WebAssembly module will be JIT-compiled. This can take up to a few seconds on debug .wasm files, but all subsequent calls will be "hot" and run at near-native speeds.

pub fn replace_module(&self, module: &[u8]) -> Result<()>

Performs a live "hot swap" of the WebAssembly module. Since execution is assumed to be single-threaded within the environment of the WapcHost, this will not cause any pending function calls to be lost. This will replace the currently executing WebAssembly module with the new bytes.

Note: you will lose all JITted functions for this module, so the first call after a hot swap will be "cold" and take longer than regular calls. There are an enormous number of ways in which a hot swap could go horribly wrong, so please ensure you have the proper guards in place before invoking it. Libraries that build upon this one can (and likely should) implement some form of security to protect against malicious swaps.

If you perform a hot swap of a WASI module, you cannot alter the parameters used to create the WASI module like the environment variables, mapped directories, pre-opened files, etc. Not abiding by this could lead to privilege escalation attacks or non-deterministic behavior after the swap.