feat: Add support for client-side prerequisite events (#299)

Author: keelerm84

contract-tests/service.rb

@@ -44,6 +44,7 @@
       'anonymous-redaction',
       'evaluation-hooks',
       'omit-anonymous-contexts',
+      'client-prereq-events',
     ],
   }.to_json
 end

lib/ldclient-rb/flags_state.rb

@@ -38,6 +38,7 @@ def add_flag(flag_state, with_reasons, details_only_if_tracked)
         meta[:version] = flag_state[:version]
       end
 
+      meta[:prerequisites] = flag_state[:prerequisites] unless flag_state[:prerequisites].nil? || flag_state[:prerequisites].empty?
       meta[:variation] = flag_state[:variation] unless flag_state[:variation].nil?
       meta[:trackEvents] = true if flag_state[:trackEvents]
       meta[:trackReason] = true if flag_state[:trackReason]

lib/ldclient-rb/impl/evaluator.rb

@@ -32,8 +32,16 @@ class EvaluatorState
       def initialize(original_flag)
         @prereq_stack = EvaluatorStack.new(original_flag.key)
         @segment_stack = EvaluatorStack.new(nil)
+        @prerequisites = []
+        @depth = 0
       end
 
+      def record_evaluated_prereq_key(key)
+        @prerequisites.push(key) if @depth.zero?
+      end
+
+      attr_accessor :depth
+      attr_reader :prerequisites
       attr_reader :prereq_stack
       attr_reader :segment_stack
     end
@@ -135,7 +143,8 @@ def self.error_result(errorKind, value = nil)
       #
       # @param flag [LaunchDarkly::Impl::Model::FeatureFlag] the flag
       # @param context [LaunchDarkly::LDContext] the evaluation context
-      # @return [EvalResult] the evaluation result
+      # @return [Array<EvalResult, EvaluatorState>] the evaluation result and a state object that may be used for
+      # inspecting the evaluation process
       def evaluate(flag, context)
         state = EvaluatorState.new(flag)
 
@@ -145,11 +154,11 @@ def evaluate(flag, context)
         rescue EvaluationException => exn
           LaunchDarkly::Util.log_exception(@logger, "Unexpected error when evaluating flag #{flag.key}", exn)
           result.detail = EvaluationDetail.new(nil, nil, EvaluationReason::error(exn.error_kind))
-          return result
+          return result, state
         rescue => exn
           LaunchDarkly::Util.log_exception(@logger, "Unexpected error when evaluating flag #{flag.key}", exn)
           result.detail = EvaluationDetail.new(nil, nil, EvaluationReason::error(EvaluationReason::ERROR_EXCEPTION))
-          return result
+          return result, state
         end
 
         unless result.big_segments_status.nil?
@@ -159,7 +168,7 @@ def evaluate(flag, context)
             detail.reason.with_big_segments_status(result.big_segments_status))
         end
         result.detail = detail
-        result
+        [result, state]
       end
 
       # @param segment [LaunchDarkly::Impl::Model::Segment]
@@ -223,13 +232,16 @@ def self.make_big_segment_ref(segment)  # method is visible for testing
               )
             end
 
+            state.record_evaluated_prereq_key(prereq_key)
             prereq_flag = @get_flag.call(prereq_key)
 
             if prereq_flag.nil?
               @logger.error { "[LDClient] Could not retrieve prerequisite flag \"#{prereq_key}\" when evaluating \"#{flag.key}\"" }
               prereq_ok = false
             else
+              state.depth += 1
               prereq_res = eval_internal(prereq_flag, context, eval_result, state)
+              state.depth -= 1
               # 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

lib/ldclient-rb/ldclient.rb

@@ -546,7 +546,8 @@ def all_flags_state(context, options={})
           next
         end
         begin
-          detail = @evaluator.evaluate(f, context).detail
+          (eval_result, eval_state) = @evaluator.evaluate(f, context)
+          detail = eval_result.detail
         rescue => exn
           detail = EvaluationDetail.new(nil, nil, EvaluationReason::error(EvaluationReason::ERROR_EXCEPTION))
           Util.log_exception(@config.logger, "Error evaluating flag \"#{k}\" in all_flags_state", exn)
@@ -558,6 +559,7 @@ def all_flags_state(context, options={})
           value: detail.value,
           variation: detail.variation_index,
           reason: detail.reason,
