featurevisor 1.1.0 → 3.0.0

data/lib/featurevisor/evaluate.rb

@@ -19,6 +19,7 @@ module Featurevisor
     VARIABLE_DISABLED = "variable_disabled" # feature is disabled, and variable's disabledValue is used
     VARIABLE_OVERRIDE_VARIATION = "variable_override_variation" # variable overridden from inside a variation
     VARIABLE_OVERRIDE_RULE = "variable_override_rule" # variable overridden from inside a rule
+    REQUIRED_FEATURES_UNMET = "required_features_unmet"
 
     # Common
     NO_MATCH = "no_match" # no rules matched
@@ -35,6 +36,50 @@ module Featurevisor
 
   # Evaluation module for feature flag evaluation
   module Evaluate
+    def self.required_features_are_matched(requirements, datafile, options)
+      return true if requirements.nil?
+
+      items = requirements.is_a?(Array) ? requirements : [requirements]
+      clean_options = options.reject do |key, _|
+        %i[feature_key variable_key default_variation_value default_variable_value].include?(key)
+      end
+      items.all? do |required|
+        if required.is_a?(String)
+          key = required
+          enabled = true
+          variation = nil
+        elsif required.key?(:feature)
+          key = required[:feature]
+          enabled = required.key?(:enabled) ? required[:enabled] : true
+          variation = required[:variation]
+        else
+          key = required[:key]
+          enabled = true
+          variation = required[:variation]
+        end
+
+        flag = evaluate_with_modules(clean_options.merge(type: "flag", feature_key: key, datafile: datafile))
+        next false unless (flag[:enabled] == true) == enabled
+        next true if variation.nil?
+
+        evaluated_variation = evaluate_with_modules(clean_options.merge(type: "variation", feature_key: key, datafile: datafile))
+        value = evaluated_variation.key?(:variation_value) ? evaluated_variation[:variation_value] : evaluated_variation.dig(:variation, :value)
+        value == variation
+      end
+    end
+
+    def self.variable_override_matches?(override, datafile, context, options)
+      return false unless required_features_are_matched(override[:requiredFeatures], datafile, options)
+
+      conditions_match = !override[:conditions] || datafile.all_conditions_are_matched(
+        datafile.parse_conditions_if_stringified(override[:conditions]), context
+      )
+      segments_match = !override[:segments] || datafile.all_segments_are_matched(
+        datafile.parse_segments_if_stringified(override[:segments]), context
+      )
+      conditions_match && segments_match &&
+        (override.key?(:conditions) || override.key?(:segments) || override.key?(:requiredFeatures))
+    end
 
     # Evaluate with modules
     # @param options [Hash] Evaluation options
@@ -53,17 +98,18 @@ module Featurevisor
         evaluation = evaluate(result_options)
 
         # Default: variation
-        if options.key?(:default_variation_value) &&
+        if result_options.key?(:default_variation_value) &&
            evaluation[:type] == "variation" &&
-           evaluation[:variation_value].nil?
-          evaluation[:variation_value] = options[:default_variation_value]
+           !evaluation.key?(:variation_value) &&
+           !evaluation.key?(:variation)
+          evaluation[:variation_value] = result_options[:default_variation_value]
         end
 
         # Default: variable
-        if options.key?(:default_variable_value) &&
+        if result_options.key?(:default_variable_value) &&
            evaluation[:type] == "variable" &&
-           evaluation[:variable_value].nil?
-          evaluation[:variable_value] = options[:default_variable_value]
+           !evaluation.key?(:variable_value)
+          evaluation[:variable_value] = result_options[:default_variable_value]
         end
 
         # Run after modules
@@ -76,7 +122,7 @@ module Featurevisor
         type = options[:type]
         feature_key = options[:feature_key]
         variable_key = options[:variable_key]
-        logger = options[:logger]
+        diagnostics = options[:diagnostics]
 
         evaluation = {
           type: type,
@@ -86,7 +132,7 @@ module Featurevisor
           error: e
         }
 
