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.

Module	Function	Parameters	Return value	Description
wapc	__host_call	bind_ptr:i32 bind_len:i32 ns_ptr:i32 ns_len:i32 cmd_ptr:i32 cmd_len:i32 payload_ptr:i32 payload_len:i32	i32	Invoked to initiate a host call.
wapc	__console_log	ptr:i32 len:i32		Allows guest to log to stdout
wapc	__guest_request	op_ptr:i32 ptr:i32		Writes the guest request payload and operation name to linear memory at the designated locations
wapc	__host_response	ptr:i32		Instructs host to write the host response payload to the given location in linear memory
wapc	__host_response_len		i32	Obtains the length of the current host response
wapc	__guest_response	ptr:i32 len:i32		Tells the host the size and location of the current guest response payload
wapc	__guest_error	ptr:i32 len:i32		Tells the host the size and location of the current guest error payload
wapc	__host_error	ptr:i32		Instructs the host to write the host error payload to the given location
wapc	__host_error_len		i32	Queries 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.

Function	Parameters	Description
__guest_call	op_len:i32 msg_len:i32	Invoked by the host to start an RPC exchange with the guest module