feat: Evaluate flags that depend on other flags

.gitmodules

@@ -1,4 +1,4 @@
 [submodule "tests/engine_tests/engine-test-data"]
 	path = tests/engine_tests/engine-test-data
 	url = https://github.com/flagsmith/engine-test-data.git
-	branch = v3.7.0
+	branch = v3.12.1

Cargo.toml

@@ -13,7 +13,8 @@ maintenance = { status = "actively-developed" }
 [dependencies]
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
-serde_json_path = "0.7"
+jsonpath-rust = "1.0"
+indexmap = { version = "2.14", features = ["serde"] }
 chrono = { version = "0.4", features = ["serde"] }
 md-5 = "0.10.1"
 num-bigint = "0.4"

src/engine.rs

@@ -1,40 +1,56 @@
 use crate::engine_eval::context::{EngineEvaluationContext, FeatureContext};
 use crate::engine_eval::result::{EvaluationResult, FlagResult, SegmentResult};
-use crate::engine_eval::segment_evaluator::SegmentEvaluator;
+use crate::engine_eval::segment_evaluator::{ResolvedFlags, SegmentEvaluator};
 use crate::utils::hashing;
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
 
-/// Holds a feature context with its associated segment name for priority comparison
-struct FeatureContextWithSegment {
-    feature_context: FeatureContext,
-    segment_name: String,
+/// Reason given to flags whose evaluation depends on themselves.
+pub const CIRCULAR_DEPENDENCY_REASON: &str = "ERROR; code=CIRCULAR_DEPENDENCY";
+
+/// A segment override, with the name of the segment it belongs to
+pub(crate) struct SegmentOverride<'a> {
+    pub(crate) feature_context: &'a FeatureContext,
+    pub(crate) segment_name: &'a str,
 }
 
 /// Helper to get priority or default
 fn get_priority_or_default(priority: Option<f64>) -> f64 {
     priority.unwrap_or(f64::INFINITY) // Weakest possible priority
 }
 
+/// Whether a segment override takes precedence over the one held so far; the first seen wins a tie
+pub(crate) fn wins_over(candidate: &FeatureContext, incumbent: Option<&FeatureContext>) -> bool {
+    incumbent.is_none_or(|incumbent| {
+        get_priority_or_default(candidate.priority) < get_priority_or_default(incumbent.priority)
+    })
+}
+
+/// Gets the reason for a flag evaluated to its environment default:
+/// `DEFAULT` if segments override the feature, `STATIC` if none does.
+pub(crate) fn get_fallback_reason(is_targeted: bool) -> String {
+    if is_targeted { "DEFAULT" } else { "STATIC" }.to_string()
+}
+
+/// Matching segments, the winning override of each feature they override, and every feature any segment overrides
+struct SegmentEvaluation<'a> {
+    segments: Vec<SegmentResult>,
+    segment_overrides: HashMap<&'a str, SegmentOverride<'a>>,
+    targeted_feature_names: HashSet<&'a str>,
+}
+
 /// Gets matching segments and their overrides
-fn get_matching_segments_and_overrides(
-    ec: &EngineEvaluationContext,
-) -> (
-    Vec<SegmentResult>,
-    HashMap<String, FeatureContextWithSegment>,
-) {
+fn evaluate_segments<'a>(
+    ec: &'a EngineEvaluationContext,
+    evaluator: &SegmentEvaluator<'a>,
+) -> SegmentEvaluation<'a> {
     let mut segments = Vec::new();
-    let mut segment_feature_contexts: HashMap<String, FeatureContextWithSegment> = HashMap::new();
-    let evaluator = SegmentEvaluator::new(ec);
-
-    // Sort segment keys for deterministic ordering
-    let mut segment_keys: Vec<_> = ec.segments.keys().collect();
-    segment_keys.sort();
+    let mut segment_overrides: HashMap<&str, SegmentOverride> = HashMap::new();
+    let mut targeted_feature_names = HashSet::new();
 
