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
- type Deps
- type 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
- type Param
- type Script
Constants ¶
This section is empty.
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 ¶
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) 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).
type EventAppender ¶
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.
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.
Source Files
Directories