v1

v1 defines the first production-ready version of the WebAssembly Transport Module (WATM) specification.

API

The current version of WATM utilizes the WebAssembly System Interface (WASI) Preview 1 to provide the basic functionalities to interact between the WebAssembly module and the host environment. In addition, we define the following API for the transport module.

Imports

WATM imports the following functions from the host environment:

Function Signature	Parameters	Results	Description
water_dial	network_iovs: ciovec_array, address_iovs: ciovec_array	fd: s32	Dial a remote address specified by network and address
water_dial_fixed	-	fd: s32	Dial a remote address controlled by WATER Runtime
water_accept	-	net_fd: s32	Accept an incoming connection from the listener managed by WATER Runtime

Exports

WATM exports the following functions to the host environment:

Function Signature	Parameters	Results	Description
watm_init_v1	-	errno: s32	Initialize the transport module
watm_ctrlpipe_v1	ctrl_fd: s32	errno: s32	Set the control pipe to the given file descriptor. Called before watm_start_v1
watm_dial_v1	internal_fd: s32	net_fd: s32	Connect to a remote server specified by WATER Runtime
watm_dial_fixed_v1	internal_fd: s32	net_fd: s32	Connect to a remote server specified by WATM
watm_accept_v1	internal_fd: s32	net_fd: s32	Accept an incoming connection
watm_associate_v1	-	errno: s32	Associate the next incoming connection with an outgoing connection (relay)
watm_start_v1	-	errno: s32	Start the (blocking) worker thread

API Represented in Different Programming Languages

To help developers understand the API, we provide the following representations of the API in different programming languages that could be more intuitive than the above table.

C representation

(planned feature)

Go representation

Imports

//go:wasmimport env water_dial
//go:noescape
func water_dial(
	networkIovs unsafe.Pointer, networkIovsLen size,
	addressIovs unsafe.Pointer, addressIovsLen size,
) (fd int32)

//go:wasmimport env water_dial_fixed
//go:noescape
func water_dial_fixed() (fd int32)

//go:wasmimport env water_accept
//go:noescape
func water_accept() (fd int32)

Exports

//export watm_init_v1
func _init() int32

//export watm_ctrlpipe_v1
func _ctrlpipe(ctrlFd int32) int32

//export watm_dial_v1
func _dial(internalFd int32) (networkFd int32)

//export watm_dial_fixed_v1
func _dial_fixed(internalFd int32) (networkFd int32)

//export watm_accept_v1
func _accept(internalFd int32) (networkFd int32)

//export watm_associate_v1
func _associate() int32 

//export watm_start_v1
func _start() int32

Rust representation

(to be added)

WIT representation

Similarly, such API can be represented in WIT.

Note that the following is a simplified example and may not strictly follow the WIT syntax. In other words, we do not guarantee the following code to be compilable.

Imports

// imports.wit
package env;

interface host {
    water_dial: func(network_iovs: ciovec_array, addr_iovs: ciovec_array) -> (net_fd: s32);
    water_dial_fixed: func() -> (net_fd: s32);
    water_accept: func() -> (conf_fd: s32);
}

world host-world {
    import host;
}

Exports

// exports.wit
interface wasm {
    watm_init_v1: func() -> (errno: s32);
    watm_ctrlpipe_v1(ctrl_fd: s32) -> (errno: s32);
    watm_dial_v1: func(internal_fd: s32) -> (net_fd: s32);
    watm_dial_fixed_v1: func(internal_fd: s32) -> (net_fd: s32);
    watm_accept_v1: func(internal_fd: s32) -> (net_fd: s32);
    watm_associate_v1: func() -> (errno: s32); 
    watm_start_v1: func() -> (errno: s32);
}

world wasm-world {
    export wasm;
}