ldclient-rb 5.1.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6a6cfa6490a0f46a455e7d65cbb9cdab695692e3
-  data.tar.gz: 6a749bb22220adfde7323876fa7174e50da15e70
+  metadata.gz: aed3c4885f97dd1ad3f8dad1e9ea37ae53931fd6
+  data.tar.gz: a33110bc3288b9529aebc076e2fa5c6c405ea41d
 SHA512:
-  metadata.gz: f05eb914183f31142ef03bbad0319dda44cd25cbbd2723619aca74ba70f6e2a2043db40da35480da65c5ac64bd6bc6a08afb3b8379787c58e51a7a8ed6fed9c8
-  data.tar.gz: 53d7974ab225003f95e9fe636dff25b30c706873a13b4a1e24a33914f309ab66a8bce7438fd2382b43afc4e1ca8cc159e6b640b7cf0733ebd62c361aa42d11e2
+  metadata.gz: 0e8fe67e4835f5a961a5bd65b3ef383f85910253c361202b75f18dff585dbb8e210b1bc388297cd771111409bf4f0620f8aeb9197d8db17da3a644976c87ff1d
+  data.tar.gz: 85ad89319527662c86f18c6d472476b887f0382715577bf6fcf105c32dce3f24b51ea888a0022daff017cb9ffe4f1a3601edaa24f4d85d073de35284e478ac5b

data/CHANGELOG.md

@@ -2,18 +2,14 @@
 
 All notable changes to the LaunchDarkly Ruby SDK will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org).
 
-## [5.1.0] - 2018-08-27
+## [5.2.0] - 2018-08-29
 ### Added:
-- The new `LDClient` method `all_flags_state()` should be used instead of `all_flags()` if you are passing flag data to the front end for use with the JavaScript SDK. It preserves some flag metadata that the front end requires in order to send analytics events correctly. Versions 2.5.0 and above of the JavaScript SDK are able to use this metadata, but the output of `all_flags_state()` will still work with older versions.
-- The `all_flags_state()` method also allows you to select only client-side-enabled flags to pass to the front end, by using the option `client_side_only: true`.
-
-### Changed:
-- Unexpected exceptions are now logged at `ERROR` level, and exception stacktraces at `DEBUG` level. Previously, both were being logged at `WARN` level.
-
-### Deprecated:
-- `LDClient.all_flags()`
+- The new `LDClient` method `variation_detail` allows you to evaluate a feature flag (using the same parameters as you would for `variation`) and receive more information about how the value was calculated. This information is returned in an `EvaluationDetail` object, which contains both the result value and a "reason" object which will tell you, for instance, if the user was individually targeted for the flag or was matched by one of the flag's rules, or if the flag returned the default value due to an error.
 
+### Fixed:
+- Evaluating a prerequisite feature flag did not produce an analytics event if the prerequisite flag was off.
 
+ 
 ## [5.1.0] - 2018-08-27
 ### Added:
 - The new `LDClient` method `all_flags_state()` should be used instead of `all_flags()` if you are passing flag data to the front end for use with the JavaScript SDK. It preserves some flag metadata that the front end requires in order to send analytics events correctly. Versions 2.5.0 and above of the JavaScript SDK are able to use this metadata, but the output of `all_flags_state()` will still work with older versions.

data/lib/ldclient-rb/evaluation.rb

@@ -2,6 +2,37 @@ 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
+
+    # @return [Object] The result of the flag evaluation. This will be either one of the flag's
+    #   variations or the default value that was passed to the `variation` method.
+    attr_reader :value
+
+    # @return [int|nil] The index of the returned value within the flag's list of variations, e.g.
+    #   0 for the first variation - or `nil` if the default value was returned.
+    attr_reader :variation_index
+
+    # @return [Hash] An object describing the main factor that influenced the flag evaluation value.
+    attr_reader :reason
+
+    # @return [boolean] True if the flag evaluated to the default value rather than to one of its
+    #   variations.
+    def default_value?
+      variation_index.nil?
+    end
+
+    def ==(other)
+      @value == other.value && @variation_index == other.variation_index && @reason == other.reason
+    end
+  end
+
   module Evaluation
     BUILTINS = [:key, :ip, :country, :email, :firstName, :lastName, :avatar, :name, :anonymous]
 
