README.md

ruleengine

Tier: Platform · Status: Full · Java original: firefly-common-rule-engine · .NET project: FireflyFramework.RuleEngine.{Interfaces,Models,Core,Web,Sdk}

Overview

ruleengine is the framework's declarative business-rule engine. Rules are authored as YAML documents (or programmatically via the models package), parsed into an AST, and evaluated by a recursive walker that resolves fact-paths against a map[string]any context.

Sub-packages mirror the .NET project split:

• models — AST: Rule, RuleSet, Logic, Condition, Action, Op.
• interfaces — port: Evaluator, Verdict.
• core — implementation of Evaluator.
• web — REST admin (planned for v26.06).
• sdk — typed admin client (planned for v26.06).

Rule shape

name: vip-tagging
version: 1
rules:
  - id: premium
    priority: 10
    when:
      all:
        - cond: { path: user.age,     op: gte, value: 18 }
        - cond: { path: user.country, op: in,  value: [ES, FR] }
    then:
      - type: tag
        params: { name: premium }
  - id: vip
    priority: 5
    when:
      any:
        - cond: { path: user.spend,    op: gt,        value: 1000 }
        - cond: { path: user.referral, op: isNotNull }
    then:
      - type: tag
        params: { name: vip }

Operators

eq, ne, lt, lte, gt, gte, in, notIn, contains, startsWith, endsWith, matches (regex), isNull, isNotNull.

Public surface

// models
type Op       string
type Condition struct { Path string; Op Op; Value any }
type Logic     struct { All, Any []Logic; Not *Logic; Cond *Condition }
type Action    struct { Type string; Params map[string]any }
type Rule      struct { ID, Description string; Priority int; When Logic; Then []Action }
type RuleSet   struct { Name, Version string; Rules []Rule }

// interfaces
type Verdict struct { Matched []string; Actions []models.Action }
type Evaluator interface { Evaluate(ctx, RuleSet, fact map[string]any) (Verdict, error) }

// core
func New() *Evaluator   // stateless

Rules fire in descending priority order; ties broken by document order. The Verdict returns the matched rule IDs and the merged action list.

Quick start

import (
    "context"
    "github.com/fireflyframework/fireflyframework-go/ruleengine/core"
    models "github.com/fireflyframework/fireflyframework-go/ruleengine/models"
)

rs := models.RuleSet{Rules: []models.Rule{{
    ID: "high-value",
    When: models.Logic{Cond: &models.Condition{Path: "amount", Op: models.Gt, Value: 1000.0}},
    Then: []models.Action{{Type: "review", Params: map[string]any{"queue": "manual"}}},
}}}

verdict, _ := core.New().Evaluate(ctx, rs, map[string]any{"amount": 1500})
// verdict.Matched == ["high-value"]
// verdict.Actions == [{Type: "review", Params: {"queue":"manual"}}]

Testing

cd ruleengine
go test ./...

Covers all / any / not composition, regex matches, range fall-through, priority ordering, and unknown-operator rejection.