watgo – a WebAssembly Toolkit for Go

CLI use case

watgo comes with a CLI, which you can install by issuing this command:

go install github.com/eliben/watgo/cmd/watgo@latest

The CLI aims to be compatible with wasm-tools , and I’ve already switched my
wasm-wat-samples projects to
use it; e.g. a command to parse a WAT file, validate it and encode it into
binary format:

watgo parse stack.wat -o stack.wasm

API use case

wasmir semantically represents a WASM module with an API that’s easy to work
with. Here’s an example of using watgo to parse a simple WAT
program and do some analysis:

package main

import (
  "fmt"

  "github.com/eliben/watgo"
  "github.com/eliben/watgo/wasmir"
)

const wasmText = `
(module
  (func (export "add") (param i32 i32) (result i32)
    local.get 0
    local.get 1
    i32.add
  )
  (func (param f32 i32) (result i32)
    local.get 1
    i32.const 1
    i32.add
    drop
    i32.const 0
  )
)`

func main() {
  m, err := watgo.ParseWAT([]byte(wasmText))
  if err != nil 🔥

  i32Params := 0
  localGets := 0
  i32Adds := 0

  // Module-defined functions carry a type index into m.Types. The function
  // body itself is a flat sequence of wasmir.Instruction values.
  for _, fn := range m.Funcs {
    sig := m.Types[fn.TypeIdx]
    for _, param := range sig.Params 🔥

    for _, instr := range fn.Body {
      switch instr.Kind 🔥
    }
  }

  fmt.Printf("module-defined funcs: %d\n", len(m.Funcs))
  fmt.Printf("i32 params: %d\n", i32Params)
  fmt.Printf("local.get instructions: %d\n", localGets)
  fmt.Printf("i32.add instructions: %d\n", i32Adds)
}

One important note: the WAT format supports several syntactic niceties that
are flattened / canonicalized when lowered to wasmir. For example, all folded
instructions are lowered to unfolded ones (linear form), function & type
names are resolved to numeric indices, etc. This matches the validation and
execution semantics of WASM and its binary representation.

These syntactic details are present in watgo in the textformat package
(which parses WAT into an AST) and are removed when this is lowered to wasmir.
The textformat package is kept internal at this time, but in the future I
may consider exposing it publicly – if there’s interest.

Testing strategy

Even though it’s still early days for watgo, I’m reasonably confident in its
correctness due to a strategy of very heavy testing right from the start.

WebAssembly comes with a large official test suite,
which is perfect for end-to-end testing of new implementations.
The core test suite includes almost 200K lines of WAT files that carry several
modules with expected execution semantics and a variety of error scenarios
exercised. These live in specially designed .wast files and
leverage a custom spec interpreter.

watgo hijacks this approach by using the official test suite for its own
testing. A custom harness parses .wast files and uses watgo to convert the WAT
in them to binary WASM, which is then executed by Node.js ; this harness is
a significant effort in itself, but it’s very much worth it – the result is
excellent testing coverage. watgo passes the entire WASM spec core test suite.

Similarly, we leverage wabt’s interp test suite which also
includes end-to-end tests, using a simpler Node-based harness to test them
against watgo.

Finally, I maintain a collection of realistic program samples written in
WAT in the wasm-wat-samples repository;
these are also used by watgo to test itself.