wasm

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

type CompiledModule interface {
	// Name returns the module name if available.
	Name() string

	// Exports lists exported functions.
	Exports() []string

	// Close releases the compiled module.
	Close(ctx context.Context) error
}

type Config struct {
	// Runtime specifies the WASM runtime to use.
	// Options: wasmtime, wasmer, wazero
	// Default: wazero
	Runtime string

	// MaxMemoryPages is the maximum memory pages (64KB each).
	// Default: 256 (16MB)
	MaxMemoryPages int

	// EnableWASI enables WASI (WebAssembly System Interface).
	// Default: true
	EnableWASI bool

	// AllowedHostFunctions lists host functions the WASM module can call.
	AllowedHostFunctions []string

	// Client is the WASM runner implementation.
	// If nil, Execute() returns ErrClientNotConfigured.
	Client Runner

	// ModuleLoader optionally pre-compiles modules.
	// If nil, modules are compiled on-demand.
	ModuleLoader ModuleLoader

	// HealthChecker optionally verifies runtime health.
	// If nil, health checks are skipped.
	HealthChecker HealthChecker

	// Logger is an optional logger for backend events.
	Logger Logger
}

type HealthChecker interface {
	// Ping checks if the WASM runtime is operational.
	Ping(ctx context.Context) error

	// Info returns runtime information.
	Info(ctx context.Context) (RuntimeInfo, error)
}

type Logger interface {
	Info(msg string, args ...any)
	Warn(msg string, args ...any)
	Error(msg string, args ...any)
}

type ModuleLoader interface {
	// Load compiles a WASM binary into a reusable module.
	// The returned module reference can be used in Spec.Module.
	Load(ctx context.Context, binary []byte) (CompiledModule, error)

	// Close releases all cached modules.
	Close(ctx context.Context) error
}

type Mount struct {
	// HostPath is the path on the host filesystem.
	HostPath string

	// GuestPath is the path inside the WASM module.
	GuestPath string

	// ReadOnly mounts the path as read-only.
	ReadOnly bool
}

type ResourceSpec struct {
	// MemoryPages is the maximum memory in 64KB pages.
	// Zero uses runtime default (typically 256 = 16MB).
	MemoryPages uint32

	// FuelLimit is the maximum fuel for metered execution.
	// Zero means unlimited (no metering).
	FuelLimit uint64

	// StackSize is the maximum call stack size in bytes.
	// Zero uses runtime default.
	StackSize uint32
}

type Result struct {
	// ExitCode is the module's exit code (0 = success).
	ExitCode int

	// Stdout contains the module's stdout output.
	Stdout string

	// Stderr contains the module's stderr output.
	Stderr string

	// Duration is the execution time.
	Duration time.Duration

	// FuelConsumed is the fuel used (if metering enabled).
	FuelConsumed uint64

	// MemoryUsed is peak memory usage in bytes.
	MemoryUsed uint64
}

type Runner interface {
	// Run executes code in a WASM sandbox and returns the result.
	// The module lifecycle (compile, instantiate, execute, cleanup) is atomic.
	//
	// The implementation must:
	//   - Validate the spec before execution
	//   - Respect ctx cancellation
	//   - Respect spec.Timeout if set
	//   - Capture stdout and stderr
	//   - Return the exit code
	//   - Clean up the module instance on completion or error
	Run(ctx context.Context, spec Spec) (Result, error)
}

type RuntimeInfo struct {
	// Name is the runtime name (wazero, wasmer, wasmtime).
	Name string

	// Version is the runtime version.
	Version string

	// Features lists supported features.
	Features []string
}

type SecuritySpec struct {
	// EnableWASI enables WebAssembly System Interface.
	// Default: true for most use cases.
	EnableWASI bool

	// AllowedHostFunctions lists host functions the module can import.
	// Empty means no host functions allowed (maximum isolation).
	AllowedHostFunctions []string

	// EnableNetwork allows WASI network access.
	// Default: false for sandbox isolation.
	EnableNetwork bool

	// EnableClock allows access to system clock.
	// Default: true (needed for timing operations).
	EnableClock bool
}

type Spec struct {
	// Module is the compiled WASM binary (required).
	// This can be raw .wasm bytes or a precompiled module reference.
	Module []byte

	// EntryPoint is the exported function to call (default: "_start" for WASI).
	EntryPoint string

	// Args are command-line arguments passed to the module.
	Args []string

	// Env contains environment variables in KEY=value format.
	Env []string

	// Stdin provides input to the module's stdin.
	Stdin []byte

	// WorkingDir is the working directory for WASI filesystem operations.
	WorkingDir string

	// Mounts defines filesystem mounts for WASI.
	Mounts []Mount

	// Resources defines resource limits.
	Resources ResourceSpec

	// Security defines security settings.
	Security SecuritySpec

	// Timeout is the maximum execution duration.
	Timeout time.Duration

	// Labels are metadata labels for tracking.
	Labels map[string]string
}

type StreamEvent struct {
	// Type identifies the event type.
	Type StreamEventType

	// Data contains the event payload (stdout/stderr bytes).
	Data []byte

	// ExitCode is set when Type is StreamEventExit.
	ExitCode int

	// Error is set when Type is StreamEventError.
	Error error
}

type StreamEventType string

type StreamRunner interface {
	Runner

	// RunStream executes and streams stdout/stderr as events.
	// The returned channel is closed when execution completes.
	// Callers should drain the channel to receive the exit event.
	RunStream(ctx context.Context, spec Spec) (<-chan StreamEvent, error)
}