launchdarkly-server-sdk 8.19.0-java → 8.20.0-java

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. checksums.yaml +4 -4
  2. data/lib/ldclient-rb/config.rb +14 -4
  3. data/lib/ldclient-rb/data_system/config_builder.rb +35 -1
  4. data/lib/ldclient-rb/data_system.rb +4 -4
  5. data/lib/ldclient-rb/evaluation_detail.rb +37 -4
  6. data/lib/ldclient-rb/events.rb +24 -16
  7. data/lib/ldclient-rb/impl/data_store/store.rb +84 -6
  8. data/lib/ldclient-rb/impl/data_system/fdv1.rb +5 -0
  9. data/lib/ldclient-rb/impl/data_system/fdv2.rb +84 -0
  10. data/lib/ldclient-rb/impl/data_system/polling.rb +18 -0
  11. data/lib/ldclient-rb/impl/data_system/protocolv2.rb +18 -0
  12. data/lib/ldclient-rb/impl/data_system/streaming.rb +16 -4
  13. data/lib/ldclient-rb/impl/data_system.rb +13 -0
  14. data/lib/ldclient-rb/impl/dependency_tracker.rb +1 -1
  15. data/lib/ldclient-rb/impl/evaluator.rb +62 -18
  16. data/lib/ldclient-rb/impl/event_summarizer.rb +13 -2
  17. data/lib/ldclient-rb/impl/event_types.rb +11 -1
  18. data/lib/ldclient-rb/impl/file_data/document.rb +267 -0
  19. data/lib/ldclient-rb/impl/file_data/merge.rb +160 -0
  20. data/lib/ldclient-rb/impl/file_data/poller.rb +87 -0
  21. data/lib/ldclient-rb/impl/file_data/reloader.rb +578 -0
  22. data/lib/ldclient-rb/impl/file_data/watcher.rb +519 -0
  23. data/lib/ldclient-rb/impl/file_data.rb +7 -0
  24. data/lib/ldclient-rb/impl/integrations/file_override_source.rb +174 -0
  25. data/lib/ldclient-rb/impl/model/feature_flag.rb +34 -0
  26. data/lib/ldclient-rb/impl/model/segment.rb +34 -0
  27. data/lib/ldclient-rb/impl/overrides/layer.rb +133 -0
  28. data/lib/ldclient-rb/impl/overrides/overlay.rb +71 -0
  29. data/lib/ldclient-rb/impl/overrides/sink.rb +240 -0
  30. data/lib/ldclient-rb/impl/overrides.rb +5 -0
  31. data/lib/ldclient-rb/integrations/file_data.rb +181 -3
  32. data/lib/ldclient-rb/integrations/test_data/flag_builder.rb +1 -1
  33. data/lib/ldclient-rb/interfaces/overrides.rb +90 -0
  34. data/lib/ldclient-rb/interfaces.rb +1 -0
  35. data/lib/ldclient-rb/ldclient.rb +109 -28
  36. data/lib/ldclient-rb/version.rb +1 -1
  37. metadata +14 -2
@@ -108,6 +108,19 @@ module LaunchDarkly
108
108
  raise NotImplementedError, "#{self.class} must implement #store"
109
109
  end
110
110
 
111
+ #
112
+ # Returns the override store's entries of the given kind, without LaunchDarkly data. The
113
+ # result is empty when no override source is configured or the store holds none. The
114
+ # returned hash must not be modified. Flag overrides are currently experimental and subject
115
+ # to change.
116
+ #
117
+ # @param kind [LaunchDarkly::Impl::DataStore::DataKind]
118
+ # @return [Hash{Symbol => Object}]
119
+ #
120
+ def override_items(kind)
121
+ raise NotImplementedError, "#{self.class} must implement #override_items"
122
+ end
123
+
111
124
  #
112
125
  # Sets the diagnostic accumulator for streaming initialization metrics.
113
126
  # This should be called before start() to ensure metrics are collected.
@@ -13,7 +13,7 @@ module LaunchDarkly
13
13
  # Updates the dependency graph when an item has changed.
14
14
  #
15
15
  # @param from_kind [Object] the changed item's kind
16
- # @param from_key [Symbol] the changed item's key
16
+ # @param from_key [String] the changed item's key
17
17
  # @param from_item [Object] the changed item (can be a Hash, model object, or nil)
18
18
  #
19
19
  def update_dependencies_from(from_kind, from_key, from_item)
@@ -12,7 +12,8 @@ module LaunchDarkly
12
12
  PrerequisiteEvalRecord = Struct.new(
13
13
  :prereq_flag, # the prerequisite flag that we evaluated
14
14
  :prereq_of_flag, # the flag that it was a prerequisite of
15
- :detail # the EvaluationDetail representing the evaluation result
15
+ :detail, # the EvaluationDetail representing the evaluation result
16
+ :override_affected # true if a definition read by the prerequisite's own evaluation came from the override store
16
17
  )
17
18
 
18
19
  class EvaluationException < StandardError
@@ -35,6 +36,9 @@ module LaunchDarkly
35
36
  @segment_stack = EvaluatorStack.new(nil)
36
37
  @prerequisites = []
37
38
  @depth = 0
39
+ # Reading the flag's own definition is the first read of the evaluation, so the marking
40
+ # starts from the flag's override marker.
41
+ @override_affected = original_flag.override?
38
42
  end
39
43
 
40
44
  def record_evaluated_prereq_key(key)
@@ -45,6 +49,10 @@ module LaunchDarkly
45
49
  attr_reader :prerequisites
46
50
  attr_reader :prereq_stack
47
51
  attr_reader :segment_stack
52
+ # True if the evaluation in progress has read a definition that carries the override marker.
53
+ # While a prerequisite is evaluated, this holds the marking of the prerequisite's own subtree.
54
+ # The marking propagates upward only.
55
+ attr_accessor :override_affected
48
56
  end
49
57
 
50
58
  #
@@ -130,7 +138,8 @@ module LaunchDarkly
130
138
  :detail, # the EvaluationDetail representing the evaluation result
131
139
  :prereq_evals, # an array of PrerequisiteEvalRecord instances, or nil
132
140
  :big_segments_status,
133
- :big_segments_membership
141
+ :big_segments_membership,
142
+ :override_affected # true if any definition read during the evaluation came from the override store
134
143
  )
135
144
 
136
145
  # Helper function used internally to construct an EvaluationDetail for an error result.
@@ -152,23 +161,25 @@ module LaunchDarkly
152
161
  result = EvalResult.new
153
162
  begin
154
163
  detail = eval_internal(flag, context, result, state)
164
+
165
+ unless result.big_segments_status.nil?
166
+ # If big_segments_status is non-nil at the end of the evaluation, it means a query was done at
167
+ # some point and we will want to include the status in the evaluation reason.
168
+ detail = EvaluationDetail.new(detail.value, detail.variation_index,
169
+ detail.reason.with_big_segments_status(result.big_segments_status))
170
+ end
155
171
  rescue EvaluationException => exn
156
172
  Impl::Util.log_exception(@logger, "Unexpected error when evaluating flag #{flag.key}", exn)
157
- result.detail = EvaluationDetail.new(nil, nil, EvaluationReason::error(exn.error_kind))
158
- return result, state
173
+ detail = EvaluationDetail.new(nil, nil, EvaluationReason::error(exn.error_kind))
159
174
  rescue => exn
160
175
  Impl::Util.log_exception(@logger, "Unexpected error when evaluating flag #{flag.key}", exn)
161
- result.detail = EvaluationDetail.new(nil, nil, EvaluationReason::error(EvaluationReason::ERROR_EXCEPTION))
162
- return result, state
176
+ detail = EvaluationDetail.new(nil, nil, EvaluationReason::error(EvaluationReason::ERROR_EXCEPTION))
163
177
  end
164
178
 
165
- unless result.big_segments_status.nil?
166
- # If big_segments_status is non-nil at the end of the evaluation, it means a query was done at
167
- # some point and we will want to include the status in the evaluation reason.
168
- detail = EvaluationDetail.new(detail.value, detail.variation_index,
169
- detail.reason.with_big_segments_status(result.big_segments_status))
170
- end
171
- result.detail = detail
179
+ # Error results are marked too. A malformed override definition yields an error reason, and an
180
+ # override still affected that result.
181
+ result.override_affected = state.override_affected
182
+ result.detail = mark_override_affected(detail, state.override_affected)
172
183
  [result, state]
173
184
  end
174
185
 
@@ -240,15 +251,27 @@ module LaunchDarkly
240
251
  @logger.error { "[LDClient] Could not retrieve prerequisite flag \"#{prereq_key}\" when evaluating \"#{flag.key}\"" }
241
252
  prereq_ok = false
242
253
  else
243
- state.depth += 1
244
- prereq_res = eval_internal(prereq_flag, context, eval_result, state)
245
- state.depth -= 1
254
+ # The prerequisite's own record reflects only the definitions that its own subtree read.
255
+ # Its marking starts from its own definition. When it is done, the marking propagates
256
+ # upward into this flag's marking, also when the evaluation ends with an error.
257
+ parent_affected = state.override_affected
258
+ state.override_affected = prereq_flag.override?
259
+ prereq_affected = state.override_affected
260
+ begin
261
+ state.depth += 1
262
+ prereq_res = eval_internal(prereq_flag, context, eval_result, state)
263
+ ensure
264
+ state.depth -= 1
265
+ prereq_affected = state.override_affected
266
+ state.override_affected = parent_affected || prereq_affected
267
+ end
246
268
  # Note that if the prerequisite flag is off, we don't consider it a match no matter what its
247
269
  # off variation was. But we still need to evaluate it in order to generate an event.
248
270
  if !prereq_flag.on || prereq_res.variation_index != prerequisite.variation
249
271
  prereq_ok = false
250
272
  end
251
- prereq_eval = PrerequisiteEvalRecord.new(prereq_flag, flag, prereq_res)
273
+ prereq_res = mark_override_affected(prereq_res, prereq_affected)
274
+ prereq_eval = PrerequisiteEvalRecord.new(prereq_flag, flag, prereq_res, prereq_affected)
252
275
  eval_result.prereq_evals = [] if eval_result.prereq_evals.nil?
253
276
  eval_result.prereq_evals.push(prereq_eval)
254
277
  end
@@ -294,7 +317,15 @@ module LaunchDarkly
294
317
  end
295
318
 
296
319
  segment = @get_segment.call(v)
297
- !segment.nil? && segment_match_context(segment, context, eval_result, state)
320
+ if segment.nil?
321
+ false
322
+ else
323
+ # The segment definition was read, so an override segment marks the evaluation here. A
324
+ # match is not required: a negated clause turns a non-match into a match, so the
325
+ # definition shapes the result either way.
326
+ state.override_affected = true if segment.override?
327
+ segment_match_context(segment, context, eval_result, state)
328
+ end
298
329
  }
299
330
  clause.negate ? !result : result
300
331
  else
@@ -482,6 +513,19 @@ module LaunchDarkly
482
513
  bucket.nil? || bucket < weight
483
514
  end
484
515
 
516
+ # Returns the detail with its reason marked as override-affected when the evaluation read a
517
+ # definition from the override store. Returns the same detail otherwise, so that the precomputed
518
+ # detail instances stay shared.
519
+ #
520
+ # @param detail [LaunchDarkly::EvaluationDetail]
521
+ # @param override_affected [Boolean]
522
+ # @return [LaunchDarkly::EvaluationDetail]
523
+ private def mark_override_affected(detail, override_affected)
524
+ return detail unless override_affected
525
+
526
+ EvaluationDetail.new(detail.value, detail.variation_index, detail.reason.with_override_affected(true))
527
+ end
528
+
485
529
  private def get_value_for_variation_or_rollout(flag, vr, context, precomputed_results)
486
530
  index, in_experiment = EvaluatorBucketing.variation_index_for_context(flag, vr, context)
487
531
 
@@ -5,6 +5,10 @@ module LaunchDarkly
5
5
  module Impl
6
6
  EventSummary = Struct.new(:start_date, :end_date, :counters)
7
7
 
8
+ # The `versions` member is a hash of hashes: flag version, then variation index, then the
9
+ # override-affected marker (a boolean), to an EventSummaryFlagVariationCounter. The marker
10
+ # takes part in the key, so override-affected and other evaluations of the same flag,
11
+ # variation, and version accumulate into separate counters.
8
12
  EventSummaryFlagInfo = Struct.new(:default, :versions, :context_kinds)
9
13
 
10
14
  EventSummaryFlagVariationCounter = Struct.new(:value, :count)
@@ -39,9 +43,16 @@ module LaunchDarkly
39
43
 
40
44
  counters_for_flag.context_kinds.merge(event.context.kinds)
41
45
 
42
- variation_counter = counters_for_flag_version[event.variation]
46
+ counters_for_variation = counters_for_flag_version[event.variation]
47
+ if counters_for_variation.nil?
48
+ counters_for_variation = Hash.new
49
+ counters_for_flag_version[event.variation] = counters_for_variation
50
+ end
51
+
52
+ override_affected = event.override_affected
53
+ variation_counter = counters_for_variation[override_affected]
43
54
  if variation_counter.nil?
44
- counters_for_flag_version[event.variation] = EventSummaryFlagVariationCounter.new(event.value, 1)
55
+ counters_for_variation[override_affected] = EventSummaryFlagVariationCounter.new(event.value, 1)
45
56
  else
46
57
  variation_counter.count = variation_counter.count + 1
47
58
  end
@@ -26,7 +26,8 @@ module LaunchDarkly
26
26
 
27
27
  class EvalEvent < Event
28
28
  def initialize(timestamp, context, key, version = nil, variation = nil, value = nil, reason = nil, default = nil,
29
- track_events = false, debug_until = nil, prereq_of = nil, sampling_ratio = nil, exclude_from_summaries = false)
29
+ track_events = false, debug_until = nil, prereq_of = nil, sampling_ratio = nil, exclude_from_summaries = false,
30
+ override_affected = false)
30
31
  super(timestamp, context, sampling_ratio, exclude_from_summaries)
31
32
  @key = key
32
33
  @version = version
@@ -38,6 +39,7 @@ module LaunchDarkly
38
39
  @track_events = track_events if track_events
39
40
  @debug_until = debug_until if debug_until
40
41
  @prereq_of = prereq_of if prereq_of
42
+ @override_affected = true if override_affected
41
43
  end
42
44
 
43
45
  attr_reader :key
@@ -49,6 +51,14 @@ module LaunchDarkly
49
51
  attr_reader :track_events
50
52
  attr_reader :debug_until
51
53
  attr_reader :prereq_of
54
+
55
+ # True if an override affected the evaluation, directly or through a prerequisite or segment.
56
+ # Such an evaluation appears only in the summary counters, under a counter that carries the
57
+ # override-affected marker. It produces no individual feature event and no debug event.
58
+ # @return [Boolean]
59
+ def override_affected
60
+ @override_affected ? true : false
61
+ end
52
62
  end
53
63
 
54
64
  class MigrationOpEvent < Event
