component

package
v0.2.35 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package component runs WebAssembly components (the Component Model, WASI Preview 2) on the same wazero engine that runs WASI Preview 1 modules.

wazero runs core modules only. A component is a set of core modules plus instructions for wiring them together and to the interfaces it imports. This package reads those instructions, instantiates each core module in wazero in the order the component gives, and supplies every imported interface itself. Nothing reaches the host except through the functions in wasi.go: the guest gets standard input and output (the broker's protocol), standard error, its arguments, clocks and random bytes. It gets no preopened directory, no environment variables and no network: socket creation and name lookup are refused, and an import of any interface outside the WASI 0.2 packages listed in allowedPackages is refused when the component is loaded.

Only the synchronous canonical ABI with UTF-8 strings is supported. A component that uses threads, its own resource types or a component import other than a WASI interface is refused with a message that says so. A component that needs WASI Preview 3 (async, streams, futures, the WASI 0.3 interfaces) is recognised by Preview3 and run by the runner in wasmtime; Load refuses it with an error that wraps ErrPreview3.

Index

Constants

This section is empty.

Variables

View Source
var ErrPreview3 = errors.New("the component needs WASI Preview 3")

ErrPreview3 is wrapped by the error Load returns for a component that needs WASI Preview 3, so a caller can tell "run this elsewhere" from "refused".

Functions

func Preview3 added in v0.2.28

func Preview3(b []byte) (p3 bool, why string, err error)

Preview3 reports whether b is a component that needs WASI Preview 3, and why. It returns an error for a Preview 3 component that imports something TAP does not provide; such a component is refused before anything starts. A Preview 2 component, or a binary that is neither, returns false and no error: Load gives that one its own verdict.

Types

type Config

type Config struct {
	Args     []string
	Stdin    io.Reader
	Stdout   io.Writer
	Stderr   io.Writer
	Walltime func() (sec int64, nsec int32)
	Nanotime func() int64
	Rand     io.Reader
}

Config is what a component may see of the host. It mirrors what a WASI Preview 1 guest is given: arguments, the three standard streams, clocks and random bytes. There is deliberately no field for directories, environment variables or network access.

type Format

type Format string

Format is the kind of WebAssembly binary an entrypoint holds.

const (
	// Module is a core WebAssembly module (WASI Preview 1).
	Module Format = "wasip1-module"
	// Component is a WebAssembly component (Component Model, WASI Preview 2).
	Component Format = "wasip2-component"
)

func Detect

func Detect(b []byte) (Format, error)

Detect reads the 8-byte preamble. A core module has version 1 and layer 0; a component has version 0x0d and layer 1. Anything else is refused.

type Program

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

Program is a loaded component: its core modules compiled, its wiring checked, ready to run once in the runtime it was loaded into.

func Load

func Load(ctx context.Context, rt wazero.Runtime, b []byte) (p *Program, err error)

Load parses and checks a component and compiles its core modules in rt. Every import is resolved here, so a component that imports something TAP does not provide is refused before any of it runs.

func (*Program) Run

func (p *Program) Run(ctx context.Context, cfg Config) (err error)

Run instantiates the component's core modules in order and calls its run function. A guest exit with status 0 and a run that returns ok both return nil; failure is a *sys.ExitError, as for a WASI Preview 1 module.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL