engine

Documentation

Overview

Package engine provides the core WebAssembly execution environment. It securely encapsulates the wazero runtime, handles WASI integration, enforces resource limits, and manages an in-memory cache of compiled plugins.

The primary entry point is NewRunner, which creates a configured Runner instance ready to execute Wasm functions or HTTP requests.

Index

• type Runner
  • func NewRunner(ctx context.Context, cfg RunnerConfig) (*Runner, error)
  • func (r *Runner) Close(ctx context.Context) error
  • func (r *Runner) LoadPlugins(ctx context.Context, dirPath string) error
  • func (r *Runner) RunFunction(ctx context.Context, wasmPath string, funcName string, params ...uint64) ([]uint64, error)
  • func (r *Runner) RunGreet(ctx context.Context, wasmPath string, name string) (string, error)
  • func (r *Runner) RunPlugin(ctx context.Context, pluginName string, funcName string, params ...uint64) ([]uint64, error)
  • func (r *Runner) RunPluginString(ctx context.Context, pluginName string, funcName string, input string) (string, error)
• type RunnerConfig

Types

type Runner

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

Runner handles the secure execution of WebAssembly modules and manages the plugin cache. It depends on RunnerConfig for security constraints.

Create a new Runner with NewRunner:

runner, err := engine.NewRunner(ctx, cfg)
defer runner.Close(ctx)

func NewRunner

func NewRunner(ctx context.Context, cfg RunnerConfig) (*Runner, error)

NewRunner initializes a secure wazero runtime and a new plugin store. It automatically integrates wasi_snapshot_preview1 for secure stdout logging.

func (*Runner) Close

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

Close libera os recursos e o cache.

func (*Runner) LoadPlugins

func (r *Runner) LoadPlugins(ctx context.Context, dirPath string) error

LoadPlugins escaneia um diretório e compila todos os arquivos .wasm encontrados.

func (*Runner) RunFunction

func (r *Runner) RunFunction(ctx context.Context, wasmPath string, funcName string, params ...uint64) ([]uint64, error)

RunFunction carrega um arquivo Wasm e executa uma função numérica genérica.

func (*Runner) RunGreet

func (r *Runner) RunGreet(ctx context.Context, wasmPath string, name string) (string, error)

RunGreet carrega o módulo e executa a lógica de saudação com strings.

func (*Runner) RunPlugin

func (r *Runner) RunPlugin(ctx context.Context, pluginName string, funcName string, params ...uint64) ([]uint64, error)

RunPlugin executa uma função de um plugin específico usando o módulo em cache.

func (*Runner) RunPluginString

func (r *Runner) RunPluginString(ctx context.Context, pluginName string, funcName string, input string) (string, error)

RunPluginString passes a string payload to a cached Wasm plugin and retrieves a string result. It leverages linear memory integration: first allocating memory on the guest, then writing the host string directly into the guest bounds.

type RunnerConfig

type RunnerConfig struct {
	// MaxMemoryPages sets the maximum amount of 64KB pages a module can allocate.
	MaxMemoryPages uint32

	// Timeout enforces a strict deadline on any function execution to prevent infinite loops.
	Timeout time.Duration

	// Stdout defines where guest modules can securely write log output via WASI.
	Stdout io.Writer
}

RunnerConfig defines security boundaries and execution limits for the Wasm environment. It must be passed to NewRunner during initialization.