featurevisor 2.0.0 → 3.0.0

data/lib/featurevisor/child_instance.rb

@@ -1,351 +1,126 @@
 # frozen_string_literal: true
 
 module Featurevisor
-  # Child instance class for managing child contexts and sticky features
+  # Child instance with isolated context and sticky state.
   class ChildInstance
-    # Initialize a new child instance
-    # @param options [Hash] Child instance options
-    # @option options [Instance] :parent Parent instance
-    # @option options [Hash] :context Child context
-    # @option options [Hash] :sticky Child sticky features
     def initialize(options)
       @parent = options[:parent]
       @context = options[:context] || {}
-      @sticky = options[:sticky] || {}
+      @sticky_features = options[:sticky_features] || {}
+      @sticky_variables = options[:sticky_variables] || {}
       @emitter = Featurevisor::Emitter.new
       @parent_unsubscribers = []
     end
 
-    # Subscribe to an event
-    # @param event_name [String] Event name
-    # @param callback [Proc] Callback function
-    # @return [Proc] Unsubscribe function
     def on(event_name, callback = nil, &block)
       callback = block if block_given?
-      
-      if event_name == "context_set" || event_name == "sticky_set"
-        @emitter.on(event_name, callback)
-      else
-        parent_unsubscribe = @parent.on(event_name, callback)
-        active = true
-        unsubscribe = nil
-        unsubscribe = proc do
-          next unless active
+      if %w[context_set sticky_features_set sticky_variables_set].include?(event_name)
+        return @emitter.on(event_name, callback)
+      end
+
+      parent_unsubscribe = @parent.on(event_name, callback)
+      active = true
+      unsubscribe = nil
+      unsubscribe = proc do
+        next unless active
 
-          active = false
-          parent_unsubscribe.call
-          @parent_unsubscribers.delete(unsubscribe)
-        end
-        @parent_unsubscribers << unsubscribe
-        unsubscribe
+        active = false
+        parent_unsubscribe.call
+        @parent_unsubscribers.delete(unsubscribe)
       end
+      @parent_unsubscribers << unsubscribe
+      unsubscribe
     end
 
-    # Close the child instance
     def close
       @parent_unsubscribers.dup.each(&:call)
       @parent_unsubscribers.clear
       @emitter.clear_all
     end
 
-    # Set context
-    # @param context [Hash] Context to set
-    # @param replace [Boolean] Whether to replace existing context
     def set_context(context, replace = false)
-      if replace
-        @context = context
-      else
-        @context = { **@context, **context }
-      end
-
-      @emitter.trigger("context_set", {
-        context: @context,
-        replaced: replace
-      })
+      @context = replace ? context : { **@context, **context }
+      @emitter.trigger("context_set", context: @context, replaced: replace)
     end
 
-    # Get context
-    # @param context [Hash, nil] Additional context to merge
-    # @return [Hash] Merged context
     def get_context(context = nil)
-      @parent.get_context({
-        **@context,
-        **(context || {})
-      })
+      @parent.get_context({ **@context, **(context || {}) })
     end
 
-    # Set sticky features
-    # @param sticky [Hash] Sticky features
-    # @param replace [Boolean] Whether to replace existing sticky features
-    def set_sticky(sticky, replace = false)
-      previous_sticky_features = @sticky || {}
-
-      if replace
-        @sticky = sticky
-      else
-        @sticky = {
-          **@sticky,
-          **sticky
-        }
-      end
+    def set_sticky_features(sticky, replace = false)
+      previous = @sticky_features
+      @sticky_features = replace ? sticky : { **@sticky_features, **sticky }
+      params = Featurevisor::Events.get_params_for_sticky_features_set_event(previous, @sticky_features, replace)
+      @emitter.trigger("sticky_features_set", params)
+    end
 
-      params = Featurevisor::Events.get_params_for_sticky_set_event(previous_sticky_features, @sticky, replace)
-      @emitter.trigger("sticky_set", params)
+    def set_sticky_variables(sticky, replace = false)
+      previous = @sticky_variables
+      @sticky_variables = replace ? sticky : { **@sticky_variables, **sticky }
+      @emitter.trigger(
+        "sticky_variables_set",
+        Featurevisor::Events.get_params_for_sticky_variables_set_event(previous, @sticky_variables, replace)
+      )
     end
 
-    # Check if a feature is enabled
-    # @param feature_key [String] Feature key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Boolean] True if feature is enabled
     def is_enabled(feature_key, context = {}, options = {})
