script

Documentation

Overview

Package script provides the runtime for invocable named Starlark functions. Scripts are compiled once from a ConfigSnapshot into an immutable registry; Engine.Call validates arguments, emits ScriptInvoked/ScriptFinished events, and executes the handler via the shared starlark.Runtime.

Index

• Variables
• func CompileScripts(snap *configpb.ConfigSnapshot) (map[string]*Script, error)
• type CallResult
• type CompileError
  • func (e *CompileError) Error() string
• type Deps
• type Engine
  • func NewEngine(scripts map[string]*Script, runtime *ghstarlark.Runtime, deps Deps) *Engine
  • func (e *Engine) Call(ctx context.Context, name string, args map[string]string, invokedBy string, ...) (*CallResult, error)
  • func (e *Engine) Get(name string) (*Script, error)
  • func (e *Engine) List() []string
  • func (e *Engine) Reload(snapshot *configpb.ConfigSnapshot) error
  • func (e *Engine) Runtime() *ghstarlark.Runtime
  • func (e *Engine) Stop(ctx context.Context) error
• type EventAppender
• type ItemError
  • func (e *ItemError) Error() string
• type Param
  • func (p Param) Coerce(s string) (any, error)
• type Script

Variables

var (
	ErrScriptNotFound = errors.New("script: unknown name")
	ErrScriptArgs     = errors.New("script: invalid arguments")
)

Sentinel errors returned by Engine.

Functions

func CompileScripts

func CompileScripts(snap *configpb.ConfigSnapshot) (map[string]*Script, error)

CompileScripts turns the snapshot's ScriptConfig list into an immutable name-keyed map of runtime Script values. Returns an aggregated CompileError with every problem found so authors get a full list at validation time.

Types

type CallResult

type CallResult struct {
	CorrelationID string
	Outcome       eventv1.RunOutcome
	Error         string
	Elapsed       time.Duration
	Steps         uint64
	Logs          []string
	ReturnValue   string
}

CallResult summarises one script invocation.

type CompileError

type CompileError struct {
	Items []*ItemError
}

CompileError aggregates every ItemError found during Compile so authors see every problem from a single `gohome config validate`.

func (*CompileError) Error

func (e *CompileError) Error() string

type Deps

type Deps struct {
	Store   EventAppender
	Logger  *slog.Logger
	Metrics *observability.Metrics
}

Deps is the set of external dependencies the script engine needs.

type Engine

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

Engine runs compiled scripts. Safe for concurrent use.

func NewEngine

func NewEngine(scripts map[string]*Script, runtime *ghstarlark.Runtime, deps Deps) *Engine

NewEngine constructs an engine with an initial script map. Nil runtime is permitted for tests that only exercise List/Get; Call will error without it.

func (*Engine) Call

func (e *Engine) Call(
	ctx context.Context,
	name string,
	args map[string]string,
	invokedBy string,
	sharedCorrID string,
) (*CallResult, error)

Call executes the named script. `invokedBy` is a provenance string like "cli:<user>" or "automation:<id>". `sharedCorrID` is used when the call is nested inside an automation run (so all events share one corr_id); empty means mint a fresh UUID.

func (*Engine) Get

func (e *Engine) Get(name string) (*Script, error)

Get returns the runtime Script by name or ErrScriptNotFound.

func (*Engine) List

func (e *Engine) List() []string

List returns script names sorted.

func (*Engine) Reload

func (e *Engine) Reload(snapshot *configpb.ConfigSnapshot) error

Reload re-compiles the snapshot and atomically swaps the script registry. In-flight Calls that captured their *Script pointer under RLock continue against the old definition.

func (*Engine) Runtime

func (e *Engine) Runtime() *ghstarlark.Runtime

Runtime returns the underlying Starlark runtime (used by automation actions).

func (*Engine) Stop

func (e *Engine) Stop(ctx context.Context) error

Stop waits for in-flight Calls to drain.

type EventAppender

type EventAppender interface {
	Append(ctx context.Context, e eventstore.Event) (uint64, error)
}

EventAppender is the eventstore subset used by the script engine.

type ItemError

type ItemError struct {
	Name   string // script name
	Path   string // "scripts[greet].params[0].default"
	Reason string
}

ItemError is one compilation error tied to a specific script and path.

func (*ItemError) Error

func (e *ItemError) Error() string

type Param

type Param struct {
	Name     string
	Type     configpb.ScriptParam_Type
	Required bool
	// Default holds the pre-coerced default for non-required params.
	// When Required is true and no arg supplied, Engine.Call rejects.
	HasDefault bool
	Default    any
}

Param is a compiled, type-resolved parameter declaration.

func (Param) Coerce

func (p Param) Coerce(s string) (any, error)

Coerce converts the stringified input to the Param's declared type. Returns the typed value (string / int64 / float64 / bool) on success.

type Script

type Script struct {
	Name    string
	Params  []Param
	Handler string
}

Script is the runtime representation of a compiled gohome.scripts entry. Immutable after Compile; callers obtain pointers under the engine RLock.