feat(Local evaluation): Use the new context-based engine (#109)

* Introduce context values evaluation data model

* Update engine test data

* Get ready for engine tests

* Introduce new engine

* Lint ✨

* Make priority clearer

* Update EvaluationResult spec

Contributes to Flagsmith/flagsmith#6121

* yay

* Fix identity traits data type

* WIP: First pass at using the new engine

* Update engine test data branch

* Let's talk, environment document

* Fix the toolbox

* Fix identity as an optional context

* Improve API

* Fix the talking

* Fix local evaluation setting

* Fix cloning contexts

* Make it easier to test private members

* Delete outdated code

* Make sure getEnvironmentFlags now works as expected

* Make code reusable

* Apples will never be bananas

* Found the key

* Connect all the dots

* Please run tests

* Stop wasting cycles

* Revert API changes in the offline handler

* Revert "Stop wasting cycles"

This reverts commit a52c914.

* Prevent us from deleting code we don't understand

* Fix casting

* Improve clarity

* Track TODO with an issue

#110

* Improve type handling in the IN operator

* Make MODULO check less prone to error

* Fix obtaining a context value

* Update comment to latest reality

* Delete skippable code

* Update test cases

* Fix tests

* Carry segment metadata around

* Please run tests

(cherry picked from commit 2913611)

* Map segment metadata from the environment context

* Comply with latest test data

* Ensure variants are selected consistently

* To each their responsibilities

* Update tests

* Respect historical variant priority (UUID-based)

* Improve architecture with feature metadata

* Fix virtual segments bleeding to the client

Author: emyller

.gitmodules

@@ -1,4 +1,4 @@
 [submodule "tests/Engine/EngineTests/EngineTestData"]
 	path = tests/Engine/EngineTests/EngineTestData
 	url = git@github.com:Flagsmith/engine-test-data.git
-	tag = v2.4.0
+	tag = v2.5.0

src/Engine/Engine.php

@@ -57,7 +57,7 @@ public static function getEvaluationResult($context): EvaluationResult
             $segmentResult = new SegmentResult();
             $segmentResult->key = $segment->key;
             $segmentResult->name = $segment->name;
-            $segmentResult->metadata = $segment->metadata ?? null;
+            $segmentResult->metadata = $segment->metadata;
             $evaluatedSegments[] = $segmentResult;
 
             foreach ($segment->overrides as $overrideFeature) {
@@ -152,6 +152,7 @@ private static function getFlagResultFromFeatureContext($feature, $splitKey)
                     $flag->enabled = $feature->enabled;
                     $flag->value = $variant->value;
                     $flag->reason = "SPLIT; weight={$variant->weight}";
+                    $flag->metadata = $feature->metadata;
                     return $flag;
                 }
                 $startPercentage = $limit;
@@ -164,6 +165,7 @@ private static function getFlagResultFromFeatureContext($feature, $splitKey)
         $flag->enabled = $feature->enabled;
         $flag->value = $feature->value;
         $flag->reason = 'DEFAULT';
+        $flag->metadata = $feature->metadata;
         return $flag;
     }
 
@@ -180,6 +182,7 @@ private static function getFlagResultFromSegmentContext($feature, $segment)
         $flag->enabled = $feature->enabled;
         $flag->value = $feature->value;
         $flag->reason = "TARGETING_MATCH; segment={$segment->name}";
+        $flag->metadata = $feature->metadata;
         return $flag;
     }
 

src/Engine/Features/FeatureStateModel.php

@@ -17,7 +17,7 @@ class FeatureStateModel
 
     public FeatureModel $feature;
     public bool $enabled;
-    private $_value;
+    public mixed $feature_state_value;
     public string $featurestate_uuid;
     public MultivariateFeatureStateValueModelList $multivariate_feature_state_values;
     public ?int $django_id = null;
@@ -157,7 +157,7 @@ public function getValue($identityId = null)
         if ($identityId && count($this->multivariate_feature_state_values) > 0) {
             return $this->getMultivariateValue($identityId);
         }
-        return $this->_value;
+        return $this->feature_state_value;
     }
 
     /**
@@ -207,7 +207,7 @@ function (
             $startPercentage = $limit;
         }
 
-        return $this->_value;
+        return $this->feature_state_value;
     }
 
     /**
@@ -217,7 +217,7 @@ function (
      */
     public function setValue($value)
     {
-        $this->_value = $value;
+        $this->feature_state_value = $value;
     }
 
 
