Documentation
¶
Overview ¶
Package wasm runs out-of-process codegen plugins as sandboxed WebAssembly modules via wazero (pure-Go, no CGO). The host serializes the IR contract (internal/plugin/contract) to a plugin's stdin and reads the response from stdout. Plugins follow the WASI convention: read all of stdin, write the JSON response to stdout, and exit 0.
The sandbox is deliberately strict (RFC 0002 §4.2): no host filesystem, no network, a fixed memory cap, and a per-run context timeout. A plugin cannot touch anything outside the request bytes it is given.
Index ¶
Constants ¶
const DefaultMemoryLimitPages = 512
DefaultMemoryLimitPages caps plugin memory. Each WebAssembly page is 64 KiB, so 512 pages = 32 MiB. This is the maximum the module may allocate.
const DefaultTimeout = 30 * time.Second
DefaultTimeout bounds a single plugin run. A plugin that does not exit within this window is terminated.
Variables ¶
This section is empty.
Functions ¶
func LoadPlugin ¶
LoadPlugin resolves a Spec to the raw WASM bytes. For a local Path it reads the file (verifying SHA256 if one was given). For a URL it returns a cached blob when present, otherwise downloads it, verifies the SHA256 BEFORE the bytes are returned (and thus before they can run), and caches it under CacheDir/<sha>.wasm.
func Run ¶
Run instantiates the WASM module from wasmBytes, feeds request on stdin, captures stdout as the response, and returns it. The module runs fully sandboxed: no host filesystem mounts, no network, a memory cap, and a context timeout. A non-zero exit yields a *RunError carrying any stderr output.
Types ¶
type RunError ¶
RunError describes a plugin that exited non-zero. It carries the exit code and any captured stderr so the caller can surface a useful diagnostic.
type RunOptions ¶
type RunOptions struct {
// Timeout bounds the run. Zero uses DefaultTimeout.
Timeout time.Duration
// MemoryLimitPages caps plugin memory in 64 KiB pages. Zero uses
// DefaultMemoryLimitPages.
MemoryLimitPages uint32
// Args are the argv passed to the module (argv[0] is conventionally the
// program name). Empty defaults to a single "plugin" arg.
Args []string
}
RunOptions configures a single plugin invocation.
type Spec ¶
type Spec struct {
// Path is a local filesystem path to a .wasm file.
Path string
// URL is an http(s) URL to fetch the .wasm file from. Requires SHA256.
URL string
// SHA256 is the lowercase hex-encoded SHA-256 of the module. Required for URL
// loads; optional (but verified when present) for Path loads.
SHA256 string
// CacheDir is the directory under which fetched modules are cached, keyed by
// sha256. Defaults to ".db-catalyst-cache/plugins" when empty.
CacheDir string
// BaseDir, when set, is prepended to a relative Path so plugin paths can be
// resolved relative to the config file.
BaseDir string
}
Spec identifies where a plugin's WASM module comes from. Exactly one of Path or URL must be set. When URL is set, SHA256 is required and verified before the bytes are ever executed.
Source Files