wapc

README

waPC Guest Library for TinyGo

Note: Consider this SDK experimental. We have yet to put it through more advanced use cases than "hello world".

This is the TinyGo implementation of the waPC standard for WebAssembly guest modules. It allows any waPC-compliant WebAssembly host to invoke to procedures inside a TinyGo compiled guest and similarly for the guest to invoke procedures exposed by the host.

Example

The following is a simple example of synchronous, bi-directional procedure calls between a WebAssembly host runtime and the guest module.

package main

import (
	wapc "github.com/wapc/wapc-guest-tinygo"
)

func main() {
	wapc.Register(wapc.Functions{
		"hello": hello,
	})
}

func hello(payload []byte) ([]byte, error) {
	wapc.HostCall("myBinding", "sample", "hello", []byte("Simon"))
	return []byte("Hello"), nil
}

tinygo build -o example/hello.wasm -target wasm -no-debug example/hello.go

Known limitations

• Only go up to 1.13 is supported by TinyGo
• The fmt package requires syscall/js.* which are not imported by the waPC host
• TinyGo has limited reflect package support, thus libraries like protobuf will likely not work
• No garbage collector - memory allocation occurs in this library

Documentation

Index

• func HostCall(binding, namespace, operation string, payload []byte) ([]byte, error)
• func Register(functions Functions)
• type Function
• type Functions
• type HostError
  • func (e *HostError) Error() string

Functions

func HostCall

func HostCall(binding, namespace, operation string, payload []byte) ([]byte, error)

HostCall invokes an operation on the host. The host uses `namespace` and `operation` to route to the `payload` to the appropriate operation. The host will return a response payload if successful.

func Register

func Register(functions Functions)

Register adds functions by name to the registery. This should be invoked in `main()`.

Types

type Function

type Function func(payload []byte) ([]byte, error)

Function is the function to register in your waPC module.

type Functions

type Functions map[string]Function

Functions is a map of function name to `Function`.

type HostError

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

HostError indicates an error when invoking a host operation.

func (*HostError) Error

func (e *HostError) Error() string