Class: LaunchDarkly::EvaluationReason

Inherits:
Object
  • Object
show all
Defined in:
lib/ldclient-rb/evaluation_detail.rb

Overview

Describes the reason that a flag evaluation produced a particular value. This is returned by methods such as LDClient#variation_detail as the ‘reason` property of an EvaluationDetail.

The ‘kind` property is always defined, but other properties will have non-nil values only for certain values of `kind`. All properties are immutable.

There is a standard JSON representation of evaluation reasons when they appear in analytics events. Use ‘as_json` or `to_json` to convert to this representation.

Use factory methods such as EvaluationReason.off to obtain instances of this class.

Constant Summary collapse

OFF =

Value for #kind indicating that the flag was off and therefore returned its configured off value.

:OFF
FALLTHROUGH =

Value for #kind indicating that the flag was on but the user did not match any targets or rules.

:FALLTHROUGH
TARGET_MATCH =

Value for #kind indicating that the user key was specifically targeted for this flag.

:TARGET_MATCH
RULE_MATCH =

Value for #kind indicating that the user matched one of the flag’s rules.

:RULE_MATCH
PREREQUISITE_FAILED =

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
ERROR =

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.

:ERROR
ERROR_CLIENT_NOT_READY =

Value for #error_kind indicating that the caller tried to evaluate a flag before the client had successfully initialized.

:CLIENT_NOT_READY
ERROR_FLAG_NOT_FOUND =

Value for #error_kind indicating that the caller provided a flag key that did not match any known flag.

:FLAG_NOT_FOUND
ERROR_MALFORMED_FLAG =

Value for #error_kind indicating that there was an internal inconsistency in the flag data, e.g. a rule specified a nonexistent variation. An error message will always be logged in this case.

:MALFORMED_FLAG
ERROR_USER_NOT_SPECIFIED =

Value for #error_kind indicating that the caller passed ‘nil` for the user parameter, or the user lacked a key.

:USER_NOT_SPECIFIED
ERROR_EXCEPTION =

Value for #error_kind indicating that an unexpected exception stopped flag evaluation. An error message will always be logged in this case.

:EXCEPTION

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#error_kind ⇒ Object (readonly)

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`.



129
130
131
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 129

def error_kind
  @error_kind
end

#kind ⇒ Object (readonly)

Indicates the general category of the reason. Will always be one of the class constants such as #OFF.



113
114
115
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 113

def kind
  @kind
end

#prerequisite_key ⇒ Object (readonly)

The key of the prerequisite flag that did not return the desired variation. If #kind is not #PREREQUISITE_FAILED, this will be ‘nil`.



125
126
127
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 125

def prerequisite_key
  @prerequisite_key
end

#rule_id ⇒ Object (readonly)

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`.



121
122
123
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 121

def rule_id
  @rule_id
end

#rule_index ⇒ Object (readonly)

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`.



117
118
119
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 117

def rule_index
  @rule_index
end

Class Method Details

.error(error_kind) ⇒ EvaluationReason

Returns an instance whose #kind is #ERROR.

Parameters:

  • error_kind (Symbol) —

    value indicating the general category of error

Returns:

Raises:

  • (ArgumentError) —

    if ‘error_kind` is not a symbol



177
178
179
180
181
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 177

def self.error(error_kind)
  raise ArgumentError.new("error_kind must be a symbol") if !(error_kind.is_a? Symbol)
  e = @@error_instances[error_kind]
  e.nil? ? make_error(error_kind) : e
end

.fallthrough ⇒ EvaluationReason

Returns an instance whose #kind is #FALLTHROUGH.

Returns:



139
140
141
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 139

def self.fallthrough
  @@fallthrough
end

.off ⇒ EvaluationReason

Returns an instance whose #kind is #OFF.

Returns:



133
134
135
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 133

def self.off
  @@off
end

.prerequisite_failed(prerequisite_key) ⇒ EvaluationReason

Returns an instance whose #kind is #PREREQUISITE_FAILED.

Parameters:

  • prerequisite_key (String) —

    key of the prerequisite flag that did not return the desired variation

Returns:

Raises:

  • (ArgumentError) —

    if ‘prerequisite_key` is nil or not a string



