expr

type AggregateEvaluator interface {
	// Add adds an expression to the tree evaluator.  This returns true
	// if the expression is aggregateable, or false if the expression will be
	// evaluated each time an event is received.
	Add(ctx context.Context, eval Evaluable) (bool, error)

	// Remove removes an expression from the aggregate evaluator
	Remove(ctx context.Context, eval Evaluable) error

	// Evaluate checks input data against all exrpesssions in the aggregate in an optimal
	// manner, only evaluating expressions when necessary (based off of tree matching).
	//
	// Note that any expressions added that cannot be evaluated optimally by trees
	// are evaluated every time this function is called.
	//
	// Evaluate returns all matching Evaluables, plus the total number of evaluations
	// executed.
	Evaluate(ctx context.Context, data map[string]any) ([]Evaluable, int32, error)

	// AggregateMatch returns all expression parts which are evaluable given the input data.
	AggregateMatch(ctx context.Context, data map[string]any) ([]*StoredExpressionPart, error)

	// Len returns the total number of aggregateable and constantly matched expressions
	// stored in the evaluator.
	Len() int

	// AggregateableLen returns the number of expressions being matched by aggregated trees.
	AggregateableLen() int

	// ConstantLen returns the total number of expressions that must constantly
	// be matched due to non-aggregateable clauses in their expressions.
	ConstantLen() int
}

type CELCompiler interface {
	// Compile calls Compile on the expression, parsing and validating the AST.
	// This returns the AST, issues during validation, and args lifted.
	Compile(expr string) (*cel.Ast, *cel.Issues, LiftedArgs)
	// Parse calls Parse on an expression, but does not check the expression
	// for valid variable names etc. within the env.
	Parse(expr string) (*cel.Ast, *cel.Issues, LiftedArgs)
}

type EngineType int

type Evaluable interface {
	// GetID returns a unique identifier for the evaluable item.  If there are
	// two instances of the same expression, the identifier should return a unique
	// string for each instance of the expression (eg. for two pauses).
	//
	// It has the Get prefix to reduce collisions with implementations who expose an
	// ID member.
	GetID() uuid.UUID

	// GetExpression returns an expression as a raw string.
	//
	// It has the Get prefix to reduce collisions with implementations who expose an
	// Expression member.
	GetExpression() string
}

type EvaluableLoader func(ctx context.Context, evaluableIDs ...uuid.UUID) ([]Evaluable, error)

type ExpressionEvaluator func(ctx context.Context, e Evaluable, input map[string]any) (bool, error)

type ExpressionPart struct {
	// GroupID represents a group ID for the expression part.
	//
	// Within an expression, multiple predicates may be chained with &&.  Each
	// of these must evaluate to `true` for an expression to match.  Group IDs
	// are shared amongst each predicate within an expression.
	//
	// This lets us determine whether the entire group has been matched.
	GroupID   groupID
	Predicate *Predicate
	Parsed    *ParsedExpression
}

type Leaf struct {
	Evals []*ExpressionPart
}

type LiftedArgs interface {
	// Get a lifted variable argument from the parsed expression.
	Get(val string) (any, bool)
	// Return all lifted variables as a map.
	Map() map[string]any
}

type MatchingEngine interface {
	// Type returns the EngineType
	Type() EngineType
	// Match takes an input event, containing key:value pairs of data, and
	// matches the given data to any ExpressionParts stored in the engine.
	//
	// Each implementation of the engine may differ on granularity of
	// expression parts received.  Some may return false positives, but
	// each MatchingEngine should NEVER omit ExpressionParts which match
	// the given input.
	Match(ctx context.Context, input map[string]any) ([]*StoredExpressionPart, error)
	// Add adds a new expression part to the matching engine for future matches.
	Add(ctx context.Context, p ExpressionPart) error
	// Remove removes an expression part from the matching engine, ensuring that the
	// ExpressionPart will not be matched in the future.
	Remove(ctx context.Context, p ExpressionPart) error

	// Search searches for a given variable<>value match, returning any expression
	// parts that match.
	//
	// Similar to match, each implementation of the engine may differ on
	// granularity of expression parts received.  Some may return false positives by
	// ignoring the variable name.  Note that each MatchingEngine should NEVER
	// omit ExpressionParts which match the given input;  false positives are okay,
	// but not returning valid matches must be impossible.
	Search(ctx context.Context, variable string, input any) []*StoredExpressionPart
}

type Node struct {
	GroupID groupID

	// Ands contains predicates at this level of the expression that are joined together
	// with an && operator.  All nodes in this set must evaluate to true in order for this
	// node in the expression to be truthy.
	//
	// Note that if any on of the Ors nodes evaluates to true, this node is truthy, regardless
	// of whether the Ands set evaluates to true.
	Ands []*Node `json:"and,omitempty"`

	// Ors represents matching OR groups within this expression.  For example, in
	// the expression `a == b && (c == 1 || d == 1)` the top-level predicate group will
	// have a child group containing the parenthesis sub-expression.
	//
	// At least one of the Or node's sub-trees must evaluate to true for the node to
	// be truthy, alongside all Ands.
	Ors []*Node `json:"or,omitempty"`

	// Predicate represents the predicate for this node.  This must evaluate to true in order
	// for the expression to be truthy.
	//
	// If this is nil, this is a parent container for a series of AND or Or checks.
	// a == b
	Predicate *Predicate
}

type ParsedExpression struct {
	Root Node

	// Vars represents rewritten literals within the expression.
	//
	// This allows us to rewrite eg. `event.data.id == "foo"` into
	// `event.data.id == vars.a` such that multiple different literals
	// share the same expression.  Using the same expression allows us
	// to cache and skip CEL parsing, which is the slowest aspect of
	// expression matching.
	Vars LiftedArgs

	// Evaluable stores the original evaluable interface that was parsed.
	EvaluableID uuid.UUID

	HasMacros bool
}

type Predicate struct {
	// Literal represents the literal value that the operator compares against.  If two
	// variable are being compared, this is nil and LiteralIdent holds a pointer to the
	// name of the second variable.
	Literal any

	// Ident is the ident we're comparing to, eg. the variable.
	Ident string

	// LiteralIdent represents the second literal that we're comparing against,
	// eg. in the expression "event.data.a == event.data.b" this stores event.data.b
	LiteralIdent *string

	// Operator is the binary operator being used.  NOTE:  This always assumes that the
	// ident is to the left of the operator, eg "event.data.value > 100".  If the value
	// is to the left of the operator, the operator will be switched
	// (ie. 100 > event.data.value becomes event.data.value < 100)
	Operator string
}

type RandomReader func(p []byte) (n int, err error)

type StoredExpressionPart struct {
	GroupID     groupID
	PredicateID uint64
	Parsed      *ParsedExpression
	Ident       *string
}

type StringExpression string

type TreeParser interface {
	Parse(ctx context.Context, eval Evaluable) (*ParsedExpression, error)
}