wasm

README

wasm

wasm wrappers for gonix project.

WASM-001: Architecture

wasm/coreutils

Wrappers for uutils coreutils coreutils/README.md.

Releasing - tags

This is a multi-module monorepo.

• wasm codeberg.org/gonix/wasm uses normal vX.Y.Z semantics versioning
• submodules like coreutils uses own go.mod tagged as coreutils/v0.1.0

go.work lists every module. Edits to root visible to subdirs without replace.

Bump when

• new upstream blob → minor (coreutils/v0.2.0)
• Go-side fix, blob same → patch (coreutils/v0.2.1)
• breaking Go API → major (coreutils/v2.0.0)

It makes no sense to try to use the same tag as upstream coreutils.wasm or other file, versions will most likely drift in the future.

Documentation

Overview

Copyright 2026 Michal Vyskocil. All rights reserved. Use of this source code is governed by a MIT license that can be found in the LICENSE file.

Package wasm provides gio helpers for "github.com/tetratelabs/wazero" providing a compatibility layer for WebAssembly binaries. Integration of WebAssembly is a bit complicated, however this module provides helpers making wazero easier to use.

1. NewBuilder returns a Builder that holds mount and compiled cache configurations.
2. Builder.Build creates a Runtime backed by a wazero runtime instance and the builder configuration.
3. Runtime.Compile compiles a wasm binary and return a FilterBuilder.
4. FilterBuilder.BuilderFunc returns a unix.FilterBuilderFunc suitable for any gonix consumer expecting one (sh, xargs, …).

Multicall binaries

Multi-call binaries (one wasm file dispatching multiple subcommands, such as uutils/coreutils) use FilterBuilder.WithMulticall to prepend a fixed argv[0] on every invocation.

codeberg.org/gonix/wasm/coreutils is the reference consumer: it embeds the rust/uutils coreutils.wasm blob and exposes one unix.FilterBuilderFunc per tool.

Mount layering

Filesystem visibility inside the wasm sandbox comes from

• Static mounts on Builder via Builder.WithDirMounts and Builder.WithFSMounts: applied to every Run on every Runtime built from that Builder. Use for read-only system overlays or shared directories.

CWD

The unix.GetDirFunc(ctx) is used to pass the cwd from a shell to the filter. This is passed as PWD environment variable into wasm sandbox.

Implicit compilation cache

wasm creates an implicit wazero.CompilationCache by default. This is shared across all Runtime in a single process. The Builder.WithCacheDir can change the cache to be directory baked

Index

• Constants
• type Builder
  • func NewBuilder() Builder
  • func (b Builder) Build(ctx context.Context) *Runtime
  • func (b *Builder) Close(ctx context.Context) error
  • func (b Builder) WithCacheDir(dir string) (Builder, error)
  • func (b Builder) WithDirMounts(mounts []DirMount) Builder
  • func (b Builder) WithFSMounts(mounts []FSMount) Builder
• type DirMount
• type ExitedError
  • func (e *ExitedError) Error() string
  • func (e *ExitedError) ExitCode() int
  • func (e *ExitedError) Unwrap() error
• type FSMount
• type FilterBuilder
  • func (b FilterBuilder) BuilderFunc(name string) unix.FilterBuilderFunc
  • func (b FilterBuilder) WithMulticall(prefix string) FilterBuilder
• type Runtime
  • func (r *Runtime) Close(ctx context.Context) error
  • func (r *Runtime) Compile(ctx context.Context, binary []byte) (FilterBuilder, error)

Constants

const (
	// ExitCodeTimeout is returned when a command context deadline expires
	// This is the same exit code as GNU timeout(1) returns
	ExitCodeTimeout = 124
	// ExitCodeCanceled is returned if the parent context is canceled
	ExitCodeCanceled = 130
)

Types

type Builder

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

Builder builds a wazero runtime a main shared context for wasm execution - it passes a configuration needed to create one The individual calls Set changes the state of the Builder

func NewBuilder

func NewBuilder() Builder

func (Builder) Build

func (b Builder) Build(ctx context.Context) *Runtime

Build creates new wazero runtime and returns an wasm abstraction It captures the existing state of the builder and further calls to With functions won't affect the created Runtime.

func (*Builder) Close

func (b *Builder) Close(ctx context.Context) error

Close invalidates the on-disk wasm cache if was configured. This uses a pointer receiver, so modify the Builder itself. Calling it twice is safe.

func (Builder) WithCacheDir

func (b Builder) WithCacheDir(dir string) (Builder, error)

WithCacheDir setups dir as a new cache dir. It's an error to call this twice. Return an error if the cache directory can't be setup.

Due the dependency on a fallible resource this can't be chained like other With calls.

func (Builder) WithDirMounts

func (b Builder) WithDirMounts(mounts []DirMount) Builder

WithDirMounts sets the parameters for wazero.FSConfig

func (Builder) WithFSMounts

func (b Builder) WithFSMounts(mounts []FSMount) Builder

WithFSMounts sets the parameters for wazero.FSConfig

type DirMount

type DirMount struct {
	Dir       string
	GuestPath string
	ReadOnly  bool
}

DirMount is a parameter for wazero.WithDirMount or wazero.WithReadOnlyDirMount

type ExitedError

type ExitedError struct {
	Name string
	Argv []string
	Code int
	Err  error
}

func (*ExitedError) Error

func (e *ExitedError) Error() string

func (*ExitedError) ExitCode

func (e *ExitedError) ExitCode() int

ExitCode reads an exit code, which can be propagated

func (*ExitedError) Unwrap

func (e *ExitedError) Unwrap() error

type FSMount

type FSMount struct {
	Dir       fs.FS
	GuestPath string
}

FSMount is a wrapper for wazero.WithFSMount

type FilterBuilder

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

FilterBuilder captures the Runtime and wazero.CompiledModule and exposes FilterBuilder.BuilderFunc which returns new unix.Filter implemented by wazero.

func (FilterBuilder) BuilderFunc

func (b FilterBuilder) BuilderFunc(name string) unix.FilterBuilderFunc

BuilderFunc returns a unix.FilterBuilderFunc - it is intentionally incompatible with unix.FilterLookupFunc pattern as this base layer does not know which commands are exported

func (FilterBuilder) WithMulticall

func (b FilterBuilder) WithMulticall(prefix string) FilterBuilder

WithMulticall sets the binary as a multicall

eg WithMulticall("coreutils") will change argv from echo "hello" to coreutils echo "hello"

type Runtime

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

Runtime connects the builder with a wazero runtime - all builder parameters are passed to the wazero Runtime when compiling the module

func (*Runtime) Close

func (r *Runtime) Close(ctx context.Context) error

Close closes wasm runtime - all compiled modules will be freed, so calling any web assembly code after this is an error

func (*Runtime) Compile

func (r *Runtime) Compile(ctx context.Context, binary []byte) (FilterBuilder, error)

Compile returns the FilterBuilder - which can be used to build individual wasm based filters. Safe to call before or after Runtime.Close