launchdarkly-server-sdk 6.1.1 → 6.4.0

data/lib/ldclient-rb/impl/evaluator.rb

@@ -1,9 +1,17 @@
 require "ldclient-rb/evaluation_detail"
 require "ldclient-rb/impl/evaluator_bucketing"
+require "ldclient-rb/impl/evaluator_helpers"
 require "ldclient-rb/impl/evaluator_operators"
 
 module LaunchDarkly
   module Impl
+    # Used internally to record that we evaluated a prerequisite flag.
+    PrerequisiteEvalRecord = Struct.new(
+      :prereq_flag,     # the prerequisite flag that we evaluated
+      :prereq_of_flag,  # the flag that it was a prerequisite of
+      :detail           # the EvaluationDetail representing the evaluation result
+    )
+
     # Encapsulates the feature flag evaluation logic. The Evaluator has no knowledge of the rest of the SDK environment;
     # if it needs to retrieve flags or segments that are referenced by a flag, it does so through a simple function that
     # is provided in the constructor. It also produces feature requests as appropriate for any referenced prerequisite
@@ -16,16 +24,28 @@ module LaunchDarkly
       #   flag data - or nil if the flag is unknown or deleted
       # @param get_segment [Function] similar to `get_flag`, but is used to query a user segment.
       # @param logger [Logger] the client's logger
-      def initialize(get_flag, get_segment, logger)
+      def initialize(get_flag, get_segment, get_big_segments_membership, logger)
         @get_flag = get_flag
         @get_segment = get_segment
+        @get_big_segments_membership = get_big_segments_membership
         @logger = logger
       end
-
-      # Used internally to hold an evaluation result and the events that were generated from prerequisites. The
-      # `detail` property is an EvaluationDetail. The `events` property can be either an array of feature request
-      # events or nil.
-      EvalResult = Struct.new(:detail, :events)
+  
+      # Used internally to hold an evaluation result and additional state that may be accumulated during an
+      # evaluation. It's simpler and a bit more efficient to represent these as mutable properties rather than
+      # trying to use a pure functional approach, and since we're not exposing this object to any application code
+      # or retaining it anywhere, we don't have to be quite as strict about immutability.
+      #
+      # The big_segments_status and big_segments_membership properties are not used by the caller; they are used
+      # during an evaluation to cache the result of any Big Segments query that we've done for this user, because
+      # we don't want to do multiple queries for the same user if multiple Big Segments are referenced in the same
+      # evaluation.
+      EvalResult = Struct.new(
+        :detail,  # the EvaluationDetail representing the evaluation result
+        :prereq_evals,  # an array of PrerequisiteEvalRecord instances, or nil
+        :big_segments_status,
+        :big_segments_membership
+      )
 
       # Helper function used internally to construct an EvaluationDetail for an error result.
       def self.error_result(errorKind, value = nil)
@@ -38,43 +58,47 @@ module LaunchDarkly
       #
       # @param flag [Object] the flag
       # @param user [Object] the user properties
-      # @param event_factory [EventFactory] called to construct a feature request event when a prerequisite flag is
-      #   evaluated; the caller is responsible for constructing the feature event for the top-level evaluation
       # @return [EvalResult] the evaluation result 
-      def evaluate(flag, user, event_factory)
+      def evaluate(flag, user)
+        result = EvalResult.new
         if user.nil? || user[:key].nil?
-          return EvalResult.new(Evaluator.error_result(EvaluationReason::ERROR_USER_NOT_SPECIFIED), [])
+          result.detail = Evaluator.error_result(EvaluationReason::ERROR_USER_NOT_SPECIFIED)
+          return result
         end
