wapc

README

waPC Guest Library for TinyGo

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.RegisterFunctions(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 -scheduler=none --no-debug -target=wasi example/hello.go

Considerations

• It is recommended to use the latest versions Go and TinyGo
• Avoid using the fmt package as it requires syscall/js.* which are not implemented by the waPC host libraries
• TinyGo has limited reflect package support, thus generated Protobuf code will likely not work without some tweaking (But we have gotten it to work!)

Documentation

Index

• func ConsoleLog(msg string)
• func HostCall(binding, namespace, operation string, payload []byte) ([]byte, error)
• func RegisterFunction(name string, fn Function)
• func RegisterFunctions(functions Functions)
• type Function
• type Functions
• type HostError
  • func (e *HostError) Error() string

Functions

func ConsoleLog

func ConsoleLog(msg string)

ConsoleLog writes the message the underlying waPC console logger.

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 RegisterFunction

func RegisterFunction(name string, fn Function)

RegisterFunction adds a single function by name to the registry. This should be invoked in `main()`.

func RegisterFunctions

func RegisterFunctions(functions Functions)

RegisterFunctions adds functions by name to the registry. 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