wadge

README

wadge: a WebAssembly bridge

wadge is a WebAssembly "bridge" enabling native applications to invoke Wasm functions that are ordinarily provided by a Wasm runtime. Use cases for this project include:

• Testing WebAssembly applications natively, using existing development tools (e.g. debuggers)
• Extending native applications with WebAssembly plugins

Currently, wadge supports Go applications written for compilation to WebAssembly components.

Bridging Wasm functions and native code

In the testing case, when you write a component using WebAssembly Interface Type (WIT) interfaces, standard Go tools like go test don’t know how to natively stub the interfaces.

In order to maintain a typical, idiomatic Go development experience, you need a “bridge” between your Go toolchain and a WebAssembly runtime that makes interfaces “just work” when it's time to test your code.

wadge (for “Wasm-bridge”) is a framework that bridges the gap, so you can work on your code in a Go-native way. This pattern can be extended beyond testing to extend native Go applications with WebAssembly functions.

How it works

wadge handles interfaces belonging to the WebAssembly System Interface (WASI) 0.2 automatically, but also allows for testing of custom interfaces defined in WIT.

• wadge uses cabish to read and write values over FFI, passing to an embedded WebAssembly runtime (Wasmtime).
• The wadge-bindgen-go utility walks the complete AST of your application and generates a binding file (bindings.wadge.go) by default.
• The bindings file utilizes //go:linkname directives to replace unimplemented functions with //go:wasmimport directives—normally provided by the runtime—using a native implementation. In turn, the native implementation invokes those imports on a WebAssembly component running in an embedded wadge instance, operating in a "harness" pattern.

Testing with a WASI interface

Add wadge to your project:

go get go.joonas.cloud/wadge

Include the wadge bindgen in your tools.go like below:

//go:build tools

package main

import (
	_ "go.bytecodealliance.org/cmd/wit-bindgen-go"
	_ "go.joonas.cloud/wadge/cmd/wadge-bindgen-go"
)

Write a test for the application in a new file called <filename>_test.go (see example)

go mod tidy && go mod download

Generate wadge bindings for your test:

go run go.joonas.cloud/wadge/cmd/wadge-bindgen-go

This generates bindings.wadge.go.

Run go test:

go test

PASS
ok  	example/http/test	0.296s

Writing a test

Writing tests with wadge generally works as you would expect writing ordinary tests in Go:

• Use the standard testing package
• Write tests in <name>_test.go files
• Target functions with tests using the TestTargetFunction naming convention

For more on testing in Go, see the testing package documentation.

See the examples/go/http directory for examples of a simple HTTP server and associated test using wasi:http.

There are a couple of wadge-specific details to note:

RunTest is written as a method of wadge:

func TestIncomingHandler(t *testing.T) {
	wadge.RunTest(t, func() {
		req, err := http.NewRequest("", "test", nil)
		if err != nil {
			t.Fatalf("failed to create new HTTP request: %s", err)
		}

wadgehttp is used to call the component's export over the HandleIncomingRequest interface of wasi:http:

resp, err := wadgehttp.HandleIncomingRequest(incominghandler.Exports.Handle, req)

In the examples/go/http test, the line above represents the only manual WASI-specific step: we pass in the component's export and a standard library HTTP request, and we receive a standard library HTTP response.

From this point on, we can test as usual—for example, making standard assert statements:

assert.Equal(t, 200, resp.StatusCode)
assert.Equal(t, http.Header{
	"foo": {
		"bar",
		"baz",
	},
	"key": {
		"value",
	},
}, resp.Header)

Testing a component with custom interfaces

In order to write a test for a component that uses a custom interface defined in WIT, you can call wadge in an init function of your test file to use a custom instance of the platform harness: a component that exports all of the functionality imported by your application.

Typically the platform harness is instantiated automatically and exports standard WASI functionality. When using custom interfaces, you can create a new instance:

instance, err := wadge.NewInstance(&wadge.Config{
		Wasm: component,
	})
	if err != nil {
		log.Fatalf("failed to construct new instance: %s", err)
	}
	wadge.SetInstance(instance)

You can see this in practice in the wadge/tests/go/wasi directory. The component in this directory uses custom fib and leftpad interfaces (defined in the /wit/ subfolder) and can be tested using go test.

The init function in the test file for this application is as follows:

func init() {
	log.SetFlags(0)
	slog.SetDefault(slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
		Level: slog.LevelDebug, ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
			if a.Key == slog.TimeKey {
				return slog.Attr{}
			}
			return a
		},
	})))

	instance, err := wadge.NewInstance(&wadge.Config{
		Wasm: component,
	})
	if err != nil {
		log.Fatalf("failed to construct new instance: %s", err)
	}
	wadge.SetInstance(instance)
}

