Documentation
¶
Overview ¶
Package runtime provides sandboxed execution environments for grut extensions. Each runtime (Lua, WASM, MCP) implements the Runtime interface, allowing the extension manager to load and execute user extensions uniformly.
Index ¶
Constants ¶
const DefaultTimeout = 100 * time.Millisecond
DefaultTimeout is the maximum time a Lua script may execute before being cancelled. The value mirrors the default from config (lua_timeout_ms = 100).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type HostAPI ¶
type HostAPI interface {
// ShowToast displays a notification to the user.
// Level should be "info", "warn", or "error".
ShowToast(title, message, level string)
// RegisterCommand adds a user-invokable command to the command palette.
RegisterCommand(name, description string, handler func() error)
// SetStatusBarItem sets a key-value pair displayed in the status bar.
SetStatusBarItem(key, value string)
// Log writes an informational message to the host log.
Log(msg string)
}
HostAPI exposes grut functionality to extension code. Implementations bridge calls from sandboxed extension code into the host application.
type LuaRuntime ¶
type LuaRuntime struct {
// contains filtered or unexported fields
}
LuaRuntime executes extension code inside a sandboxed gopher-lua VM.
func NewLuaRuntime ¶
func NewLuaRuntime(manifest *extension.Manifest, api HostAPI) (*LuaRuntime, error)
NewLuaRuntime creates a sandboxed Lua VM wired to the provided host API. The VM has dangerous modules removed and grut host functions registered.
func (*LuaRuntime) Close ¶
func (r *LuaRuntime) Close()
Close shuts down the Lua VM and releases associated resources.
func (*LuaRuntime) Load ¶
func (r *LuaRuntime) Load(entryPoint string) error
Load reads the Lua file at entryPoint and executes it inside the sandbox. Execution is subject to the configured timeout.
func (*LuaRuntime) SetTimeout ¶
func (r *LuaRuntime) SetTimeout(d time.Duration)
SetTimeout overrides the default execution timeout. A zero or negative duration disables the timeout (useful for testing only).
type MCPRuntime ¶
type MCPRuntime struct {
// contains filtered or unexported fields
}
MCPRuntime manages an MCP extension server as a subprocess, communicating via JSON-RPC 2.0 over stdin/stdout pipes.
func NewMCPRuntime ¶
func NewMCPRuntime(manifest *extension.Manifest) (*MCPRuntime, error)
NewMCPRuntime creates a new MCP runtime for the given extension manifest. The runtime is not started until Load is called.
func (*MCPRuntime) Close ¶
func (m *MCPRuntime) Close()
Close stops the MCP server subprocess. It closes stdin first, then kills the process and waits for it to exit. Safe to call multiple times or on an already-exited process.
func (*MCPRuntime) Load ¶
func (m *MCPRuntime) Load(entryPoint string) error
Load starts the MCP server subprocess using the given entry point. The interpreter is determined from the entry point file extension:
- .py → python3 (python on Windows)
- .js → node
- .ts → npx tsx
- binary (no ext or .exe) → direct execution
func (*MCPRuntime) Name ¶
func (m *MCPRuntime) Name() string
Name returns the runtime type identifier.
func (*MCPRuntime) Running ¶
func (m *MCPRuntime) Running() bool
Running reports whether the subprocess is still alive.
func (*MCPRuntime) SendRequest ¶
func (m *MCPRuntime) SendRequest(method string, params any) (json.RawMessage, error)
SendRequest sends a JSON-RPC 2.0 request to the subprocess and returns the result. Requests are serialized; only one is in flight at a time.
type Runtime ¶
type Runtime interface {
// Load reads and executes the extension entry-point script or module.
Load(entryPoint string) error
// Close releases all resources owned by the runtime.
Close()
// Name returns the runtime identifier (e.g. "lua", "wasm", "mcp").
Name() string
}
Runtime is the common interface for all extension runtimes.
type WASMRuntime ¶
type WASMRuntime struct {
// contains filtered or unexported fields
}
WASMRuntime executes WASM extensions inside a sandboxed wazero instance.
func NewWASMRuntime ¶
func NewWASMRuntime(manifest *extension.Manifest, hostAPI HostAPI) (*WASMRuntime, error)
NewWASMRuntime creates a new WASM runtime configured with a 64 MiB memory cap and no filesystem access. The returned runtime is ready for Load.
func (*WASMRuntime) Close ¶
func (w *WASMRuntime) Close()
Close releases all resources held by the wazero runtime.
func (*WASMRuntime) Load ¶
func (w *WASMRuntime) Load(entryPoint string) error
Load reads a WASM binary from entryPoint, compiles it, registers host imports, and instantiates the module.
Source Files