wazero

README

wazero

WebAssembly is a way to safely run code compiled in other languages. Runtimes execute WebAssembly Modules (Wasm), which are most often binaries with a .wasm extension.

wazero is a WebAssembly 1.0 (20191205) spec compliant runtime written in Go. It has zero dependencies, and doesn't rely on CGO. This means you can run applications in other languages and still keep cross compilation.

Import wazero and extend your Go application with code written in any language!

Example

The best way to learn this and other features you get with wazero is by trying one of our examples. For the impatient, here's how invoking a factorial function looks in wazero:

func main() {
	// Choose the context to use for function calls.
	ctx := context.Background()

	// Read a WebAssembly binary containing an exported "fac" function.
	// * Ex. (func (export "fac") (param i64) (result i64) ...
	source, _ := os.ReadFile("./tests/bench/testdata/fac.wasm")

	// Instantiate the module and return its exported functions
	module, _ := wazero.NewRuntime().InstantiateModuleFromCode(ctx, source)
	defer module.Close()

	// Discover 7! is 5040
	fmt.Println(module.ExportedFunction("fac").Call(ctx, 7))
}

Note: While the source for this is in the WebAssembly 1.0 (20191205) Text Format, it could have been written in another language that compiles to (targets) WebAssembly, such as AssemblyScript, C, C++, Rust, TinyGo or Zig.

Deeper dive

The former example is a pure function. While a good start, you probably are wondering how to do something more realistic, like read a file. WebAssembly Modules (Wasm) are sandboxed similar to containers. They can't read anything on your machine unless you explicitly allow it.

The WebAssembly Core Specification is a standard, governed by W3C process, but it has no scope to specify how system resources like files are accessed. Instead, WebAssembly defines "host functions" and the signatures they can use. In wazero, "host functions" are written in Go, and let you do anything including access files. The main constraint is that WebAssembly only allows numeric types.

For example, you can grant WebAssembly code access to your console by exporting a function written in Go. The below function can be imported into standard WebAssembly as the module "env" and the function name "log_i32".

env, err := r.NewModuleBuilder("env").
	ExportFunction("log_i32", func(v uint32) {
		fmt.Println("log_i32 >>", v)
	}).
	Instantiate(ctx)
if err != nil {
	log.Fatal(err)
}
defer env.Close()

While not a standards body like W3C, there is another dominant community in the WebAssembly ecosystem: The Bytecode Alliance. The Bytecode Alliance controls the WebAssembly System Interface (WASI), which is a set of function imports similar to Go's x/sys/unix. The "wasi_snapshot_preview1" version of WASI is widely implemented, so wazero bundles an implementation. That way, you don't have to write these functions.

For example, here's how you can allow WebAssembly modules to read "/work/home/a.txt" as "/a.txt" or "./a.txt":

wm, err := wasi.InstantiateSnapshotPreview1(ctx, r)
defer wm.Close()

config := wazero.ModuleConfig().WithFS(os.DirFS("/work/home"))
module, err := r.InstantiateModule(ctx, binary, config)
defer module.Close()
...

While we hope this deeper dive was useful, we also provide examples to elaborate each point. Please try these before raising usage questions as they may answer them for you!

Runtime

There are two runtime configurations supported in wazero, where JIT is default:

1. Interpreter: a naive interpreter-based implementation of Wasm virtual machine. Its implementation doesn't have any platform (GOARCH, GOOS) specific code, therefore interpreter can be used for any compilation target available for Go (such as riscv64).
2. JIT: compiles WebAssembly modules, generates the machine code, and executing it all at runtime. Currently wazero implements the JIT compiler for amd64 and arm64 target. Generally speaking, JIT is faster than Interpreter by order of magnitude. However, the implementation is immature and has a bunch of aspects that could be improved (for example, it just does a singlepass compilation and doesn't do any optimizations, etc.). Please refer to internal/wasm/jit/RATIONALE.md for the design choices and considerations in our JIT compiler.

Both configurations pass 100% of WebAssembly spec test suites (on supported platforms).

Runtime	Usage	amd64	arm64	others
Interpreter	wazero.NewRuntimeConfigInterpreter()	✅	✅	✅
JIT	wazero.NewRuntimeConfigJIT()	✅	✅	❌

If you don't choose, ex wazero.NewRuntime(), JIT is used if supported. You can also force the interpreter like so:

r := wazero.NewRuntimeWithConfig(wazero.NewRuntimeConfigInterpreter())

Support Policy

The below support policy focuses on compatability concerns of those embedding wazero into their Go applications.

wazero

wazero is an early project, so APIs are subject to change until version 1.0.

We expect 1.0 to be at or before Q3 2022, so please practice the current APIs to ensure they work for you!

Go

wazero has no dependencies except Go, so the only source of conflict in your project's use of Wazero is the Go version.

To simplify our support policy, we adopt Go's Release Policy (two versions).

This means wazero will remain compilable and tested on the the version prior to the latest release of Go.

For example, once Go 1.29 is released, wazero may choose to use a Go 1.28 feature.

Platform

wazero has two runtime modes: Interpreter and JIT. The only supported operating systems are ones we test, but that doesn't necessarily mean other operating system versions won't work.

We currently test Linux (Ubuntu and scratch), MacOS and Windows as packaged by GitHub Actions.

• Interpreter
  • Linux is tested on amd64 (native) as well arm64 and riscv64 via emulation.
  • MacOS and Windows are only tested on amd64.
• JIT
  • Linux is tested on amd64 (native) as well arm64 via emulation.
  • MacOS and Windows are only tested on amd64.

wazero has no dependencies and doesn't require CGO. This means it can also be embedded in an application that doesn't use an operating system. This is a main differentiator between wazero and alternatives.

We verify wazero's independence by running tests in Docker's scratch image. This approach ensures compatibility with any parent image.

Standards Compliance

wazero understands that while no-one desired to create confusion, confusion exists both in what is a standard and what in practice is in fact a standard feature. To help with this, we created some guidance both on the status quo of WebAssembly portability and what we support.

The WebAssembly Core Specification 1.0 (20191205) is the only part of the WebAssembly ecosystem that is a W3C recommendation.

In practice, this specification is not enough. Most compilers that target Wasm rely on features that have not yet gone through W3C recommendation process, such as bulk-memory-operations.

Also, most compilers implement system calls using the WebAssembly System Interface (WASI). While WASI aims to be a common layer for portability, it is not governed by a standards body, like W3C. Moreover, while commonly implemented, WASI is not yet versioned. Its last stable point was the "wasi_snapshot_preview1" tag released at the end of 2020.

While this seems scary, the confusion caused by non-standard features and non-standard specifications is not as bad as it sounds. The WebAssembly ecosystem is generally responsive regardless of where things are written down and wazero provides tools, such as built-in support for WASI, to reduce pain.

The goal of this section isn't to promote a W3C recommendation exclusive approach, rather to help you understand common language around portable features and which of those wazero supports at the moment. While we consider features formalized through W3C recommendation status mandatory, we actively pursue non-standard features as well interop with commonly used infrastructure such as AssemblyScript.

In summary, we hope this section can guide you in terms of what wazero supports as well as how to classify a request for a feature we don't yet support.

WebAssembly Core

wazero supports the only WebAssembly specification which has reached W3C Recommendation (REC) phase: WebAssembly Core Specification 1.0 (20191205).

Independent verification is possible via the WebAssembly spec test suite, which we run on every change and against all supported platforms.

One current limitation of wazero is that it doesn't fully implement the Text Format, yet, e.g. compiling .wat files. The intent is to finish this, and meanwhile users can work around this using tools such as wat2wasm to compile the text format into the binary format.

Post 1.0 Features

The last W3C REC was at the end of 2019. There were other features that didn't make the cut or were developed in the years since. The community unofficially refers to these as Finished Proposals.

To ensure compatability, wazero does not opt-in to any non-standard feature by default. However, the following status covers what's currently possible with wazero.RuntimeConfig.

Feature	Status
mutable-global	✅
nontrapping-float-to-int-conversions	❌
sign-extension-ops	✅
multi-value	✅
JS-BigInt-integration	N/A
reference-types	❌
bulk-memory-operations	❌
simd	❌

Note: While the above are specified in a WebAssembly GitHub repository, they are not W3C recommendations (standards). This means they can change further between now and any future update to the W3C WebAssembly core specification. Due to this, we cannot guarantee future compatability. Please encourage the WebAssembly community to formalize features you rely on, specifically to reach the W3C recommendation (REC) phase.

WebAssembly System Interface (WASI)

As of early 2022, the WebAssembly System Interface (WASI) has never reached the recommendation phase of the W3C. The closest to stability is a draft (snapshot-01) released in late 2020. Some functions of this draft are used in practice while some features are not known to be used at all. Further confusion exists because some compilers (ex GrainLang) import functions not used. Finally, snapshot-01 includes features such as "rights" that will be removed.

For all of these reasons, wazero will not implement all WASI features, just to complete the below chart. If you desire something not yet implemented, please raise an issue and include your use case (ex which language you are using to compile, a.k.a. target Wasm).

Click to see the full list of supported WASI systemcalls

Function	Status	Known Usage
args_get	✅	TinyGo
args_sizes_get	✅	TinyGo
environ_get	✅	TinyGo
environ_sizes_get	✅	TinyGo
clock_res_get	❌
clock_time_get	✅	TinyGo
fd_advise	❌
fd_allocate	❌
fd_close	✅	TinyGo
fd_datasync	❌
fd_fdstat_get	✅	TinyGo
fd_fdstat_set_flags	❌
fd_fdstat_set_rights	❌
fd_filestat_get	❌
fd_filestat_set_size	❌
fd_filestat_set_times	❌
fd_pread	❌
fd_prestat_get	✅	TinyGo,fs.FS
fd_prestat_dir_name	✅	TinyGo
fd_pwrite	❌
fd_read	✅	TinyGo,fs.FS
fd_readdir	❌
fd_renumber	❌
fd_seek	✅	TinyGo
fd_sync	❌
fd_tell	❌
fd_write	✅	fs.FS
path_create_directory	❌
path_filestat_get	❌
path_filestat_set_times	❌
path_link	❌
path_open	✅	TinyGo,fs.FS
path_readlink	❌
path_remove_directory	❌
path_rename	❌
path_symlink	❌
path_unlink_file	❌
poll_oneoff	✅	TinyGo
proc_exit	✅	AssemblyScript
proc_raise	❌
sched_yield	❌
random_get	✅
sock_recv	❌
sock_send	❌
sock_shutdown	❌

History of wazero

wazero was originally developed by Takeshi Yoneda as a hobby project in mid 2020. In late 2021, it was sponsored by Tetrate as a top-level project. That said, Takeshi's original motivation is as relevant today as when he started the project, and worthwhile reading:

If you want to provide Wasm host environments in your Go programs, currently there's no other choice than using CGO andleveraging the state-of-the-art runtimes written in C++/Rust (e.g. V8, Wasmtime, Wasmer, WAVM, etc.), and there's no pure Go Wasm runtime out there. (There's only one exception named wagon, but it was archived with the mention to this project.)

First, why do you want to write host environments in Go? You might want to have plugin systems in your Go project and want these plugin systems to be safe/fast/flexible, and enable users to write plugins in their favorite languages. That's where Wasm comes into play. You write your own Wasm host environments and embed Wasm runtime in your projects, and now users are able to write plugins in their own favorite lanugages (AssembyScript, C, C++, Rust, Zig, etc.). As a specific example, you maybe write proxy severs in Go and want to allow users to extend the proxy via Proxy-Wasm ABI. Maybe you are writing server-side rendering applications via Wasm, or OpenPolicyAgent is using Wasm for plugin system.

However, experienced Golang developers often avoid using CGO because it introduces complexity. For example, CGO projects are larger and complicated to consume due to their libc + shared library dependency. Debugging is more difficult for Go developers when most of a library is written in Rustlang. CGO is not Go -- Rob Pike dives in deeper. In short, the primary motivation to start wazero was to avoid CGO.

wazero compiles WebAssembly modules into native assembly (JIT) by default. You may be surprised to find equal or better performance vs mature JIT-style runtimes because CGO is slow. More specifically, if you make large amount of CGO calls which cross the boundary between Go and C (stack) space, then the usage of CGO could be a bottleneck.

Documentation

Overview

Example

This is an example of how to use WebAssembly via adding two numbers.

See https://github.com/heeus/hwazero/tree/main/examples for more examples.

// Choose the context to use for function calls.
ctx := context.Background()

// Create a new WebAssembly Runtime.
r := NewRuntime()

// Add a module to the runtime named "wasm/math" which exports one function "add", implemented in WebAssembly.
mod, err := r.InstantiateModuleFromCode(ctx, []byte(`(module $wasm/math
    (func $add (param i32 i32) (result i32)
        local.get 0
        local.get 1
        i32.add
    )
    (export "add" (func $add))
)`))
if err != nil {
	log.Fatal(err)
}
defer mod.Close()

// Get a function that can be reused until its module is closed:
add := mod.ExportedFunction("add")

x, y := uint64(1), uint64(2)
results, err := add.Call(ctx, x, y)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("%s: %d + %d = %d\n", mod.Name(), x, y, results[0])

Output:

wasm/math: 1 + 2 = 3

Index

• Constants
• type CompiledCode
  • func (c *CompiledCode) Close()
• type ModuleBuilder
• type ModuleConfig
  • func NewModuleConfig() *ModuleConfig
  • func (c *ModuleConfig) WithArgs(args ...string) *ModuleConfig
  • func (c *ModuleConfig) WithEnv(key, value string) *ModuleConfig
  • func (c *ModuleConfig) WithFS(fs fs.FS) *ModuleConfig
  • func (c *ModuleConfig) WithImport(oldModule, oldName, newModule, newName string) *ModuleConfig
  • func (c *ModuleConfig) WithImportModule(oldModule, newModule string) *ModuleConfig
  • func (c *ModuleConfig) WithName(name string) *ModuleConfig
  • func (c *ModuleConfig) WithStartFunctions(startFunctions ...string) *ModuleConfig
  • func (c *ModuleConfig) WithStderr(stderr io.Writer) *ModuleConfig
  • func (c *ModuleConfig) WithStdin(stdin io.Reader) *ModuleConfig
  • func (c *ModuleConfig) WithStdout(stdout io.Writer) *ModuleConfig
  • func (c *ModuleConfig) WithWorkDirFS(fs fs.FS) *ModuleConfig
• type Runtime
  • func NewRuntime() Runtime
  • func NewRuntimeWithConfig(config *RuntimeConfig) Runtime
• type RuntimeConfig
  • func NewRuntimeConfig() *RuntimeConfig
  • func NewRuntimeConfigInterpreter() *RuntimeConfig
  • func NewRuntimeConfigJIT() *RuntimeConfig
  • func (c *RuntimeConfig) WithFeatureMultiValue(enabled bool) *RuntimeConfig
  • func (c *RuntimeConfig) WithFeatureMutableGlobal(enabled bool) *RuntimeConfig
  • func (c *RuntimeConfig) WithFeatureSignExtensionOps(enabled bool) *RuntimeConfig
  • func (c *RuntimeConfig) WithFinishedFeatures() *RuntimeConfig
  • func (c *RuntimeConfig) WithMemoryMaxPages(memoryMaxPages uint32) *RuntimeConfig

Examples

• Package

Constants

const JITSupported = true

Types

type CompiledCode

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

CompiledCode is a WebAssembly 1.0 (20191205) module ready to be instantiated (Runtime.InstantiateModule) as an\ api.Module.

Note: In WebAssembly language, this is a decoded, validated, and possibly also compiled module. wazero avoids using the name "Module" for both before and after instantiation as the name conflation has caused confusion. See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#semantic-phases%E2%91%A0

func (*CompiledCode) Close

func (c *CompiledCode) Close()

Close releases all the allocated resources for this CompiledCode.

Note: it is safe to call Close while having outstanding calls from Modules instantiated from this *CompiledCode.

type ModuleBuilder

type ModuleBuilder interface {

	// ExportFunction adds a function written in Go, which a WebAssembly module can import.
	//
	// * name - the name to export. Ex "random_get"
	// * goFunc - the `func` to export.
	//
	// Noting a context exception described later, all parameters or result types must match WebAssembly 1.0 (20191205) value
	// types. This means uint32, uint64, float32 or float64. Up to one result can be returned.
	//
	// Ex. This is a valid host function:
	//
	//	addInts := func(x uint32, uint32) uint32 {
	//		return x + y
	//	}
	//
	// Host functions may also have an initial parameter (param[0]) of type context.Context or api.Module.
	//
	// Ex. This uses a Go Context:
	//
	//	addInts := func(m context.Context, x uint32, uint32) uint32 {
	//		// add a little extra if we put some in the context!
	//		return x + y + m.Value(extraKey).(uint32)
	//	}
	//
	// Ex. This uses an api.Module to reads the parameters from memory. This is important because there are only numeric
	// types in Wasm. The only way to share other data is via writing memory and sharing offsets.
	//
	//	addInts := func(m api.Module, offset uint32) uint32 {
	//		x, _ := m.Memory().ReadUint32Le(offset)
	//		y, _ := m.Memory().ReadUint32Le(offset + 4) // 32 bits == 4 bytes!
	//		return x + y
	//	}
	//
	// If both parameters exist, they must be in order at positions zero and one.
	//
	// Ex. This uses propagates context properly when calling other functions exported in the api.Module:
	//	callRead := func(ctx context.Context, m api.Module, offset, byteCount uint32) uint32 {
	//		fn = m.ExportedFunction("__read")
	//		results, err := fn(ctx, offset, byteCount)
	//	--snip--
	//
	// Note: If a function is already exported with the same name, this overwrites it.
	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#host-functions%E2%91%A2
	ExportFunction(name string, goFunc interface{}) ModuleBuilder

	// ExportFunctions is a convenience that calls ExportFunction for each key/value in the provided map.
	ExportFunctions(nameToGoFunc map[string]interface{}) ModuleBuilder

	// ExportMemory adds linear memory, which a WebAssembly module can import and become available via api.Memory.
	//
	// * name - the name to export. Ex "memory" for wasi.ModuleSnapshotPreview1
	// * minPages - the possibly zero initial size in pages (65536 bytes per page).
	//
	// For example, the WebAssembly 1.0 Text Format below is the equivalent of this builder method:
	//	// (memory (export "memory") 1)
	//	builder.ExportMemory(1)
	//
	// Note: This is allowed to grow to RuntimeConfig.WithMemoryMaxPages (4GiB). To bound it, use ExportMemoryWithMax.
	// Note: If a memory is already exported with the same name, this overwrites it.
	// Note: Version 1.0 (20191205) of the WebAssembly spec allows at most one memory per module.
	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#memory-section%E2%91%A0
	ExportMemory(name string, minPages uint32) ModuleBuilder

	// ExportMemoryWithMax is like ExportMemory, but can prevent overuse of memory.
	//
	// For example, the WebAssembly 1.0 Text Format below is the equivalent of this builder method:
	//	// (memory (export "memory") 1 1)
	//	builder.ExportMemoryWithMax(1, 1)
	//
	// Note: maxPages must be at least minPages and no larger than RuntimeConfig.WithMemoryMaxPages
	ExportMemoryWithMax(name string, minPages, maxPages uint32) ModuleBuilder

	// ExportGlobalI32 exports a global constant of type api.ValueTypeI32.
	//
	// For example, the WebAssembly 1.0 Text Format below is the equivalent of this builder method:
	//	// (global (export "canvas_width") i32 (i32.const 1024))
	//	builder.ExportGlobalI32("canvas_width", 1024)
	//
	// Note: If a global is already exported with the same name, this overwrites it.
	// Note: The maximum value of v is math.MaxInt32 to match constraints of initialization in binary format.
	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#value-types%E2%91%A0
	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#syntax-globaltype
	ExportGlobalI32(name string, v int32) ModuleBuilder

	// ExportGlobalI64 exports a global constant of type api.ValueTypeI64.
	//
	// For example, the WebAssembly 1.0 Text Format below is the equivalent of this builder method:
	//	// (global (export "start_epoch") i64 (i64.const 1620216263544))
	//	builder.ExportGlobalI64("start_epoch", 1620216263544)
	//
	// Note: If a global is already exported with the same name, this overwrites it.
	// Note: The maximum value of v is math.MaxInt64 to match constraints of initialization in binary format.
	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#value-types%E2%91%A0
	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#syntax-globaltype
	ExportGlobalI64(name string, v int64) ModuleBuilder

	// ExportGlobalF32 exports a global constant of type api.ValueTypeF32.
	//
	// For example, the WebAssembly 1.0 Text Format below is the equivalent of this builder method:
	//	// (global (export "math/pi") f32 (f32.const 3.1415926536))
	//	builder.ExportGlobalF32("math/pi", 3.1415926536)
	//
	// Note: If a global is already exported with the same name, this overwrites it.
	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#syntax-globaltype
	ExportGlobalF32(name string, v float32) ModuleBuilder

	// ExportGlobalF64 exports a global constant of type api.ValueTypeF64.
	//
	// For example, the WebAssembly 1.0 Text Format below is the equivalent of this builder method:
	//	// (global (export "math/pi") f64 (f64.const 3.14159265358979323846264338327950288419716939937510582097494459))
	//	builder.ExportGlobalF64("math/pi", 3.14159265358979323846264338327950288419716939937510582097494459)
	//
	// Note: If a global is already exported with the same name, this overwrites it.
	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#syntax-globaltype
	ExportGlobalF64(name string, v float64) ModuleBuilder

	// Build returns a module to instantiate, or returns an error if any of the configuration is invalid.
	Build(ctx context.Context) (*CompiledCode, error)

	// Instantiate is a convenience that calls Build, then Runtime.InstantiateModule
	//
	// Note: Fields in the builder are copied during instantiation: Later changes do not affect the instantiated result.
	Instantiate(ctx context.Context) (api.Module, error)
}

ModuleBuilder is a way to define a WebAssembly 1.0 (20191205) in Go.

Ex. Below defines and instantiates a module named "env" with one function:

ctx := context.Background()
hello := func() {
	fmt.Fprintln(stdout, "hello!")
}
env, _ := r.NewModuleBuilder("env").ExportFunction("hello", hello).Instantiate(ctx)

If the same module may be instantiated multiple times, it is more efficient to separate steps. Ex.

env, _ := r.NewModuleBuilder("env").ExportFunction("get_random_string", getRandomString).Build(ctx)

env1, _ := r.InstantiateModuleWithConfig(ctx, env, NewModuleConfig().WithName("env.1"))
defer env1.Close()

env2, _ := r.InstantiateModuleWithConfig(ctx, env, NewModuleConfig().WithName("env.2"))
defer env2.Close()

Note: Builder methods do not return errors, to allow chaining. Any validation errors are deferred until Build. Note: Insertion order is not retained. Anything defined by this builder is sorted lexicographically on Build.

type ModuleConfig

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

ModuleConfig configures resources needed by functions that have low-level interactions with the host operating system. Using this, resources such as STDIN can be isolated (ex via StartWASICommandWithConfig), so that the same module can be safely instantiated multiple times.

Note: While wazero supports Windows as a platform, host functions using ModuleConfig follow a UNIX dialect. See RATIONALE.md for design background and relationship to WebAssembly System Interfaces (WASI).

func NewModuleConfig

func NewModuleConfig() *ModuleConfig

func (*ModuleConfig) WithArgs

func (c *ModuleConfig) WithArgs(args ...string) *ModuleConfig

WithArgs assigns command-line arguments visible to an imported function that reads an arg vector (argv). Defaults to none.

These values are commonly read by the functions like "args_get" in "wasi_snapshot_preview1" although they could be read by functions imported from other modules.

Similar to os.Args and exec.Cmd Env, many implementations would expect a program name to be argv[0]. However, neither WebAssembly nor WebAssembly System Interfaces (WASI) define this. Regardless, you may choose to set the first argument to the same value set via WithName.

Note: This does not default to os.Args as that violates sandboxing. Note: Runtime.InstantiateModule errs if any value is empty. See https://linux.die.net/man/3/argv See https://en.wikipedia.org/wiki/Null-terminated_string

func (*ModuleConfig) WithEnv

func (c *ModuleConfig) WithEnv(key, value string) *ModuleConfig

WithEnv sets an environment variable visible to a Module that imports functions. Defaults to none.

Validation is the same as os.Setenv on Linux and replaces any existing value. Unlike exec.Cmd Env, this does not default to the current process environment as that would violate sandboxing. This also does not preserve order.

Environment variables are commonly read by the functions like "environ_get" in "wasi_snapshot_preview1" although they could be read by functions imported from other modules.

While similar to process configuration, there are no assumptions that can be made about anything OS-specific. For example, neither WebAssembly nor WebAssembly System Interfaces (WASI) define concerns processes have, such as case-sensitivity on environment keys. For portability, define entries with case-insensitively unique keys.

Note: Runtime.InstantiateModule errs if the key is empty or contains a NULL(0) or equals("") character. See https://linux.die.net/man/3/environ See https://en.wikipedia.org/wiki/Null-terminated_string

func (*ModuleConfig) WithFS

func (c *ModuleConfig) WithFS(fs fs.FS) *ModuleConfig

WithFS assigns the file system to use for any paths beginning at "/". Defaults to not found.

Ex. This sets a read-only, embedded file-system to serve files under the root ("/") and working (".") directories:

//go:embed testdata/index.html
var testdataIndex embed.FS

rooted, err := fs.Sub(testdataIndex, "testdata")
require.NoError(t, err)

// "index.html" is accessible as both "/index.html" and "./index.html" because we didn't use WithWorkDirFS.
config := wazero.NewModuleConfig().WithFS(rooted)

Note: This sets WithWorkDirFS to the same file-system unless already set.

func (*ModuleConfig) WithImport

func (c *ModuleConfig) WithImport(oldModule, oldName, newModule, newName string) *ModuleConfig

WithImport replaces a specific import module and name with a new one. This allows you to break up a monolithic module imports, such as "env". This can also help reduce cyclic dependencies.

For example, if a module was compiled with one module owning all imports:

(import "js" "tbl" (table $tbl 4 funcref))
(import "js" "increment" (func $increment (result i32)))
(import "js" "decrement" (func $decrement (result i32)))
(import "js" "wasm_increment" (func $wasm_increment (result i32)))
(import "js" "wasm_decrement" (func $wasm_decrement (result i32)))

Use this function to import "increment" and "decrement" from the module "go" and other imports from "wasm":

config.WithImportModule("js", "wasm")
config.WithImport("wasm", "increment", "go", "increment")
config.WithImport("wasm", "decrement", "go", "decrement")

Upon instantiation, imports resolve as if they were compiled like so:

(import "wasm" "tbl" (table $tbl 4 funcref))
(import "go" "increment" (func $increment (result i32)))
(import "go" "decrement" (func $decrement (result i32)))
(import "wasm" "wasm_increment" (func $wasm_increment (result i32)))
(import "wasm" "wasm_decrement" (func $wasm_decrement (result i32)))

Note: Any WithImport instructions happen in order, after any WithImportModule instructions.

func (*ModuleConfig) WithImportModule

func (c *ModuleConfig) WithImportModule(oldModule, newModule string) *ModuleConfig

WithImportModule replaces every import with oldModule with newModule. This is helpful for modules who have transitioned to a stable status since the underlying wasm was compiled.

For example, if a module was compiled like below, with an old module for WASI:

(import "wasi_unstable" "args_get" (func (param i32, i32) (result i32)))

Use this function to update it to the current version:

config.WithImportModule("wasi_unstable", wasi.ModuleSnapshotPreview1)

See WithImport for a comprehensive example. Note: Any WithImportModule instructions happen in order, before any WithImport instructions.

func (*ModuleConfig) WithName

func (c *ModuleConfig) WithName(name string) *ModuleConfig

WithName configures the module name. Defaults to what was decoded from the module source.

If the source was in WebAssembly 1.0 (20191205) Binary Format, this defaults to what was decoded from the custom name section. Otherwise, if it was decoded from Text Format, this defaults to the module ID stripped of leading '$'.

For example, if the Module was decoded from the text format `(module $math)`, the default name is "math".

See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#name-section%E2%91%A0 See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#custom-section%E2%91%A0 See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#modules%E2%91%A0%E2%91%A2

func (*ModuleConfig) WithStartFunctions

func (c *ModuleConfig) WithStartFunctions(startFunctions ...string) *ModuleConfig

WithStartFunctions configures the functions to call after the module is instantiated. Defaults to "_start".

Note: If any function doesn't exist, it is skipped. However, all functions that do exist are called in order.

func (*ModuleConfig) WithStderr

func (c *ModuleConfig) WithStderr(stderr io.Writer) *ModuleConfig

WithStderr configures where standard error (file descriptor 2) is written. Defaults to io.Discard.

This writer is most commonly used by the functions like "fd_write" in "wasi_snapshot_preview1" although it could be used by functions imported from other modules.

Note: The caller is responsible to close any io.Writer they supply: It is not closed on api.Module Close. Note: This does not default to os.Stderr as that both violates sandboxing and prevents concurrent modules. See https://linux.die.net/man/3/stderr

func (*ModuleConfig) WithStdin

func (c *ModuleConfig) WithStdin(stdin io.Reader) *ModuleConfig

WithStdin configures where standard input (file descriptor 0) is read. Defaults to return io.EOF.

This reader is most commonly used by the functions like "fd_read" in "wasi_snapshot_preview1" although it could be used by functions imported from other modules.

Note: The caller is responsible to close any io.Reader they supply: It is not closed on api.Module Close. Note: This does not default to os.Stdin as that both violates sandboxing and prevents concurrent modules. See https://linux.die.net/man/3/stdin

func (*ModuleConfig) WithStdout

func (c *ModuleConfig) WithStdout(stdout io.Writer) *ModuleConfig

WithStdout configures where standard output (file descriptor 1) is written. Defaults to io.Discard.

This writer is most commonly used by the functions like "fd_write" in "wasi_snapshot_preview1" although it could be used by functions imported from other modules.

Note: The caller is responsible to close any io.Writer they supply: It is not closed on api.Module Close. Note: This does not default to os.Stdout as that both violates sandboxing and prevents concurrent modules. See https://linux.die.net/man/3/stdout

func (*ModuleConfig) WithWorkDirFS

func (c *ModuleConfig) WithWorkDirFS(fs fs.FS) *ModuleConfig

WithWorkDirFS indicates the file system to use for any paths beginning at "./". Defaults to the same as WithFS.

Ex. This sets a read-only, embedded file-system as the root ("/"), and a mutable one as the working directory ("."):

//go:embed appA
var rootFS embed.FS

// Files relative to this source under appA are available under "/" and files relative to "/work/appA" under ".".
config := wazero.NewModuleConfig().WithFS(rootFS).WithWorkDirFS(os.DirFS("/work/appA"))

Note: os.DirFS documentation includes important notes about isolation, which also applies to fs.Sub. As of Go 1.18, the built-in file-systems are not jailed (chroot). See https://github.com/golang/go/issues/42322

type Runtime

type Runtime interface {
	// NewModuleBuilder lets you create modules out of functions defined in Go.
	//
	// Ex. Below defines and instantiates a module named "env" with one function:
	//
	//	ctx := context.Background()
	//	hello := func() {
	//		fmt.Fprintln(stdout, "hello!")
	//	}
	//	_, err := r.NewModuleBuilder("env").ExportFunction("hello", hello).Instantiate(ctx)
	NewModuleBuilder(moduleName string) ModuleBuilder

	// Module returns exports from an instantiated module or nil if there aren't any.
	Module(moduleName string) api.Module

	// CompileModule decodes the WebAssembly 1.0 (20191205) text or binary source or errs if invalid.
	// Any pre-compilation done after decoding the source is dependent on the RuntimeConfig.
	//
	// There are two main reasons to use CompileModule instead of InstantiateModuleFromCode:
	//  * Improve performance when the same module is instantiated multiple times under different names
	//  * Reduce the amount of errors that can occur during InstantiateModule.
	//
	// Note: when `ctx` is nil, it defaults to context.Background.
	// Note: The resulting module name defaults to what was binary from the custom name section.
	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#name-section%E2%91%A0
	CompileModule(ctx context.Context, source []byte) (*CompiledCode, error)

	// InstantiateModuleFromCode instantiates a module from the WebAssembly 1.0 (20191205) text or binary source or
	// errs if invalid.
	//
	// Ex.
	//	ctx := context.Background()
	//	module, _ := wazero.NewRuntime().InstantiateModuleFromCode(ctx, source)
	//	defer module.Close()
	//
	// Note: when `ctx` is nil, it defaults to context.Background.
	// Note: This is a convenience utility that chains CompileModule with InstantiateModule. To instantiate the same
	// source multiple times, use CompileModule as InstantiateModule avoids redundant decoding and/or compilation.
	InstantiateModuleFromCode(ctx context.Context, source []byte) (api.Module, error)

	// InstantiateModuleFromCodeWithConfig is a convenience function that chains CompileModule to
	// InstantiateModuleWithConfig.
	//
	// Ex. To only change the module name:
	//	ctx := context.Background()
	//	r := wazero.NewRuntime()
	//	wasm, _ := r.InstantiateModuleFromCodeWithConfig(ctx, source, wazero.NewModuleConfig().
	//		WithName("wasm")
	//	)
	//	defer wasm.Close()
	//
	// Note: When `ctx` is nil, it defaults to context.Background.
	InstantiateModuleFromCodeWithConfig(ctx context.Context, source []byte, config *ModuleConfig) (api.Module, error)

	// InstantiateModule instantiates the module namespace or errs if the configuration was invalid.
	//
	// Ex.
	//	ctx := context.Background()
	//	r := wazero.NewRuntime()
	//	compiled, _ := r.CompileModule(ctx, source)
	//	defer compiled.Close()
	//	module, _ := r.InstantiateModule(ctx, compiled)
	//	defer module.Close()
	//
	// While CompiledCode is pre-validated, there are a few situations which can cause an error:
	//  * The module name is already in use.
	//  * The module has a table element initializer that resolves to an index outside the Table minimum size.
	//  * The module has a start function, and it failed to execute.
	//
	// Note: When `ctx` is nil, it defaults to context.Background.
	InstantiateModule(ctx context.Context, compiled *CompiledCode) (api.Module, error)

	// InstantiateModuleWithConfig is like InstantiateModule, except you can override configuration such as the module
	// name or ENV variables.
	//
	// For example, you can use this to define different args depending on the importing module.
	//
	//	ctx := context.Background()
	//	r := wazero.NewRuntime()
	//	wasi, _ := wasi.InstantiateSnapshotPreview1(r)
	//	compiled, _ := r.CompileModule(ctx, source)
	//
	//	// Initialize base configuration:
	//	config := wazero.NewModuleConfig().WithStdout(buf)
	//
	//	// Assign different configuration on each instantiation
	//	module, _ := r.InstantiateModuleWithConfig(ctx, compiled, config.WithName("rotate").WithArgs("rotate", "angle=90", "dir=cw"))
	//
	// Note: when `ctx` is nil, it defaults to context.Background.
	// Note: Config is copied during instantiation: Later changes to config do not affect the instantiated result.
	InstantiateModuleWithConfig(ctx context.Context, compiled *CompiledCode, config *ModuleConfig) (mod api.Module, err error)
}

Runtime allows embedding of WebAssembly 1.0 (20191205) modules.

Ex.

ctx := context.Background()
r := wazero.NewRuntime()
compiled, _ := r.CompileModule(ctx, source)
module, _ := r.InstantiateModule(ctx, compiled)
defer module.Close()

See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/

func NewRuntime

func NewRuntime() Runtime

func NewRuntimeWithConfig

func NewRuntimeWithConfig(config *RuntimeConfig) Runtime

NewRuntimeWithConfig returns a runtime with the given configuration.

type RuntimeConfig

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

RuntimeConfig controls runtime behavior, with the default implementation as NewRuntimeConfig

func NewRuntimeConfig

func NewRuntimeConfig() *RuntimeConfig

NewRuntimeConfig returns NewRuntimeConfigJIT

func NewRuntimeConfigInterpreter

func NewRuntimeConfigInterpreter() *RuntimeConfig

NewRuntimeConfigInterpreter interprets WebAssembly modules instead of compiling them into assembly.

func NewRuntimeConfigJIT

func NewRuntimeConfigJIT() *RuntimeConfig

NewRuntimeConfigJIT compiles WebAssembly modules into runtime.GOARCH-specific assembly for optimal performance.

Note: This panics at runtime the runtime.GOOS or runtime.GOARCH does not support JIT. Use NewRuntimeConfig to safely detect and fallback to NewRuntimeConfigInterpreter if needed.

func (*RuntimeConfig) WithFeatureMultiValue

func (c *RuntimeConfig) WithFeatureMultiValue(enabled bool) *RuntimeConfig

WithFeatureMultiValue enables multiple values ("multi-value"). This defaults to false as the feature was not finished in WebAssembly 1.0 (20191205).

This has the following effects: * Function (`func`) types allow more than one result * Block types (`block`, `loop` and `if`) can be arbitrary function types

See https://github.com/WebAssembly/spec/blob/main/proposals/multi-value/Overview.md

func (*RuntimeConfig) WithFeatureMutableGlobal

func (c *RuntimeConfig) WithFeatureMutableGlobal(enabled bool) *RuntimeConfig

WithFeatureMutableGlobal allows globals to be mutable. This defaults to true as the feature was finished in WebAssembly 1.0 (20191205).

When false, an api.Global can never be cast to an api.MutableGlobal, and any source that includes global vars will fail to parse.

func (*RuntimeConfig) WithFeatureSignExtensionOps

func (c *RuntimeConfig) WithFeatureSignExtensionOps(enabled bool) *RuntimeConfig

WithFeatureSignExtensionOps enables sign extension instructions ("sign-extension-ops"). This defaults to false as the feature was not finished in WebAssembly 1.0 (20191205).

This has the following effects: * Adds instructions `i32.extend8_s`, `i32.extend16_s`, `i64.extend8_s`, `i64.extend16_s` and `i64.extend32_s`

See https://github.com/WebAssembly/spec/blob/main/proposals/sign-extension-ops/Overview.md

func (*RuntimeConfig) WithFinishedFeatures

func (c *RuntimeConfig) WithFinishedFeatures() *RuntimeConfig

WithFinishedFeatures enables currently supported "finished" feature proposals. Use this to improve compatibility with tools that enable all features by default.

Note: The features implied can vary and can lead to unpredictable behavior during updates. Note: This only includes "finished" features, but "finished" is not an official W3C term: it is possible that "finished" features do not make the next W3C recommended WebAssembly core specification. See https://github.com/WebAssembly/spec/tree/main/proposals

func (*RuntimeConfig) WithMemoryMaxPages

func (c *RuntimeConfig) WithMemoryMaxPages(memoryMaxPages uint32) *RuntimeConfig

WithMemoryMaxPages reduces the maximum number of pages a module can define from 65536 pages (4GiB) to a lower value.

Notes: * If a module defines no memory max limit, Runtime.CompileModule sets max to this value. * If a module defines a memory max larger than this amount, it will fail to compile (Runtime.CompileModule). * Any "memory.grow" instruction that results in a larger value than this results in an error at runtime. * Zero is a valid value and results in a crash if any module uses memory.

See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#grow-mem See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#memory-types%E2%91%A0