gojs

README

Overview

When GOOS=js and GOARCH=wasm, Go's compiler targets WebAssembly Binary format (%.wasm).

Wazero's "github.com/tetratelabs/wazero/imports/go" package allows you to run a %.wasm file compiled by Go. This is similar to what is implemented in wasm_exec.js. See https://wazero.io/languages/go/ for more.

Example

wazero includes an example that makes HTTP client requests.

Experimental

Go defines js "EXPERIMENTAL... exempt from the Go compatibility promise." Accordingly, wazero cannot guarantee this will work from release to release, or that usage will be relatively free of bugs. Due to this and the relatively high implementation overhead, most will choose TinyGo instead.

Documentation

Overview

Package gojs allows you to run wasm binaries compiled by Go when `GOARCH=wasm GOOS=js`. See https://wazero.io/languages/go/ for more.

Experimental

Go defines js "EXPERIMENTAL... exempt from the Go compatibility promise." Accordingly, wazero cannot guarantee this will work from release to release, or that usage will be relatively free of bugs. Due to this and the relatively high implementation overhead, most will choose TinyGo instead.

Index

• func Instantiate(ctx context.Context, r wazero.Runtime) (api.Closer, error)
• func MustInstantiate(ctx context.Context, r wazero.Runtime)
• func Run(ctx context.Context, r wazero.Runtime, compiled wazero.CompiledModule, ...) error
• func WithRoundTripper(ctx context.Context, rt http.RoundTripper) context.Context
• type FunctionExporter
  • func NewFunctionExporter() FunctionExporter

Functions

func Instantiate

func Instantiate(ctx context.Context, r wazero.Runtime) (api.Closer, error)

Instantiate instantiates the "go" module, used by `GOARCH=wasm GOOS=js`, into the runtime.

Notes

• Failure cases are documented on wazero.Runtime InstantiateModule.
• Closing the wazero.Runtime has the same effect as closing the result.
• To add more functions to the "env" module, use FunctionExporter.

func MustInstantiate

func MustInstantiate(ctx context.Context, r wazero.Runtime)

MustInstantiate calls Instantiate or panics on error.

This is a simpler function for those who know the module "go" is not already instantiated, and don't need to unload it.

func Run

func Run(ctx context.Context, r wazero.Runtime, compiled wazero.CompiledModule, config wazero.ModuleConfig) error

Run instantiates a new module and calls "run" with the given config.

Parameters

• ctx: context to use when instantiating the module and calling "run".
• r: runtime to instantiate both the host and guest (compiled) module in.
• compiled: guest binary compiled with `GOARCH=wasm GOOS=js`
• config: the configuration such as args, env or filesystem to use.

Example

After compiling your Wasm binary with wazero.Runtime's `CompileModule`, run it like below:

// Use compilation cache to reduce performance penalty of multiple runs.
ctx = experimental.WithCompilationCacheDirName(ctx, ".build")

// Instantiate the host functions used for each call.
gojs.MustInstantiate(r)

// Execute the "run" function, which corresponds to "main" in stars/main.go.
err = gojs.Run(ctx, r, compiled, config)
if exitErr, ok := err.(*sys.ExitError); ok && exitErr.ExitCode() != 0 {
	log.Panicln(err)
} else if !ok {
	log.Panicln(err)
}

Notes

• Use wazero.RuntimeConfig `WithWasmCore2` to avoid needing to pick >1.0 features set by `GOWASM` or used internally by Run.
• Wasm generated by `GOARCH=wasm GOOS=js` is very slow to compile. Use experimental.WithCompilationCacheDirName to improve performance.
• The guest module is closed after being run.

func WithRoundTripper

func WithRoundTripper(ctx context.Context, rt http.RoundTripper) context.Context

WithRoundTripper sets the http.RoundTripper used to Run Wasm.

For example, if the code compiled via `GOARCH=wasm GOOS=js` uses http.RoundTripper, you can avoid failures by assigning an implementation like so:

ctx = gojs.WithRoundTripper(ctx, http.DefaultTransport)
err = gojs.Run(ctx, r, compiled, config)

Types

type FunctionExporter

type FunctionExporter interface {
	// ExportFunctions builds functions to export with a
	// wazero.HostModuleBuilder named "go".
	ExportFunctions(wazero.HostModuleBuilder)
}

FunctionExporter configures the functions in the "go" module used by `GOARCH=wasm GOOS=js`.

func NewFunctionExporter

func NewFunctionExporter() FunctionExporter

NewFunctionExporter returns a FunctionExporter object.