-
-        # If the flag doesn't have any prerequisites (which most flags don't) then it cannot generate any feature
-        # request events for prerequisites and we can skip allocating an array.
-        if flag[:prerequisites] && !flag[:prerequisites].empty?
-          events = []
-        else
-          events = nil
+        
+        detail = eval_internal(flag, user, result)
+        if !result.big_segments_status.nil?
+          # If big_segments_status is non-nil at the end of the evaluation, it means a query was done at
+          # some point and we will want to include the status in the evaluation reason.
+          detail = EvaluationDetail.new(detail.value, detail.variation_index,
+            detail.reason.with_big_segments_status(result.big_segments_status))
         end
+        result.detail = detail
+        return result
+      end
 
-        detail = eval_internal(flag, user, events, event_factory)
-        return EvalResult.new(detail, events.nil? || events.empty? ? nil : events)
+      def self.make_big_segment_ref(segment)  # method is visible for testing
+        # The format of Big Segment references is independent of what store implementation is being
+        # used; the store implementation receives only this string and does not know the details of
+        # the data model. The Relay Proxy will use the same format when writing to the store.
+        "#{segment[:key]}.g#{segment[:generation]}"
       end
 
       private
       
-      def eval_internal(flag, user, events, event_factory)
+      def eval_internal(flag, user, state)
         if !flag[:on]
-          return get_off_value(flag, EvaluationReason::off)
+          return EvaluatorHelpers.off_result(flag)
         end
 
-        prereq_failure_reason = check_prerequisites(flag, user, events, event_factory)
-        if !prereq_failure_reason.nil?
-          return get_off_value(flag, prereq_failure_reason)
-        end
+        prereq_failure_result = check_prerequisites(flag, user, state)
+        return prereq_failure_result if !prereq_failure_result.nil?
 
         # Check user target matches
         (flag[:targets] || []).each do |target|
           (target[:values] || []).each do |value|
             if value == user[:key]
-              return get_variation(flag, target[:variation], EvaluationReason::target_match)
+              return EvaluatorHelpers.target_match_result(target, flag)
             end
           end
         end
@@ -83,22 +107,24 @@ module LaunchDarkly
         rules = flag[:rules] || []
         rules.each_index do |i|
           rule = rules[i]
-          if rule_match_user(rule, user)
+          if rule_match_user(rule, user, state)
             reason = rule[:_reason]  # try to use cached reason for this rule
             reason = EvaluationReason::rule_match(i, rule[:id]) if reason.nil?
-            return get_value_for_variation_or_rollout(flag, rule, user, reason)
+            return get_value_for_variation_or_rollout(flag, rule, user, reason,
+              EvaluatorHelpers.rule_precomputed_results(rule))
           end
         end
 
         # Check the fallthrough rule
         if !flag[:fallthrough].nil?
-          return get_value_for_variation_or_rollout(flag, flag[:fallthrough], user, EvaluationReason::fallthrough)
+          return get_value_for_variation_or_rollout(flag, flag[:fallthrough], user, EvaluationReason::fallthrough,
+            EvaluatorHelpers.fallthrough_precomputed_results(flag))
         end
 
         return EvaluationDetail.new(nil, nil, EvaluationReason::fallthrough)
       end
 
-      def check_prerequisites(flag, user, events, event_factory)
+      def check_prerequisites(flag, user, state)
         (flag[:prerequisites] || []).each do |prerequisite|
           prereq_ok = true
           prereq_key = prerequisite[:key]
@@ -109,44 +135,44 @@ module LaunchDarkly
             prereq_ok = false
           else
             begin
-              prereq_res = eval_internal(prereq_flag, user, events, event_factory)
+              prereq_res = eval_internal(prereq_flag, user, state)
               # 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 = event_factory.new_eval_event(prereq_flag, user, prereq_res, nil, flag)
-              events.push(event)
+              prereq_eval = PrerequisiteEvalRecord.new(prereq_flag, flag, prereq_res)
+              state.prereq_evals = [] if state.prereq_evals.nil?
+              state.prereq_evals.push(prereq_eval)
             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
-            reason = prerequisite[:_reason]  # try to use cached reason
-            return reason.nil? ? EvaluationReason::prerequisite_failed(prereq_key) : reason
+            return EvaluatorHelpers.prerequisite_failed_result(prerequisite, flag)
           end
         end
         nil
       end
 