167
168
169
170
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 167

def self.prerequisite_failed(prerequisite_key)
  raise ArgumentError.new("prerequisite_key must be a string") if !(prerequisite_key.is_a? String)
  new(:PREREQUISITE_FAILED, nil, nil, prerequisite_key, nil)
end

.rule_match(rule_index, rule_id) ⇒ EvaluationReason

Returns an instance whose #kind is #RULE_MATCH.

Parameters:

  • rule_index (Number) —

    the index of the rule that was matched (0 for the first rule in the feature flag)

  • rule_id (String) —

    unique string identifier for the matched rule

Returns:

Raises:

  • (ArgumentError) —

    if ‘rule_index` is not a number or `rule_id` is not a string



156
157
158
159
160
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 156

def self.rule_match(rule_index, rule_id)
  raise ArgumentError.new("rule_index must be a number") if !(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
  new(:RULE_MATCH, rule_index, rule_id, nil, nil)
end

.target_match ⇒ EvaluationReason

Returns an instance whose #kind is #TARGET_MATCH.

Returns:



145
146
147
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 145

def self.target_match
  @@target_match
end

Instance Method Details

#==(other) ⇒ Object 



183
184
185
186
187
188
189
190
191
192
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 183

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
  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)
  end
end

#[](key) ⇒ Object

Allows this object to be treated as a hash corresponding to its JSON representation. For instance, if ‘reason.kind` is #RULE_MATCH, then `reason` will be `“RULE_MATCH”` and `reason` will be equal to `reason.rule_index`.



247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 247

def [](key)
  case key
  when :kind
    @kind.to_s
  when :ruleIndex
    @rule_index
  when :ruleId
    @rule_id
  when :prerequisiteKey
    @prerequisite_key
  when :errorKind
    @error_kind.nil? ? nil : @error_kind.to_s
  else
    nil
  end
end

#as_json ⇒ Hash

Returns a hash that can be used as a JSON representation of the reason, in the format used in LaunchDarkly analytics events.

Returns:

  • (Hash) 


220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 220

def as_json(*) # parameter is unused, but may be passed if we're using the json gem
  # Note that this implementation is somewhat inefficient; it allocates a new hash every time.
  # However, in normal usage the SDK only serializes reasons if 1. full event tracking is
  # 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
  when :RULE_MATCH
    { kind: @kind, ruleIndex: @rule_index, ruleId: @rule_id }
  when :PREREQUISITE_FAILED
    { kind: @kind, prerequisiteKey: @prerequisite_key }
  when :ERROR
    { kind: @kind, errorKind: @error_kind }
  else
    { kind: @kind }
  end
end

#inspect ⇒ String

Returns a concise string representation of the reason. Examples: ‘“FALLTHROUGH”`, `“ERROR(FLAG_NOT_FOUND)”`. The exact syntax is not guaranteed to remain the same; this is meant for debugging.

Returns:

  • (String) 


204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 204

def inspect
  case @kind
  when :RULE_MATCH
    "RULE_MATCH(#{@rule_index},#{@rule_id})"
  when :PREREQUISITE_FAILED
    "PREREQUISITE_FAILED(#{@prerequisite_key})"
  when :ERROR
    "ERROR(#{@error_kind})"
  else
    @kind.to_s
  end
end

#to_json(*a) ⇒ String

Same as #as_json, but converts the JSON structure into a string.

Returns:

  • (String) 


240
241
242
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 240

def to_json(*a)
  as_json.to_json(a)
end

#to_s ⇒ String

Equivalent to #inspect.

Returns:

  • (String) 


196
197
198
 
# File 'lib/ldclient-rb/evaluation_detail.rb', line 196

def to_s
  inspect
end