@@ -107,113 +138,103 @@ module LaunchDarkly
         end
     }
 
-    class EvaluationError < StandardError
+    # Used internally to hold an evaluation result and the events that were generated from prerequisites.
+    EvalResult = Struct.new(:detail, :events)
+
+    def error_result(errorKind, value = nil)
+      EvaluationDetail.new(value, nil, { kind: 'ERROR', errorKind: errorKind })
     end
 
-    # Evaluates a feature flag, returning a hash containing the evaluation result and any events
-    # generated during prerequisite evaluation. Raises EvaluationError if the flag is not well-formed
-    # Will return nil, but not raise an exception, indicating that the rules (including fallthrough) did not match
-    # In that case, the caller should return the default value.
+    # 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 flag.nil?
-        raise EvaluationError, "Flag does not exist"
-      end
-
       if user.nil? || user[:key].nil?
-        raise EvaluationError, "Invalid user"
+        return EvalResult.new(error_result('USER_NOT_SPECIFIED'), [])
       end
 
       events = []
+      detail = eval_internal(flag, 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
 
-      if flag[:on]
-        res = eval_internal(flag, user, store, events, logger)
-        if !res.nil?
-          res[:events] = events
-          return res
+      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
 
-      offVariation = flag[:offVariation]
-      if !offVariation.nil? && offVariation < flag[:variations].length
-        value = flag[:variations][offVariation]
-        return { variation: offVariation, value: value, events: events }
+      # Check the fallthrough rule
+      if !flag[:fallthrough].nil?
+        return get_value_for_variation_or_rollout(flag, flag[:fallthrough], user,
+          { kind: 'FALLTHROUGH' }, logger)
       end
 
-      { variation: nil, value: nil, events: events }
+      return EvaluationDetail.new(nil, nil, { kind: 'FALLTHROUGH' })
     end
 
-    def eval_internal(flag, user, store, events, logger)
-      failed_prereq = false
-      # Evaluate prerequisites, if any
+    def check_prerequisites(flag, user, store, events, logger)
       (flag[:prerequisites] || []).each do |prerequisite|
-        prereq_flag = store.get(FEATURES, prerequisite[:key])
+        prereq_ok = true
+        prereq_key = prerequisite[:key]
+        prereq_flag = store.get(FEATURES, prereq_key)
 
-        if prereq_flag.nil? || !prereq_flag[:on]
-          failed_prereq = true
+        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_flag[:key],
-              variation: prereq_res.nil? ? nil : prereq_res[:variation],
-              value: prereq_res.nil? ? nil : prereq_res[:value],
+              key: prereq_key,
+              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)
-            if prereq_res.nil? || prereq_res[:variation] != prerequisite[:variation]
-              failed_prereq = true
-            end
           rescue => exn
-            logger.error { "[LDClient] Error evaluating prerequisite: #{exn.inspect}" }
-            failed_prereq = true
+            Util.log_exception(logger, "Error evaluating prerequisite flag \"#{prereq_key}\" for flag \"{flag[:key]}\"", exn)
+            prereq_ok = false
           end
         end
-      end
-
-      if failed_prereq
-        return nil
-      end
-      # The prerequisites were satisfied.
-      # Now walk through the evaluation steps and get the correct
-      # variation index
-      eval_rules(flag, user, store)
-    end
-
-    def eval_rules(flag, user, store)
-      # Check user target matches
-      (flag[:targets] || []).each do |target|
-        (target[:values] || []).each do |value|
-          if value == user[:key]
-            return { variation: target[:variation], value: get_variation(flag, target[:variation]) }
-          end
+        if !prereq_ok
+          return { kind: 'PREREQUISITE_FAILED', prerequisiteKey: prereq_key }
         end
       end
