rules

Documentation

Overview

Package rules implements stage.Stage with deterministic, YAML-defined matching: ordered rules of payload and field matchers mapped to categories. First matching rule wins; no match means ErrUnclassified so the cascade escalates. As a deterministic stage it always emits confidence 1, with a reason naming the rule and what it matches on.

Index

• Constants
• type Config
• type FieldMatcher
• type Matcher
• type Rule
• type Stage
  • func Load(path string) (*Stage, error)
  • func New(rules []Rule) (*Stage, error)
  • func Parse(data []byte) (*Stage, error)
  • func (s *Stage) Classify(ctx context.Context, r domain.Record) (domain.Classification, error)
  • func (s *Stage) Name() string

Constants

const Name = "rules"

Name identifies this stage in classifications, stats, and logs.

Types

type Config

type Config struct {
	Rules []Rule `yaml:"rules"`
}

Config is the YAML document shape.

type FieldMatcher

type FieldMatcher struct {
	Path     string   `yaml:"path"`
	Exact    *string  `yaml:"exact"`
	Contains *string  `yaml:"contains"`
	Regex    *string  `yaml:"regex"`
	Exists   *bool    `yaml:"exists"`
	Gt       *float64 `yaml:"gt"`
	Gte      *float64 `yaml:"gte"`
	Lt       *float64 `yaml:"lt"`
	Lte      *float64 `yaml:"lte"`
}

FieldMatcher tests one value in a record's decoded Fields, addressed by a dot-separated Path (see fieldpath). Exactly one condition must be set:

• Exact (equal), Contains (substring), Regex (pattern) compare the value as text; a value that is an object or array never matches. Numbers are matched by their text form, so quote them in YAML (exact: "500").
• Gt, Gte, Lt, Lte compare the value as a number; a value that is not numeric (including a numeric-looking string) never matches.
• Exists is true when the path is present, false when absent.

type Matcher

type Matcher struct {
	Contains *string       `yaml:"contains"`
	Regex    *string       `yaml:"regex"`
	Field    *FieldMatcher `yaml:"field"`
}

Matcher is one condition inside an Any or All group: exactly one of a payload Contains substring, a payload Regex, or a Field test.

type Rule

type Rule struct {
	ID       string         `yaml:"id"`
	Category string         `yaml:"category"`
	Contains []string       `yaml:"contains"`
	Regex    []string       `yaml:"regex"`
	Fields   []FieldMatcher `yaml:"fields"`
	Any      []Matcher      `yaml:"any"`
	All      []Matcher      `yaml:"all"`
}

Rule maps matchers to a category. It carries up to three matcher blocks, all of which must be satisfied for the rule to match (an absent block is ignored):

• the top-level Contains/Regex/Fields matchers, satisfied when ANY of them hits (the shorthand for a simple rule);
• All, satisfied when every listed matcher hits;
• Any, satisfied when at least one listed matcher hits.

Substring matching is case-sensitive; use (?i) in a regex for case-insensitive matching. ID and Category label the rule in errors and in the reason attached to a match.

type Stage

type Stage struct {
	// contains filtered or unexported fields
}

Stage is a deterministic rule-matching stage.

func Load

func Load(path string) (*Stage, error)

Load builds a Stage from a YAML file.

func New

func New(rules []Rule) (*Stage, error)

New compiles rules in order. Every rule needs a category and at least one matcher; every regex must compile and every matcher must be well formed.

func Parse

func Parse(data []byte) (*Stage, error)

Parse builds a Stage from a YAML document. Unknown fields are rejected so a misspelled key (categorie, containsx) is a clear error rather than a rule that silently does nothing.

func (*Stage) Classify

func (s *Stage) Classify(ctx context.Context, r domain.Record) (domain.Classification, error)

Classify implements stage.Stage: first matching rule wins, and the result carries the rule's precomputed reason (its id/category and what it matches on).

func (*Stage) Name

func (s *Stage) Name() string

Name implements stage.Stage.