-      def rule_match_user(rule, user)
+      def rule_match_user(rule, user, state)
         return false if !rule[:clauses]
 
         (rule[:clauses] || []).each do |clause|
-          return false if !clause_match_user(clause, user)
+          return false if !clause_match_user(clause, user, state)
         end
 
         return true
       end
 
-      def clause_match_user(clause, user)
+      def clause_match_user(clause, user, state)
         # 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
           result = (clause[:values] || []).any? { |v|
             segment = @get_segment.call(v)
-            !segment.nil? && segment_match_user(segment, user)
+            !segment.nil? && segment_match_user(segment, user, state)
           }
           clause[:negate] ? !result : result
         else
@@ -168,11 +194,42 @@ module LaunchDarkly
         clause[:negate] ? !result : result
       end
 
-      def segment_match_user(segment, user)
+      def segment_match_user(segment, user, state)
         return false unless user[:key]
+        segment[:unbounded] ? big_segment_match_user(segment, user, state) : simple_segment_match_user(segment, user, true)
+      end
 
-        return true if segment[:included].include?(user[:key])
-        return false if segment[:excluded].include?(user[:key])
+      def big_segment_match_user(segment, user, state)
+        if !segment[:generation]
+          # Big segment queries can only be done if the generation is known. If it's unset,
+          # that probably means the data store was populated by an older SDK that doesn't know
+          # about the generation property and therefore dropped it from the JSON data. We'll treat
+          # that as a "not configured" condition.
+          state.big_segments_status = BigSegmentsStatus::NOT_CONFIGURED
+          return false
+        end
+        if !state.big_segments_status
+          result = @get_big_segments_membership.nil? ? nil : @get_big_segments_membership.call(user[:key])
+          if result
+            state.big_segments_membership = result.membership
+            state.big_segments_status = result.status
+          else
+            state.big_segments_membership = nil
+            state.big_segments_status = BigSegmentsStatus::NOT_CONFIGURED
+          end
+        end
+        segment_ref = Evaluator.make_big_segment_ref(segment)
+        membership = state.big_segments_membership
+        included = membership.nil? ? nil : membership[segment_ref]
+        return included if !included.nil?
+        simple_segment_match_user(segment, user, false)
+      end
+
+      def simple_segment_match_user(segment, user, use_includes_and_excludes)
+        if use_includes_and_excludes
+          return true if segment[:included].include?(user[:key])
+          return false if segment[:excluded].include?(user[:key])
+        end
 
         (segment[:rules] || []).each do |r|
           return true if segment_rule_match_user(r, user, segment[:key], segment[:salt])
@@ -190,35 +247,32 @@ module LaunchDarkly
         return true if !rule[:weight]
         
         # All of the clauses are met. See if the user buckets in
-        bucket = EvaluatorBucketing.bucket_user(user, segment_key, rule[:bucketBy].nil? ? "key" : rule[:bucketBy], salt)
+        bucket = EvaluatorBucketing.bucket_user(user, segment_key, rule[:bucketBy].nil? ? "key" : rule[:bucketBy], salt, nil)
         weight = rule[:weight].to_f / 100000.0
         return bucket < weight
       end
 
       private
-
-      def get_variation(flag, index, reason)
-        if index < 0 || index >= flag[:variations].length
-          @logger.error("[LDClient] Data inconsistency in feature flag \"#{flag[:key]}\": invalid variation index")
-          return Evaluator.error_result(EvaluationReason::ERROR_MALFORMED_FLAG)
-        end
-        EvaluationDetail.new(flag[:variations][index], index, reason)
-      end
-
-      def get_off_value(flag, reason)
-        if flag[:offVariation].nil?  # off variation unspecified - return default value
-          return EvaluationDetail.new(nil, nil, reason)
-        end
-        get_variation(flag, flag[:offVariation], reason)
-      end
-
-      def get_value_for_variation_or_rollout(flag, vr, user, reason)
-        index = EvaluatorBucketing.variation_index_for_user(flag, vr, user)
+      
+      def get_value_for_variation_or_rollout(flag, vr, user, reason, precomputed_results)
+        index, in_experiment = EvaluatorBucketing.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 Evaluator.error_result(EvaluationReason::ERROR_MALFORMED_FLAG)
         end
