Skip to content

13_feature_control_.md

Latest commit

 

History

History
242 lines (180 loc) · 7.81 KB

13_feature_control_.md

File metadata and controls

242 lines (180 loc) · 7.81 KB

Chapter 13: Feature Control

In the previous chapter, Tagging System, we explored how tags are used to group devices or entities, enabling efficient categorization and management. Now, we move on to Feature Control, an abstraction that allows us to enable or disable specific features for devices. This functionality is critical for managing feature rollouts, ensuring that features are activated based on predefined rules, device contexts, and tags.

13.1 Motivation

The Feature Control abstraction addresses the need to selectively enable or disable features for devices based on their context, such as their model, environment, or associated tags. This enables fine-grained control over which devices can access specific features and ensures that only eligible devices are impacted by feature changes.

Central Use Case

Imagine a scenario where an organization wants to enable a new feature, "Advanced Streaming," for a subset of devices. The devices eligible for this feature are those:

  1. Belonging to a specific model (MODEL_XYZ).
  2. Operating in the PROD environment.
  3. Associated with the tag PremiumDevices.

The Feature Control abstraction evaluates the device context and tags against predefined rules to determine whether the device should have the "Advanced Streaming" feature enabled.

13.2 Key Concepts

13.2.1 Feature

A Feature is a specific functionality or capability that can be controlled (enabled or disabled) for a device. Each feature has:

  • Name: A unique identifier for the feature.
  • Enabled State: Indicates whether the feature is enabled for a device.
  • Configuration Data: Additional data used by the feature (optional).

Example Feature:

{
    "name": "Advanced Streaming",
    "enable": true,
    "configData": {
        "streamQuality": "4K"
    }
}

13.2.2 Feature Rule

A Feature Rule defines the conditions under which a feature is enabled for a device. Each rule consists of:

  • Conditions: Logical checks (e.g., model = MODEL_XYZ, env = PROD).
  • Feature IDs: A list of features that should be enabled if the conditions are met.

Example Feature Rule:

{
    "id": "rule_001",
    "name": "Enable Advanced Streaming for Premium Devices",
    "condition": {
        "freeArg": {
            "type": "STRING",
            "name": "model"
        },
        "operation": "IS",
        "fixedArg": {
            "value": "MODEL_XYZ"
        }
    },
    "featureIds": ["Advanced Streaming"]
}

13.2.3 Feature Control Response

The Feature Control Response is the output of the feature control evaluation. It includes:

  • Feature Responses: A list of features and their enabled states for the device.

Example Response:

{
    "featureControl": {
        "features": [
            {
                "name": "Advanced Streaming",
                "enable": true,
                "configData": {
                    "streamQuality": "4K"
                }
            }
        ]
    }
}

13.3 Using Feature Control

Step 1: Initialize Context Map

The context map represents the device state and is used as input for feature control evaluation.

Example Code:

contextMap := map[string]string{
    "model": "MODEL_XYZ",
    "env": "PROD",
    "eStbMac": "AA:BB:CC:DD:EE:FF",
}

Explanation:

  • model: The device model.
  • env: The environment (e.g., PROD).
  • eStbMac: The MAC address of the device.

Step 2: Evaluate Feature Rules

Pass the context map to the Eval method of the FeatureControlRuleBase to evaluate feature rules.

Example Code:

featureControlRuleBase := featurecontrol.NewFeatureControlRuleBase()
featureControl, _ := featureControlRuleBase.Eval(contextMap, "STB", log.Fields{})

Explanation:

  • NewFeatureControlRuleBase: Initializes the rule base for feature control.
  • Eval: Evaluates the context map against the feature rules and returns the enabled features.

Step 3: Handle the Feature Control Response

The Eval method returns a FeatureControl object containing the list of enabled features.

Example Code:

for _, feature := range featureControl.FeatureResponses {
    fmt.Printf("Feature: %s, Enabled: %v\n", feature["name"], feature["enable"])
}

Explanation:

  • Iterates over the list of features in the response.
  • Prints the name and enabled state of each feature.

13.4 Internal Implementation

Sequence Diagram: Feature Control Evaluation

The following sequence diagram illustrates the process of evaluating feature rules:

sequenceDiagram
participant Device as Device
participant API as Feature Control API
participant Rules as Feature Rules Engine
participant DB as Database

Device->>API: Request feature control settings
API->>Rules: Evaluate context map
Rules->>DB: Fetch feature rules
DB-->>Rules: Return matching rules
Rules-->>API: Return feature control response
API-->>Device: Respond with enabled features
Loading

Key Code Components

1. Evaluating Rules

The Eval method evaluates feature rules and generates the feature control response.

File: dataapi/featurecontrol/feature_rule_eval.go

func (f *FeatureControlRuleBase) Eval(context map[string]string, applicationType string, fields log.Fields) (*rfc.FeatureControl, []*rfc.FeatureRule) {
    appliedFeatureRules := f.ProcessFeatureRules(context, applicationType)
    featureMap := make(map[string]*rfc.Feature)
    for _, rule := range appliedFeatureRules {
        f.AddFeaturesToResult(featureMap, rule.FeatureIds)
    }
    featureResponses := []rfc.FeatureResponse{}
    for _, feature := range featureMap {
        featureResponses = append(featureResponses, rfc.CreateFeatureResponseObject(*feature))
    }
    return &rfc.FeatureControl{FeatureResponses: featureResponses}, appliedFeatureRules
}

Explanation:

  • ProcessFeatureRules: Finds the rules that match the context map.
  • AddFeaturesToResult: Adds the features from the matched rules to the result.
  • CreateFeatureResponseObject: Converts features into response objects.

2. Processing Feature Rules

The ProcessFeatureRules method retrieves and evaluates feature rules.

File: dataapi/featurecontrol/feature_rule_eval.go

func (f *FeatureControlRuleBase) ProcessFeatureRules(context map[string]string, applicationType string) []*rfc.FeatureRule {
    rules := rfc.GetSortedFeatureRules()
    matchedRules := []*rfc.FeatureRule{}
    for _, rule := range rules {
        if applicationType == rule.ApplicationType && f.RuleProcessorFactory.RuleProcessor().Evaluate(rule.Rule, context, log.Fields{}) {
            matchedRules = append(matchedRules, rule)
        }
    }
    return matchedRules
}

Explanation:

  • GetSortedFeatureRules: Retrieves all feature rules from the database.
  • Evaluate: Checks if the rule matches the context map.

13.5 Best Practices

  1. Define Clear Rules: Ensure feature rules are well-structured and avoid overlapping conditions.
  2. Utilize Tags: Use tags to group devices and simplify rule definitions.
  3. Log Rule Evaluations: Enable logging for rule evaluations to debug and monitor feature control decisions.

Summary

In this chapter, we explored Feature Control, an abstraction that allows features to be enabled or disabled for devices based on their context and predefined rules. We learned how to define feature rules, evaluate them using the FeatureControlRuleBase, and handle the response to manage feature rollouts effectively.

In the next chapter, Database Operations, we will dive into how the xconfwebconfig application interacts with the database to manage data.

Generated by AI Codebase Knowledge Builder