-        logger.error("error during evaluation", evaluation)
+        diagnostics.error("Error during evaluation", evaluation)
 
         evaluation
       end
@@ -100,8 +146,8 @@ module Featurevisor
       feature_key = options[:feature_key]
       variable_key = options[:variable_key]
       context = options[:context]
-      logger = options[:logger]
-      datafile_reader = options[:datafile_reader]
+      diagnostics = options[:diagnostics]
+      datafile = options[:datafile]
       sticky = options[:sticky]
       modules_manager = options[:modules_manager]
       evaluation = nil
@@ -120,7 +166,7 @@ module Featurevisor
               reason: Featurevisor::EvaluationReason::DISABLED
             }
 
-            feature = datafile_reader.get_feature(feature_key)
+            feature = datafile.get_feature(feature_key)
 
             # serve variable default value if feature is disabled (if explicitly specified)
             if type == "variable"
@@ -156,7 +202,7 @@ module Featurevisor
             end
 
             # serve disabled variation value if feature is disabled (if explicitly specified)
-            if type == "variation" && feature && feature[:disabledVariationValue]
+            if type == "variation" && feature && feature.key?(:disabledVariationValue)
               evaluation = {
                 type: type,
                 feature_key: feature_key,
@@ -166,7 +212,7 @@ module Featurevisor
               }
             end
 
-            logger.debug("feature is disabled", evaluation)
+            diagnostics.debug("feature is disabled", evaluation)
 
             return evaluation
           end
@@ -186,7 +232,7 @@ module Featurevisor
               enabled: sticky_feature[:enabled]
             }
 
-            logger.debug("using sticky enabled", evaluation)
+            diagnostics.debug("using sticky enabled", evaluation)
 
             return evaluation
           end
@@ -195,7 +241,7 @@ module Featurevisor
           if type == "variation"
             variation_value = sticky_feature[:variation]
 
-            unless variation_value.nil?
+            if sticky_feature.key?(:variation)
               evaluation = {
                 type: type,
                 feature_key: feature_key,
@@ -203,7 +249,7 @@ module Featurevisor
                 variation_value: variation_value
               }
 
-              logger.debug("using sticky variation", evaluation)
+              diagnostics.debug("using sticky variation", evaluation)
 
               return evaluation
             end
@@ -223,7 +269,7 @@ module Featurevisor
                 variable_value: variable_value
               }
 
-              logger.debug("using sticky variable", evaluation)
+              diagnostics.debug("using sticky variable", evaluation)
 
               return evaluation
             end
@@ -231,7 +277,7 @@ module Featurevisor
         end
 
         # Feature
-        feature = feature_key.is_a?(String) ? datafile_reader.get_feature(feature_key) : feature_key
+        feature = feature_key.is_a?(String) ? datafile.get_feature(feature_key) : feature_key
 
         # feature: not found
         unless feature
@@ -241,14 +287,14 @@ module Featurevisor
             reason: Featurevisor::EvaluationReason::FEATURE_NOT_FOUND
           }
 
-          logger.warn("feature not found", evaluation)
+          diagnostics.warn("feature not found", evaluation)
 
           return evaluation
         end
 
         # feature: deprecated
         if type == "flag" && feature[:deprecated]
-          logger.warn("feature is deprecated", { feature_key: feature_key })
+          diagnostics.warn("feature is deprecated", { feature_key: feature_key })
         end
 
         # variableSchema
@@ -268,13 +314,13 @@ module Featurevisor
               variable_key: variable_key
             }
 
-            logger.warn("variable schema not found", evaluation)
+            diagnostics.warn("variable schema not found", evaluation)
 
             return evaluation
           end
 
           if variable_schema[:deprecated]
