308 lines
8.7 KiB
Go
308 lines
8.7 KiB
Go
// 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 (
|
|
"bytes"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"strconv"
|
|
"strings"
|
|
"time"
|
|
|
|
"github.com/samcharles93/archie-core/internal/domain/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
|
|
dec := json.NewDecoder(bytes.NewReader(payload))
|
|
dec.UseNumber()
|
|
if err := dec.Decode(&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] = normalize(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 json.Number:
|
|
return want == TypeNumber
|
|
case bool:
|
|
return want == TypeBool
|
|
case map[string]any:
|
|
return want == TypeObject
|
|
case []any:
|
|
return want == TypeArray
|
|
default:
|
|
return false
|
|
}
|
|
}
|
|
|
|
// normalize converts json.Number to float64 so resolved values are ordinary
|
|
// JSON-encodable Go types for the preview response, matching
|
|
// encoding/json's own default number decoding.
|
|
func normalize(v any) any {
|
|
if n, ok := v.(json.Number); ok {
|
|
f, err := n.Float64()
|
|
if err != nil {
|
|
return fmt.Sprint(n)
|
|
}
|
|
return f
|
|
}
|
|
return v
|
|
}
|