runtime

type ExecSpec struct {
	// Path is the module's absolute path in the container's root.
	Path string
	// Args is argv, Args[0] included; Env is "KEY=value" entries.
	Args, Env []string
	// Stdin, Stdout and Stderr default to empty / discard.
	Stdin          io.Reader
	Stdout, Stderr io.Writer
	// Terminal, when set, is the process's terminal (exec -t).
	Terminal *wasi.Terminal
}

type Execer interface {
	Exec(ctx context.Context, spec ExecSpec) (Process, uint32, error)
}

type Executor interface {
	// Start validates and compiles the module, then runs it in the
	// background. A missing module wraps ErrNotFound, an invalid one
	// ErrInvalid.
	Start(ctx context.Context, spec Spec) (Process, error)
	// Close releases the executor's resources.
	Close(ctx context.Context) error
}

type Mount struct {
	Path     string
	FS       *rootfs.FS
	ReadOnly bool
}

type Process interface {
	// Wait blocks until the process ends.
	Wait() Result
	// Kill ends the process; Wait then reports Killed.
	Kill()
}

type Result struct {
	ExitCode int
	// ProcExit reports that the guest ended with proc_exit(ProcCode), the
	// raw u32; ExitCode is then bounded to 0..125 (see ExitCodeOf).
	ProcExit bool
	ProcCode uint32
	// TimedOut reports a wall-clock cancel.
	TimedOut bool
	// Killed reports a cancel through Process.Kill or the context.
	Killed bool
	// Error describes an abnormal end (a trap), empty on a normal exit.
	Error string
}

type Spec struct {
	// ID names the process in errors and logs.
	ID string
	// FS is the container's root filesystem, preopened as "/".
	FS *rootfs.FS
	// Mounts are volumes, each preopened at its own path.
	Mounts []Mount
	// Path is the module's absolute path inside FS.
	Path string
	// Args is argv, Args[0] included.
	Args []string
	// Env is "KEY=value" entries.
	Env []string
	// Stdin, Stdout and Stderr default to empty / discard.
	Stdin          io.Reader
	Stdout, Stderr io.Writer
	// MemoryLimitBytes bounds the module's linear memory (0 = executor
	// default). It is rounded down to whole 64 KiB pages.
	MemoryLimitBytes int64
	// Timeout cancels the run after this wall-clock time (0 = none).
	Timeout time.Duration
	// Net is the container's network endpoint (nil: no network). Only
	// the engine's WASI host serves sockets.
	Net netdriver.Endpoint
	// Caps are capabilities granted to the process ("gpu", from run
	// --gpu); host modules read them through the engine's WASI host.
	Caps []string
	// OnEvent receives what the process's host modules report (wasi.Proc.Emit):
	// module, action, attributes. It may be called from any goroutine.
	OnEvent func(module, action string, attrs map[string]string)
	// Terminal is the container's terminal (run -t), if any; the engine's
	// WASI host reports it to the guest's processes.
	Terminal *wasi.Terminal
	// Processes bounds the processes the container may spawn (the
	// engine's WASI host only; zero values are its defaults).
	Processes wasi.GroupLimits
}

type Stats struct {
	// MemoryBytes is the guest's linear memory now (it never shrinks);
	// MemoryLimitBytes the most it may grow to.
	MemoryBytes, MemoryLimitBytes int64
}

type StatsReporter interface {
	Stats() Stats
}