-    
-      # Check custom rules
-      (flag[:rules] || []).each do |rule|
-        return variation_for_user(rule, user, flag) if rule_match_user(rule, user, store)
-      end
-
-      # Check the fallthrough rule
-      if !flag[:fallthrough].nil?
-        return variation_for_user(flag[:fallthrough], user, flag)
-      end
-
-      # Not even the fallthrough matched-- return the off variation or default
       nil
     end
 
-    def get_variation(flag, index)
-      if index >= flag[:variations].length
-        raise EvaluationError, "Invalid variation index"
-      end
-      flag[:variations][index]
-    end
-
     def rule_match_user(rule, user, store)
       return false if !rule[:clauses]
 
@@ -242,9 +263,8 @@ module LaunchDarkly
       return false if val.nil?
 
       op = OPERATORS[clause[:op].to_sym]
-
       if op.nil?
-        raise EvaluationError, "Unsupported operator #{clause[:op]} in evaluation"
+        return false
       end
 
       if val.is_a? Enumerable
@@ -257,9 +277,9 @@ module LaunchDarkly
       maybe_negate(clause, match_any(op, val, clause[:values]))
     end
 
-    def variation_for_user(rule, user, flag)
+    def variation_index_for_user(flag, rule, user)
       if !rule[:variation].nil? # fixed variation
-        return { variation: rule[:variation], value: get_variation(flag, rule[:variation]) }
+        return rule[:variation]
       elsif !rule[:rollout].nil? # percentage rollout
         rollout = rule[:rollout]
         bucket_by = rollout[:bucketBy].nil? ? "key" : rollout[:bucketBy]
@@ -268,12 +288,12 @@ module LaunchDarkly
         rollout[:variations].each do |variate|
           sum += variate[:weight].to_f / 100000.0
           if bucket < sum
-            return { variation: variate[:variation], value: get_variation(flag, variate[:variation]) }
+            return variate[:variation]
           end
         end
         nil
       else # the rule isn't well-formed
-        raise EvaluationError, "Rule does not define a variation or rollout"
+        nil
       end
     end
 
@@ -350,5 +370,31 @@ module LaunchDarkly
       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

data/lib/ldclient-rb/events.rb

@@ -363,6 +363,7 @@ module LaunchDarkly
         else
           out[:userKey] = event[:user].nil? ? nil : event[:user][:key]
         end
