launchdarkly-server-sdk 6.2.5 → 7.0.0

data/lib/ldclient-rb/evaluation_detail.rb

@@ -12,7 +12,7 @@ module LaunchDarkly
     # @raise [ArgumentError] if `variation_index` or `reason` is not of the correct type
     def initialize(value, variation_index, reason)
       raise ArgumentError.new("variation_index must be a number") if !variation_index.nil? && !(variation_index.is_a? Numeric)
-      raise ArgumentError.new("reason must be an EvaluationReason") if !(reason.is_a? EvaluationReason)
+      raise ArgumentError.new("reason must be an EvaluationReason") unless reason.is_a? EvaluationReason
       @value = value
       @variation_index = variation_index
       @reason = reason
@@ -70,20 +70,20 @@ module LaunchDarkly
   class EvaluationReason
     # Value for {#kind} indicating that the flag was off and therefore returned its configured off value.
     OFF = :OFF
-    
-    # Value for {#kind} indicating that the flag was on but the user did not match any targets or rules.
+
+    # Value for {#kind} indicating that the flag was on but the context did not match any targets or rules.
     FALLTHROUGH = :FALLTHROUGH
-    
-    # Value for {#kind} indicating that the user key was specifically targeted for this flag.
+
+    # Value for {#kind} indicating that the context key was specifically targeted for this flag.
     TARGET_MATCH = :TARGET_MATCH
-    
-    # Value for {#kind} indicating that the user matched one of the flag's rules.
+
+    # Value for {#kind} indicating that the context matched one of the flag's rules.
     RULE_MATCH = :RULE_MATCH
-    
+
     # Value for {#kind} indicating that the flag was considered off because it had at least one
     # prerequisite flag that either was off or did not return the desired variation.
     PREREQUISITE_FAILED = :PREREQUISITE_FAILED
-    
+
     # Value for {#kind} indicating that the flag could not be evaluated, e.g. because it does not exist
     # or due to an unexpected error. In this case the result value will be the application default value
     # that the caller passed to the client. Check {#error_kind} for more details on the problem.
@@ -100,8 +100,8 @@ module LaunchDarkly
     # a rule specified a nonexistent  variation. An error message will always be logged in this case.
     ERROR_MALFORMED_FLAG = :MALFORMED_FLAG
 
-    # Value for {#error_kind} indicating that the caller passed `nil` for the user parameter, or the
-    # user lacked a key.
+    # Value for {#error_kind} indicating that the caller passed `nil` for the context parameter, or the
+    # context was invalid.
     ERROR_USER_NOT_SPECIFIED = :USER_NOT_SPECIFIED
 
     # Value for {#error_kind} indicating that an unexpected exception stopped flag evaluation. An error
@@ -110,27 +110,42 @@ module LaunchDarkly
 
     # Indicates the general category of the reason. Will always be one of the class constants such
     # as {#OFF}.
+    # @return [Symbol]
     attr_reader :kind
 
     # The index of the rule that was matched (0 for the first rule in the feature flag). If
     # {#kind} is not {#RULE_MATCH}, this will be `nil`.
+    # @return [Integer|nil]
     attr_reader :rule_index
 
     # A unique string identifier for the matched rule, which will not change if other rules are added
     # or deleted. If {#kind} is not {#RULE_MATCH}, this will be `nil`.
+    # @return [String]
     attr_reader :rule_id
 
     # A boolean or nil value representing if the rule or fallthrough has an experiment rollout.
+    # @return [Boolean|nil]
     attr_reader :in_experiment
 
     # The key of the prerequisite flag that did not return the desired variation. If {#kind} is not
     # {#PREREQUISITE_FAILED}, this will be `nil`.
+    # @return [String]
     attr_reader :prerequisite_key
 
     # A value indicating the general category of error. This should be one of the class constants such
     # as {#ERROR_FLAG_NOT_FOUND}. If {#kind} is not {#ERROR}, it will be `nil`.
+    # @return [Symbol]
     attr_reader :error_kind
 
+    # Describes the validity of Big Segment information, if and only if the flag evaluation required
+    # querying at least one Big Segment. Otherwise it returns `nil`. Possible values are defined by
+    # {BigSegmentsStatus}.
+    #
+    # Big Segments are a specific kind of context segments. For more information, read the LaunchDarkly
+    # documentation: https://docs.launchdarkly.com/home/users/big-segments
+    # @return [Symbol]
+    attr_reader :big_segments_status
+
     # Returns an instance whose {#kind} is {#OFF}.
     # @return [EvaluationReason]
     def self.off
@@ -161,9 +176,9 @@ module LaunchDarkly
     # @return [EvaluationReason]
     # @raise [ArgumentError] if `rule_index` is not a number or `rule_id` is not a string
     def self.rule_match(rule_index, rule_id, in_experiment=false)
-      raise ArgumentError.new("rule_index must be a number") if !(rule_index.is_a? Numeric)
+      raise ArgumentError.new("rule_index must be a number") unless rule_index.is_a? Numeric
       raise ArgumentError.new("rule_id must be a string") if !rule_id.nil? && !(rule_id.is_a? String) # in test data, ID could be nil
-      
+
       if in_experiment
         er = new(:RULE_MATCH, rule_index, rule_id, nil, nil, true)
       else
@@ -178,7 +193,7 @@ module LaunchDarkly
     # @return [EvaluationReason]
     # @raise [ArgumentError] if `prerequisite_key` is nil or not a string
     def self.prerequisite_failed(prerequisite_key)
