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 ¶
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) 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 ¶
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.
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 ¶
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 ¶
WithMemoryMiB bounds each linear memory of an applet and its dependencies. The default is 64 MiB, and 4096 MiB is the WASM limit.