+          prerequisites: eval_state.prerequisites,
           version: f[:version],
           trackEvents: f[:trackEvents] || requires_experiment_data,
           trackReason: requires_experiment_data,
@@ -705,7 +707,7 @@ def evaluate_internal(key, context, default, with_reasons)
       end
 
       begin
-        res = @evaluator.evaluate(feature, context)
+        (res, _) = @evaluator.evaluate(feature, context)
         unless res.prereq_evals.nil?
           res.prereq_evals.each do |prereq_eval|
             record_prereq_flag_eval(prereq_eval.prereq_flag, prereq_eval.prereq_of_flag, context, prereq_eval.detail, with_reasons)

spec/impl/evaluator_big_segments_spec.rb

@@ -19,7 +19,7 @@ module Impl
             .with_segment(segment)
             .build
           flag = Flags.boolean_flag_with_clauses(Clauses.match_segment(segment))
-          result = e.evaluate(flag, user_context)
+          (result, _) = e.evaluate(flag, user_context)
           expect(result.detail.value).to be false
           expect(result.detail.reason.big_segments_status).to be(BigSegmentsStatus::NOT_CONFIGURED)
         end
@@ -35,7 +35,7 @@ module Impl
             .with_segment(segment)
             .build
           flag = Flags.boolean_flag_with_clauses(Clauses.match_segment(segment))
-          result = e.evaluate(flag, user_context)
+          (result, _) = e.evaluate(flag, user_context)
           expect(result.detail.value).to be false
           expect(result.detail.reason.big_segments_status).to be(BigSegmentsStatus::NOT_CONFIGURED)
         end
@@ -52,7 +52,7 @@ module Impl
             .with_big_segment_for_context(user_context, segment, true)
             .build
           flag = Flags.boolean_flag_with_clauses(Clauses.match_segment(segment))
-          result = e.evaluate(flag, user_context)
+          (result, _) = e.evaluate(flag, user_context)
           expect(result.detail.value).to be true
           expect(result.detail.reason.big_segments_status).to be(BigSegmentsStatus::HEALTHY)
         end
@@ -72,7 +72,7 @@ module Impl
             .with_big_segment_for_context(user_context, segment, nil)
             .build
           flag = Flags.boolean_flag_with_clauses(Clauses.match_segment(segment))
-          result = e.evaluate(flag, user_context)
+          (result, _) = e.evaluate(flag, user_context)
           expect(result.detail.value).to be true
           expect(result.detail.reason.big_segments_status).to be(BigSegmentsStatus::HEALTHY)
         end
@@ -92,7 +92,7 @@ module Impl
             .with_big_segment_for_context(user_context, segment, false)
             .build
           flag = Flags.boolean_flag_with_clauses(Clauses.match_segment(segment))
-          result = e.evaluate(flag, user_context)
+          (result, _) = e.evaluate(flag, user_context)
           expect(result.detail.value).to be false
           expect(result.detail.reason.big_segments_status).to be(BigSegmentsStatus::HEALTHY)
         end
@@ -110,7 +110,7 @@ module Impl
             .with_big_segments_status(BigSegmentsStatus::STALE)
             .build
           flag = Flags.boolean_flag_with_clauses(Clauses.match_segment(segment))
-          result = e.evaluate(flag, user_context)
+          (result, _) = e.evaluate(flag, user_context)
           expect(result.detail.value).to be true
           expect(result.detail.reason.big_segments_status).to be(BigSegmentsStatus::STALE)
         end
@@ -148,7 +148,7 @@ module Impl
           # The membership deliberately does not include segment1, because we want the first rule to be
           # a non-match so that it will continue on and check segment2 as well.
 
-          result = e.evaluate(flag, user_context)
+          (result, _) = e.evaluate(flag, user_context)
           expect(result.detail.value).to be true
           expect(result.detail.reason.big_segments_status).to be(BigSegmentsStatus::HEALTHY)
 

spec/impl/evaluator_clause_spec.rb

@@ -9,28 +9,32 @@ module Impl
           context = LDContext.create({ key: 'x', kind: 'user', name: 'Bob' })
           clause = { attribute: 'name', op: 'in', values: ['Bob'] }
           flag = Flags.boolean_flag_with_clauses(clause)