-        return get_variation(flag, index, reason)
+        if precomputed_results
+          return precomputed_results.for_variation(index, in_experiment)
+        else
+          #if in experiment is true, set reason to a different reason instance/singleton with in_experiment set
+          if in_experiment
+            if reason.kind == :FALLTHROUGH
+              reason = EvaluationReason::fallthrough(in_experiment)
+            elsif reason.kind == :RULE_MATCH
+              reason = EvaluationReason::rule_match(reason.rule_index, reason.rule_id, in_experiment)
+            end
+          end
+          return EvaluatorHelpers.evaluation_detail_for_variation(flag, index, reason)
+        end
       end
     end
   end

data/lib/ldclient-rb/impl/evaluator_bucketing.rb

@@ -10,20 +10,26 @@ module LaunchDarkly
       # @param user [Object] the user properties
       # @return [Number] the variation index, or nil if there is an error
       def self.variation_index_for_user(flag, rule, user)
+
         variation = rule[:variation]
-        return variation if !variation.nil? # fixed variation
+        return variation, false if !variation.nil? # fixed variation
         rollout = rule[:rollout]
-        return nil if rollout.nil?
+        return nil, false if rollout.nil?
         variations = rollout[:variations]
         if !variations.nil? && variations.length > 0 # percentage rollout
-          rollout = rule[:rollout]
           bucket_by = rollout[:bucketBy].nil? ? "key" : rollout[:bucketBy]
-          bucket = bucket_user(user, flag[:key], bucket_by, flag[:salt])
+
+          seed = rollout[:seed]
+          bucket = bucket_user(user, flag[:key], bucket_by, flag[:salt], seed) # may not be present
           sum = 0;
           variations.each do |variate|
+            if rollout[:kind] == "experiment" && !variate[:untracked]
+              in_experiment = true
+            end
+
             sum += variate[:weight].to_f / 100000.0
             if bucket < sum
-              return variate[:variation]
+              return variate[:variation], !!in_experiment
             end
           end
           # The user's bucket value was greater than or equal to the end of the last bucket. This could happen due
@@ -31,9 +37,12 @@ module LaunchDarkly
           # data could contain buckets that don't actually add up to 100000. Rather than returning an error in
           # this case (or changing the scaling, which would potentially change the results for *all* users), we
           # will simply put the user in the last bucket.
-          variations[-1][:variation]
+          last_variation = variations[-1]
+          in_experiment = rollout[:kind] == "experiment" && !last_variation[:untracked]
+
+          [last_variation[:variation], in_experiment]
         else # the rule isn't well-formed
-          nil
+          [nil, false]
         end
       end
 
@@ -44,7 +53,7 @@ module LaunchDarkly
       # @param bucket_by [String|Symbol] the name of the user attribute to be used for bucketing
       # @param salt [String] the feature flag's or segment's salt value
       # @return [Number] the bucket value, from 0 inclusive to 1 exclusive
-      def self.bucket_user(user, key, bucket_by, salt)
+      def self.bucket_user(user, key, bucket_by, salt, seed)
         return nil unless user[:key]
 
         id_hash = bucketable_string_value(EvaluatorOperators.user_value(user, bucket_by))
@@ -56,7 +65,11 @@ module LaunchDarkly
           id_hash += "." + user[:secondary].to_s
         end
 