@@ -0,0 +1,267 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "ldclient-rb/impl/model/serialization"
4
+
5
+ require "json"
6
+ require "yaml"
7
+
8
+ module LaunchDarkly
9
+ module Impl
10
+ #
11
+ # Shared file reading, parsing, and merging code for the components that load flag and
12
+ # segment data from local files.
13
+ #
14
+ # @private
15
+ #
16
+ module FileData
17
+ #
18
+ # Raised when a file cannot be read or parsed. It carries the path so that callers can
19
+ # tell a per-file failure from a failure to merge the files' contents.
20
+ #
21
+ class ReadError < StandardError
22
+ # @return [String]
23
+ attr_reader :path
24
+
25
+ # @return [Boolean] true when the file does not exist
26
+ attr_reader :missing
27
+
28
+ #
29
+ # @param path [String]
30
+ # @param message [String]
31
+ # @param missing [Boolean]
32
+ #
33
+ def initialize(path, message, missing: false)
34
+ super("#{message} [#{path}]")
35
+ @path = path
36
+ @missing = missing
37
+ end
38
+ end
39
+
40
+ #
41
+ # The parsed form of one data file. A document may contain full flag definitions, flag key
42
+ # to value entries, and segment definitions. Every hash has symbol keys.
43
+ #
44
+ class Document
45
+ # @return [Hash{Symbol => Hash}]
46
+ attr_reader :flags
47
+
48
+ # @return [Hash{Symbol => Object}]
49
+ attr_reader :flag_values
50
+
51
+ # @return [Hash{Symbol => Hash}]
52
+ attr_reader :segments
53
+
54
+ #
55
+ # @param flags [Hash{Symbol => Hash}]
56
+ # @param flag_values [Hash{Symbol => Object}]
57
+ # @param segments [Hash{Symbol => Hash}]
58
+ #
59
+ def initialize(flags: {}, flag_values: {}, segments: {})
60
+ @flags = flags
61
+ @flag_values = flag_values
62
+ @segments = segments
63
+ end
64
+
65
+ # The document of YAML content that is only a null, such as an empty file, a comment, or
66
+ # "---": a document with no entries.
67
+ NONE = new(flags: {}.freeze, flag_values: {}.freeze, segments: {}.freeze).freeze
68
+
69
+ #
70
+ # Parses the content of a data file in the given format. {FileData.format_of} chooses the
71
+ # format of a file from its name.
72
+ #
73
+ # Whether content with no entries is valid depends on the format, like the rest of the
74
+ # content. Content that is empty or only white space is not a JSON document, so it fails to
75
+ # parse. In YAML it is a document with no entries, {NONE}, and so is a YAML document that is
76
+ # only a null, such as one with only a comment. A document that is not a mapping, or whose
77
+ # "flags", "flagValues", or "segments" member is not a mapping, is an error, and so is
78
+ # content that is not valid UTF-8, in either format.
79
+ #
80
+ # @param content [String] UTF-8 content
81
+ # @param format [Symbol] `:json` or `:yaml`
82
+ # @return [Document]
83
+ # @raise [ArgumentError] if the content is not a valid document
84
+ # @raise [JSON::ParserError, Psych::SyntaxError] if the content cannot be parsed
85
+ #
86
+ def self.parse(content, format:)
87
+ FileData.check_encoding(content)
88
+ case format
89
+ when :json
90
+ # A file that is being rewritten in place can be empty for a moment. Failing to parse
91
+ # keeps its last good data until it is complete.
92
+ raise ArgumentError, "the file has no content, which is not a JSON document" if FileData.blank?(content)
93
+
94
+ raw = JSON.parse(content)
95
+ when :yaml
96
+ # The YAML parser rejects some white space, such as a tab, that is still no content.
97
+ return NONE if FileData.blank?(content)
98
+
99
+ raw = YAML.safe_load(content)
100
+ return NONE if raw.nil?
101
+ else
102
+ raise ArgumentError, "unknown file format #{format.inspect}"
103
+ end
104
+ raise ArgumentError, "file content must be an object" unless raw.is_a?(Hash)
105
+
106
+ data = FileData.symbolize_keys(raw)
107
+ Document.new(
108
+ flags: section(data, :flags),
109
+ flag_values: section(data, :flagValues),
110
+ segments: section(data, :segments)
111
+ )
112
+ end
113
+
114
+ #
115
+ # Reads and parses one data file.
116
+ #
117
+ # @param path [String]
118
+ # @return [Document]
119
+ # @raise [ReadError] if the file cannot be read or parsed
120
+ #
121
+ def self.read(path)
122
+ content = FileData.read_file(path)
123
+ FileData.parse_file(path, content)
124
+ end
125
+
126
+ private_class_method def self.section(data, name)
127
+ value = data[name]
128
+ return {} if value.nil?
129
+ raise ArgumentError, "\"#{name}\" must be an object" unless value.is_a?(Hash)
130
+
131
+ value
132
+ end
133
+ end
134
+
135
+ # The endings of the names of the files that are read as YAML, compared without regard to
136
+ # case. Every other file is read as JSON.
137
+ YAML_FILE_NAME_ENDINGS = [".yaml", ".yml"].freeze
138
+
139
+ # The bytes that count as white space when deciding whether content is empty.
140
+ WHITE_SPACE_BYTES = [0x20, 0x09, 0x0a, 0x0d, 0x0b, 0x0c].freeze
141
+ private_constant :WHITE_SPACE_BYTES
142
+
143
+ #
144
+ # Returns the format of a data file, which its name decides: a name that ends in ".yaml" or
145
+ # ".yml", in any case, is YAML, and any other name is JSON.
146
+ #
147
+ # @param path [String]
148
+ # @return [Symbol] `:json` or `:yaml`
149
+ #
150
+ def self.format_of(path)
151
+ path.downcase.end_with?(*YAML_FILE_NAME_ENDINGS) ? :yaml : :json
152
+ end
153
+
154
+ #
155
+ # Raises an error if the content is not valid UTF-8.
156
+ #
157
+ # @param content [String]
158
+ # @raise [ArgumentError] if the content is not valid UTF-8
159
+ #
160
+ def self.check_encoding(content)
161
+ return if content.valid_encoding?
162
+
163
+ if content.b.start_with?(*UTF16_AND_UTF32_BOMS)
164
+ raise ArgumentError, "the file is encoded in UTF-16 or UTF-32; data files must be UTF-8"
165
+ end
166
+ raise ArgumentError, "the file is not valid UTF-8"
167
+ end
168
+
169
+ #
170
+ # Returns true if the content is empty or only white space.
171
+ #
172
+ # @param content [String]
173
+ # @return [Boolean]
174
+ #
175
+ def self.blank?(content)
176
+ content.each_byte.all? { |byte| WHITE_SPACE_BYTES.include?(byte) }
177
+ end
178
+
179
+ # The byte order marks of UTF-8 and of the encodings that files must not use.
180
+ UTF8_BOM = "\xEF\xBB\xBF".b.freeze
181
+ UTF16_AND_UTF32_BOMS = ["\xFF\xFE".b, "\xFE\xFF".b, "\x00\x00\xFE\xFF".b].freeze
182
+ private_constant :UTF8_BOM, :UTF16_AND_UTF32_BOMS
183
+
184
+ #
185
+ # Reads the raw content of one file, as UTF-8 and without a UTF-8 byte order mark, whatever
186
+ # the process's default encoding. The bytes are not checked here: {Document.parse} rejects
187
+ # content that is not valid UTF-8, so that such a file fails to load like any other content
188
+ # that cannot be parsed.
189
+ #
190
+ # @param path [String]
191
+ # @return [String]
192
+ # @raise [ReadError] if the file cannot be read
193
+ #
194
+ def self.read_file(path)
195
+ content = File.binread(path)
196
+ content = content.byteslice(UTF8_BOM.bytesize..) if content.start_with?(UTF8_BOM)
197
+ content.force_encoding(Encoding::UTF_8)
198
+ rescue Errno::ENOENT => e
199
+ raise ReadError.new(path, "unable to read file: #{e.message}", missing: true)
200
+ rescue SystemCallError, IOError => e
201
+ raise ReadError.new(path, "unable to read file: #{e.message}")
202
+ end
203
+
204
+ #
205
+ # Parses raw content that was read from the given path.
206
+ #
207
+ # @param path [String]
208
+ # @param content [String]
209
+ # @return [Document]
210
+ # @raise [ReadError] if the content cannot be parsed
211
+ #
212
+ def self.parse_file(path, content)
213
+ Document.parse(content, format: format_of(path))
214
+ rescue StandardError => e
215
+ raise ReadError.new(path, "error parsing file: #{e.message}")
216
+ end
217
+
218
+ #
219
+ # Recursively converts hash keys to symbols. The SDK expects all data model objects to
220
+ # have symbol keys.
221
+ #
222
+ # @param value [Object]
223
+ # @return [Object]
224
+ #
225
+ def self.symbolize_keys(value)
226
+ case value
227
+ when Hash
228
+ value.to_h { |k, v| [k.to_s.to_sym, symbolize_keys(v)] }
229
+ when Array
230
+ value.map { |v| symbolize_keys(v) }
231
+ else
232
+ value
233
+ end
234
+ end
235
+
236
+ #
237
+ # Expands a flag key to value entry into a full flag definition that returns the given
238
+ # value for every context. The flag is on, has the value as its only variation, and
239
+ # serves that variation as its fallthrough, so an evaluation reports the FALLTHROUGH
240
+ # reason kind.
241
+ #
242
+ # @param key [String]
243
+ # @param value [Object]
244
+ # @return [Hash]
245
+ #
246
+ def self.make_flag_with_value(key, value)
247
+ {
248
+ key: key,
249
+ on: true,
250
+ version: 1,
251
+ fallthrough: { variation: 0 },
252
+ variations: [value],
253
+ }
254
+ end
255
+
256
+ #
257
+ # Converts each path to an absolute path.
258
+ #
259
+ # @param paths [Array<String>, String]
260
+ # @return [Array<String>]
261
+ #
262
+ def self.absolute_paths(paths)
263
+ Array(paths).map { |p| File.absolute_path(p.to_s) }
264
+ end
265
+ end
266
+ end
267
+ end
@@ -0,0 +1,160 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "ldclient-rb/impl/data_store"
4
+ require "ldclient-rb/impl/file_data/document"
5
+ require "ldclient-rb/impl/model/serialization"
6
+
7
+ module LaunchDarkly
8
+ module Impl
9
+ module FileData
10
+ #
11
+ # Values for the duplicate keys handling option. They select what happens when the same
12
+ # flag or segment key appears in more than one document.
13
+ #
14
+ module DuplicateKeysHandling
15
+ # A duplicated key makes the merge fail.
16
+ FAIL = :fail
17
+
18
+ # Only the first occurrence of a duplicated key is kept, in the order the documents were given.
19
+ IGNORE = :ignore
20
+
21
+ ALL = [FAIL, IGNORE].freeze
22
+ end
23
+
24
+ #
25
+ # Raised when documents cannot be combined, for example because a key is duplicated, an
26
+ # entry is not an object, or an entry cannot be deserialized into the data model.
27
+ #
28
+ class MergeError < StandardError
29
+ end
30
+
31
+ #
32
+ # Counts the entries the merge kept from one document.
33
+ #
34
+ DocumentSummary = Struct.new(:flags, :segments)
35
+
36
+ #
37
+ # Describes one configured file after a reload. `present` is false when the file does not
38
+ # exist and missing files are skipped.
39
+ #
40
+ FileSummary = Struct.new(:path, :present, :flags, :segments)
41
+
42
+ #
43
+ # The merged items from one or more documents.
44
+ #
45
+ class MergeResult
46
+ # @return [Hash{Symbol => LaunchDarkly::Impl::Model::FeatureFlag}]
47
+ attr_reader :flags
48
+
49
+ # @return [Hash{Symbol => LaunchDarkly::Impl::Model::Segment}]
50
+ attr_reader :segments
51
+
52
+ # @return [Array<DocumentSummary>] one entry per input document, in order
53
+ attr_reader :documents
54
+
55
+ # @return [Array<FileSummary>] set by the Reloader, one entry per configured file, in order
56
+ attr_accessor :files
57
+
58
+ def initialize(flags, segments, documents)
59
+ @flags = flags
60
+ @segments = segments
61
+ @documents = documents
62
+ @files = []
63
+ end
64
+
65
+ # @return [Boolean]
66
+ def empty?
67
+ @flags.empty? && @segments.empty?
68
+ end
69
+ end
70
+
71
+ #
72
+ # Combines the items of the given documents into one set of flags and one set of segments.
73
+ # Flag key to value entries expand into full flag definitions. Entries are deserialized into
74
+ # the SDK's data model classes, which validate them. The documents are processed in order,
75
+ # and the configured duplicate keys handling applies when the same key appears more than once.
76
+ #
77
+ # The key under which an entry appears in the document is the item's key for every purpose:
78
+ # the item is stored under it, duplicates are detected by it, and the item's own "key" member
79
+ # is set to it, so that evaluations report the flag by that key. A missing "version" defaults
80
+ # to 1.
81
+ #
82
+ # @param documents [Array<Document>]
83
+ # @param duplicate_keys_handling [Symbol] one of the {DuplicateKeysHandling} values
84
+ # @param logger [Logger, nil] receives data model validation messages
85
+ # @return [MergeResult]
86
+ # @raise [MergeError] if the documents cannot be combined
87
+ #
88
+ def self.merge(documents, duplicate_keys_handling: DuplicateKeysHandling::FAIL, logger: nil)
89
+ flags = {}
90
+ segments = {}
91
+ summaries = []
92
+
93
+ documents.each do |document|
94
+ summary = DocumentSummary.new(0, 0)
95
+
96
+ document.flags.each do |key, data|
97
+ data = prepare_entry("flag", key, data)
98
+ item = deserialize(DataStore::FEATURES, "flag", key, data, logger)
99
+ summary.flags += 1 if insert(flags, "flag", key, item, duplicate_keys_handling)
100
+ end
101
+
102
+ document.flag_values.each do |key, value|
103
+ data = make_flag_with_value(key.to_s, value)
104
+ item = Model.deserialize(DataStore::FEATURES, data, logger)
105
+ summary.flags += 1 if insert(flags, "flag", key, item, duplicate_keys_handling)
106
+ end
107
+
108
+ document.segments.each do |key, data|
109
+ data = prepare_entry("segment", key, data)
110
+ item = deserialize(DataStore::SEGMENTS, "segment", key, data, logger)
111
+ summary.segments += 1 if insert(segments, "segment", key, item, duplicate_keys_handling)
112
+ end
113
+
114
+ summaries << summary
115
+ end
116
+
117
+ MergeResult.new(flags, segments, summaries)
118
+ end
119
+
120
+ #
121
+ # Validates one full flag or segment entry, sets its key to the key it appears under, and fills
122
+ # in its version.
123
+ #
124
+ private_class_method def self.prepare_entry(category, key, data)
125
+ raise MergeError, "#{category} \"#{key}\" is not an object" unless data.is_a?(Hash)
126
+
127
+ data = data.dup
128
+ data[:key] = key.to_s
129
+ data[:version] = 1 if data[:version].nil?
130
+ data
131
+ end
132
+
133
+ #
134
+ # Deserializes one entry into its data model class. The model classes raise for a value
135
+ # that does not fit the schema, and that failure is reported as a merge error that names
136
+ # the entry.
137
+ #
138
+ private_class_method def self.deserialize(kind, category, key, data, logger)
139
+ Model.deserialize(kind, data, logger)
140
+ rescue => e
141
+ raise MergeError, "#{category} \"#{key}\" is not valid: #{e.message}"
142
+ end
143
+
144
+ #
145
+ # Adds an item unless its key was already seen. Returns true when it added the item.
146
+ #
147
+ private_class_method def self.insert(items, category, key, item, duplicate_keys_handling)
148
+ key = key.to_sym
149
+ if items.key?(key)
150
+ return false if duplicate_keys_handling == DuplicateKeysHandling::IGNORE
151
+
152
+ raise MergeError, "#{category} key \"#{key}\" was used more than once"
153
+ end
154
+
155
+ items[key] = item
156
+ true
157
+ end
158
+ end
159
+ end
160
+ end