-          expect(basic_evaluator.evaluate(flag, context).detail.value).to be true
+          (result, _) = basic_evaluator.evaluate(flag, context)
+          expect(result.detail.value).to be true
         end
 
         it "can match custom attribute" do
           context = LDContext.create({ key: 'x', kind: 'user', name: 'Bob', legs: 4 })
           clause = { attribute: 'legs', op: 'in', values: [4] }
           flag = Flags.boolean_flag_with_clauses(clause)
-          expect(basic_evaluator.evaluate(flag, context).detail.value).to be true
+          (result, _) = basic_evaluator.evaluate(flag, context)
+          expect(result.detail.value).to be true
         end
 
         it "returns false for missing attribute" do
           context = LDContext.create({ key: 'x', kind: 'user', name: 'Bob' })
           clause = { attribute: 'legs', op: 'in', values: [4] }
           flag = Flags.boolean_flag_with_clauses(clause)
-          expect(basic_evaluator.evaluate(flag, context).detail.value).to be false
+          (result, _) = basic_evaluator.evaluate(flag, context)
+          expect(result.detail.value).to be false
         end
 
         it "returns false for unknown operator" do
           context = LDContext.create({ key: 'x', kind: 'user', name: 'Bob' })
           clause = { attribute: 'name', op: 'unknown', values: [4] }
           flag = Flags.boolean_flag_with_clauses(clause)
-          expect(basic_evaluator.evaluate(flag, context).detail.value).to be false
+          (result, _) = basic_evaluator.evaluate(flag, context)
+          expect(result.detail.value).to be false
         end
 
         it "does not stop evaluating rules after clause with unknown operator" do
@@ -40,14 +44,16 @@ module Impl
           clause1 = { attribute: 'name', op: 'in', values: ['Bob'] }
           rule1 = { clauses: [ clause1 ], variation: 1 }
           flag = Flags.boolean_flag_with_rules(rule0, rule1)
-          expect(basic_evaluator.evaluate(flag, context).detail.value).to be true
+          (result, _) = basic_evaluator.evaluate(flag, context)
+          expect(result.detail.value).to be true
         end
 
         it "can be negated" do
           context = LDContext.create({ key: 'x', kind: 'user', name: 'Bob' })
           clause = { attribute: 'name', op: 'in', values: ['Bob'], negate: true }
           flag = Flags.boolean_flag_with_clauses(clause)
-          expect(basic_evaluator.evaluate(flag, context).detail.value).to be false
+          (result, _) = basic_evaluator.evaluate(flag, context)
+          expect(result.detail.value).to be false
         end
 
         it "clause match uses context kind" do
@@ -59,9 +65,12 @@ module Impl
 
           flag = Flags.boolean_flag_with_clauses(clause)
 
-          expect(basic_evaluator.evaluate(flag, context1).detail.value).to be true
-          expect(basic_evaluator.evaluate(flag, context2).detail.value).to be false
-          expect(basic_evaluator.evaluate(flag, context3).detail.value).to be true
+          (result, _) = basic_evaluator.evaluate(flag, context1)
+          expect(result.detail.value).to be true
+          (result, _) = basic_evaluator.evaluate(flag, context2)
+          expect(result.detail.value).to be false
+          (result, _) = basic_evaluator.evaluate(flag, context3)
+          expect(result.detail.value).to be true
         end
 
         it "clause match by kind attribute" do
@@ -78,9 +87,12 @@ module Impl
 
           flag = Flags.boolean_flag_with_clauses(clause)
 
-          expect(basic_evaluator.evaluate(flag, context1).detail.value).to be false
-          expect(basic_evaluator.evaluate(flag, context2).detail.value).to be true
-          expect(basic_evaluator.evaluate(flag, context3).detail.value).to be true
+          (result, _) = basic_evaluator.evaluate(flag, context1)
+          expect(result.detail.value).to be false
+          (result, _) = basic_evaluator.evaluate(flag, context2)
+          expect(result.detail.value).to be true
+          (result, _) = basic_evaluator.evaluate(flag, context3)
+          expect(result.detail.value).to be true
         end
       end
     end

spec/impl/evaluator_prereq_spec.rb

@@ -18,7 +18,8 @@ module Impl
         context = LDContext.create({ key: 'x' })
         detail = EvaluationDetail.new('b', 1, EvaluationReason::prerequisite_failed('badfeature'))
         e = EvaluatorBuilder.new(logger).with_unknown_flag('badfeature').build