+        out[:reason] = event[:reason] if !event[:reason].nil?
         out
       when "identify"
         {

data/lib/ldclient-rb/flags_state.rb

@@ -15,12 +15,13 @@ module LaunchDarkly
     end
 
     # Used internally to build the state map.
-    def add_flag(flag, value, variation)
+    def add_flag(flag, value, variation, reason = nil)
       key = flag[:key]
       @flag_values[key] = value
       meta = { version: flag[:version], trackEvents: flag[:trackEvents] }
       meta[:variation] = variation if !variation.nil?
       meta[:debugEventsUntilDate] = flag[:debugEventsUntilDate] if flag[:debugEventsUntilDate]
+      meta[:reason] = reason if !reason.nil?
       @flag_metadata[key] = meta
     end
 

data/lib/ldclient-rb/ldclient.rb

@@ -115,57 +115,54 @@ module LaunchDarkly
     # @param key [String] the unique feature key for the feature flag, as shown
     #   on the LaunchDarkly dashboard
     # @param user [Hash] a hash containing parameters for the end user requesting the flag
-    # @param default=false the default value of the flag
+    # @param default the default value of the flag
     #
     # @return the variation to show the user, or the
     #   default value if there's an an error
     def variation(key, user, default)
-      return default if @config.offline?
-
-      if !initialized?
-        if @store.initialized?
-          @config.logger.warn { "[LDClient] Client has not finished initializing; using last known values from feature store" }
-        else
-          @config.logger.error { "[LDClient] Client has not finished initializing; feature store unavailable, returning default value" }
-          @event_processor.add_event(kind: "feature", key: key, value: default, default: default, user: user)
-          return default
-        end
-      end
-
-      sanitize_user(user) if !user.nil?
-      feature = @store.get(FEATURES, key)
-
-      if feature.nil?
-        @config.logger.info { "[LDClient] Unknown feature flag #{key}. Returning default value" }
-        @event_processor.add_event(kind: "feature", key: key, value: default, default: default, user: user)
-        return default
-      end
-
-      unless user
-        @config.logger.error { "[LDClient] Must specify user" }
-        @event_processor.add_event(make_feature_event(feature, user, nil, default, default))
-        return default
-      end
+      evaluate_internal(key, user, default, false).value
+    end
 
-      begin
-        res = evaluate(feature, user, @store, @config.logger)
-        if !res[:events].nil?
-          res[:events].each do |event|
-            @event_processor.add_event(event)
-          end
-        end
-        value = res[:value]
-        if value.nil?
-          @config.logger.debug { "[LDClient] Result value is null in toggle" }
-          value = default
-        end
-        @event_processor.add_event(make_feature_event(feature, user, res[:variation], value, default))
-        return value
-      rescue => exn
-        Util.log_exception(@config.logger, "Error evaluating feature flag", exn)
-        @event_processor.add_event(make_feature_event(feature, user, nil, default, default))
-        return default
-      end
+    #
+    # Determines the variation of a feature flag for a user, like `variation`, but also
+    # provides additional information about how this value was calculated.
+    #
+    # The return value of `variation_detail` is an `EvaluationDetail` object, which has
+    # three properties:
+    #
+    # `value`: the value that was calculated for this user (same as the return value
+    # of `variation`)
+    #
+    # `variation_index`: the positional index of this value in the flag, e.g. 0 for the
+    # first variation - or `nil` if the default value was returned
+    #
+    # `reason`: a hash describing the main reason why this value was selected. Its `:kind`
+    # property will be one of the following:
+    #
+    # * `'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; the `:ruleIndex` and
+    # `:ruleId` properties indicate the positional index and unique identifier of the rule
+    # * `'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; the
+    # `:prerequisiteKey` property indicates the key of the prerequisite that failed
+    # * `'ERROR'`: the flag could not be evaluated, e.g. because it does not exist or due
+    # to an unexpected error, and therefore returned the default value; the `:errorKind`
+    # property describes the nature of the error, such as `'FLAG_NOT_FOUND'`
+    #
+    # The `reason` will also be included in analytics events, if you are capturing
+    # detailed event data for this flag.
+    #
+    # @param key [String] the unique feature key for the feature flag, as shown
+    #   on the LaunchDarkly dashboard
+    # @param user [Hash] a hash containing parameters for the end user requesting the flag
+    # @param default the default value of the flag
+    #
+    # @return an `EvaluationDetail` object describing the result
+    #
+    def variation_detail(key, user, default)
+      evaluate_internal(key, user, default, true)
     end
 
     #
@@ -213,6 +210,8 @@ module LaunchDarkly
     # @param options={} [Hash] Optional parameters to control how the state is generated
     # @option options [Boolean] :client_side_only (false) True if only flags marked for use with the
     #   client-side SDK should be included in the state. By default, all flags are included.
+    # @option options [Boolean] :with_reasons (false) True if evaluation reasons should be included
+    #   in the state (see `variation_detail`). By default, they are not included.
     # @return [FeatureFlagsState] a FeatureFlagsState object which can be serialized to JSON
     #
     def all_flags_state(user, options={})
@@ -234,16 +233,17 @@ module LaunchDarkly
 
       state = FeatureFlagsState.new(true)
       client_only = options[:client_side_only] || false
+      with_reasons = options[:with_reasons] || false
       features.each do |k, f|
         if client_only && !f[:clientSide]
           next
         end
         begin
           result = evaluate(f, user, @store, @config.logger)
-          state.add_flag(f, result[:value], result[:variation])
+          state.add_flag(f, result.detail.value, result.detail.variation_index, with_reasons ? result.detail.reason : nil)
         rescue => exn
           Util.log_exception(@config.logger, "Error evaluating flag \"#{k}\" in all_flags_state", exn)
-          state.add_flag(f, nil, nil)
+          state.add_flag(f, nil, nil, with_reasons ? { kind: 'ERROR', errorKind: 'EXCEPTION' } : nil)
         end
       end
 
@@ -261,27 +261,83 @@ module LaunchDarkly
       @store.stop
     end
 
+    private
+
+    # @return [EvaluationDetail]
+    def evaluate_internal(key, user, default, include_reasons_in_events)
+      if @config.offline?
+        return error_result('CLIENT_NOT_READY', default)
+      end
+
+      if !initialized?
+        if @store.initialized?
+          @config.logger.warn { "[LDClient] Client has not finished initializing; using last known values from feature store" }
+        else
+          @config.logger.error { "[LDClient] Client has not finished initializing; feature store unavailable, returning default value" }
+          @event_processor.add_event(kind: "feature", key: key, value: default, default: default, user: user)
+          return error_result('CLIENT_NOT_READY', default)
+        end
+      end
+
+      sanitize_user(user) if !user.nil?
+      feature = @store.get(FEATURES, key)
+
+      if feature.nil?
+        @config.logger.info { "[LDClient] Unknown feature flag \"#{key}\". Returning default value" }
+        detail = error_result('FLAG_NOT_FOUND', default)
+        @event_processor.add_event(kind: "feature", key: key, value: default, default: default, user: user,
+          reason: include_reasons_in_events ? detail.reason : nil)
+        return detail
+      end
+
+      unless user
+        @config.logger.error { "[LDClient] Must specify user" }
+        detail = error_result('USER_NOT_SPECIFIED', default)
+        @event_processor.add_event(make_feature_event(feature, user, detail, default, include_reasons_in_events))
+        return detail
+      end
+
+      begin
+        res = evaluate(feature, user, @store, @config.logger)
+        if !res.events.nil?
+          res.events.each do |event|
+            @event_processor.add_event(event)
+          end
+        end
+        detail = res.detail
+        if detail.default_value?
+          detail = EvaluationDetail.new(default, nil, detail.reason)
+        end
+        @event_processor.add_event(make_feature_event(feature, user, detail, default, include_reasons_in_events))
+        return detail
+      rescue => exn
+        Util.log_exception(@config.logger, "Error evaluating feature flag \"#{key}\"", exn)
+        detail = error_result('EXCEPTION', default)
+        @event_processor.add_event(make_feature_event(feature, user, detail, default, include_reasons_in_events))
+        return detail
+      end
+    end
+
     def sanitize_user(user)
       if user[:key]
         user[:key] = user[:key].to_s
       end
     end
 
-    def make_feature_event(flag, user, variation, value, default)
+    def make_feature_event(flag, user, detail, default, with_reasons)
       {
         kind: "feature",
         key: flag[:key],
         user: user,
-        variation: variation,
-        value: value,
+        variation: detail.variation_index,
+        value: detail.value,
         default: default,
         version: flag[:version],
         trackEvents: flag[:trackEvents],
-        debugEventsUntilDate: flag[:debugEventsUntilDate]
+        debugEventsUntilDate: flag[:debugEventsUntilDate],
+        reason: with_reasons ? detail.reason : nil
       }
     end
-
-    private :evaluate, :sanitize_user, :make_feature_event
   end
 
   #