@@ -232,7 +232,7 @@ protected function setValues($values)
         unset($values->feature_state_value);
         $this->setValuesSerializer($values);
         if (!empty($featureStateValue)) {
-            $this->_value = $featureStateValue;
+            $this->feature_state_value = $featureStateValue;
         }
     }
 

src/Engine/Utils/Types/Context/EvaluationContext.php

@@ -36,7 +36,7 @@ public static function fromJsonObject($jsonContext)
         }
 
         $context->segments = [];
-        foreach ($jsonContext->segments as $jsonSegment) {
+        foreach (($jsonContext->segments ?? []) as $jsonSegment) {
             $segment = new SegmentContext();
             $segment->key = $jsonSegment->key;
             $segment->name = $jsonSegment->name;
@@ -51,6 +51,15 @@ public static function fromJsonObject($jsonContext)
         return $context;
     }
 
+    /**
+     * Deep clone the EvaluationContext
+     * @return EvaluationContext
+     */
+    public function deepClone(): self
+    {
+        return EvaluationContext::fromJsonObject($this);
+    }
+
     /**
      * @param array<object> $jsonRules
      * @return array<SegmentRule>
@@ -60,15 +69,17 @@ private static function _convertRules($jsonRules)
         $rules = [];
         foreach ($jsonRules as $jsonRule) {
             $rule = new SegmentRule();
-            $rule->type = SegmentRuleType::from($jsonRule->type);
+            $rule->type = $jsonRule->type instanceof SegmentRuleType
+                ? $jsonRule->type
+                : SegmentRuleType::from($jsonRule->type);
 
             $rule->conditions = [];
             foreach ($jsonRule->conditions ?? [] as $jsonCondition) {
                 $condition = new SegmentCondition();
                 $condition->property = $jsonCondition->property;
-                $condition->operator = SegmentConditionOperator::from(
-                    $jsonCondition->operator,
-                );
+                $condition->operator = $jsonCondition->operator instanceof SegmentConditionOperator
+                    ? $jsonCondition->operator
+                    : SegmentConditionOperator::from($jsonCondition->operator);
                 $condition->value = $jsonCondition->value;
                 $rule->conditions[] = $condition;
             }
@@ -93,11 +104,12 @@ private static function _convertFeatures($jsonFeatures): array
         foreach ($jsonFeatures as $jsonFeature) {
             $feature = new FeatureContext();
             $feature->key = $jsonFeature->key;
-            $feature->feature_key = $jsonFeature->feature_key;
+            $feature->feature_key = (string) $jsonFeature->feature_key;
             $feature->name = $jsonFeature->name;
             $feature->enabled = $jsonFeature->enabled;
             $feature->value = $jsonFeature->value;
             $feature->priority = $jsonFeature->priority ?? null;
+            $feature->metadata = (array) ($jsonFeature->metadata ?? []);
             $feature->variants = [];
             foreach ($jsonFeature->variants ?? [] as $jsonVariant) {
                 $variant = new FeatureValue();

src/Engine/Utils/Types/Context/FeatureContext.php

@@ -24,4 +24,7 @@ class FeatureContext
 
     /** @var array<FeatureValue> */
     public $variants;
+
+    /** @var ?array<string,mixed> */
+    public $metadata;
 }

src/Engine/Utils/Types/Result/FlagResult.php

@@ -2,7 +2,7 @@
 
 namespace Flagsmith\Engine\Utils\Types\Result;
 
-class FlagResult
+class FlagResult implements \JsonSerializable
 {
     /** @var string */
     public $feature_key;
@@ -18,4 +18,19 @@ class FlagResult
 
     /** @var ?string */
     public $reason;
+
+    /** @var ?array<string,mixed> */
+    public $metadata;
+
+    public function jsonSerialize(): array
+    {
+        $data = get_object_vars($this);
+
+        // 'metadata' is only added if there is any
+        if (empty($this->metadata)) {
+            unset($data['metadata']);
+        }
+
+        return $data;
+    }
 }

src/Engine/Utils/Types/Result/SegmentResult.php

@@ -15,14 +15,11 @@ class SegmentResult implements \JsonSerializable
 
     public function jsonSerialize(): array
     {
-        $data = [
-            'key' => $this->key,
-            'name' => $this->name,
-        ];
+        $data = get_object_vars($this);
 
         // 'metadata' is only added if there is any
-        if (!empty($this->metadata)) {
-            $data['metadata'] = $this->metadata;
+        if (empty($this->metadata)) {
+            unset($data['metadata']);
         }
 
         return $data;