wasm

type ByteMeter ¶

type ByteMeter interface {
	AddIn(n int64)
	AddOut(n int64)
}

ByteMeter accumulates sandbox network byte counters (UC-43).

type Capabilities ¶

type Capabilities struct {
	Env           map[string]string `json:"env,omitempty"`
	Preopens      []Preopen         `json:"preopens,omitempty"`
	Args          []string          `json:"args,omitempty"`
	MemoryMB      int               `json:"memory_mb,omitempty"`
	WallTimeoutNs int64             `json:"wall_timeout_ns,omitempty"`
	// WASIListenPort enables wasip1 pre-open TCP listeners when >= 0 (0 = ephemeral).
	// When unset, use -1 to disable.
	WASIListenPort int    `json:"wasi_listen_port,omitempty"`
	WASIListenHost string `json:"wasi_listen_host,omitempty"`
}

Capabilities configures WASI preopens, env, args, and resource limits for an instance.

func CapsFromResourceLimits(base Capabilities, memoryMB int, wallTimeout time.Duration) Capabilities

func (c Capabilities) ListenEnabled() bool

type Engine ¶

type Engine interface {
	// LoadModule compiles bytes from path. Idempotent per path within one engine.
	LoadModule(ctx context.Context, path string, opts LoadOptions) error
	// Instantiate creates a runnable instance with the given capabilities.
	Instantiate(ctx context.Context, caps Capabilities) error
	// InvokeExport calls an exported function by name.
	InvokeExport(ctx context.Context, name string) error
	// Run re-instantiates with caps, invokes export, and captures stdout/stderr.
	Run(ctx context.Context, caps Capabilities, export string) (RunResult, error)
	// StopInstance tears down the active instance but keeps the compiled module.
	StopInstance(ctx context.Context) error
	// CaptureSnapshot exports linear memory from the active instance.
	CaptureSnapshot(ctx context.Context) (SnapshotCapture, error)
	// RestoreSnapshot re-instantiates and loads memory from a capture.
	RestoreSnapshot(ctx context.Context, snap SnapshotRestoreInput, caps Capabilities) error
	// Close releases compiled module and any active instance.
	Close(ctx context.Context) error
	// ResolvedListenPort returns the host port for an ephemeral wasip1 listener (0 in caps).
	ResolvedListenPort() (int, bool)
	// SupportsListen reports whether the engine can host a wasip1 TCP listener
	// (the HTTP ingress / expose_port path). wazero can; the wasmtime backend
	// cannot yet (see plans/wasm-runtime.md "Still open"). Callers must reject
	// listen requests up front rather than silently failing to resolve a port.
	SupportsListen() bool
}

Engine compiles and runs a single WASM module with WASI.

func NewEngine(ctx context.Context) (Engine, error)

func NewEngineFor(ctx context.Context, name string) (Engine, error)

type LoadOptions ¶

type LoadOptions struct {
	MemoryMB int
}

LoadOptions carries per-load engine configuration. MemoryMB sets the wazero runtime memory-limit pages before compilation so a later Instantiate with the same cap does not rebuild the runtime (plans/wasm-create-latency.md Phase 1).

type LoadTimingReporter ¶

type LoadTimingReporter interface {
	LastLoadTimings() LoadTimings
}

LoadTimingReporter is an optional engine capability: an engine that implements it exposes the sub-stage breakdown of its most recent LoadModule. It is type-asserted by the worker (like NetworkAwareEngine) so the base Engine interface — and the wasmtime backend and the test mocks that implement it — stay untouched.

type LoadTimings ¶

type LoadTimings struct {
	NewEngine   time.Duration `json:"new_engine_ns,omitempty"`
	RuntimeInit time.Duration `json:"runtime_init_ns,omitempty"`
	Read        time.Duration `json:"read_ns,omitempty"`
	Compile     time.Duration `json:"compile_ns,omitempty"`
}

LoadTimings breaks the cold-create wasm_load stage into its sub-costs. It exists because a single wasm_load timer told us the stage was ~2.8s p50 for CPython on t3.medium but not WHICH step owned it — and the firecracker create-latency episode proved that guessing the dominant sub-cost before measuring it burns effort on the wrong lever. Splitting the timer lets the create path emit per-step Server-Timing entries so the resident-module work (plans/wasm-resident-module-host.md) targets the real bottleneck.

The fields mirror the cold LoadModule sequence in the worker:

NewEngine   — worker: NewEngineFor builds the first wazero runtime + WASI.
RuntimeInit — engine: LoadModule rebuilds the runtime at the target memory
              limit (+ WASI + compile-cache open). This is a second runtime
              build today; see the plan's "redundant double init" note.
Read        — engine: os.ReadFile of the module bytes (25MB for CPython).
Compile     — engine: wazero CompileModule (compile-cache assisted; a full
              cold compile is ~10s, a cache hit ~seconds of deserialize).

Durations marshal to JSON as their nanosecond integer (time.Duration is int64), so they cross the worker IPC boundary losslessly.

type MultiInstanceEngine ¶

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

MultiInstanceEngine holds one resident wazero runtime + one compiled module and instantiates many isolated instances from it — compile-once, instantiate-many. It is the Phase 1 primitive for the resident-module host (plans/wasm-resident-module-host.md), extended in Phase 2b PR-A with per-instance network hooks (multiNetHost) and call/lifecycle locking.