-        hash_key = "%s.%s.%s" % [key, salt, id_hash]
+        if seed
+          hash_key = "%d.%s" % [seed, id_hash]
+        else
+          hash_key = "%s.%s.%s" % [key, salt, id_hash]
+        end
 
         hash_val = (Digest::SHA1.hexdigest(hash_key))[0..14]
         hash_val.to_i(16) / Float(0xFFFFFFFFFFFFFFF)

data/lib/ldclient-rb/impl/evaluator_helpers.rb

@@ -0,0 +1,53 @@
+require "ldclient-rb/evaluation_detail"
+
+# This file contains any pieces of low-level evaluation logic that don't need to be inside the Evaluator
+# class, because they don't depend on any SDK state outside of their input parameters.
+
+module LaunchDarkly
+  module Impl
+    module EvaluatorHelpers
+      def self.off_result(flag, logger = nil)
+        pre = flag[:_preprocessed]
+        pre ? pre.off_result : evaluation_detail_for_off_variation(flag, EvaluationReason::off, logger)
+      end
+
+      def self.target_match_result(target, flag, logger = nil)
+        pre = target[:_preprocessed]
+        pre ? pre.match_result : evaluation_detail_for_variation(
+          flag, target[:variation], EvaluationReason::target_match, logger)
+      end
+
+      def self.prerequisite_failed_result(prereq, flag, logger = nil)
+        pre = prereq[:_preprocessed]
+        pre ? pre.failed_result : evaluation_detail_for_off_variation(
+          flag, EvaluationReason::prerequisite_failed(prereq[:key]), logger
+        )
+      end
+
+      def self.fallthrough_precomputed_results(flag)
+        pre = flag[:_preprocessed]
+        pre ? pre.fallthrough_factory : nil
+      end
+
+      def self.rule_precomputed_results(rule)
+        pre = rule[:_preprocessed]
+        pre ? pre.all_match_results : nil
+      end
+
+      def self.evaluation_detail_for_off_variation(flag, reason, logger = nil)
+        index = flag[:offVariation]
+        index.nil? ? EvaluationDetail.new(nil, nil, reason) : evaluation_detail_for_variation(flag, index, reason, logger)
+      end
+
+      def self.evaluation_detail_for_variation(flag, index, reason, logger = nil)
+        vars = flag[:variations] || []
+        if index < 0 || index >= vars.length
+          logger.error("[LDClient] Data inconsistency in feature flag \"#{flag[:key]}\": invalid variation index") unless logger.nil?
+          EvaluationDetail.new(nil, nil, EvaluationReason::error(EvaluationReason::ERROR_MALFORMED_FLAG))
+        else
+          EvaluationDetail.new(vars[index], index, reason)
+        end
+      end
+    end
+  end
+end

data/lib/ldclient-rb/impl/evaluator_operators.rb

@@ -89,7 +89,7 @@ module LaunchDarkly
 
       private
 
-      BUILTINS = Set[:key, :ip, :country, :email, :firstName, :lastName, :avatar, :name, :anonymous]
+      BUILTINS = Set[:key, :secondary, :ip, :country, :email, :firstName, :lastName, :avatar, :name, :anonymous]
       NUMERIC_VERSION_COMPONENTS_REGEX = Regexp.new("^[0-9.]*")
 
       private_constant :BUILTINS

data/lib/ldclient-rb/impl/event_summarizer.rb