-            logger.warn("variable is deprecated", {
+            diagnostics.warn("variable is deprecated", {
               feature_key: feature_key,
               variable_key: variable_key
             })
@@ -289,13 +335,13 @@ module Featurevisor
             reason: Featurevisor::EvaluationReason::NO_VARIATIONS
           }
 
-          logger.warn("no variations", evaluation)
+          diagnostics.warn("no variations", evaluation)
 
           return evaluation
         end
 
         # Forced
-        force_result = datafile_reader.get_matched_force(feature, context)
+        force_result = datafile.get_matched_force(feature, context)
         force = force_result[:force]
         force_index = force_result[:forceIndex]
 
@@ -311,7 +357,7 @@ module Featurevisor
               enabled: force[:enabled]
             }
 
-            logger.debug("forced enabled found", evaluation)
+            diagnostics.debug("forced enabled found", evaluation)
 
             return evaluation
           end
@@ -330,7 +376,7 @@ module Featurevisor
                 variation: variation
               }
 
-              logger.debug("forced variation found", evaluation)
+              diagnostics.debug("forced variation found", evaluation)
 
               return evaluation
             end
@@ -350,46 +396,16 @@ module Featurevisor
               variable_value: variable_value
             }
 
-            logger.debug("forced variable", evaluation)
+            diagnostics.debug("forced variable", evaluation)
 
             return evaluation
           end
         end
 
         # Required
-        if type == "flag" && feature[:required] && feature[:required].length > 0
-          required_features_are_enabled = feature[:required].all? do |required|
-            required_key = nil
-            required_variation = nil
-
-            if required.is_a?(String)
-              required_key = required
-            else
-              required_key = required[:key]
-              required_variation = required[:variation]
-            end
-
-            required_evaluation = evaluate(options.merge(type: "flag", feature_key: required_key))
-            required_is_enabled = required_evaluation[:enabled]
-
-            next false unless required_is_enabled
-
-            if required_variation
-              required_variation_evaluation = evaluate(options.merge(type: "variation", feature_key: required_key))
-
-              required_variation_value = nil
-
-              if has_key?(required_variation_evaluation, :variation_value)
-                required_variation_value = fetch_with_symbol_key(required_variation_evaluation, :variation_value)
-              elsif required_variation_evaluation[:variation]
-                required_variation_value = required_variation_evaluation[:variation][:value]
-              end
-
-              next required_variation_value == required_variation
-            end
-
-            true
-          end
+        required_features = feature[:requiredFeatures] || feature[:required]
+        if type == "flag" && required_features && !Array(required_features).empty?
+          required_features_are_enabled = required_features_are_matched(required_features, datafile, options)
 
           unless required_features_are_enabled
             evaluation = {
@@ -397,10 +413,11 @@ module Featurevisor
               feature_key: feature_key,
               reason: Featurevisor::EvaluationReason::REQUIRED,
               required: feature[:required],
+              required_features: feature[:requiredFeatures],
               enabled: required_features_are_enabled
             }
 
-            logger.debug("required features not enabled", evaluation)
+            diagnostics.debug("required features not enabled", evaluation)
 
             return evaluation
           end
@@ -412,7 +429,7 @@ module Featurevisor
           feature_key: feature_key,
           bucket_by: feature[:bucketBy],
           context: context,
-          logger: logger
+          diagnostics: diagnostics
         })
 
         # Run bucket key modules
@@ -438,13 +455,13 @@ module Featurevisor
         matched_allocation = nil
 
         if type != "flag"
-          matched_traffic = datafile_reader.get_matched_traffic(feature[:traffic], context)
+          matched_traffic = datafile.get_matched_traffic(feature[:traffic], context)
 
           if matched_traffic
-            matched_allocation = datafile_reader.get_matched_allocation(matched_traffic, bucket_value)
+            matched_allocation = datafile.get_matched_allocation(matched_traffic, bucket_value)
           end
         else
-          matched_traffic = datafile_reader.get_matched_traffic(feature[:traffic], context)
+          matched_traffic = datafile.get_matched_traffic(feature[:traffic], context)
         end
 
         if matched_traffic
