gojs

README

Overview

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

Wazero's "github.com/tetratelabs/wazero/experimental/gojs" 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. Moreover, GOOS=wasip1 will be shipped in Go 1.21, and once that's available in two releases wazero will remove this package.

Due to these concerns and the relatively high implementation overhead, most will choose TinyGo instead of gojs.

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. Moreover, `GOOS=wasi` will happen, and once that's available in two releases wazero will remove this package.

Due to these concerns and the relatively high implementation overhead, most will choose TinyGo instead of gojs.

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
• type Config
  • func NewConfig(moduleConfig wazero.ModuleConfig) Config
• 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, moduleConfig Config) 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 Config to use including wazero.ModuleConfig or extensions of it.

Example

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

// Instantiate host functions needed by gojs
gojs.MustInstantiate(ctx, r)

// Assign any configuration relevant for your compiled wasm.
config := gojs.NewConfig(wazero.NewConfig())

// Run your wasm, notably handing any ExitError
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

• Wasm generated by `GOARCH=wasm GOOS=js` is very slow to compile: Use wazero.RuntimeConfig with wazero.CompilationCache when re-running the same binary.
• The guest module is closed after being run.

Types

type Config

type Config interface {
	// WithOSWorkdir sets the initial working directory used to Run Wasm to
	// the value of os.Getwd instead of the default of root "/".
	//
	// Here's an example that overrides this to the current directory:
	//
	//	err = gojs.Run(ctx, r, compiled, gojs.NewConfig(moduleConfig).
	//			WithOSWorkdir())
	//
	// Note: To use this feature requires mounting the real root directory via
	// wazero.FSConfig `WithDirMount`. On windows, this root must be the same drive
	// as the value of os.Getwd. For example, it would be an error to mount `C:\`
	// as the guest path "", while the current directory is inside `D:\`.
	WithOSWorkdir() Config

	// WithOSUser allows the guest to see the current user's uid, gid, euid and
	// groups, instead of zero for each value.
	//
	// Here's an example that uses the real user's IDs:
	//
	//	err = gojs.Run(ctx, r, compiled, gojs.NewConfig(moduleConfig).
	//			WithOSUser())
	//
	// Note: This has no effect on windows.
	WithOSUser() Config

	// 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:
	//
	//	err = gojs.Run(ctx, r, compiled, gojs.NewConfig(moduleConfig).
	//			WithRoundTripper(ctx, http.DefaultTransport))
	WithRoundTripper(http.RoundTripper) Config
}

Config extends wazero.ModuleConfig with GOOS=js specific extensions. Use NewConfig to create an instance.

func NewConfig

func NewConfig(moduleConfig wazero.ModuleConfig) Config

NewConfig returns a Config that can be used for configuring module instantiation.

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.