Documentation
¶
Overview ¶
Package execution runs one restricted, bounded Starlark program at a time.
Engine is compiled from the fixed language surface merged with process-neutral capability bindings. Each Execute call receives a request-specific NativeCall and converts only main's final value.
Index ¶
Constants ¶
const MaxAgentErrorBytes = 256
MaxAgentErrorBytes is the maximum UTF-8 size of an approved agent-visible capability-failure suffix, including a trailing ASCII ellipsis when truncated.
Variables ¶
var ( // ErrInvalidProgram classifies invalid source, entrypoint behavior, or loading-phase native calls. ErrInvalidProgram = errors.New("invalid program") // ErrInvalidArguments classifies native arguments rejected before the native port. ErrInvalidArguments = errors.New("invalid capability arguments") // ErrPermissionDenied classifies a recognized authorization denial. ErrPermissionDenied = errors.New("permission denied") // ErrPolicyFailure classifies an authorization evaluation error or panic. ErrPolicyFailure = errors.New("authorization policy failure") // ErrResourceLimit classifies source, step, native-call, depth, or value-size exhaustion. ErrResourceLimit = errors.New("resource limit exceeded") // ErrCapabilityFailure classifies a native handler or handler-result failure. ErrCapabilityFailure = errors.New("capability failed") // ErrInternal classifies an unexpected runtime or contract failure. ErrInternal = errors.New("internal failure") )
Functions ¶
func SafeDetail ¶
SafeDetail reports the approved suffix attached to err, if any.
Extraction follows the error chain with errors.As.
func WithSafeDetail ¶
WithSafeDetail attaches detail to cause without changing cause.Error.
Empty detail returns cause unchanged. Callers must pass only model-derived suffixes or sanitized explicitly handler-authored detail; host-derived text must not be attached.
Types ¶
type CapabilityBinding ¶
type CapabilityBinding struct {
// ID is the stable capability identity passed to NativeCall.
ID string
// Name is the dotted Starlark path used to assemble the frozen namespace.
Name string
// Input is the exact compiled input shape used to bind keyword arguments.
Input []binding.FieldShape
}
CapabilityBinding is one process-neutral capability exposed to the interpreter.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine owns the frozen language surface and capability namespace shared by fresh execution threads.
func New ¶
func New(bindings []CapabilityBinding) (*Engine, error)
New compiles one immutable execution engine from the fixed language surface and capability bindings.
type Limits ¶
type Limits struct {
// MaxSourceBytes bounds the submitted Starlark source length.
MaxSourceBytes int
// MaxExecutionSteps bounds abstract Starlark interpreter work.
MaxExecutionSteps uint64
// MaxNativeCalls bounds attempted capability invocations.
MaxNativeCalls uint64
// MaxValueDepth bounds recursive crossing-value conversion.
MaxValueDepth int
// MaxValueBytes supplies the byte-derived materialization bound.
MaxValueBytes int
}
Limits contains the prevalidated positive budgets for one execution.
Source Files