-        result = e.evaluate(flag, context)
+        (result, state) = e.evaluate(flag, context)
+        expect(state.prerequisites).to eq(['badfeature'])
         expect(result.detail).to eq(detail)
         expect(result.prereq_evals).to eq(nil)
       end
@@ -36,9 +37,11 @@ module Impl
         )
         context = LDContext.create({ key: 'x' })
         e = EvaluatorBuilder.new(logger).with_unknown_flag('badfeature').build
-        result1 = e.evaluate(flag, context)
+        (result1, state1) = e.evaluate(flag, context)
+        expect(state1.prerequisites).to eq(['badfeature'])
         expect(result1.detail.reason).to eq EvaluationReason::prerequisite_failed('badfeature')
-        result2 = e.evaluate(flag, context)
+        (result2, state2) = e.evaluate(flag, context)
+        expect(state2.prerequisites).to eq(['badfeature'])
         expect(result2.detail).to be result1.detail
       end
 
@@ -69,7 +72,8 @@ module Impl
           PrerequisiteEvalRecord.new(flag1, flag, EvaluationDetail.new('d', 0, EvaluationReason::fallthrough())),
         ]
         e = EvaluatorBuilder.new(logger).with_flag(flag1).with_unknown_flag('feature2').build
-        result = e.evaluate(flag, context)
+        (result, state) = e.evaluate(flag, context)
+        expect(state.prerequisites).to eq(['feature1'])
         expect(result.detail).to eq(detail)
         expect(result.prereq_evals).to eq(expected_prereqs)
       end
@@ -102,7 +106,8 @@ module Impl
           PrerequisiteEvalRecord.new(flag1, flag, EvaluationDetail.new(nil, nil, EvaluationReason::prerequisite_failed('feature2'))),
         ]
         e = EvaluatorBuilder.new(logger).with_flag(flag1).with_unknown_flag('feature2').build
-        result = e.evaluate(flag, context)
+        (result, state) = e.evaluate(flag, context)
+        expect(state.prerequisites).to eq(['feature1'])
         expect(result.detail).to eq(detail)
         expect(result.prereq_evals).to eq(expected_prereqs)
       end
@@ -136,7 +141,8 @@ module Impl
           PrerequisiteEvalRecord.new(flag1, flag, EvaluationDetail.new('e', 1, EvaluationReason::off)),
         ]
         e = EvaluatorBuilder.new(logger).with_flag(flag1).build
-        result = e.evaluate(flag, context)
+        (result, state) = e.evaluate(flag, context)
+        expect(state.prerequisites).to eq(['feature1'])
         expect(result.detail).to eq(detail)
         expect(result.prereq_evals).to eq(expected_prereqs)
       end
@@ -168,7 +174,8 @@ module Impl
           PrerequisiteEvalRecord.new(flag1, flag, EvaluationDetail.new('d', 0, EvaluationReason::fallthrough)),
         ]
         e = EvaluatorBuilder.new(logger).with_flag(flag1).build
-        result = e.evaluate(flag, context)
+        (result, state) = e.evaluate(flag, context)
+        expect(state.prerequisites).to eq(['feature1'])
         expect(result.detail).to eq(detail)
         expect(result.prereq_evals).to eq(expected_prereqs)
       end
@@ -200,7 +207,8 @@ module Impl
           PrerequisiteEvalRecord.new(flag1, flag, EvaluationDetail.new('e', 1, EvaluationReason::fallthrough)),
         ]
         e = EvaluatorBuilder.new(logger).with_flag(flag1).build
-        result = e.evaluate(flag, context)
+        (result, state) = e.evaluate(flag, context)
+        expect(state.prerequisites).to eq(['feature1'])
         expect(result.detail).to eq(detail)
         expect(result.prereq_evals).to eq(expected_prereqs)
       end
@@ -224,7 +232,7 @@ module Impl
           flags.each { |flag| builder.with_flag(flag) }
 
           evaluator = builder.build
-          result = evaluator.evaluate(flags[0], LDContext.with_key('user'))
+          (result, _) = evaluator.evaluate(flags[0], LDContext.with_key('user'))
           reason = EvaluationReason::error(EvaluationReason::ERROR_MALFORMED_FLAG)
           expect(result.detail.reason).to eq(reason)
         end