@@ -0,0 +1,63 @@
+require "ldclient-rb/impl/event_types"
+
+module LaunchDarkly
+  module Impl
+    EventSummary = Struct.new(:start_date, :end_date, :counters)
+
+    EventSummaryFlagInfo = Struct.new(:default, :versions)
+
+    EventSummaryFlagVariationCounter = Struct.new(:value, :count)
+
+    # Manages the state of summarizable information for the EventProcessor, including the
+    # event counters and user deduplication. Note that the methods of this class are
+    # deliberately not thread-safe; the EventProcessor is responsible for enforcing
+    # synchronization across both the summarizer and the event queue.
+    class EventSummarizer
+      class Counter
+      end
+
+      def initialize
+        clear
+      end
+
+      # Adds this event to our counters, if it is a type of event we need to count.
+      def summarize_event(event)
+        return if !event.is_a?(LaunchDarkly::Impl::EvalEvent)
+
+        counters_for_flag = @counters[event.key]
+        if counters_for_flag.nil?
+          counters_for_flag = EventSummaryFlagInfo.new(event.default, Hash.new)
+          @counters[event.key] = counters_for_flag
+        end
+        counters_for_flag_version = counters_for_flag.versions[event.version]
+        if counters_for_flag_version.nil?
+          counters_for_flag_version = Hash.new
+          counters_for_flag.versions[event.version] = counters_for_flag_version
+        end
+        variation_counter = counters_for_flag_version[event.variation]
+        if variation_counter.nil?
+          counters_for_flag_version[event.variation] = EventSummaryFlagVariationCounter.new(event.value, 1)
+        else
+          variation_counter.count = variation_counter.count + 1
+        end
+        time = event.timestamp
+        if !time.nil?
+          @start_date = time if @start_date == 0 || time < @start_date
+          @end_date = time if time > @end_date
+        end
+      end
+
+      # Returns a snapshot of the current summarized event data, and resets this state.
+      def snapshot
+        ret = EventSummary.new(@start_date, @end_date, @counters)
+        ret
+      end
+
+      def clear
+        @start_date = 0
+        @end_date = 0
+        @counters = {}
+      end
+    end
+  end
+end

data/lib/ldclient-rb/impl/event_types.rb

@@ -0,0 +1,90 @@
+module LaunchDarkly
+  module Impl
+    class Event
+      def initialize(timestamp, user)
+        @timestamp = timestamp
+        @user = user
+      end
+
+      attr_reader :timestamp
+      attr_reader :kind
+      attr_reader :user
+    end
+
+    class EvalEvent < Event
+      def initialize(timestamp, user, key, version = nil, variation = nil, value = nil, reason = nil, default = nil,
+        track_events = false, debug_until = nil, prereq_of = nil)
+        super(timestamp, user)
+        @key = key
+        @version = version
+        @variation = variation
+        @value = value
+        @reason = reason
+        @default = default
+        # avoid setting rarely-used attributes if they have no value - this saves a little space per instance
+        @track_events = track_events if track_events
+        @debug_until = debug_until if debug_until
+        @prereq_of = prereq_of if prereq_of
+      end
+
+      attr_reader :key
+      attr_reader :version
+      attr_reader :variation
+      attr_reader :value
+      attr_reader :reason
+      attr_reader :default
+      attr_reader :track_events
+      attr_reader :debug_until
+      attr_reader :prereq_of
+    end
+
+    class IdentifyEvent < Event
+      def initialize(timestamp, user)
+        super(timestamp, user)
+      end
+    end
+
+    class CustomEvent < Event
+      def initialize(timestamp, user, key, data = nil, metric_value = nil)
+        super(timestamp, user)
+        @key = key
+        @data = data if !data.nil?
+        @metric_value = metric_value if !metric_value.nil?
+      end
+
+      attr_reader :key
+      attr_reader :data
+      attr_reader :metric_value
+    end
+
+    class AliasEvent < Event
+      def initialize(timestamp, key, context_kind, previous_key, previous_context_kind)
+        super(timestamp, nil)
+        @key = key
+        @context_kind = context_kind
+        @previous_key = previous_key
+        @previous_context_kind = previous_context_kind
+      end
+
+      attr_reader :key
+      attr_reader :context_kind
+      attr_reader :previous_key
+      attr_reader :previous_context_kind
+    end
+
+    class IndexEvent < Event
+      def initialize(timestamp, user)
+        super(timestamp, user)
+      end
+    end
+
+    class DebugEvent < Event
+      def initialize(eval_event)
+        super(eval_event.timestamp, eval_event.user)
+        @eval_event = eval_event
+      end
+
+      attr_reader :eval_event
+    end
+  end
+end