launchdarkly-server-sdk 5.5.7

data/lib/ldclient-rb/evaluation.rb

@@ -0,0 +1,455 @@
+require "date"
+require "semantic"
+
+module LaunchDarkly
+  # An object returned by {LDClient#variation_detail}, combining the result of a flag evaluation with
+  # an explanation of how it was calculated.
+  class EvaluationDetail
+    def initialize(value, variation_index, reason)
+      @value = value
+      @variation_index = variation_index
+      @reason = reason
+    end
+
+    #
+    # The result of the flag evaluation. This will be either one of the flag's variations, or the
+    # default value that was passed to {LDClient#variation_detail}. It is the same as the return
+    # value of {LDClient#variation}.
+    #
+    # @return [Object]
+    #
+    attr_reader :value
+
+    #
+    # The index of the returned value within the flag's list of variations. The first variation is
+    # 0, the second is 1, etc. This is `nil` if the default value was returned.
+    #
+    # @return [int|nil]
+    #
+    attr_reader :variation_index
+
+    #
+    # An object describing the main factor that influenced the flag evaluation value.
+    #
+    # This object is currently represented as a Hash, which may have the following keys:
+    #
+    # `:kind`: The general category of reason. Possible values:
+    #
+    # * `'OFF'`: the flag was off and therefore returned its configured off value
+    # * `'FALLTHROUGH'`: the flag was on but the user did not match any targets or rules
+    # * `'TARGET_MATCH'`: the user key was specifically targeted for this flag
+    # * `'RULE_MATCH'`: the user matched one of the flag's rules
+    # * `'PREREQUISITE_FAILED`': the flag was considered off because it had at least one
+    # prerequisite flag that either was off or did not return the desired variation
+    # * `'ERROR'`: the flag could not be evaluated, so the default value was returned
+    #
+    # `:ruleIndex`: If the kind was `RULE_MATCH`, this is the positional index of the
+    # matched rule (0 for the first rule).
+    #
+    # `:ruleId`: If the kind was `RULE_MATCH`, this is the rule's unique identifier.
+    #
+    # `:prerequisiteKey`: If the kind was `PREREQUISITE_FAILED`, this is the flag key of
+    # the prerequisite flag that failed.
+    #
+    # `:errorKind`: If the kind was `ERROR`, this indicates the type of error:
+    #
+    # * `'CLIENT_NOT_READY'`: the caller tried to evaluate a flag before the client had
+    # successfully initialized
+    # * `'FLAG_NOT_FOUND'`: the caller provided a flag key that did not match any known flag
+    # * `'MALFORMED_FLAG'`: there was an internal inconsistency in the flag data, e.g. a
+    # rule specified a nonexistent variation
+    # * `'USER_NOT_SPECIFIED'`: the user object or user key was not provied
+    # * `'EXCEPTION'`: an unexpected exception stopped flag evaluation
+    #
+    # @return [Hash]
+    #
+    attr_reader :reason
+
+    #
+    # Tests whether the flag evaluation returned a default value. This is the same as checking
+    # whether {#variation_index} is nil.
+    #
+    # @return [Boolean]
+    #
+    def default_value?
+      variation_index.nil?
+    end
+
+    def ==(other)
+      @value == other.value && @variation_index == other.variation_index && @reason == other.reason
+    end
+  end
+
+  # @private
+  module Evaluation
+    BUILTINS = [:key, :ip, :country, :email, :firstName, :lastName, :avatar, :name, :anonymous]
+
+    NUMERIC_VERSION_COMPONENTS_REGEX = Regexp.new("^[0-9.]*")
+
+    DATE_OPERAND = lambda do |v|
+      if v.is_a? String
+        begin
+          DateTime.rfc3339(v).strftime("%Q").to_i
+        rescue => e
+          nil
+        end
+      elsif v.is_a? Numeric
+        v
+      else
+        nil
+      end
+    end
+
+    SEMVER_OPERAND = lambda do |v|
+      semver = nil
+      if v.is_a? String
+        for _ in 0..2 do
+          begin
+            semver = Semantic::Version.new(v)
+            break  # Some versions of jruby cannot properly handle a return here and return from the method that calls this lambda
+          rescue ArgumentError
+            v = addZeroVersionComponent(v)
+          end
+        end
+      end
+      semver
+    end
+
+    def self.addZeroVersionComponent(v)
+      NUMERIC_VERSION_COMPONENTS_REGEX.match(v) { |m|
+        m[0] + ".0" + v[m[0].length..-1]
+      }
+    end
+
+    def self.comparator(converter)
+      lambda do |a, b|
+        av = converter.call(a)
+        bv = converter.call(b)
+        if !av.nil? && !bv.nil?
+          yield av <=> bv
+        else
+          return false
+        end
+      end
+    end
+
+    OPERATORS = {
+      in:
+        lambda do |a, b|
+          a == b
+        end,
+      endsWith:
+        lambda do |a, b|
+          (a.is_a? String) && (a.end_with? b)
+        end,
+      startsWith:
+        lambda do |a, b|
+          (a.is_a? String) && (a.start_with? b)
+        end,
+      matches:
+        lambda do |a, b|
+          (b.is_a? String) && !(Regexp.new b).match(a).nil?
+        end,
+      contains:
+        lambda do |a, b|
+          (a.is_a? String) && (a.include? b)
+        end,
+      lessThan:
+        lambda do |a, b|
+          (a.is_a? Numeric) && (a < b)
+        end,
+      lessThanOrEqual:
+        lambda do |a, b|
+          (a.is_a? Numeric) && (a <= b)
+        end,
+      greaterThan:
+        lambda do |a, b|
+          (a.is_a? Numeric) && (a > b)
+        end,
+      greaterThanOrEqual:
+        lambda do |a, b|
+          (a.is_a? Numeric) && (a >= b)
+        end,
+      before:
+        comparator(DATE_OPERAND) { |n| n < 0 },
+      after:
+        comparator(DATE_OPERAND) { |n| n > 0 },
+      semVerEqual:
+        comparator(SEMVER_OPERAND) { |n| n == 0 },
+      semVerLessThan:
+        comparator(SEMVER_OPERAND) { |n| n < 0 },
+      semVerGreaterThan:
+        comparator(SEMVER_OPERAND) { |n| n > 0 },
+      segmentMatch:
+        lambda do |a, b|
+          false   # we should never reach this - instead we special-case this operator in clause_match_user
+        end
+    }
+
+    # Used internally to hold an evaluation result and the events that were generated from prerequisites.
+    EvalResult = Struct.new(:detail, :events)
+
+    USER_ATTRS_TO_STRINGIFY_FOR_EVALUATION = [ :key, :secondary ]
+    # Currently we are not stringifying the rest of the built-in attributes prior to evaluation, only for events.
+    # This is because it could affect evaluation results for existing users (ch35206).
+    
+    def error_result(errorKind, value = nil)
+      EvaluationDetail.new(value, nil, { kind: 'ERROR', errorKind: errorKind })
+    end
+
+    # Evaluates a feature flag and returns an EvalResult. The result.value will be nil if the flag returns
+    # the default value. Error conditions produce a result with an error reason, not an exception.
+    def evaluate(flag, user, store, logger)
+      if user.nil? || user[:key].nil?
+        return EvalResult.new(error_result('USER_NOT_SPECIFIED'), [])
+      end
+
+      sanitized_user = Util.stringify_attrs(user, USER_ATTRS_TO_STRINGIFY_FOR_EVALUATION)
+
+      events = []
+      detail = eval_internal(flag, sanitized_user, store, events, logger)
+      return EvalResult.new(detail, events)
+    end
+
+    def eval_internal(flag, user, store, events, logger)
+      if !flag[:on]
+        return get_off_value(flag, { kind: 'OFF' }, logger)
+      end
+
+      prereq_failure_reason = check_prerequisites(flag, user, store, events, logger)
+      if !prereq_failure_reason.nil?
+        return get_off_value(flag, prereq_failure_reason, logger)
+      end
+
+      # Check user target matches
+      (flag[:targets] || []).each do |target|
+        (target[:values] || []).each do |value|
+          if value == user[:key]
+            return get_variation(flag, target[:variation], { kind: 'TARGET_MATCH' }, logger)
+          end
+        end
+      end
+    
+      # Check custom rules
+      rules = flag[:rules] || []
+      rules.each_index do |i|
+        rule = rules[i]
+        if rule_match_user(rule, user, store)
+          return get_value_for_variation_or_rollout(flag, rule, user,
+            { kind: 'RULE_MATCH', ruleIndex: i, ruleId: rule[:id] }, logger)
+        end
+      end
+
+      # Check the fallthrough rule
+      if !flag[:fallthrough].nil?
+        return get_value_for_variation_or_rollout(flag, flag[:fallthrough], user,
+          { kind: 'FALLTHROUGH' }, logger)
+      end
+
+      return EvaluationDetail.new(nil, nil, { kind: 'FALLTHROUGH' })
+    end
+
+    def check_prerequisites(flag, user, store, events, logger)
+      (flag[:prerequisites] || []).each do |prerequisite|
+        prereq_ok = true
+        prereq_key = prerequisite[:key]
+        prereq_flag = store.get(FEATURES, prereq_key)
+
+        if prereq_flag.nil?
+          logger.error { "[LDClient] Could not retrieve prerequisite flag \"#{prereq_key}\" when evaluating \"#{flag[:key]}\"" }
+          prereq_ok = false
+        else
+          begin
+            prereq_res = eval_internal(prereq_flag, user, store, events, logger)
+            # Note that if the prerequisite flag is off, we don't consider it a match no matter what its
+            # off variation was. But we still need to evaluate it in order to generate an event.
+            if !prereq_flag[:on] || prereq_res.variation_index != prerequisite[:variation]
+              prereq_ok = false
+            end
+            event = {
+              kind: "feature",
+              key: prereq_key,
+              user: user,
+              variation: prereq_res.variation_index,
+              value: prereq_res.value,
+              version: prereq_flag[:version],
+              prereqOf: flag[:key],
+              trackEvents: prereq_flag[:trackEvents],
+              debugEventsUntilDate: prereq_flag[:debugEventsUntilDate]
+            }
+            events.push(event)
+          rescue => exn
+            Util.log_exception(logger, "Error evaluating prerequisite flag \"#{prereq_key}\" for flag \"#{flag[:key]}\"", exn)
+            prereq_ok = false
+          end
+        end
+        if !prereq_ok
+          return { kind: 'PREREQUISITE_FAILED', prerequisiteKey: prereq_key }
+        end
+      end
+      nil
+    end
+
+    def rule_match_user(rule, user, store)
+      return false if !rule[:clauses]
+
+      (rule[:clauses] || []).each do |clause|
+        return false if !clause_match_user(clause, user, store)
+      end
+
+      return true
+    end
+
+    def clause_match_user(clause, user, store)
+      # In the case of a segment match operator, we check if the user is in any of the segments,
+      # and possibly negate
+      if clause[:op].to_sym == :segmentMatch
+        (clause[:values] || []).each do |v|
+          segment = store.get(SEGMENTS, v)
+          return maybe_negate(clause, true) if !segment.nil? && segment_match_user(segment, user)
+        end
+        return maybe_negate(clause, false)
+      end
+      clause_match_user_no_segments(clause, user)
+    end
+
+    def clause_match_user_no_segments(clause, user)
+      val = user_value(user, clause[:attribute])
+      return false if val.nil?
+
+      op = OPERATORS[clause[:op].to_sym]
+      if op.nil?
+        return false
+      end
+
+      if val.is_a? Enumerable
+        val.each do |v|
+          return maybe_negate(clause, true) if match_any(op, v, clause[:values])
+        end
+        return maybe_negate(clause, false)
+      end
+
+      maybe_negate(clause, match_any(op, val, clause[:values]))
+    end
+
+    def variation_index_for_user(flag, rule, user)
+      if !rule[:variation].nil? # fixed variation
+        return rule[:variation]
+      elsif !rule[:rollout].nil? # percentage rollout
+        rollout = rule[:rollout]
+        bucket_by = rollout[:bucketBy].nil? ? "key" : rollout[:bucketBy]
+        bucket = bucket_user(user, flag[:key], bucket_by, flag[:salt])
+        sum = 0;
+        rollout[:variations].each do |variate|
+          sum += variate[:weight].to_f / 100000.0
+          if bucket < sum
+            return variate[:variation]
+          end
+        end
+        nil
+      else # the rule isn't well-formed
+        nil
+      end
+    end
+
+    def segment_match_user(segment, user)
+      return false unless user[:key]
+
+      return true if segment[:included].include?(user[:key])
+      return false if segment[:excluded].include?(user[:key])
+
+      (segment[:rules] || []).each do |r|
+        return true if segment_rule_match_user(r, user, segment[:key], segment[:salt])
+      end
+
+      return false
+    end
+
+    def segment_rule_match_user(rule, user, segment_key, salt)
+      (rule[:clauses] || []).each do |c|
+        return false unless clause_match_user_no_segments(c, user)
+      end
+
+      # If the weight is absent, this rule matches
+      return true if !rule[:weight]
+      
+      # All of the clauses are met. See if the user buckets in
+      bucket = bucket_user(user, segment_key, rule[:bucketBy].nil? ? "key" : rule[:bucketBy], salt)
+      weight = rule[:weight].to_f / 100000.0
+      return bucket < weight
+    end
+
+    def bucket_user(user, key, bucket_by, salt)
+      return nil unless user[:key]
+
+      id_hash = bucketable_string_value(user_value(user, bucket_by))
+      if id_hash.nil?
+        return 0.0
+      end
+
+      if user[:secondary]
+        id_hash += "." + user[:secondary]
+      end
+
+      hash_key = "%s.%s.%s" % [key, salt, id_hash]
+
+      hash_val = (Digest::SHA1.hexdigest(hash_key))[0..14]
+      hash_val.to_i(16) / Float(0xFFFFFFFFFFFFFFF)
+    end
+
+    def bucketable_string_value(value)
+      return value if value.is_a? String
+      return value.to_s if value.is_a? Integer
+      nil
+    end
+
+    def user_value(user, attribute)
+      attribute = attribute.to_sym
+
+      if BUILTINS.include? attribute
+        user[attribute]
+      elsif !user[:custom].nil?
+        user[:custom][attribute]
+      else
+        nil
+      end
+    end
+
+    def maybe_negate(clause, b)
+      clause[:negate] ? !b : b
+    end
+
+    def match_any(op, value, values)
+      values.each do |v|
+        return true if op.call(value, v)
+      end
+      return false
+    end
+
+    private
+
+    def get_variation(flag, index, reason, logger)
+      if index < 0 || index >= flag[:variations].length
+        logger.error("[LDClient] Data inconsistency in feature flag \"#{flag[:key]}\": invalid variation index")
+        return error_result('MALFORMED_FLAG')
+      end
+      EvaluationDetail.new(flag[:variations][index], index, reason)
+    end
+
+    def get_off_value(flag, reason, logger)
+      if flag[:offVariation].nil?  # off variation unspecified - return default value
+        return EvaluationDetail.new(nil, nil, reason)
+      end
+      get_variation(flag, flag[:offVariation], reason, logger)
+    end
+
+    def get_value_for_variation_or_rollout(flag, vr, user, reason, logger)
+      index = variation_index_for_user(flag, vr, user)
+      if index.nil?
+        logger.error("[LDClient] Data inconsistency in feature flag \"#{flag[:key]}\": variation/rollout object with no variation or rollout")
+        return error_result('MALFORMED_FLAG')
+      end
+      return get_variation(flag, index, reason, logger)
+    end
+  end
+end