runner

package
v0.1.0 Latest Latest
Warning

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

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

Documentation

Overview

Package runner runs applets in a WebAssembly sandbox.

An applet is a WebAssembly module as produced by the build package, or compatible with it: it exports _start, and transforms a stream of JSON objects according to the protocol below. Besides WASI, it may only import from dependency modules given to NewEngine, such as the Javy plugin for applets built by package build. Each run gets fresh instances of the applet and its dependencies, with no filesystem, no network, a fixed clock and a deterministic random source.

The protocol between host and applet uses the standard streams, one line per message:

  • stdin: the first line is the params (JSON, null if there are none), followed by one input object per line. EOF means the host is done sending input.
  • stdout: one output object per line.
  • stderr: one record per line: {"log": "..."} to log a line, {"done": true} when the applet is done, which must be its last output, or {"error": "...", "stack": "...", "input": <index or null>} when it fails. Lines that are not records are logged as they are.

A run succeeds only if _start returns and the applet reported done.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrMemory is returned when the applet runs out of memory.
	ErrMemory = errors.New("applet exceeded its memory limit")
	// ErrInvalidOutput is returned when the applet writes a line to stdout
	// that is not a JSON object.
	ErrInvalidOutput = errors.New("applet wrote output that is not a JSON object")
	// ErrNotDone is returned when the applet stops without reporting that it
	// is done.
	ErrNotDone = errors.New("applet stopped without reporting that it is done")
	// ErrAfterDone is returned when the applet writes output after
	// reporting that it is done.
	ErrAfterDone = errors.New("applet wrote output after reporting that it is done")
)

Functions

This section is empty.

Types

type Applet

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

Applet is a loaded applet, which can be run many times.

func (*Applet) Close

func (a *Applet) Close(ctx context.Context) error

Close releases the applet.

func (*Applet) Run

func (a *Applet) Run(ctx context.Context, params json.RawMessage, input iter.Seq2[json.RawMessage, error], output func(json.RawMessage) error, log func(string)) error

Run runs the applet once, streaming objects through it:

  • When the applet reads its next input object, Run takes it from input. When input ends, the applet's input ends. If input yields an error, the run stops and Run returns that error. If the applet stops reading early, Run stops input: the iteration's yield returns false.
  • For each object the applet outputs, Run calls output. If output returns an error, the run stops and Run returns that error.
  • For each line the applet logs, Run calls log.

input, output and log are called one at a time, and the applet waits while they do; nothing is read ahead. While input blocks, ctx cannot stop the applet, so input should return when ctx is done. input may be nil for no input, and output and log may be nil to discard what the applet outputs or logs.

func (*Applet) RunAll

func (a *Applet) RunAll(ctx context.Context, params json.RawMessage, inputs []json.RawMessage, log func(string)) ([]json.RawMessage, error)

RunAll runs the applet once on the given input objects, and returns its output objects. It holds all input and output in memory at once, so it is meant for small runs and tests; Run streams them instead. If the run fails, RunAll also returns the output objects from before the failure. It calls log, if not nil, for each line the applet logs.

type AppletError

type AppletError struct {
	Message string
	Stack   string
	// Input is the index of the input object the applet was processing, or -1
	// if it was not processing an input object.
	Input int
}

AppletError is returned when the applet fails.

func (*AppletError) Error

func (e *AppletError) Error() string

type Engine

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

Engine loads and runs applets. It is safe for concurrent use.

func NewEngine

func NewEngine(ctx context.Context, deps map[string][]byte, limits Limits) (*Engine, error)

NewEngine compiles the dependency modules, which applets may import from by their name in deps. Dependencies may only import WASI. Compiling can take a while; create one Engine and reuse it.

func (*Engine) Close

func (e *Engine) Close(ctx context.Context) error

Close releases the engine. Runs in progress fail.

func (*Engine) Load

func (e *Engine) Load(ctx context.Context, wasm []byte) (*Applet, error)

Load compiles an applet module.

type Limits

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

Limits bounds the resources of a run. The time of a run is bounded by the context passed to Run.

func (Limits) WithCloseOnContextDone

func (l Limits) WithCloseOnContextDone(d bool) Limits

WithCloseOnContextDone sets whether cancelling the context passed to Run stops the execution. The default is true. If you set this to false, the performance improves, but the sandbox can continue running forever, so be aware that this breaks the security model.

func (Limits) WithMemoryMiB

func (l Limits) WithMemoryMiB(mebibytes uint32) Limits

WithMemoryMiB bounds each linear memory of an applet and its dependencies. The default is 64 MiB, and 4096 MiB is the WASM limit.

Jump to

Keyboard shortcuts

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