waPC

这是 waPC 主机协议的 Rust 实现。这个工具包定义了 WapcHost 结构体和 WebAssemblyEngineProvider 特性，以提供 WebAssembly 模块的动态执行。有关 WebAssembly 引擎实现的详细信息，请参阅下面的提供者工具包。

• wasmtime-provider
• wasm3-provider

wapc

wapc 工具包提供了一个符合 RPC 机制（称为 waPC，即 WebAssembly Procedure Calls）的高级 WebAssembly 主机运行时。waPC 设计为一个固定、轻量级的标准，允许 guest/host 边界两边进行包含任意二进制有效负载的方法调用。合同的任何一方都不需要执行显式分配，确保了可能在不同垃圾收集器和内存重定位、压缩等情况中表现不同的 wasm 目标的最大可移植性。

要使用 wapc，首先您需要一个符合 waPC 规范的 WebAssembly 模块（称为 guest），以便加载和执行。您可以在 GitHub 仓库 中找到许多这样的示例。

接下来，您需要选择一个运行时引擎。waPC 描述了 wasm-RPC 所需的函数调用流程，但它并没有规定如何执行低级 WebAssembly 函数调用。这允许您选择最适合您需求的引擎，无论是基于 JIT 的引擎还是基于解释器的引擎。只需实例化实现 WebAssemblyEngineProvider 特性的任何内容，并将其传递给 WapcHost 构造函数，WapcHost 将简化所有 RPC。

要执行函数调用，确保在创建您的 WapcHost 时提供了合适的主机回调函数（或闭包）。然后调用 call 函数以启动 RPC 流程。

示例

以下是一个 WebAssembly 主机运行时和 guest 模块之间同步、双向过程调用的示例。

use wasmtime_provider::WasmtimeEngineProvider; // Or Wasm3EngineProvider
use wapc::WapcHost;
use std::error::Error;
pub fn main() -> Result<(), Box<dyn Error>> {

  // Sample host callback that prints the operation a WASM module requested.
  let host_callback = |id: u64, bd: &str, ns: &str, op: &str, payload: &[u8]| {
    println!("Guest {} invoked '{}->{}:{}' with a {} byte payload",
    id, bd, ns, op, payload.len());
    // Return success with zero-byte payload.
    Ok(vec![])
  };

  let file = "../../wasm/crates/wasm-basic/build/wasm_basic.wasm";
  let module_bytes = std::fs::read(file)?;

  let engine = WasmtimeEngineProvider::new(&module_bytes, None)?;
  let host = WapcHost::new(Box::new(engine), Some(Box::new(host_callback)))?;

  let res = host.call("ping", b"payload bytes")?;
  assert_eq!(res, b"payload bytes");

  Ok(())
}

要运行示例，请参阅各个引擎提供者仓库中的示例。

• wasmtime-provider - 利用Bytecode Alliance运行时wasmtime进行WebAssembly的JIT编译和执行。
• wasm3-provider - 使用wasm3的C解释器运行时（带有Rust封装）

注意

waPC是响应式的。主机发起请求，客户端做出响应。在请求过程中，客户端可以回叫主机并与环境（通过WASI）交互。当请求完成后，客户端应被视为已停放，直到下一次请求。

RPC交换流程

以下是对支持waPC交换流程的函数调用的详细概述，该流程始终由消费者调用call函数触发。调用和处理这些底层函数是引擎提供者的责任，而协调高级控制流程是WapcHost的工作。

1. 主机通过引擎提供者在WebAssembly模块上调用__guest_call
2. 客户端调用__guest_request函数来指示主机将请求参数写入线性内存
3. 客户端使用步骤2中生成的指针值以及op_len和msg_len参数来检索操作（UTF-8字符串）和有效负载（不透明的字节数组）
4. 客户端执行工作
5. （可选） 客户端调用主机上的__host_call，并使用指示binding、namespace、operation和有效负载的指针和长度
6. （可选） 客户端可以使用__host_response和host_response_len函数来获取和解释结果
7. （可选） 客户端可以使用__host_error_len和__host_error来获取主机错误（如果有的话）（当__host_call返回0时）
   1. 步骤5-7可以根据客户端需要的不同主机调用重复进行
8. 客户端将调用guest_error来指示处理过程中是否发生错误
9. 客户端将调用guest_response来存储不透明的响应有效负载
10. 客户端将在__guest_call结束时返回0（错误）或1（成功）