Repository Public
1// Package actions is the typed action catalog and the single place where an2// action row is created or moved to another state. There is no free-form3// command anywhere: every action is one of the catalogued types, and its4// parameters are validated against the type's specification before anything5// is stored.6package actions78import (9 "encoding/json"10 "fmt"11 "math"12 "regexp"13 "slices"14 "sort"15 "unicode/utf8"16)1718// Prop is one parameter of an action type: a deliberately small subset of19// JSON Schema (enough for the catalog, small enough to audit).20type Prop struct {21 Type string // string | integer | boolean | object22 Description string //23 Enum []string // string24 Pattern *regexp.Regexp // string25 MaxLen int // string (runes); 0 = 25626 Min, Max *int64 // integer27 MaxBytes int // object: free-form JSON object bounded in encoded size (validated by the agent)28}2930// Spec is the parameter specification of an action type. Unknown fields are always refused.31type Spec struct {32 Props map[string]Prop33 Required []string34}3536// ParamError names the offending parameter.37type ParamError struct {38 Field string39 Reason string40}4142func (e *ParamError) Error() string { return "params." + e.Field + ": " + e.Reason }4344func i64(v int64) *int64 { return &v }4546// Validate checks params strictly: no unknown field, required fields, and47// per-field type, enum, range, pattern and size.48func (s Spec) Validate(params map[string]any) error {49 keys := make([]string, 0, len(params))50 for k := range params {51 keys = append(keys, k)52 }53 sort.Strings(keys) // deterministic error54 for _, k := range keys {55 p, ok := s.Props[k]56 if !ok {57 return &ParamError{k, "unknown parameter"}58 }59 if err := p.check(params[k]); err != nil {60 return &ParamError{k, err.Error()}61 }62 }63 for _, k := range s.Required {64 if _, ok := params[k]; !ok {65 return &ParamError{k, "required"}66 }67 }68 return nil69}7071func (p Prop) check(v any) error {72 switch p.Type {73 case "string":74 s, ok := v.(string)75 if !ok {76 return fmt.Errorf("must be a string")77 }78 max := p.MaxLen79 if max == 0 {80 max = 25681 }82 if utf8.RuneCountInString(s) > max {83 return fmt.Errorf("must be at most %d characters", max)84 }85 if len(p.Enum) > 0 && !slices.Contains(p.Enum, s) {86 return fmt.Errorf("must be one of %v", p.Enum)87 }88 if p.Pattern != nil && !p.Pattern.MatchString(s) {89 return fmt.Errorf("does not match %s", p.Pattern.String())90 }91 case "integer":92 var n int6493 switch x := v.(type) {94 case float64:95 if x != math.Trunc(x) || math.Abs(x) > 1<<53 {96 return fmt.Errorf("must be an integer")97 }98 n = int64(x)99 case json.Number:100 i, err := x.Int64()101 if err != nil {102 return fmt.Errorf("must be an integer")103 }104 n = i105 case int:106 n = int64(x)107 case int64:108 n = x109 default:110 return fmt.Errorf("must be an integer")111 }112 if p.Min != nil && n < *p.Min {113 return fmt.Errorf("must be >= %d", *p.Min)114 }115 if p.Max != nil && n > *p.Max {116 return fmt.Errorf("must be <= %d", *p.Max)117 }118 case "boolean":119 if _, ok := v.(bool); !ok {120 return fmt.Errorf("must be a boolean")121 }122 case "object":123 m, ok := v.(map[string]any)124 if !ok {125 return fmt.Errorf("must be an object")126 }127 b, err := json.Marshal(m)128 if err != nil {129 return fmt.Errorf("must be a JSON object")130 }131 if max := p.MaxBytes; max > 0 && len(b) > max {132 return fmt.Errorf("must be at most %d bytes of JSON", max)133 }134 default:135 return fmt.Errorf("unsupported specification") // catalog bug: refuse rather than accept136 }137 return nil138}139140// JSONSchema renders the specification as a JSON Schema (draft 2020-12) object.141func (s Spec) JSONSchema() map[string]any {142 props := map[string]any{}143 for name, p := range s.Props {144 o := map[string]any{"type": p.Type}145 if p.Description != "" {146 o["description"] = p.Description147 }148 switch p.Type {149 case "string":150 if len(p.Enum) > 0 {151 o["enum"] = slices.Clone(p.Enum)152 }153 if p.Pattern != nil {154 o["pattern"] = p.Pattern.String()155 }156 max := p.MaxLen157 if max == 0 {158 max = 256159 }160 o["maxLength"] = max161 case "integer":162 if p.Min != nil {163 o["minimum"] = *p.Min164 }165 if p.Max != nil {166 o["maximum"] = *p.Max167 }168 case "object":169 o["additionalProperties"] = true170 }171 props[name] = o172 }173 out := map[string]any{"type": "object", "additionalProperties": false, "properties": props}174 if len(s.Required) > 0 {175 out["required"] = slices.Clone(s.Required)176 }177 return out178}179