-    // Process segments in sorted order
-    for segment_key in segment_keys {
-        let segment_context = &ec.segments[segment_key];
+    for (segment_key, segment_context) in &ec.segments {
+        targeted_feature_names.extend(segment_context.overrides.iter().map(|o| o.name.as_str()));
 
-        if !evaluator.is_context_in_segment(segment_context) {
+        if !evaluator.matches_segment_key(segment_key) {
             continue;
         }
 
@@ -46,39 +62,62 @@ fn get_matching_segments_and_overrides(
 
         // Process segment overrides
         for override_fc in &segment_context.overrides {
-            let feature_name = &override_fc.name;
-
-            // Check if we should update the segment feature context
-            let should_update = if let Some(existing) = segment_feature_contexts.get(feature_name) {
-                let existing_priority = get_priority_or_default(existing.feature_context.priority);
-                let override_priority = get_priority_or_default(override_fc.priority);
-                override_priority < existing_priority
-            } else {
-                true
-            };
-
-            if should_update {
-                segment_feature_contexts.insert(
-                    feature_name.clone(),
-                    FeatureContextWithSegment {
-                        feature_context: override_fc.clone(),
-                        segment_name: segment_context.name.clone(),
+            let incumbent = segment_overrides
+                .get(override_fc.name.as_str())
+                .map(|o| o.feature_context);
+            if wins_over(override_fc, incumbent) {
+                segment_overrides.insert(
+                    &override_fc.name,
+                    SegmentOverride {
+                        feature_context: override_fc,
+                        segment_name: &segment_context.name,
                     },
                 );
             }
         }
     }
 
-    (segments, segment_feature_contexts)
+    SegmentEvaluation {
+        segments,
+        segment_overrides,
+        targeted_feature_names,
+    }
 }
 
 /// Gets flag results from feature contexts and segment overrides
 fn get_flag_results(
     ec: &EngineEvaluationContext,
-    segment_feature_contexts: &HashMap<String, FeatureContextWithSegment>,
+    segment_evaluation: &SegmentEvaluation,
+    identity_key: Option<&String>,
 ) -> HashMap<String, FlagResult> {
     let mut flags = HashMap::new();
 
+    // Process all features
+    for feature_context in ec.features.values() {
+        let feature_name = feature_context.name.as_str();
+        let flag_result = match segment_evaluation.segment_overrides.get(feature_name) {
+            Some(segment_override) => get_flag_result_from_feature_context(
+                segment_override.feature_context,
+                identity_key,
+                format!("TARGETING_MATCH; segment={}", segment_override.segment_name),
+            ),
+            None => get_flag_result_from_feature_context(
+                feature_context,
+                identity_key,
+                get_fallback_reason(
+                    segment_evaluation
+                        .targeted_feature_names
+                        .contains(feature_name),
+                ),
+            ),
+        };
+        flags.insert(feature_context.name.clone(), flag_result);
+    }
+
+    flags
+}
+
+pub fn get_evaluation_result(ec: &EngineEvaluationContext) -> EvaluationResult {
     // Get identity key if identity exists
     // If identity key is not provided, construct it from environment key and identifier
     let identity_key: Option<String> = ec.identity.as_ref().map(|i| {
@@ -89,54 +128,49 @@ fn get_flag_results(
         }
     });
 
-    // Process all features
-    for feature_context in ec.features.values() {
-        // Check if we have a segment override for this feature
-        if let Some(segment_fc) = segment_feature_contexts.get(&feature_context.name) {
-            // Use segment override with multivariate evaluation
-            let fc = &segment_fc.feature_context;
-            let reason = format!("TARGETING_MATCH; segment={}", segment_fc.segment_name);
-            let flag_result =
-                get_flag_result_from_feature_context(fc, identity_key.as_ref(), reason);
-            flags.insert(feature_context.name.clone(), flag_result);
-        } else {
-            // Use default feature context
-            let flag_result = get_flag_result_from_feature_context(
-                feature_context,
-                identity_key.as_ref(),
-                "DEFAULT".to_string(),
-            );
-            flags.insert(feature_context.name.clone(), flag_result);
+    let evaluator = SegmentEvaluator::with_flag_dependencies(ec, identity_key.as_ref());
+    let segment_evaluation = evaluate_segments(ec, &evaluator);
+    let mut flags = get_flag_results(ec, &segment_evaluation, identity_key.as_ref());
+
+    // Flags read by segment conditions take precedence, as only they were resolved guarding against cycles
+    let ResolvedFlags {
+        flags: resolved_flags,
+        cyclic,
+    } = evaluator.into_resolved_flags();
+    flags.extend(
+        resolved_flags
+            .into_iter()
+            .map(|(feature_name, flag)| (feature_name.to_string(), flag)),
+    );
+    for feature_name in cyclic {
+        if let Some(flag) = flags.get_mut(feature_name) {
+            flag.reason = CIRCULAR_DEPENDENCY_REASON.to_string();
         }
     }
 
-    flags
-}
-
-pub fn get_evaluation_result(ec: &EngineEvaluationContext) -> EvaluationResult {
-    // Process segments
-    let (segments, segment_feature_contexts) = get_matching_segments_and_overrides(ec);
-
-    // Get flag results
-    let flags = get_flag_results(ec, &segment_feature_contexts);
-
-    EvaluationResult { flags, segments }
+    EvaluationResult {
+        flags,
+        segments: segment_evaluation.segments,
+    }
 }
 
 /// Creates a FlagResult from a FeatureContext
-fn get_flag_result_from_feature_context(
+pub(crate) fn get_flag_result_from_feature_context(
     feature_context: &FeatureContext,
     identity_key: Option<&String>,
     default_reason: String,
 ) -> FlagResult {
     let mut reason = default_reason;
     let mut value = feature_context.value.clone();
+    let mut variant = None;
 
     // Handle multivariate features
     if !feature_context.variants.is_empty()
         && identity_key.is_some()
         && !feature_context.key.is_empty()
     {
+        variant = Some("control".to_string()); // Unless a variant is selected below
+
         // Sort variants by priority (lower priority value = higher priority)
         let mut sorted_variants = feature_context.variants.clone();
         sorted_variants.sort_by(|a, b| {
@@ -151,11 +185,12 @@ fn get_flag_result_from_feature_context(
 
         // Select variant based on weighted distribution
         let mut cumulative_weight = 0.0;
-        for variant in &sorted_variants {
-            cumulative_weight += variant.weight;
+        for feature_value in &sorted_variants {
+            cumulative_weight += feature_value.weight;
             if (hash_percentage as f64) <= cumulative_weight {
-                value = variant.value.clone();
-                reason = format!("SPLIT; weight={}", variant.weight);
+                value = feature_value.value.clone();
+                variant = feature_value.key.clone();
+                reason = format!("SPLIT; weight={}", feature_value.weight);
                 break;
             }
         }
@@ -165,6 +200,7 @@ fn get_flag_result_from_feature_context(
         enabled: feature_context.enabled,
         name: feature_context.name.clone(),
         value,
+        variant,
         reason,
         metadata: feature_context.metadata.clone(),
     }
@@ -189,7 +225,7 @@ mod tests {
                 name: "test".to_string(),
             },
             features: HashMap::new(),
-            segments: HashMap::new(),
+            segments: Default::default(),
             identity: None,
         };
 

src/engine_eval/context.rs

@@ -1,4 +1,5 @@
 use crate::types::FlagsmithValue;
+use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 
@@ -29,6 +30,9 @@ fn default_feature_type() -> String {
 /// Represents a multivariate value for a feature flag.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct FeatureValue {
+    /// The key identifying this variant in flag results.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub key: Option<String>,
     /// The value of the feature.
     pub value: FlagsmithValue,
     /// The weight of the feature value variant, as a percentage number (i.e. 100.0).
@@ -257,9 +261,9 @@ pub struct EngineEvaluationContext {
     #[serde(default)]
     pub features: HashMap<String, FeatureContext>,
 
-    /// Segment contexts indexed by segment key.
+    /// Segment contexts indexed by segment key, in evaluation order.
     #[serde(default)]
-    pub segments: HashMap<String, SegmentContext>,
+    pub segments: IndexMap<String, SegmentContext>,
 
     /// Optional identity context for evaluation.
     #[serde(skip_serializing_if = "Option::is_none")]

src/engine_eval/mappers.rs

@@ -7,6 +7,7 @@ use crate::environments::Environment;
 use crate::features::{FeatureState, MultivariateFeatureStateValue};
 use crate::identities::{Identity, Trait};
 use crate::segments::{Segment, SegmentRule as OldSegmentRule};
+use indexmap::IndexMap;
 use sha2::{Digest, Sha256};
 use std::collections::HashMap;
 
@@ -24,7 +25,7 @@ pub fn environment_to_context(environment: Environment) -> EngineEvaluationConte
             name: environment.name.clone(),
         },
         features: HashMap::new(),
-        segments: HashMap::new(),
+        segments: IndexMap::new(),
         identity: None,
     };
 
@@ -91,6 +92,7 @@ fn map_multivariate_values_to_variants(
     mv_values
         .iter()
         .map(|mv| FeatureValue {
+            key: None,
             value: mv.multivariate_feature_option.value.clone(),
             weight: mv.percentage_allocation as f64,
             priority: None,
@@ -340,3 +342,36 @@ pub fn add_identity_to_context(
     new_context.identity = Some(identity);
     new_context
 }
+
+/// Gets the context to evaluate environment flags against
+///
+/// # Arguments
+/// * `context` - The context to evaluate environment flags for
+///
+/// # Returns
+/// A new context without identity, keeping only segments whose every condition reads the environment or other flags
+pub fn remove_identity_from_context(context: &EngineEvaluationContext) -> EngineEvaluationContext {
+    EngineEvaluationContext {
+        environment: context.environment.clone(),
+        features: context.features.clone(),
+        segments: context
+            .segments
+            .iter()
+            .filter(|(_, segment)| is_identity_free(&segment.rules))
+            .map(|(key, segment)| (key.clone(), segment.clone()))
+            .collect(),
+        identity: None,
+    }
+}
+
+fn is_identity_free(rules: &[SegmentRule]) -> bool {
+    const IDENTITY_FREE_PROPERTY_PREFIXES: [&str; 4] =
+        ["$.environment.", "$.environment[", "$.flags.", "$.flags["];
+    rules.iter().all(|rule| {
+        rule.conditions.iter().all(|condition| {
+            IDENTITY_FREE_PROPERTY_PREFIXES
+                .iter()
+                .any(|prefix| condition.property.starts_with(prefix))
+        }) && is_identity_free(&rule.rules)
+    })
+}

src/engine_eval/mod.rs

@@ -12,6 +12,6 @@ pub mod mappers;
 
 // Re-export commonly used types for convenience
 pub use context::{EngineEvaluationContext, FeatureContext, FeatureMetadata, SegmentSource};
-pub use mappers::{add_identity_to_context, environment_to_context};
+pub use mappers::{add_identity_to_context, environment_to_context, remove_identity_from_context};
 pub use result::{EvaluationResult, FlagResult, SegmentResult};
 pub use segment_evaluator::is_context_in_segment;