// Package mapping owns the payload field-mapping vocabulary and its // resolve/preview rule: binding named fields to JSON paths inside a // captured webhook payload, and deciding -- loudly -- when a path a mapping // depends on has drifted out from under it. See package mapping import ( json "encoding/json/v2" "errors" "fmt" "strconv" "strings" "time" "github.com/samcharles93/archie-core/modules/events/internal/eventtype" ) // FieldType is the expected JSON shape of a mapped field, checked at // resolve time. type FieldType string const ( TypeString FieldType = "string" TypeNumber FieldType = "number" TypeBool FieldType = "bool" TypeObject FieldType = "object" TypeArray FieldType = "array" TypeAny FieldType = "any" ) // Failure reasons. A field either resolves to a value or fails for exactly // one of these -- never both. const ( ReasonMissing = "missing" ReasonNull = "null" ReasonTypeMismatch = "type_mismatch" ) // Field binds one named field the workflow receives to a path into a // captured payload. Required=false suppresses ReasonMissing only -- a // present-but-wrong-shape value always fails, so a mapping never silently // hands an agent a value it didn't expect. type Field struct { Name string `json:"name"` Path string `json:"path"` Type FieldType `json:"type"` Required bool `json:"required"` } // Mapping is a named set of field bindings belonging to one event type and // checked against its schema (CheckSchema). Any number of bindings may reuse // it. MatchCount and LastMatchedAt are read-only: the store counts each // capture the mapping resolved at dispatch. type Mapping struct { ID string `json:"id"` Name string `json:"name"` SourceHint string `json:"source_hint"` EventTypeID string `json:"event_type_id"` Fields []Field `json:"fields"` MatchCount int64 `json:"match_count"` LastMatchedAt time.Time `json:"last_matched_at"` CreatedAt time.Time `json:"created_at"` UpdatedAt time.Time `json:"updated_at"` } // validTypes is the set of FieldType values Validate accepts. var validTypes = map[FieldType]bool{ TypeString: true, TypeNumber: true, TypeBool: true, TypeObject: true, TypeArray: true, TypeAny: true, } // Validate checks a mapping is well-formed before it is persisted or // previewed: a name, at least one field, and every field naming a // non-empty field name, a non-empty path, and a recognised type. It does // not check the mapping against any payload -- that is Resolve's job. func (m Mapping) Validate() error { if strings.TrimSpace(m.Name) == "" { return fmt.Errorf("mapping: name is required") } if len(m.Fields) == 0 { return fmt.Errorf("mapping: at least one field is required") } seen := make(map[string]bool, len(m.Fields)) for i, f := range m.Fields { if strings.TrimSpace(f.Name) == "" { return fmt.Errorf("mapping: field %d: name is required", i) } if strings.TrimSpace(f.Path) == "" { return fmt.Errorf("mapping: field %d (%s): path is required", i, f.Name) } if !validTypes[f.Type] { return fmt.Errorf("mapping: field %d (%s): unrecognised type %q", i, f.Name, f.Type) } // A duplicate name would let one field silently overwrite another's // resolved value in Resolve's values map -- reject it here instead // of losing data silently at resolve time. if seen[f.Name] { return fmt.Errorf("mapping: field %d: duplicate field name %q", i, f.Name) } seen[f.Name] = true } return nil } // Failure describes one field that did not resolve cleanly against a payload -- // named by field and path so the operator knows exactly what drifted. type Failure struct { FieldName string `json:"field_name"` Path string `json:"path"` Reason string `json:"reason"` } // Resolve walks payload independently for each field, so one field's // failure never stops the others from resolving -- preview must show every // problem at once, not the first one. A field that fails never appears in // values. func Resolve(fields []Field, payload []byte) (values map[string]any, failures []Failure) { values = make(map[string]any, len(fields)) var root any if err := json.Unmarshal(payload, &root); err != nil { for _, f := range fields { failures = append(failures, Failure{FieldName: f.Name, Path: f.Path, Reason: ReasonMissing}) } return values, failures } for _, f := range fields { v, found := walk(root, parsePath(f.Path)) if !found { if f.Required { failures = append(failures, Failure{FieldName: f.Name, Path: f.Path, Reason: ReasonMissing}) } continue } if v == nil { failures = append(failures, Failure{FieldName: f.Name, Path: f.Path, Reason: ReasonNull}) continue } if !typeMatches(v, f.Type) { failures = append(failures, Failure{FieldName: f.Name, Path: f.Path, Reason: ReasonTypeMismatch}) continue } values[f.Name] = v } return values, failures } // pathSegment is a map key, an array index, or Invalid. walk always fails on // Invalid. type pathSegment struct { Key string Index int Invalid bool } // parsePath splits "data.items[0].id" into // [{Key:"data"} {Key:"items"} {Index:0} {Key:"id"}]. No wildcards, no // filters -- the grammar is exactly what a click-through UI generates. func parsePath(path string) []pathSegment { var segs []pathSegment for part := range strings.SplitSeq(path, ".") { if part == "" { continue } for { open := strings.IndexByte(part, '[') if open < 0 { if part != "" { segs = append(segs, pathSegment{Key: part, Index: -1}) } break } if open > 0 { segs = append(segs, pathSegment{Key: part[:open], Index: -1}) } closeIdx := strings.IndexByte(part[open:], ']') if closeIdx < 0 { segs = append(segs, pathSegment{Invalid: true}) break } closeIdx += open idx, err := strconv.Atoi(part[open+1 : closeIdx]) if err != nil { segs = append(segs, pathSegment{Invalid: true}) } else { segs = append(segs, pathSegment{Index: idx}) } part = part[closeIdx+1:] if part == "" { break } } } return segs } // walk descends node by path. found=false means the path does not exist in // the payload at all (missing), which is distinct from resolving to a JSON // null (node == nil, found == true). func walk(node any, path []pathSegment) (value any, found bool) { cur := node for _, seg := range path { if seg.Invalid { return nil, false } if cur == nil { return nil, false } if seg.Index >= 0 { arr, ok := cur.([]any) if !ok || seg.Index >= len(arr) { return nil, false } cur = arr[seg.Index] continue } obj, ok := cur.(map[string]any) if !ok { return nil, false } v, ok := obj[seg.Key] if !ok { return nil, false } cur = v } return cur, true } // ErrSchema marks a mapping whose field paths or types disagree with its // event type's inferred schema. var ErrSchema = errors.New("mapping: field does not fit the event type's schema") // CheckSchema refuses fields whose path the event type's schema lacks, or // whose declared type differs from the schema's. Array indices match the // schema's "[]" segment, and a path the example held as null accepts any type. func CheckSchema(fields []Field, schema map[string]eventtype.ValueType) error { for _, f := range fields { got, ok := schema[schemaPath(f.Path)] if !ok { return fmt.Errorf("%w: %s: path %q is not in the event type", ErrSchema, f.Name, f.Path) } if f.Type != TypeAny && got != eventtype.TypeNull && string(got) != string(f.Type) { return fmt.Errorf("%w: %s: path %q is %s, not %s", ErrSchema, f.Name, f.Path, got, f.Type) } } return nil } // schemaPath rewrites a resolve path ("items[0].id") into the schema's form // ("items[].id"). A malformed path has no schema form. func schemaPath(path string) string { var b strings.Builder for _, seg := range parsePath(path) { switch { case seg.Invalid: return "" case seg.Index >= 0: b.WriteString("[]") default: if b.Len() > 0 { b.WriteByte('.') } b.WriteString(seg.Key) } } return b.String() } func typeMatches(v any, want FieldType) bool { if want == TypeAny { return true } switch v.(type) { case string: return want == TypeString case float64: return want == TypeNumber case bool: return want == TypeBool case map[string]any: return want == TypeObject case []any: return want == TypeArray default: return false } }