Documentation
¶
Overview ¶
Package binding compiles restricted Go input and output types into immutable conversion plans and owns process-neutral value conversion.
Typed handler values, Starlark values, and JSON-shaped maps share one allowed matrix: nil, bool, string, int64, finite float64, []any, and map[string]any. ValidateValue, FromStarlark, and ToStarlark enforce that matrix plus positive depth and materialization limits. json.Number and other numeric types are rejected. Plan.InputShape remains the only descriptor source for compiled input fields. Plan.OutputShape remains a flat FieldShape slice whose Type strings carry nested list, dict, struct, and nullable notation.
Index ¶
- Variables
- func BindShape(fields []FieldShape, args starlark.Tuple, kwargs []starlark.Tuple) (map[string]any, error)
- func FromStarlark(value starlark.Value, maxDepth int, maxNodes int) (any, error)
- func ToStarlark(value any, maxDepth int, maxNodes int) (starlark.Value, error)
- func ValidIdentifier(name string) bool
- func ValidateInputShape(fields []FieldShape) error
- func ValidateValue(value any, maxDepth int, maxNodes int) error
- type FieldShape
- type Plan
- func (plan *Plan) BindValue(arguments map[string]any) (any, map[string]any, error)
- func (plan *Plan) ConvertOutput(output any, maxDepth int, maxNodes int) (map[string]any, error)
- func (plan *Plan) InputShape() []FieldShape
- func (plan *Plan) InputType() reflect.Type
- func (plan *Plan) OutputShape() []FieldShape
- func (plan *Plan) OutputType() reflect.Type
- func (plan *Plan) Signature(capabilityName string) string
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidPlan classifies an input or output type that cannot form a restricted binding plan. ErrInvalidPlan = errors.New("invalid binding plan") // ErrInvalidArguments classifies Starlark arguments rejected before authorization. ErrInvalidArguments = errors.New("invalid capability arguments") // ErrUnsupportedValue classifies a Go or Starlark value outside the supported conversion surface. ErrUnsupportedValue = errors.New("unsupported value") // ErrValueLimit classifies converted output that exceeds a configured depth or byte limit. ErrValueLimit = errors.New("converted value limit exceeded") )
Functions ¶
func BindShape ¶
func BindShape(fields []FieldShape, args starlark.Tuple, kwargs []starlark.Tuple) (map[string]any, error)
BindShape binds keyword-only Starlark arguments against a validated input shape.
It returns only a fresh canonical JSON-shaped map. Explicit Starlark None and omission both leave an optional key absent. Callers must not treat the result as the authoritative authorization map; parent re-binding constructs that.
func FromStarlark ¶
FromStarlark converts a Starlark value into a process-neutral MCP value.
maxDepth and maxNodes must be positive. Active cycles are rejected, and destination containers are allocated only after their child counts fit the remaining materialization budget.
func ToStarlark ¶
ToStarlark converts a process-neutral MCP value into a Starlark value.
maxDepth and maxNodes must be positive. Active cycles are rejected, and destination containers are allocated only after their child counts fit the remaining materialization budget.
func ValidIdentifier ¶
ValidIdentifier reports whether name is accepted as an identifier by the pinned Starlark scanner.
func ValidateInputShape ¶
func ValidateInputShape(fields []FieldShape) error
ValidateInputShape reports whether fields is a combination Plan.InputShape can produce.
Required scalars are exactly Type "str", "int", "bool", or "float" with Required true. Optional scalars are exactly those types with " | None" and Required false. An empty shape is valid. Names must be unique Starlark identifiers. Any other pair, including the literal "unsupported" notation, is rejected.
func ValidateValue ¶
ValidateValue reports whether value is a process-neutral MCP value within the supplied limits.
Accepted values are nil, bool, string, int64, finite float64, []any, and map[string]any, recursively. json.Number and other numeric types are rejected. maxDepth and maxNodes must be positive. Active cycles are rejected.
Types ¶
type FieldShape ¶
type FieldShape struct {
// Name is the field's exact Starlark and JSON name.
Name string `json:"name"`
// Type is the compact Starlark-facing value notation.
Type string `json:"type"`
// Required reports whether the caller or handler must provide the field.
Required bool `json:"required"`
}
FieldShape is one model-facing field in a supported capability input or output structure.
type Plan ¶
type Plan struct {
// contains filtered or unexported fields
}
Plan is an immutable compiled input, output, signature, and canonical-argument plan.
func Compile ¶
Compile creates an immutable restricted plan for exact input and output struct types.
func CompileFor ¶
CompileFor compiles the exact generic input and output types once.
func (*Plan) BindValue ¶
BindValue reconstructs the exact registered Go input and a fresh canonical map.
The decoded child map is never returned or retained. A present optional key with a nil value is treated as explicit None and omitted from the canonical map. Invalid normalized maps are classified with ErrInvalidArguments.
func (*Plan) ConvertOutput ¶
ConvertOutput converts the plan's exact handler output to a process-neutral object.
maxDepth and maxNodes must be positive. The root struct is depth 1. Pointers add no depth. Nested structs, lists, and maps add one depth through their value node. Destination maps, lists, and sorted map-key slices are allocated only after their child counts fit the remaining materialization budget.
func (*Plan) InputShape ¶
func (plan *Plan) InputShape() []FieldShape
InputShape returns a fresh model-facing description of the compiled input fields.
func (*Plan) OutputShape ¶
func (plan *Plan) OutputShape() []FieldShape
OutputShape returns a fresh model-facing description of the compiled output fields.
func (*Plan) OutputType ¶
OutputType returns the exact Go output type compiled into the plan.
Source Files