-      raise ArgumentError.new("prerequisite_key must be a string") if !(prerequisite_key.is_a? String)
+      raise ArgumentError.new("prerequisite_key must be a string") unless prerequisite_key.is_a? String
       new(:PREREQUISITE_FAILED, nil, nil, prerequisite_key, nil)
     end
 
@@ -188,7 +203,7 @@ module LaunchDarkly
     # @return [EvaluationReason]
     # @raise [ArgumentError] if `error_kind` is not a symbol
     def self.error(error_kind)
-      raise ArgumentError.new("error_kind must be a symbol") if !(error_kind.is_a? Symbol)
+      raise ArgumentError.new("error_kind must be a symbol") unless error_kind.is_a? Symbol
       e = @@error_instances[error_kind]
       e.nil? ? make_error(error_kind) : e
     end
@@ -196,11 +211,13 @@ module LaunchDarkly
     def ==(other)
       if other.is_a? EvaluationReason
         @kind == other.kind && @rule_index == other.rule_index && @rule_id == other.rule_id &&
-          @prerequisite_key == other.prerequisite_key && @error_kind == other.error_kind
+          @prerequisite_key == other.prerequisite_key && @error_kind == other.error_kind &&
+          @big_segments_status == other.big_segments_status
       elsif other.is_a? Hash
         @kind.to_s == other[:kind] && @rule_index == other[:ruleIndex] && @rule_id == other[:ruleId] &&
           @prerequisite_key == other[:prerequisiteKey] &&
-          (other[:errorKind] == @error_kind.nil? ? nil : @error_kind.to_s)
+          (other[:errorKind] == @error_kind.nil? ? nil : @error_kind.to_s) &&
+          (other[:bigSegmentsStatus] == @big_segments_status.nil? ? nil : @big_segments_status.to_s)
       end
     end
 
@@ -242,7 +259,7 @@ module LaunchDarkly
       # enabled for a flag and the application called variation_detail, or 2. experimentation is
       # enabled for an evaluation. We can't reuse these hashes because an application could call
       # as_json and then modify the result.
-      case @kind
+      ret = case @kind
       when :RULE_MATCH
         if @in_experiment
           { kind: @kind, ruleIndex: @rule_index, ruleId: @rule_id, inExperiment: @in_experiment }
@@ -262,6 +279,10 @@ module LaunchDarkly
       else
         { kind: @kind }
       end
+      unless @big_segments_status.nil?
+        ret[:bigSegmentsStatus] = @big_segments_status
+      end
+      ret
     end
 
     # Same as {#as_json}, but converts the JSON structure into a string.
@@ -285,27 +306,36 @@ module LaunchDarkly
         @prerequisite_key
       when :errorKind
         @error_kind.nil? ? nil : @error_kind.to_s
+      when :bigSegmentsStatus
+        @big_segments_status.nil? ? nil : @big_segments_status.to_s
       else
         nil
       end
     end
 
-    private
+    def with_big_segments_status(big_segments_status)
+      return self if @big_segments_status == big_segments_status
+      EvaluationReason.new(@kind, @rule_index, @rule_id, @prerequisite_key, @error_kind, @in_experiment, big_segments_status)
+    end
 
-    def initialize(kind, rule_index, rule_id, prerequisite_key, error_kind, in_experiment=nil)
+    #
+    # Constructor that sets all properties. Applications should not normally use this constructor,
+    # but should use class methods like {#off} to avoid creating unnecessary instances.
+    #
+    def initialize(kind, rule_index, rule_id, prerequisite_key, error_kind, in_experiment=nil,
+        big_segments_status = nil)
       @kind = kind.to_sym
       @rule_index = rule_index
       @rule_id = rule_id
-      @rule_id.freeze if !rule_id.nil?
+      @rule_id.freeze unless rule_id.nil?
       @prerequisite_key = prerequisite_key
-      @prerequisite_key.freeze if !prerequisite_key.nil?
+      @prerequisite_key.freeze unless prerequisite_key.nil?
       @error_kind = error_kind
       @in_experiment = in_experiment
+      @big_segments_status = big_segments_status
     end
 
-    private_class_method :new
-
-    def self.make_error(error_kind)
+    private_class_method def self.make_error(error_kind)
       new(:ERROR, nil, nil, nil, error_kind)
     end
 
@@ -318,7 +348,36 @@ module LaunchDarkly
       ERROR_FLAG_NOT_FOUND => make_error(ERROR_FLAG_NOT_FOUND),
       ERROR_MALFORMED_FLAG => make_error(ERROR_MALFORMED_FLAG),
       ERROR_USER_NOT_SPECIFIED => make_error(ERROR_USER_NOT_SPECIFIED),
-      ERROR_EXCEPTION => make_error(ERROR_EXCEPTION)
+      ERROR_EXCEPTION => make_error(ERROR_EXCEPTION),
     }
   end
+
+  #
+  # Defines the possible values of {EvaluationReason#big_segments_status}.
+  #
+  module BigSegmentsStatus
+    #
+    # Indicates that the Big Segment query involved in the flag evaluation was successful, and
+    # that the segment state is considered up to date.
+    #
+    HEALTHY = :HEALTHY
+
+    #
+    # Indicates that the Big Segment query involved in the flag evaluation was successful, but
+    # that the segment state may not be up to date.
+    #
+    STALE = :STALE
+
+    #
+    # Indicates that Big Segments could not be queried for the flag evaluation because the SDK
+    # configuration did not include a Big Segment store.
+    #
+    NOT_CONFIGURED = :NOT_CONFIGURED
+
+    #
+    # Indicates that the Big Segment query involved in the flag evaluation failed, for instance
+    # due to a database error.
+    #
+    STORE_ERROR = :STORE_ERROR
+  end
 end