wasmrpc

WASM-RPC

This module provides a convenient and simple way for WASM modules to send RPC requests to the host, without necessarily generating bindings for every possible client language. Clients only need to implement a single function linked to the WASM environment module and a JSON (TODO) or MSGP serializer.

Runtime setup

The host must provide a set of receivers similar to the stdlib RPC services. Receivers are functions exposed to client modules and are responsible for defining their own arguments and responses.

// ArithmeticEnv is an example of a host environment used to store a persistent state between invocations of any receiver
type ArithmeticEnv struct {
    LastCaller string
}

// AdderReceiver is an example of a receiver that simply adds two numbers.
type AdderReceiver struct {
    Args AddArgs
    Resp AddResp
}

// AddArgs are an example of parameters for an addition receiver
type AddArgs struct {
    A, B int
}

// AddResp is an example of the result of an addition receiver
type AddResp struct {
    C int
}

// Binding implements the wasmrpc.Receiver interface
func (a *AdderReceiver) Binding() (codecs.RpcArgs, codecs.RpcResp) {
    return &a.Args, &a.Resp
}

// Execute implements the wasmrpc.Receiver interface
func (a *AdderReceiver) Execute(caller string, env *ArithmeticEnv, _ any) (err error) {
    env.LastCaller = caller
    a.Resp.C = a.Args.A + a.Args.B
    return
}

Receivers are bundled into a wasmrpc.Host with a host environment to store persistent data available to all receivers. The wasmrpc.Host is then used to instantiate a new RPC runtime where client modules have access to the host and it's receivers.

func main() {
    env := new(mock.ArithmeticEnv)
    host := wasmrpc.NewHost(env)
    host.RegisterReceiver("add", new(AdderReceiver))

	rt, runtimeContext, err := wasmrpc.NewRpcRuntime(host, wazero.NewRuntimeConfig())
	// Error checking...
}

After that use the wazero.Runtime like usual and make sure to always pass the runtimeContext (or a child context) to all wazero function calls (like instantiations or module function calls). This is required to provide modules with a link to the RPC host.

An example of the receiver implementation can be seen in the mock package and an extended example of the runtime usage can be seen in the test.

Client setup

On the client side define a function with the following signature and make sure that the function is imported by the linker from the env module as WasmRPC.

func (param i32 i32 i32) (result i32))

To invoke an RPC function the client needs to serialize the request into an allocated buffer and call WasmRPC where the parameters in turn are:

1. The memory pointer to the start of the buffer
2. The length of the request
3. The maximum capacity of the buffer

The function call will block until execution on the host is complete. The host will then write the result into the same buffer and return the length of the response. In case that the response would exceed the allocated buffer capacity no data will be written and the returned response size is zero.

Examples for different languages and compilation instructions can be found in the examples folder (TODO).

RPC spec

For MessagePack the MessagePack-RPC Specification must be used for encoding end decoding messages. The msgprpc package provides a tinygo friendly implementation ready to use.

For JSON the JSON-RPC 2.0 Specification must be used.