-      @parent.is_enabled(
-        feature_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+      @parent.is_enabled(feature_key, child_context(context), child_options(options))
     end
 
-    # Evaluate a feature flag and return its full evaluation details.
     def evaluate_flag(feature_key, context = {}, options = {})
-      @parent.evaluate_flag(
-        feature_key,
-        { **@context, **context },
-        { **options, __featurevisor_child_sticky: @sticky }
-      )
+      @parent.evaluate_flag(feature_key, child_context(context), child_options(options))
     end
 
-    # Get variation value
-    # @param feature_key [String] Feature key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [String, nil] Variation value or nil
     def get_variation(feature_key, context = {}, options = {})
-      @parent.get_variation(
-        feature_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+      @parent.get_variation(feature_key, child_context(context), child_options(options))
     end
 
-    # Evaluate a variation and return its full evaluation details.
     def evaluate_variation(feature_key, context = {}, options = {})
-      @parent.evaluate_variation(
-        feature_key,
-        { **@context, **context },
-        { **options, __featurevisor_child_sticky: @sticky }
-      )
-    end
-
-    # Get variable value
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Object, nil] Variable value or nil
-    def get_variable(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+      @parent.evaluate_variation(feature_key, child_context(context), child_options(options))
     end
 
-    # Evaluate a variable and return its full evaluation details.
-    def evaluate_variable(feature_key, variable_key, context = {}, options = {})
-      @parent.evaluate_variable(
-        feature_key,
-        variable_key,
-        { **@context, **context },
-        { **options, __featurevisor_child_sticky: @sticky }
-      )
+    def get_variable(feature_or_variable_key, variable_key_or_context = nil, context_or_options = {}, options = {})
+      delegate_variable(:get_variable, feature_or_variable_key, variable_key_or_context, context_or_options, options)
     end
 
-    # Get variable as boolean
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Boolean, nil] Boolean value or nil
-    def get_variable_boolean(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_boolean(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def evaluate_variable(feature_or_variable_key, variable_key_or_context = nil, context_or_options = {}, options = {})
+      delegate_variable(:evaluate_variable, feature_or_variable_key, variable_key_or_context, context_or_options, options)
     end
 
-    # Get variable as string
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [String, nil] String value or nil
-    def get_variable_string(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_string(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    %i[boolean string integer double array object json].each do |type|
+      define_method("get_variable_#{type}") do |feature_or_variable_key, variable_key_or_context = nil, context_or_options = {}, options = {}|
+        delegate_variable("get_variable_#{type}".to_sym, feature_or_variable_key, variable_key_or_context, context_or_options, options)
+      end
     end
 
-    # Get variable as integer
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Integer, nil] Integer value or nil
-    def get_variable_integer(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_integer(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def get_feature_evaluations(context = {}, feature_keys = [], options = {})
+      @parent.get_feature_evaluations(child_context(context), feature_keys, child_options(options))
     end
 
-    # Get variable as double
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Float, nil] Float value or nil
-    def get_variable_double(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_double(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def get_variable_evaluations(context = {}, variable_keys = [], options = {})
+      @parent.get_variable_evaluations(child_context(context), variable_keys, child_options(options))
     end
 
-    # Get variable as array
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Array, nil] Array value or nil
-    def get_variable_array(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_array(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
-    end
+    private
 
-    # Get variable as object
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Hash, nil] Object value or nil
-    def get_variable_object(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_object(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def child_context(context)
+      { **@context, **context }
     end
 
-    # Get variable as JSON
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Object, nil] JSON value or nil
-    def get_variable_json(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_json(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def child_options(options)
+      {
+        **options,
+        __featurevisor_child_sticky_features: @sticky_features,
+        __featurevisor_child_sticky_variables: @sticky_variables
+      }
     end
 
-    # Get all evaluations
-    # @param context [Hash] Context
-    # @param feature_keys [Array<String>] Feature keys to evaluate
-    # @param options [Hash] Override options
-    # @return [Hash] All evaluations
-    def get_all_evaluations(context = {}, feature_keys = [], options = {})
-      @parent.get_all_evaluations(
-        {
-          **@context,
-          **context
-        },
-        feature_keys,
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def delegate_variable(method, first, second, third, fourth)
+      if second.nil? || second.is_a?(Hash)
+        @parent.public_send(method, first, child_context(second || {}), child_options(third))
+      else
+        @parent.public_send(method, first, second, child_context(third), child_options(fourth))
+      end
     end
-
-    private
   end
 end

data/lib/featurevisor/emitter.rb

@@ -2,7 +2,7 @@
 
 module Featurevisor
   # Event names for the emitter
-  EVENT_NAMES = %w[datafile_set context_set sticky_set error].freeze
+  EVENT_NAMES = %w[datafile_set context_set sticky_features_set sticky_variables_set error].freeze
 
   # Event emitter class for handling event subscriptions and triggers
   class Emitter

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,18 +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.key?(:variation_value) &&
            !evaluation.key?(:variation)
-          evaluation[:variation_value] = options[:default_variation_value]
+          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.key?(:variable_value)
-          evaluation[:variable_value] = options[:default_variable_value]
+          evaluation[:variable_value] = result_options[:default_variable_value]
         end
 
         # Run after modules
@@ -358,39 +403,9 @@ module Featurevisor
         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 = {
@@ -398,6 +413,7 @@ module Featurevisor
               feature_key: feature_key,
               reason: Featurevisor::EvaluationReason::REQUIRED,
               required: feature[:required],
+              required_features: feature[:requiredFeatures],
               enabled: required_features_are_enabled
             }
 
@@ -601,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.all_conditions_are_matched(conditions, context)
-              elsif o[:segments]
-                segments = datafile.parse_segments_if_stringified(o[:segments])
-                datafile.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]
@@ -627,7 +633,8 @@ 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]
               }
 
               diagnostics.debug("variable override from rule", evaluation)
@@ -675,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.all_conditions_are_matched(conditions, context)
-                elsif o[:segments]
-                  segments = datafile.parse_segments_if_stringified(o[:segments])
-                  datafile.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]
@@ -700,7 +697,8 @@ 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]
                 }
 
                 diagnostics.debug("variable override from variation", evaluation)

data/lib/featurevisor/evaluation_data_provider.rb

@@ -5,7 +5,7 @@ require "json"
 module Featurevisor
   # Private datafile and matching adapter used by the evaluator.
   class InstanceEvaluationDataProvider
-    attr_reader :schema_version, :revision, :featurevisor_version, :segments, :features, :diagnostics, :regex_cache
+    attr_reader :schema_version, :revision, :featurevisor_version, :segments, :features, :variables, :diagnostics, :regex_cache
 
     # Initialize a new evaluation data provider.
     # @param options [Hash] Options hash containing datafile and diagnostics
@@ -20,6 +20,7 @@ module Featurevisor
       @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