@@ -461,7 +478,7 @@ module Featurevisor
               enabled: false
             }
 
-            logger.debug("matched rule with 0 percentage", evaluation)
+            diagnostics.debug("matched rule with 0 percentage", evaluation)
 
             return evaluation
           end
@@ -487,7 +504,7 @@ module Featurevisor
                   enabled: matched_traffic[:enabled].nil? ? true : matched_traffic[:enabled]
                 }
 
-                logger.debug("matched", evaluation)
+                diagnostics.debug("matched", evaluation)
 
                 return evaluation
               end
@@ -502,7 +519,7 @@ module Featurevisor
                 enabled: false
               }
 
-              logger.debug("not matched", evaluation)
+              diagnostics.debug("not matched", evaluation)
 
               return evaluation
             end
@@ -520,7 +537,7 @@ module Featurevisor
                 enabled: matched_traffic[:enabled]
               }
 
-              logger.debug("override from rule", evaluation)
+              diagnostics.debug("override from rule", evaluation)
 
               return evaluation
             end
@@ -538,7 +555,7 @@ module Featurevisor
                 enabled: true
               }
 
-              logger.debug("matched traffic", evaluation)
+              diagnostics.debug("matched traffic", evaluation)
 
               return evaluation
             end
@@ -562,7 +579,7 @@ module Featurevisor
                   variation: variation
                 }
 
-                logger.debug("override from rule", evaluation)
+                diagnostics.debug("override from rule", evaluation)
 
                 return evaluation
               end
@@ -584,7 +601,7 @@ module Featurevisor
                   variation: variation
                 }
 
-                logger.debug("allocated variation", evaluation)
+                diagnostics.debug("allocated variation", evaluation)
 
                 return evaluation
               end
@@ -600,17 +617,7 @@ module Featurevisor
              has_key?(matched_traffic[:variableOverrides], variable_key)
             overrides = fetch_with_symbol_key(matched_traffic[:variableOverrides], variable_key)
 
-            override_index = overrides.find_index do |o|
-              if o[:conditions]
-                conditions = o[:conditions].is_a?(String) && o[:conditions] != "*" ? JSON.parse(o[:conditions]) : o[:conditions]
-                datafile_reader.all_conditions_are_matched(conditions, context)
-              elsif o[:segments]
-                segments = datafile_reader.parse_segments_if_stringified(o[:segments])
-                datafile_reader.all_segments_are_matched(segments, context)
-              else
-                false
-              end
-            end
+            override_index = overrides.find_index { |o| variable_override_matches?(o, datafile, context, options) }
 
             unless override_index.nil?
               override = overrides[override_index]
@@ -626,10 +633,11 @@ module Featurevisor
                 variable_key: variable_key,
                 variable_schema: variable_schema,
                 variable_value: override[:value],
-                variable_override_index: override_index
+                variable_override_index: override_index,
+                variable_override_key: override[:key]
               }
 
-              logger.debug("variable override from rule", evaluation)
+              diagnostics.debug("variable override from rule", evaluation)
 
               return evaluation
             end
@@ -652,7 +660,7 @@ module Featurevisor
               variable_value: variable_value
             }
 
-            logger.debug("override from rule", evaluation)
+            diagnostics.debug("override from rule", evaluation)
 
             return evaluation
           end
@@ -674,17 +682,7 @@ module Featurevisor
             if variation && variation[:variableOverrides] && has_key?(variation[:variableOverrides], variable_key)
               overrides = fetch_with_symbol_key(variation[:variableOverrides], variable_key)
 
-              override_index = overrides.find_index do |o|
-                if o[:conditions]
-                  conditions = o[:conditions].is_a?(String) && o[:conditions] != "*" ? JSON.parse(o[:conditions]) : o[:conditions]
-                  datafile_reader.all_conditions_are_matched(conditions, context)
-                elsif o[:segments]
-                  segments = datafile_reader.parse_segments_if_stringified(o[:segments])
-                  datafile_reader.all_segments_are_matched(segments, context)
-                else
-                  false
-                end
-              end
+              override_index = overrides.find_index { |o| variable_override_matches?(o, datafile, context, options) }
 
               unless override_index.nil?
                 override = overrides[override_index]