Documentation

Index

• Variables
• func CurrentErrorHandler() func(error)
• func RunTest(t *testing.T, f func())
• func SetErrorHandler(f func(error)) func(error)
• func WithCurrentErrorHandler(f func(func(error)))
• func WithCurrentInstance[T any](f func(*Instance) T) T
• func WithErrorHandler(handler func(error), f func())
• func WithInstance(i *Instance, f func())
• type Config
• type Instance
  • func NewInstance(conf *Config) (*Instance, error)
  • func SetInstance(i *Instance) *Instance
  • func (i Instance) Call(instance string, name string, args ...unsafe.Pointer) error

Variables

var Passthrough []byte

Passthrough is a default passthrough Wasm component, which reexports all standard WASI interfaces

Functions

func CurrentErrorHandler

func CurrentErrorHandler() func(error)

CurrentErrorHandler atomically loads the current global error handler. CurrentErrorHandler is safe for concurrent use.

func RunTest

func RunTest(t *testing.T, f func())

RunTest executes `f` with current global `wadge` Instance and global error handler, which calls `t.Fatal` on errors. RunTest is safe for concurrent use, but calling it from within `f` will cause a deadlock.

func SetErrorHandler

func SetErrorHandler(f func(error)) func(error)

SetErrorHandler atomically sets a global error handler and returns previous value. SetErrorHandler is safe for concurrent use.

func WithCurrentErrorHandler

func WithCurrentErrorHandler(f func(func(error)))

WithCurrentErrorHandler executes `f` with current global error handler. WithCurrentErrorHandler is safe for concurrent use, but calling it from within `f` will cause a deadlock.

func WithCurrentInstance

func WithCurrentInstance[T any](f func(*Instance) T) T

WithCurrentInstance executes `f` with current global `wadge` Instance. WithCurrentInstance is safe for concurrent use, but calling it from within `f` will cause a deadlock. If no global `wadge` Instance has been configured, WithCurrentInstance will attempt to use `Passthrough`. It will call `log.Fatal` if instantiating it fails.

func WithErrorHandler

func WithErrorHandler(handler func(error), f func())

WithErrorHandler executes `f` with `handler` as the global error handler resetting it back to previous value once `f` returns WithErrorHandler is safe for concurrent use, but calling it from within `handler` or `f` will cause a deadlock

func WithInstance

func WithInstance(i *Instance, f func())

WithInstance executes `f` with `i` as the global `wadge` Instance resetting it back to previous value once `f` returns WithInstance is safe for concurrent use, but calling it from within `f` will cause a deadlock

Types

type Config

type Config struct {
	// Wasm is the component bytes to instantiate, this can either be
	// binary Wasm or WAT.
	// In case a Wasm module is specified here, the runtime will componentize it.
	Wasm []byte
}

Config is `wadge` runtime configuration

type Instance

type Instance struct {
	// contains filtered or unexported fields
}

Instance is an instantiated Wasm component in `wadge` runtime

func NewInstance

func NewInstance(conf *Config) (*Instance, error)

NewInstance instantiates a new Wasm component in `wadge` runtime given a `Config`.

func SetInstance

func SetInstance(i *Instance) *Instance

SetInstance atomically sets a global `wadge` Instance. SetInstance is safe for concurrent use.

func (Instance) Call

func (i Instance) Call(instance string, name string, args ...unsafe.Pointer) error

Call calls function `name` within `instance` with arguments passed according to `cabish` specification