-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
new: WATM v1 Spec documentation (#13)
* update: make spec a directory and move v0 spec Signed-off-by: Gaukas Wang <[email protected]> * new: v1 spec Signed-off-by: Gaukas Wang <[email protected]> --------- Signed-off-by: Gaukas Wang <[email protected]>
- Loading branch information
Showing
3 changed files
with
189 additions
and
16 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| --- | ||
| layout: default | ||
| title: WATM Specification | ||
| parent: WebAssembly Transport Module | ||
| nav_order: 3 | ||
| has_children: true | ||
| permalink: /transport-module/spec.html | ||
| --- | ||
|
|
||
| # WebAssembly Transport Module (WATM) Specification | ||
| By design, WATER supports multiple different implementations of the standard WebAssembly Transport Module (WATM) specification, for versioning and customization purposes. This page lists the available official versions of the WATM specification. | ||
|
|
||
| ## Current Version | ||
| We are rolling out [v1](spec/v1.html) as the most current WebAssembly Transport Module (WATM) specification. | ||
|
|
||
| ## Deprecated Versions | ||
|
|
||
| - [v0](spec/v0.html) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,156 @@ | ||
| --- | ||
| layout: default | ||
| title: v1 | ||
| grand_parent: WebAssembly Transport Module | ||
| parent: WATM Specification | ||
| nav_order: 1 | ||
| --- | ||
|
|
||
| # 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 | ||
|
|
||
| <details> | ||
| <summary>Imports</summary> | ||
|
|
||
| <div class="highlighter-rouge"> | ||
| <div class="highlight"> | ||
| <pre class="highlight"> | ||
| <code>//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)</code> | ||
| </pre> | ||
| </div> | ||
| </div> | ||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Exports</summary> | ||
|
|
||
| <div class="highlighter-rouge"> | ||
| <div class="highlight"> | ||
| <pre class="highlight"> | ||
| <code>//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</code> | ||
| </pre> | ||
| </div> | ||
| </div> | ||
| </details> | ||
|
|
||
| ### 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._ | ||
|
|
||
| <details> | ||
| <summary>Imports</summary> | ||
|
|
||
| <div class="highlighter-rouge"> | ||
| <div class="highlight"> | ||
| <pre class="highlight"> | ||
| <code>// 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; | ||
| }</code> | ||
| </pre> | ||
| </div> | ||
| </div> | ||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Exports</summary> | ||
|
|
||
| <div class="highlighter-rouge"> | ||
| <div class="highlight"> | ||
| <pre class="highlight"> | ||
| <code> | ||
| // 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; | ||
| }</code> | ||
| </pre> | ||
| </div> | ||
| </div> | ||
| </details> |