@@ -699,10 +697,11 @@ module Featurevisor
                   variable_key: variable_key,
                   variable_schema: variable_schema,
                   variable_value: override[:value],
-                  variable_override_index: override_index
+                  variable_override_index: override_index,
+                  variable_override_key: override[:key]
                 }
 
-                logger.debug("variable override from variation", evaluation)
+                diagnostics.debug("variable override from variation", evaluation)
 
                 return evaluation
               end
@@ -725,7 +724,7 @@ module Featurevisor
                 variable_value: variable_value
               }
 
-              logger.debug("allocated variable", evaluation)
+              diagnostics.debug("allocated variable", evaluation)
 
               return evaluation
             end
@@ -742,7 +741,7 @@ module Featurevisor
             bucket_value: bucket_value
           }
 
-          logger.debug("no matched variation", evaluation)
+          diagnostics.debug("no matched variation", evaluation)
 
           return evaluation
         end
@@ -760,7 +759,7 @@ module Featurevisor
               variable_value: variable_schema[:defaultValue]
             }
 
-            logger.debug("using default value", evaluation)
+            diagnostics.debug("using default value", evaluation)
 
             return evaluation
           end
@@ -774,7 +773,7 @@ module Featurevisor
             bucket_value: bucket_value
           }
 
-          logger.debug("variable not found", evaluation)
+          diagnostics.debug("variable not found", evaluation)
 
           return evaluation
         end
@@ -788,7 +787,7 @@ module Featurevisor
           enabled: false
         }
 
-        logger.debug("nothing matched", evaluation)
+        diagnostics.debug("nothing matched", evaluation)
 
         evaluation
       rescue => e
@@ -800,7 +799,7 @@ module Featurevisor
           error: e
         }
 
-        logger.error("error", evaluation)
+        diagnostics.error("Error during evaluation", evaluation)
 
         evaluation
       end

data/lib/featurevisor/{datafile_reader.rb → evaluation_data_provider.rb}

@@ -3,23 +3,24 @@
 require "json"
 
 module Featurevisor
-  # DatafileReader class for reading and processing Featurevisor datafiles
-  class DatafileReader
-    attr_reader :schema_version, :revision, :featurevisor_version, :segments, :features, :logger, :regex_cache
+  # Private datafile and matching adapter used by the evaluator.
+  class InstanceEvaluationDataProvider
+    attr_reader :schema_version, :revision, :featurevisor_version, :segments, :features, :variables, :diagnostics, :regex_cache
 
-    # Initialize a new DatafileReader
-    # @param options [Hash] Options hash containing datafile and logger
+    # Initialize a new evaluation data provider.
+    # @param options [Hash] Options hash containing datafile and diagnostics
     # @option options [Hash] :datafile Datafile content
-    # @option options [Logger] :logger Logger instance
+    # @option options [DiagnosticReporter] :diagnostics Diagnostic reporter
     def initialize(options)
       datafile = options[:datafile]
-      @logger = options[:logger]
+      @diagnostics = options[:diagnostics]
 
       @schema_version = datafile[:schemaVersion]
       @revision = datafile[:revision]
       @featurevisor_version = datafile[:featurevisorVersion]
       @segments = (datafile[:segments] || {}).transform_keys(&:to_sym)
       @features = (datafile[:features] || {}).transform_keys(&:to_sym)
+      @variables = (datafile[:variables] || {}).transform_keys(&:to_sym)
 
       # Transform nested structures to use symbol keys
       @features.each do |_key, feature|
@@ -72,7 +73,8 @@ module Featurevisor
         revision: @revision,
         featurevisorVersion: @featurevisor_version,
         segments: @segments,
