Skip to content

09_rules_engine_.md

Latest commit

 

History

History
245 lines (178 loc) · 7.67 KB

09_rules_engine_.md

File metadata and controls

245 lines (178 loc) · 7.67 KB

Chapter 9: Rules Engine

In the previous chapter, Firmware Activation and Rules, we explored how activation rules ensure safe and controlled firmware rollouts by defining criteria for firmware activation based on device context and predefined rules. In this chapter, we will delve into the Rules Engine, which provides the core logic for evaluating rules, conditions, and arguments. This abstraction is central to decision-making within the xconfwebconfig application.

9.1 Motivation

The Rules Engine is the backbone of xconfwebconfig for evaluating complex rules that determine firmware assignments, device configurations, and feature activation. At its core, the Rules Engine ensures that every decision made by the application—whether regarding firmware updates or feature controls—is based on logical rules defined by administrators.

Central Use Case

Imagine a scenario where a set-top box (STB) requests its firmware configuration. The firmware must be determined based on multiple parameters, such as the device’s model, MAC address, current firmware version, and environment (e.g., PROD, STAGING). The Rules Engine evaluates these parameters against predefined rules stored in the database and determines the appropriate firmware configuration or blocks the request if no rule matches.

9.2 Key Concepts

9.2.1 Condition

A Condition is the basic building block of a rule. It specifies a logical check that must be satisfied for the rule to apply. Each condition consists of:

  • Free Argument: A dynamic value derived from the device context (e.g., model, firmwareVersion, ipAddress).
  • Operation: The logical operation performed (e.g., IS, IN, LIKE).
  • Fixed Argument: A static value or set of values the free argument is compared against.

Example Condition:

{
    "freeArg": {
        "type": "STRING",
        "name": "model"
    },
    "operation": "IS",
    "fixedArg": {
        "value": "MODEL_XYZ"
    }
}

Explanation:

  • The condition checks if the model free argument is equal to the fixed argument value MODEL_XYZ.

9.2.2 Rule

A Rule is a logical expression composed of one or more conditions. Rules can be simple (containing a single condition) or compound (combining multiple conditions using logical relations like AND or OR).

Example Rule:

{
    "negated": false,
    "relation": "AND",
    "compoundParts": [
        {
            "condition": {
                "freeArg": {
                    "type": "STRING",
                    "name": "model"
                },
                "operation": "IS",
                "fixedArg": {
                    "value": "MODEL_XYZ"
                }
            }
        },
        {
            "condition": {
                "freeArg": {
                    "type": "STRING",
                    "name": "env"
                },
                "operation": "IS",
                "fixedArg": {
                    "value": "PROD"
                }
            }
        }
    ]
}

Explanation:

  • This rule applies only if the model is MODEL_XYZ and the env is PROD.

9.2.3 Rule Processor

The Rule Processor is responsible for evaluating rules against a given context map. It uses a collection of Condition Evaluators to process each condition and determine whether the rule matches the context.

9.3 Using the Rules Engine

Step 1: Defining Context Map

The context map represents the state of the device making the request. For example:

contextMap := map[string]string{
    "model": "MODEL_XYZ",
    "firmwareVersion": "1.0.0",
    "env": "PROD",
    "ipAddress": "192.168.1.1",
}

Explanation:

  • This map contains relevant device attributes, such as model, firmwareVersion, env, and ipAddress, which the rules engine will evaluate.

Step 2: Creating Rules

Rules are typically defined in the database, but for demonstration purposes, you can create them programmatically:

rule := rulesengine.NewEmptyRule()
conditionModel := rulesengine.NewCondition(
    &rulesengine.FreeArg{Type: "STRING", Name: "model"},
    "IS",
    &rulesengine.FixedArg{Value: "MODEL_XYZ"},
)
rule.SetCondition(conditionModel)

Explanation:

  • This code creates a simple rule that checks if the model is MODEL_XYZ.

Step 3: Evaluating Rules

To evaluate a rule, pass the context map and rule to the Rule Processor:

ruleProcessor := rulesengine.NewRuleProcessor()
isMatch := ruleProcessor.Evaluate(rule, contextMap, log.Fields{})

Explanation:

  • Evaluate: Checks whether the rule matches the context.
  • isMatch: Returns true if the rule matches, otherwise false.

Step 4: Handling the Result

Based on the evaluation result, you can take appropriate actions:

if isMatch {
    fmt.Println("Rule matched! Proceed with firmware assignment.")
} else {
    fmt.Println("No matching rule found. Block the request.")
}

9.4 Internal Implementation

Sequence Diagram: Rule Evaluation

Here’s a high-level overview of the workflow when the Rules Engine evaluates a rule:

sequenceDiagram
participant Context as Device Context
participant RuleProcessor as Rule Processor
participant Evaluators as Condition Evaluators
participant RuleStore as Rule Database

Context->>RuleProcessor: Pass context map
RuleProcessor->>RuleStore: Fetch rules
RuleStore-->>RuleProcessor: Return rules
RuleProcessor->>Evaluators: Evaluate conditions
Evaluators-->>RuleProcessor: Return evaluation result
RuleProcessor-->>Context: Return match result
Loading

Code Walkthrough: Key Functions

1. Condition Evaluation

The Evaluate method in the BaseEvaluator processes individual conditions:

func (e *BaseEvaluator) Evaluate(condition *Condition, context map[string]string) bool {
    freeArgValue := context[condition.GetFreeArg().GetName()]
    fixedArg := condition.GetFixedArg()
    return e.evaluateInternal(freeArgValue, fixedArg.GetValue())
}

Explanation:

  • Retrieves the free argument value from the context map and compares it with the fixed argument using the specified operation.

2. Rule Evaluation

The Evaluate method in the RuleProcessor handles rule evaluation:

func (p *RuleProcessor) Evaluate(r *Rule, context map[string]string, fields log.Fields) bool {
    if r.IsCompound() {
        for _, cp := range r.GetCompoundParts() {
            if !p.Evaluate(&cp, context, fields) {
                return false
            }
        }
        return true
    }
    return p.evaluateWithNegation(r, r.IsNegated(), context)
}

Explanation:

  • Evaluates compound rules by recursively processing each part.
  • Handles negated rules by inverting the result.

9.5 Best Practices

  1. Define Clear Rules: Ensure rules are well-structured and avoid overly complex logic.
  2. Use Compound Rules Sparingly: Combine conditions only when necessary to maintain simplicity.
  3. Log Evaluation Results: Use logging to track the evaluation process for debugging and analysis.

Summary

In this chapter, we explored the Rules Engine, which provides the core logic for evaluating rules, conditions, and arguments in xconfwebconfig. You learned how to define and evaluate rules using the Rule Processor, leveraging the context map and condition evaluators. This abstraction is vital for decision-making processes within the application.

In the next chapter, Device Configuration Management, we will explore how xconfwebconfig manages device configurations.

Generated by AI Codebase Knowledge Builder