waPC Specification

The waPC protocol standardizes communication and error handling for native code calling into WebAssembly and WebAssembly calling out to native code.

Terms

waPC Hosts

A waPC host is the native environment that initializes and make requests of waPC guests.

waPC Guests

A waPC guest is a WebAssembly module that exposes commands (functions) that a host can call.

Guest call

A request from a host to a guest.

Host call

A request from a guest to a host.

RPC Exchange flow

The following is an outline of which functions are invoked and in which order to support a waPC exchange flow. waPC Host libraries should hide the details of this flow from their users.

  1. Host invokes __guest_call on the WebAssembly module.
  2. Guest calls the __guest_request function to instruct the host to write the request parameters to linear memory.
  3. Guest uses the op_len and msg_len parameters along with the pointer values it generated in step 2 to retrieve the operation (UTF-8 string) and payload (opaque byte array).
  4. Guest performs work.
  5. (Optional) Guest invokes __host_call on host with pointers and lengths indicating the binding, namespace, operation, and payload.
  6. (Optional) Guest can use __host_response and host_response_len functions to obtain and interpret results.
  7. (Optional) Guest can use __host_error_len and __host_error to obtain the host error if indicated (__host_call returns 0).
  8. A guest can repeat 5-7 as many times as it needs.
  9. Guest will call guest_error to indicate if an error occurred during processing.
  10. Guest will call guest_response to store the opaque response payload.
  11. Guest will return 0 (error) or 1 (success) at the end of __guest_call.

Required Host Exports

List of functions that must be exported by the host.

ModuleFunctionParametersReturn valueDescription
wapc__host_callbind_ptr:i32
bind_len:i32
ns_ptr:i32
ns_len:i32
cmd_ptr:i32
cmd_len:i32
payload_ptr:i32
payload_len:i32
i32Invoked to initiate a host call.
wapc__console_logptr:i32
len:i32
Allows guest to log to stdout
wapc__guest_requestop_ptr:i32
ptr:i32
Writes the guest request payload and operation name to linear memory at the designated locations
wapc__host_responseptr:i32Instructs host to write the host response payload to the given location in linear memory
wapc__host_response_leni32Obtains the length of the current host response
wapc__guest_responseptr:i32
len:i32
Tells the host the size and location of the current guest response payload
wapc__guest_errorptr:i32
len:i32
Tells the host the size and location of the current guest error payload
wapc__host_errorptr:i32Instructs the host to write the host error payload to the given location
wapc__host_error_leni32Queries the host for the length of the current host error (0 if none)

Required Guest Exports

List of functions that must be exported by the guest.

FunctionParametersDescription
__guest_callop_len:i32
msg_len:i32
Invoked by the host to start an RPC exchange with the guest module
Last modified November 22, 2021: added spec spage (c5fce73)