-        features: @features
+        features: @features,
+        variables: @variables
       }.compact
     end
 
@@ -88,6 +90,10 @@ module Featurevisor
       segment
     end
 
+    def get_segment_keys
+      @segments.keys
+    end
+
     # Get all feature keys
     # @return [Array<Symbol>] Array of feature keys
     def get_feature_keys
@@ -104,7 +110,9 @@ module Featurevisor
     # Get variable keys for a feature
     # @param feature_key [String] Feature key
     # @return [Array<String>] Array of variable keys
-    def get_variable_keys(feature_key)
+    def get_variable_keys(feature_key = nil)
+      return @variables.keys if feature_key.nil?
+
       feature = get_feature(feature_key)
 
       return [] unless feature
@@ -112,6 +120,10 @@ module Featurevisor
       (feature[:variablesSchema] || {}).keys
     end
 
+    def get_global_variable(variable_key)
+      @variables[variable_key.to_sym] || @variables[variable_key]
+    end
+
     # Check if a feature has variations
     # @param feature_key [String] Feature key
     # @return [Boolean] True if feature has variations
@@ -133,7 +145,15 @@ module Featurevisor
 
       return @regex_cache[cache_key] if @regex_cache[cache_key]
 
-      regex = Regexp.new(regex_string, flags)
+      ruby_flags = 0
+      ruby_flags |= Regexp::IGNORECASE if flags.include?("i")
+      # Ruby's MULTILINE option controls dot matching newlines, which is the
+      # JavaScript `s` behavior. Ruby anchors already operate per line.
+      ruby_flags |= Regexp::MULTILINE if flags.include?("s")
+      invalid_flags = flags.delete("gimsuy")
+      raise ArgumentError, "invalid regular expression flags: #{invalid_flags}" unless invalid_flags.empty?
+
+      regex = Regexp.new(regex_string, ruby_flags)
       @regex_cache[cache_key] = regex
       @regex_cache[cache_key]
     end
@@ -155,12 +175,11 @@ module Featurevisor
           result = Conditions.condition_is_matched(conditions, context, get_regex_proc)
           return result
         rescue => e
-          @logger.warn("Error in condition evaluation: #{e.message}", {
-            error: e.class.name,
-            details: {
-              condition: conditions,
-              context: context
-            }
+          @diagnostics.warn(e.message, {
+            code: "condition_match_error",
+            error: e,
+            condition: conditions,
+            context: context
           })
           return false
         end
@@ -183,10 +202,12 @@ module Featurevisor
       end
 
       if conditions.is_a?(Hash) && conditions[:not] && conditions[:not].is_a?(Array)
+        return false if conditions[:not].empty?
         return !all_conditions_are_matched({ and: conditions[:not] }, context)
       end
 
       if conditions.is_a?(Hash) && conditions["not"] && conditions["not"].is_a?(Array)
+        return false if conditions["not"].empty?
         return !all_conditions_are_matched({ "and" => conditions["not"] }, context)
       end
 
@@ -244,10 +265,12 @@ module Featurevisor
         end
 
         if group_segments[:not] && group_segments[:not].is_a?(Array)
+          return false if group_segments[:not].empty?
           return !all_segments_are_matched({ and: group_segments[:not] }, context)
         end
 
         if group_segments["not"] && group_segments["not"].is_a?(Array)
+          return false if group_segments["not"].empty?
           return !all_segments_are_matched({ "and" => group_segments["not"] }, context)
         end
 
@@ -333,7 +356,7 @@ module Featurevisor
       begin
         JSON.parse(conditions)
       rescue => e
-        @logger.error("Error parsing conditions", {
+        @diagnostics.error("Error parsing conditions", {
           error: e,
           details: {
             conditions: conditions
@@ -355,5 +378,5 @@ module Featurevisor
     end
   end
 
-  private_constant :DatafileReader
+  private_constant :InstanceEvaluationDataProvider
 end