Bucketing constraint: wazero sets the memory limit at the runtime level and a CompiledModule is bound to its runtime, so one MultiInstanceEngine serves a single (module, memoryMB) bucket. MemoryMB is fixed at construction.

Isolation: wazero gives every InstantiateModule its own linear memory. Networking is keyed by mod.Name() (= sandboxID) via multiNetHost so co-tenants cannot share sockets. wasip1 listeners and checkpoint/restore remain out of scope for resident hosts.

func NewMultiInstanceEngine(ctx context.Context, memoryMB int) (*MultiInstanceEngine, error)

func (m *MultiInstanceEngine) ClearNetworkHook(sandboxID string)

func (m *MultiInstanceEngine) Close(ctx context.Context) error

func (m *MultiInstanceEngine) HasInstance(sandboxID string) bool

func (m *MultiInstanceEngine) InstanceCount() int

func (m *MultiInstanceEngine) Instantiate(ctx context.Context, sandboxID string, caps Capabilities) error

func (m *MultiInstanceEngine) InvokeExport(ctx context.Context, sandboxID, name string) error

func (m *MultiInstanceEngine) LastLoadTimings() LoadTimings

func (m *MultiInstanceEngine) LoadModule(ctx context.Context, path string) error

func (m *MultiInstanceEngine) Loaded() bool

func (m *MultiInstanceEngine) MemoryMB() int

func (m *MultiInstanceEngine) Run(ctx context.Context, sandboxID string, caps Capabilities, export string) (RunResult, error)

func (m *MultiInstanceEngine) SetNetworkHook(sandboxID string, hook *NetworkHook)

func (m *MultiInstanceEngine) StopInstance(ctx context.Context, sandboxID string) error

type NetByteCounter ¶

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

NetByteCounter is a thread-safe ByteMeter backed by atomic counters.

func (c *NetByteCounter) AddIn(n int64)

func (c *NetByteCounter) AddOut(n int64)

func (c *NetByteCounter) In() int64

func (c *NetByteCounter) Out() int64

type NetDialer ¶

type NetDialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

NetDialer dials outbound TCP for a sandbox. Implementations must enforce egress policy and byte accounting (UC-43 NetMediator in the worker).

type NetworkAwareEngine ¶

type NetworkAwareEngine interface {
	Engine
	SetNetworkHook(hook *NetworkHook)
	ClearNetworkHook()
}

NetworkAwareEngine exposes per-sandbox network mediation on the default engine.

type NetworkHook ¶

type NetworkHook struct {
	SandboxID string
	Dial      NetDialer
	// Meter receives wasip1 sock_accept/recv/send and host-module socket bytes.
	Meter ByteMeter
}

NetworkHook binds a sandbox identity to mediated egress dials for the engine.

type Preopen ¶

type Preopen struct {
	GuestPath string `json:"guest_path"`
	HostPath  string `json:"host_path"`
}

Preopen maps a host directory into the guest filesystem.

type RunResult ¶

type RunResult struct {
	ExitCode int        `json:"exit_code"`
	Stdout   string     `json:"stdout,omitempty"`
	Stderr   string     `json:"stderr,omitempty"`
	Usage    UsageStats `json:"usage,omitempty"`
}

RunResult captures a single invocation's outcome.

type SnapshotBaseModule ¶

type SnapshotBaseModule struct {
	Digest string `json:"digest"`
	Size   int64  `json:"size"`
}

SnapshotBaseModule references the compiled module by digest.

type SnapshotCapture ¶

type SnapshotCapture struct {
	Config    SnapshotConfig
	Memory    []byte
	Globals   []byte
	WASIState []byte
}

SnapshotCapture holds the host-boundary state written into mem.snap.

type SnapshotConfig ¶

type SnapshotConfig struct {
	SchemaVersion     int                `json:"schema_version"`
	Engine            string             `json:"engine"`
	EngineVersion     string             `json:"engine_version"`
	WASIVersion       string             `json:"wasi_version"`
	BaseModule        SnapshotBaseModule `json:"base_module"`
	Entrypoint        string             `json:"entrypoint"`
	Durability        string             `json:"durability"`
	CapturedAt        string             `json:"captured_at"`
	CloneGeneration   string             `json:"clone_generation"`
	MemoryChecksum    string             `json:"memory_checksum"`
	WASIStateChecksum string             `json:"wasi_state_checksum"`
	GlobalsCount      int                `json:"globals_count"`
}

SnapshotConfig is the v1 config descriptor (§4.8.1).

type SnapshotRestoreInput ¶

type SnapshotRestoreInput struct {
	Config    SnapshotConfig
	Memory    []byte
	Globals   []byte
	WASIState []byte
}

SnapshotRestoreInput is validated artifact content for engine reconstruction.

func ReadSnapshotDir(dir string, runningEngine string) (SnapshotRestoreInput, error)

type UsageStats ¶

type UsageStats struct {
	WallDurationMs int64 `json:"wall_duration_ms"`
	// Instructions is populated only on the wasmtime engine seam (UC-42b).
	Instructions int64 `json:"instructions,omitempty"`
}

UsageStats captures per-invocation metering for billing (UC-42a on wazero).